public_key: Document pkix_path_validation/3 and pkix_crls_validate/3

4 files changed, 119 insertions, 19 deletions

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()
 	 }.
 </code>
 
@@ -290,7 +290,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'Extension'{
 	  extnID,    % id_extensions() | oid() 
 	  critical,  % boolean()
-	  extnValue  % asn1_der_encoded() 
+	  extnValue  % der_encoded()
 	 }.
 </code>
 
@@ -461,7 +461,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 
 #'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'</p>
 
 #'CertificationRequestInfo_subjectPKInfo_algorithm'{
      algorithm = oid(),
-     parameters = asn1_der_encoded()
+     parameters = der_encoded()
 }	  
 
 #'CertificationRequest_signatureAlgorithm'{
      algorithm = oid(),
-     parameters = asn1_der_encoded()
+     parameters = der_encoded()
      }  
    </code> 
  </section>
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 @@
     
     <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 +89,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>
     
@@ -357,18 +362,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>
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 @@
     
     </legalnotice>
 
-    <title>Using the public_key API</title>
+    <title>Getting Started</title>
     <file>using_public_key.xml</file>
   </header>
 
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());