diff options
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
| -rw-r--r-- | lib/public_key/doc/src/public_key.xml | 171 |
1 files changed, 141 insertions, 30 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 2ec1fcff9d..5864de2d57 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>2012</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -33,12 +33,30 @@ <module>public_key</module> <modulesummary> API module for public key infrastructure.</modulesummary> <description> - <p>This module provides functions to handle public key infrastructure - from <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</url>- X.509 certificates and some parts of the PKCS-standard. + <p>This module provides functions to handle public key infrastructure. It can + encode/decode different file formats (PEM, openssh), sign and verify digital signatures and validate + certificate paths and certificate revocation lists. </p> </description> <section> + <title>public_key</title> + + <list type="bulleted"> + <item>public_key requires the crypto application.</item> + + <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://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf"> DSA</url>- 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> + </list> + </section> + + <section> <title>COMMON DATA TYPES </title> <note><p>All records used in this manual @@ -58,10 +76,13 @@ <p><code>boolean() = true | false</code></p> - <p><code>string = [bytes()]</code></p> + <p><code>string() = [bytes()]</code></p> + + <p><code>der_encoded() = binary()</code></p> - <p><code>pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' - 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' | 'SubjectPublicKeyInfo'| 'PrivateKeyInfo' | 'CertificationRequest'</code></p> + <p><code>pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' | + 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' | 'SubjectPublicKeyInfo' | + 'PrivateKeyInfo' | 'CertificationRequest'</code></p> <p><code>pem_entry () = {pki_asn1_type(), binary(), %% DER or encrypted DER not_encrypted | cipher_info()} </code></p> @@ -86,6 +107,9 @@ <p><code> dss_digest_type() = 'sha' </code></p> + <p><code> crl_reason() = unspecified | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | privilegeWithdrawn | aACompromise + </code></p> + <p><code> ssh_file() = openssh_public_key | rfc4716_public_key | known_hosts | auth_keys </code></p> @@ -150,7 +174,7 @@ <func> <name>der_decode(Asn1type, Der) -> term()</name> - <fsummary> Decodes a public key asn1 der encoded entity.</fsummary> + <fsummary> Decodes a public key ASN.1 DER encoded entity.</fsummary> <type> <v>Asn1Type = atom()</v> <d> ASN.1 type present in the public_key applications @@ -158,7 +182,7 @@ <v>Der = der_encoded()</v> </type> <desc> - <p> Decodes a public key ASN.1 der encoded entity.</p> + <p> Decodes a public key ASN.1 DER encoded entity.</p> </desc> </func> @@ -180,14 +204,14 @@ <func> <name>pem_decode(PemBin) -> [pem_entry()]</name> <fsummary>Decode PEM binary data and return - entries as ASN.1 der encoded entities. </fsummary> + entries as ASN.1 DER encoded entities. </fsummary> <type> <v>PemBin = binary()</v> <d>Example {ok, PemBin} = file:read_file("cert.pem").</d> </type> <desc> <p>Decode PEM binary data and return - entries as ASN.1 der encoded entities.</p> + entries as ASN.1 DER encoded entities.</p> </desc> </func> @@ -211,8 +235,8 @@ <v> Password = string() </v> </type> <desc> - <p>Decodes a pem entry. pem_decode/1 returns a list of pem - entries. Note that if the pem entry is of type + <p>Decodes a PEM entry. pem_decode/1 returns a list of PEM + entries. Note that if the PEM entry is of type 'SubjectPublickeyInfo' it will be further decoded to an rsa_public_key() or dsa_public_key().</p> </desc> @@ -221,7 +245,7 @@ <func> <name>pem_entry_encode(Asn1Type, Entity) -> pem_entry()</name> <name>pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry()</name> - <fsummary> Creates a pem entry that can be fed to pem_encode/1.</fsummary> + <fsummary> Creates a PEM entry that can be fed to pem_encode/1.</fsummary> <type> <v>Asn1Type = pki_asn1_type()</v> <v>Entity = term()</v> @@ -235,7 +259,7 @@ <v>Password = string()</v> </type> <desc> - <p> Creates a pem entry that can be feed to pem_encode/1.</p> + <p> Creates a PEM entry that can be feed to pem_encode/1.</p> </desc> </func> @@ -265,12 +289,12 @@ <func> <name>pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{}</name> - <fsummary> Decodes an ASN.1 der encoded pkix x509 certificate.</fsummary> + <fsummary> Decodes an ASN.1 DER encoded PKIX x509 certificate.</fsummary> <type> <v>Cert = der_encoded()</v> </type> <desc> - <p>Decodes an ASN.1 der encoded pkix certificate. The otp option + <p>Decodes an ASN.1 DER encoded PKIX certificate. The otp option will use the customized ASN.1 specification OTP-PKIX.asn1 for decoding and also recursively decode most of the standard parts.</p> @@ -279,14 +303,15 @@ <func> <name>pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded()</name> - <fsummary>Der encodes a pkix x509 certificate or part of such a + <fsummary>DER encodes a PKIX x509 certificate or part of such a certificate.</fsummary> <type> <v>Asn1Type = atom()</v> <d>The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either .</d> + <v>Entity = #'Certificate'{} | #'OTPCertificate'{} | a valid subtype</v> </type> <desc> - <p>Der encodes a pkix x509 certificate or part of such a + <p>DER encodes a PKIX x509 certificate or part of such a certificate. This function must be used for encoding certificates or parts of certificates that are decoded/created in the otp format, whereas for the plain format this function will directly call der_encode/2. </p> @@ -356,18 +381,104 @@ </desc> </func> - <!-- <func> --> - <!-- <name>pkix_path_validation()</name> --> - <!-- <fsummary> Performs a basic path validation according to RFC 5280.</fsummary> --> - <!-- <type> --> - <!-- <v></v> --> - <!-- </type> --> - <!-- <desc> --> - <!-- <p> Performs a basic path validation according to RFC 5280.</p> --> - <!-- </desc> --> - <!-- </func> --> + <func> + <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> CertChain = [der_encode()]</v> + <d>A list of DER encoded certificates in trust order ending with the peer certificate.</d> + <v> Options = proplists:proplists()</v> + <v>PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', + 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> + </type> + <desc> + <p> + 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 + from the supplied <c>verify_fun</c> + </p> + + <taglist> + <p> Available options are: </p> + + <tag>{verify_fun, fun()}</tag> + <item> + <p>The fun should be defined as:</p> + + <code> +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()}. + </code> + + <p>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 <c>selfsigned_peer</c> 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.</p> + + </item> + <tag>{max_path_length, integer()}</tag> + <item> + The <c>max_path_length</c> is the maximum number of non-self-issued + intermediate certificates that may follow the peer certificate + in a valid certification path. So if <c>max_path_length</c> 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. + </item> + </taglist> + </desc> + </func> + + <func> + <name>pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus()</name> + <fsummary> Performs CRL validation.</fsummary> + <type> + <v> OTPCertificate = #'OTPCertificate'{}</v> + <v> DPAndCRLs = [{DP::#'DistributionPoint'{} ,CRL::#'CertificateList'{}}] </v> + <v> Options = proplists:proplists()</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 + </seealso></p> + <taglist> + <p> Available options are: </p> + <tag>{update_crl, fun()}</tag> + <item> + <p>The fun has the following type spec:</p> + + <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 + public_key will use the default implementation: + </p> + <code> fun(_DP, CRL) -> CRL end</code> + </item> + </taglist> + </desc> + </func> - <func> <name>pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encode()</name> <fsummary>Signs certificate.</fsummary> @@ -388,7 +499,7 @@ <v>Key = rsa_public_key() | dsa_public_key()</v> </type> <desc> - <p> Verify pkix x.509 certificate signature.</p> + <p> Verify PKIX x.509 certificate signature.</p> </desc> </func> |