From 1c6aa8a70fb2041d1df3c1f4203d5fbb8a41e4fb Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 17 Dec 2012 15:23:52 +0100 Subject: public_key: Document pkix_path_validation/3 and pkix_crls_validate/3 --- lib/public_key/doc/src/cert_records.xml | 10 +-- lib/public_key/doc/src/public_key.xml | 115 +++++++++++++++++++++++++--- lib/public_key/doc/src/using_public_key.xml | 2 +- lib/public_key/src/public_key.erl | 11 ++- 4 files changed, 119 insertions(+), 19 deletions(-) (limited to 'lib/public_key') diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml index 93c26f4639..6d3d4b3107 100644 --- a/lib/public_key/doc/src/cert_records.xml +++ b/lib/public_key/doc/src/cert_records.xml @@ -119,7 +119,7 @@ #'AlgorithmIdentifier'{ algorithm, % oid() - parameters % asn1_der_encoded() + parameters % der_encoded() }. @@ -290,7 +290,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'Extension'{ extnID, % id_extensions() | oid() critical, % boolean() - extnValue % asn1_der_encoded() + extnValue % der_encoded() }. @@ -461,7 +461,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'Attribute'{ type, % oid() - values % [asn1_der_encoded()] + values % [der_encoded()] }). #'BasicConstraints'{ @@ -660,12 +660,12 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'CertificationRequestInfo_subjectPKInfo_algorithm'{ algorithm = oid(), - parameters = asn1_der_encoded() + parameters = der_encoded() } #'CertificationRequest_signatureAlgorithm'{ algorithm = oid(), - parameters = asn1_der_encoded() + parameters = der_encoded() } diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index b240d53571..93ba45e457 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -58,7 +58,9 @@

boolean() = true | false

-

string = [bytes()]

+

string() = [bytes()]

+ +

der_encoded() = binary()

pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' | 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' | 'SubjectPublicKeyInfo' | @@ -87,6 +89,9 @@

dss_digest_type() = 'sha'

+

crl_reason() = unspecified | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | privilegeWithdrawn | aACompromise +

+

ssh_file() = openssh_public_key | rfc4716_public_key | known_hosts | auth_keys

@@ -357,18 +362,104 @@ - - - - - - - - - - + + pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicKeyInfo, PolicyTree}} | {error, {bad_cert, Reason}} + Performs a basic path validation according to RFC 5280. + + TrustedCert = #'OTPCertificate'{} | der_encode() | unknown_ca | selfsigned_peer + Normally a trusted certificate but it can also be one of the path validation + errors unknown_ca or selfsigned_peer that can be discovered while + constructing the input to this function and that should be run through the verify_fun. + CertChain = [der_encode()] + A list of DER encoded certificates in trust order ending with the peer certificate. + Options = proplists:proplists() + PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', + rsa_public_key() | integer(), 'NULL' | 'Dss-Parms'{}} + PolicyTree = term() + At the moment this will always be an empty list as Policies are not currently supported + Reason = cert_expired | invalid_issuer | invalid_signature | unknown_ca | + selfsigned_peer | name_not_permitted | missing_basic_constraint | invalid_key_usage | crl_reason() + + + +

+ Performs a basic path validation according to + RFC 5280. + However CRL validation is done separately by pkix_crls_validate/3 and should be called + from the supplied verify_fun +

+ + +

Available options are:

+ + {verify_fun, fun()} + +

The fun should be defined as:

+ + +fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | + {extension, #'Extension'{}}, + InitialUserState :: term()) -> + {valid, UserState :: term()} | {valid_peer, UserState :: term()} | + {fail, Reason :: term()} | {unknown, UserState :: term()}. + + +

If the verify callback fun returns {fail, Reason}, the + verification process is immediately stopped. If the verify + callback fun returns {valid, UserState}, the verification + process is continued, this can be used to accept specific path + validation errors such as selfsigned_peer as well as + verifying application specific extensions. If called with an + extension unknown to the user application the return value + {unknown, UserState} should be used.

+ + + {max_path_length, integer()} + + The max_path_length is the maximum number of non-self-issued + intermediate certificates that may follow the peer certificate + in a valid certification path. So if max_path_length is 0 the PEER must + be signed by the trusted ROOT-CA directly, if 1 the path can + be PEER, CA, ROOT-CA, if it is 2 PEER, CA, CA, ROOT-CA and so + on. + + + + + + + pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus() + Performs CRL validation. + + OTPCertificate = #'OTPCertificate'{} + DPAndCRLs = [{DP::#'DistributionPoint'{} ,CRL::#'CertificateList'{}}] + Options = proplists:proplists() + CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | + {bad_cert, {revoked, crl_reason()}} + + +

Performs CRL validation. It is intended to be called from + the verify fun of pkix_path_validation/3 +

+ +

Available options are:

+ {update_crl, fun()} + +

The fun has the following type spec:

+ + fun(#'DistributionPoint'{}, #'CertificateList'{}) -> #'CertificateList'{} + +

The fun should use the information in the distribution point to acesses + the lates possible version of the CRL. If this fun is not specified + public_key will use the default implementation: +

+ fun(_DP, CRL) -> CRL end + + + + - pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encode() Signs certificate. diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index f0eaeb8654..1224b57aed 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -21,7 +21,7 @@ - Using the public_key API + Getting Started using_public_key.xml diff --git a/lib/public_key/src/public_key.erl b/lib/public_key/src/public_key.erl index fa999c5ab9..5686920dd4 100644 --- a/lib/public_key/src/public_key.erl +++ b/lib/public_key/src/public_key.erl @@ -51,6 +51,8 @@ -type public_crypt_options() :: [{rsa_pad, rsa_padding()}]. -type rsa_digest_type() :: 'md5' | 'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'. -type dss_digest_type() :: 'none' | 'sha'. %% None is for backwards compatibility +-type crl_reason() :: unspecified | keyCompromise | cACompromise | affiliationChanged | superseded + | cessationOfOperation | certificateHold | privilegeWithdrawn | aACompromise. -define(UINT32(X), X:32/unsigned-big-integer). -define(DER_NULL, <<5, 0>>). @@ -507,7 +509,7 @@ pkix_normalize_name(Issuer) -> %%-------------------------------------------------------------------- -spec pkix_path_validation(Cert::binary()| #'OTPCertificate'{} | atom(), CertChain :: [binary()] , - Options :: list()) -> + Options :: proplist:proplist()) -> {ok, {PublicKeyInfo :: term(), PolicyTree :: term()}} | {error, {bad_cert, Reason :: term()}}. @@ -542,7 +544,14 @@ pkix_path_validation(#'OTPCertificate'{} = TrustedCert, CertChain, Options) Options), path_validation(CertChain, ValidationState). +%-------------------------------------------------------------------- +-spec pkix_crls_validate(#'OTPCertificate'{}, + [{DP::#'DistributionPoint'{} ,CRL::#'CertificateList'{}}], + Options :: proplist:proplist()) -> valid | {bad_cert, revocation_status_undetermined} + | {bad_cert, {revoked, crl_reason()}}. +%% Description: Performs a basic path validation according to RFC 5280. +%%-------------------------------------------------------------------- pkix_crls_validate(OtpCert, [{_,_,_} |_] = DPAndCRLs, Options) -> pkix_crls_validate(OtpCert, DPAndCRLs, DPAndCRLs, Options, pubkey_crl:init_revokation_state()); -- cgit v1.2.3