diff options
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
| -rw-r--r-- | lib/public_key/doc/src/public_key.xml | 96 |
1 files changed, 74 insertions, 22 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index fc3479cb64..e3473f80d7 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2008</year> - <year>2013</year> + <year>2014</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -48,12 +48,12 @@ <item>Supports <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280 </url> - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile </item> - <item>Supports <url href="http://www.rsa.com/rsalabs/node.asp?id=2125"> PKCS-1 </url> - RSA Cryptography Standard </item> + <item>Supports <url href="http://www.ietf.org/rfc/rfc3447.txt"> PKCS-1 </url> - RSA Cryptography Standard </item> <item>Supports <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf"> DSS</url>- Digital Signature Standard (DSA - Digital Signature Algorithm)</item> - <item>Supports <url href="http://www.rsa.com/rsalabs/node.asp?id=2126"> PKCS-3 </url> - Diffie-Hellman Key Agreement Standard </item> - <item>Supports <url href="http://www.rsa.com/rsalabs/node.asp?id=2127"> PKCS-5</url> - Password-Based Cryptography Standard </item> - <item>Supports <url href="http://www.rsa.com/rsalabs/node.asp?id=2130"> PKCS-8</url> - Private-Key Information Syntax Standard</item> - <item>Supports <url href="http://www.rsa.com/rsalabs/node.asp?id=2132"> PKCS-10</url> - Certification Request Syntax Standard</item> + <item>Supports <url href="http://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-3-diffie-hellman-key-agreement-standar.htm"> PKCS-3 </url> - Diffie-Hellman Key Agreement Standard </item> + <item>Supports <url href="http://www.ietf.org/rfc/rfc2898.txt"> PKCS-5</url> - Password-Based Cryptography Standard </item> + <item>Supports <url href="http://www.ietf.org/rfc/rfc5208.txt"> PKCS-8</url> - Private-Key Information Syntax Standard</item> + <item>Supports <url href="http://www.ietf.org/rfc/rfc5967.txt"> PKCS-10</url> - Certification Request Syntax Standard</item> </list> </section> @@ -75,7 +75,7 @@ <p><em>Data Types </em></p> - <p><code>oid() - a tuple of integers as generated by the ASN1 compiler.</code></p> + <p><code>oid() - Object Identifier, a tuple of integers as generated by the ASN1 compiler.</code></p> <p><code>boolean() = true | false</code></p> @@ -92,7 +92,7 @@ not_encrypted | cipher_info()}</code></p> <p><code>cipher_info() = {"RC2-CBC | "DES-CBC" | "DES-EDE3-CBC", - crypto:rand_bytes(8)} | 'PBES2-params'}</code></p> + crypto:rand_bytes(8) | {#'PBEParameter{}, digest_type()} |#'PBES2-params'{}}</code></p> <p><code>public_key() = rsa_public_key() | dsa_public_key() | ec_public_key()</code></p> <p><code>private_key() = rsa_private_key() | dsa_private_key() | ec_private_key()</code></p> @@ -113,6 +113,8 @@ <p><code>rsa_padding() = 'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding' | 'rsa_no_padding'</code></p> + + <p><code>digest_type() - Union of below digest types</code></p> <p><code>rsa_digest_type() = 'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</code></p> @@ -429,10 +431,12 @@ <name>pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicKeyInfo, PolicyTree}} | {error, {bad_cert, Reason}} </name> <fsummary> Performs a basic path validation according to RFC 5280.</fsummary> <type> - <v> TrustedCert = #'OTPCertificate'{} | der_encode() | unknown_ca | selfsigned_peer </v> - <d>Normally a trusted certificate but it can also be one of the path validation - errors <c>unknown_ca </c> or <c>selfsigned_peer </c> that can be discovered while - constructing the input to this function and that should be run through the <c>verify_fun</c>.</d> + <v> TrustedCert = #'OTPCertificate'{} | der_encode() | atom() </v> + <d>Normally a trusted certificate but it can also be a path validation + error that can be discovered while + constructing the input to this function and that should be run through the <c>verify_fun</c>. + For example <c>unknown_ca </c> or <c>selfsigned_peer </c> + </d> <v> CertChain = [der_encode()]</v> <d>A list of DER encoded certificates in trust order ending with the peer certificate.</d> <v> Options = proplists:proplist()</v> @@ -440,8 +444,8 @@ rsa_public_key() | integer(), 'NULL' | 'Dss-Parms'{}}</v> <v> PolicyTree = term() </v> <d>At the moment this will always be an empty list as Policies are not currently supported</d> - <v> Reason = cert_expired | invalid_issuer | invalid_signature | unknown_ca | - selfsigned_peer | name_not_permitted | missing_basic_constraint | invalid_key_usage | crl_reason() + <v> Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted | + missing_basic_constraint | invalid_key_usage | {revoked, crl_reason()} | atom() </v> </type> <desc> @@ -449,7 +453,7 @@ Performs a basic path validation according to <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280.</url> However CRL validation is done separately by <seealso - marker="public_key#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> and should be called + marker="#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> and should be called from the supplied <c>verify_fun</c> </p> @@ -461,11 +465,14 @@ <p>The fun should be defined as:</p> <code> -fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | - {extension, #'Extension'{}}, +fun(OtpCert :: #'OTPCertificate'{}, + Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} | + {extension, #'Extension'{}}, InitialUserState :: term()) -> - {valid, UserState :: term()} | {valid_peer, UserState :: term()} | - {fail, Reason :: term()} | {unknown, UserState :: term()}. + {valid, UserState :: term()} | + {valid_peer, UserState :: term()} | + {fail, Reason :: term()} | + {unknown, UserState :: term()}. </code> <p>If the verify callback fun returns {fail, Reason}, the @@ -488,6 +495,35 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | on. </item> </taglist> + + <p> Possible reasons for a bad certificate are: </p> + <taglist> + <tag>cert_expired</tag> + <item>The certificate is no longer valid as its expiration date has passed.</item> + + <tag>invalid_issuer</tag> + <item>The certificate issuer name does not match the name of the issuer certificate in the chain.</item> + + <tag>invalid_signature</tag> + <item>The certificate was not signed by its issuer certificate in the chain.</item> + + <tag>name_not_permitted</tag> + <item>Invalid Subject Alternative Name extension.</item> + + <tag>missing_basic_constraint</tag> + <item>Certificate, required to have the basic constraints extension, does not have + a basic constraints extension.</item> + + <tag>invalid_key_usage</tag> + <item>Certificate key is used in an invalid way according to the key usage extension.</item> + + <tag>{revoked, crl_reason()}</tag> + <item>Certificate has been revoked.</item> + + <tag>atom()</tag> + <item>Application specific error reason that should be checked by the verify_fun</item> + </taglist> + </desc> </func> @@ -496,14 +532,14 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | <fsummary> Performs CRL validation.</fsummary> <type> <v> OTPCertificate = #'OTPCertificate'{}</v> - <v> DPAndCRLs = [{DP::#'DistributionPoint'{} ,CRL::#'CertificateList'{}}] </v> + <v> DPAndCRLs = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] </v> <v> Options = proplists:proplist()</v> <v> CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | {bad_cert, {revoked, crl_reason()}}</v> </type> <desc> <p> Performs CRL validation. It is intended to be called from - the verify fun of <seealso marker="public_key#pkix_path_validation-3"> pkix_path_validation/3 + the verify fun of <seealso marker="#pkix_path_validation-3"> pkix_path_validation/3 </seealso></p> <taglist> <p> Available options are: </p> @@ -511,7 +547,8 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | <item> <p>The fun has the following type spec:</p> - <code> fun(#'DistributionPoint'{}, #'CertificateList'{}) -> #'CertificateList'{}</code> + <code> fun(#'DistributionPoint'{}, #'CertificateList'{}) -> + #'CertificateList'{}</code> <p>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 @@ -519,6 +556,21 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | </p> <code> fun(_DP, CRL) -> CRL end</code> </item> + + <tag>{issuer_fun, fun()}</tag> + <item> + <p>The fun has the following type spec:</p> + + <code> +fun(#'DistributionPoint'{}, #'CertificateList'{}, + {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) -> + {ok, #'OTPCertificate'{}, [der_encoded]}</code> + + <p>The fun should return the root certificate and certificate chain + that has signed the CRL. + </p> + <code> fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}</code> + </item> </taglist> </desc> </func> |