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 +- 3 files changed, 109 insertions(+), 18 deletions(-) (limited to 'lib/public_key/doc') 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 -- cgit v1.2.3