Merge branch 'ia/public_key/CRL/OTP-7045'

* ia/public_key/CRL/OTP-7045:
  public_key: Enhance documentation
  public_key: CTify test suites
  public_key: Document pkix_path_validation/3 and pkix_crls_validate/3
  Support CRL verification in public_key
  All basic test cases pass

1 files changed, 137 insertions, 27 deletions

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index b240d53571..66c9217579 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -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 vlidate
+    certificate paths and certificate revokation 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,7 +76,9 @@
     
     <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' |
@@ -87,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>
     
@@ -151,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
@@ -159,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>
     
@@ -181,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> 
     
@@ -212,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> 
@@ -222,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>
@@ -236,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>
 
@@ -266,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>
@@ -280,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> 
@@ -357,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>
@@ -389,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>