Revise the public_key API

Cleaned up and documented the public_key API to
make it useful for general use.

1 files changed, 300 insertions, 200 deletions

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index dc9a96906f..c72719fac4 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
@@ -34,11 +34,7 @@
   <modulesummary> API module for public key infrastructure.</modulesummary>
   <description>
     <p>This module provides functions to handle public key infrastructure
-    from RFC 3280 - X.509 certificates (will later be upgraded to RFC 5280)
-    and some parts of the PKCS-standard.
-    Currently this application is mainly used by the new
-    ssl implementation. The API is yet under construction 
-    and only a few of the functions are currently documented and thereby supported.
+    from RFC 5280 - X.509 certificates and some parts of the PKCS-standard.
     </p>
   </description>
 
@@ -62,37 +58,37 @@
     
     <p><c>boolean() = true | false</c></p> 
 
-    <p><c>string = [bytes()]</c></p> 
-     
-    <p><c>asn1_der_encoded() = binary() | [bytes()]</c></p> 
+    <p><c>string = [bytes()]</c></p>
+   
+    <p><c>der_encoded() = binary() </c></p>
 
-    <p><c>der_bin() = binary() </c></p> 
+    <p><c>decrypt_der() = binary() </c></p>
     
-    <p><c>oid() - a tuple of integers 
-    as generated by the asn1 compiler.</c></p>
-
-    <p><c>public_key() = rsa_public_key() | dsa_public_key()</c></p> 
+    <p><c>pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'|
+    'DSAPrivateKey' | 'DHParameter'</c></p>
 
+     <p><c>pem_entry () = {pki_asn1_type(), der_encoded() | decrypt_der(), not_encrypted |
+     {"DES-CBC" | "DES-EDE3-CBC",  crypto:rand_bytes(8)}}.</c></p>
+     
     <p><c>rsa_public_key()  = #'RSAPublicKey'{}</c></p> 
     
     <p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p>
 
-    <p><c>dsa_public_key() = integer() </c></p> 
-
-    <p><c>public_key_params() = dsa_key_params() </c></p>
-    
-    <p><c>dsa_key_params()  = #'Dss-Parms'{} </c></p> 
-    
-    <p><c>private_key() =  rsa_private_key() | dsa_private_key()</c></p> 
+    <p><c>dsa_public_key() = {integer(),  #'Dss-Parms'{}} </c></p> 
 
     <p><c>rsa_private_key() = #'RSAPrivateKey'{} </c></p> 
     
     <p><c>dsa_private_key() = #'DSAPrivateKey'{}</c></p>
+    
+    <p><c> public_crypt_options() = [{rsa_pad, rsa_padding()}]. </c></p>
 
-    <p><c>x509_certificate() = "#Certificate{}"</c></p>
-
-    <p><c>x509_tbs_certificate() = #'TBSCertificate'{} </c></p> 
-
+    <p><c> rsa_padding() =  'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding' 
+    | 'rsa_no_padding'</c></p>
+    
+    <p><c> rsa_digest_type()  = 'md5' | 'sha' </c></p>
+    
+    <p><c> dss_digest_type()  = 'none' | 'sha' </c></p>
+    
 <!--     <p><c>policy_tree() = [Root, Children]</c></p> -->
     
 <!--     <p><c>Root = #policy_tree_node{}</c></p>    -->
@@ -121,197 +117,301 @@
 <!--          that would satisfy this policy in the certificate x+1. </item>         -->
 <!--     </taglist> -->
   </section> 
-  
-<funcs>  
-  <func> 
-    <name>decode_private_key(KeyInfo) -> </name> 
-    <name>decode_private_key(KeyInfo, Password) -> {ok, PrivateKey} | {error, Reason}</name> 
-    <fsummary> Decodes an asn1 der encoded private key.</fsummary> 
-    <type> 
-      <v> KeyInfo =  {KeyType, der_bin(), ChipherInfo} </v>
-      <d> As returned from pem_to_der/1 for private keys</d>
-      <v> KeyType =  rsa_private_key | dsa_private_key </v>
-      <v> ChipherInfo = opaque() | no_encryption </v>
-      <d> ChipherInfo may contain encryption parameters if the private key is password
-      protected, these are opaque to the user just pass the value returned by pem_to_der/1
-      to this function.</d>
-      <v> Password =  string() </v>
-      <d>Must be specified if CipherInfo =/= no_encryption</d>
-      <v> PrivateKey =  private_key() </v>
-      <v> Reason = term() </v> 
-    </type>
-    <desc>
-	 <p>Decodes an asn1 der encoded private key.</p>
-    </desc> 
-  </func> 
-     
+
+<funcs>    
+
   <func>
-    <name>pem_to_der(File) -> {ok, [Entry]}</name>
-    <fsummary>Reads a PEM file and translates it into its asn1 der
-    encoded parts.</fsummary>
+    <name>decrypt_private(CipherText, Key [, Options]) -> binary()</name>
+    <fsummary>Public key decryption.</fsummary>
     <type>
-      <v>File = path()</v> 
-    <v>Password = string()</v> 
-    <v>Entry = {entry_type(), der_bin(), CipherInfo}</v>
-    <v> ChipherInfo = opaque() | no_encryption </v>
-    <d> ChipherInfo may contain encryption parameters if the private key is password
-    protected, these will be handled by the function decode_private_key/2. </d>
-    <v>entry_type() = cert | cert_req | rsa_private_key | dsa_private_key | 
-    dh_params </v>
+      <v>CipherText = binary()</v>
+      <v>Key = rsa_private_key()</v>
+      <v>Options = public_crypt_options()</v>
   </type> 
   <desc> 
-    <p>Reads a PEM file and translates it into its asn1 der 
-    encoded parts.</p> 
+    <p>Public key decryption using the private key.</p> 
+  </desc> 
+  </func>
+
+  <func>
+    <name>decrypt_public(CipherText, Key [, Options]) - > binary()</name>
+    <fsummary></fsummary>
+    <type>
+      <v>CipherText = binary()</v>
+      <v>Key = rsa_public_key()</v>
+      <v>Options = public_crypt_options()</v>
+  </type> 
+  <desc> 
+    <p> Public key decryption using the public key.</p> 
   </desc> 
   </func> 
-    
-  <func> 
-    <name>pkix_decode_cert(Cert, Type) -> {ok, DecodedCert} | {error, Reason}</name> 
-    <fsummary> Decodes an asn1 der encoded pkix certificate. </fsummary> 
-    <type> 
-      <v>Cert = asn1_der_encoded() </v>
-      <v>Type = plain | otp</v> 
-      <v>DecodeCert = x509_certificate() </v> 
-      <d>When type is specified as otp the asn1 spec OTP-PKIX.asn1 is used to decode known
-      extensions and enhance the signature field in
-      #'Certificate'{} and '#TBSCertificate'{}. This is currently used by the new ssl
-      implementation but not documented and supported for the public_key application.</d> 
-      <v>Reason = term() </v> 
+
+  <func>
+    <name>der_decode(Asn1type, Der) -> term()</name>
+    <fsummary> Decodes a public key asn1 der encoded entity.</fsummary>
+    <type>
+      <v>Asn1Type = atom() -</v>
+      <d> Asn1 type present in the public_key applications
+      asn1 specifications.</d>
+      <v>Der = der_encoded()</v>
     </type> 
-    <desc>
-      <p> Decodes an asn1 encoded pkix certificate.</p> 
+    <desc> 
+      <p> Decodes a public key asn1 der encoded entity.</p> 
     </desc> 
   </func>
+    
+  <func>
+    <name>der_encode(Asn1Type, Entity) -> der_encoded()</name>
+    <fsummary> Encodes a public key entity with asn1 DER encoding.</fsummary>
+    <type>
+      <v>Asn1Type = atom()</v>
+      <d> Asn1 type present in the public_key applications
+	 asn1 specifications.</d>
+      <v>Entity = term() - The erlang representation of <c> Asn1Type</c></v>
+  </type> 
+  <desc> 
+    <p> Encodes a public key entity with asn1 DER encoding.</p> 
+  </desc> 
+  </func>
+
+  <func>
+    <name>pem_decode(PemBin) -> [pem_entry()]</name>
+    <fsummary>Decode PEM binary data and return
+    entries as asn1 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 asn1 der encoded entities.</p> 
+  </desc> 
+  </func> 
+    
+   <func>
+    <name>pem_encode(PemEntries) -> binary()</name>
+    <fsummary>Creates a PEM binary</fsummary>
+    <type>
+      <v> PemEntries = [pem_entry()] </v> 
+  </type> 
+  <desc> 
+    <p>Creates a PEM binary</p> 
+  </desc> 
+  </func>
+
+   <func>
+    <name>pem_entry_decode(PemEntry [, Password]) -> term()</name>
+    <fsummary>Decodes a pem entry.</fsummary>
+    <type>
+      <v> PemEntry = pem_entry() </v> 
+      <v> Password = string() </v> 
+  </type> 
+  <desc> 
+    <p>Decodes a pem entry. pem_decode/1 returns a list of
+    pem entries.</p> 
+  </desc> 
+  </func>
+
+   <func>
+    <name>pem_entry_encode(Asn1Type, Entity [,{CipherInfo, Password}]) -> pem_entry()</name>
+    <fsummary> Creates a pem entry that can be feed to pem_encode/1.</fsummary>
+    <type>
+      <v>Asn1Type = atom()</v>
+      <v>Entity = term()</v>
+      <v>CipherInfo = {"DES-CBC" | "DES-EDE3-CBC",  crypto:rand_bytes(8)}</v>
+      <v>Password = string()</v> 
+  </type> 
+  <desc> 
+    <p> Creates a pem entry that can be feed to pem_encode/1.</p> 
+  </desc> 
+  </func>
+
+  <func>
+    <name>encrypt_private(PlainText, Key) -> binary()</name>
+    <fsummary> Public key encryption using the private key.</fsummary>
+    <type>
+      <v>PlainText = binary()</v>
+      <v>Key = rsa_private_key()</v> 
+  </type> 
+  <desc> 
+    <p> Public key encryption using the private key.</p> 
+  </desc> 
+  </func>   
+
+  <func>
+    <name>encrypt_public(PlainText, Key) -> binary()</name>
+    <fsummary> Public key encryption using the public key.</fsummary>
+    <type>
+      <v>PlainText = binary()</v>
+      <v>Key = rsa_public_key()</v> 
+  </type> 
+  <desc> 
+    <p> Public key encryption using the public key.</p> 
+  </desc> 
+  </func>   
   
-<!--     <func> -->
-<!--       <name> pkix_encode_cert(Cert) -> {ok, EncodedCert} | {error, Reason}</name> -->
-<!--       <fsummary>Encodes a certificate record using asn1. </fsummary> -->
-<!--       <type> -->
-<!-- 	<v>Cert = x509_certificate() </v> -->
-<!-- 	<v>EncodedCert = asn1_der_encoded() </v> -->
-<!-- 	<v>Reason = term() </v> -->
-<!--       </type> -->
-<!--       <desc> -->
-<!-- 	<p> Encodes a certificate record using asn1.</p> -->
-<!--       </desc> -->
-<!--     </func> -->
+  <func>
+    <name> pkix_decode_cert(Cert, otp|plain) ->  #'Certificate'{} | #'OTPCertificate'{}</name>
+    <fsummary> Decodes an asn1 der encoded pkix x509 certificate.</fsummary>
+    <type>
+      <v>Cert = der_encoded()</v> 
+  </type> 
+  <desc> 
+    <p>Decodes an asn1 der encoded pkix certificate.  The otp option
+    will use the customized asn1 specification OTP-PKIX.asn1 for
+    decoding and also recursively decode most of the standard
+    parts.</p>
+  </desc> 
+  </func>
 
-<!--     <func> -->
-<!--       <name>pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, Result} | {error, Reason}</name> -->
-      
-<!--       <fsummary>Performs a basic path validation according to RFC 3280</fsummary> -->
-<!--       <type> -->
-<!-- 	<v>TrustedCert = asn1_der_encoded()</v> -->
-<!-- 	<v>CertChain = [asn1_der_encoded()]</v> -->
-<!-- 	<v>Options = [{Option, Value}]</v>	 -->
-<!--       <v>Result = {{algorithm(), public_key(), -->
-<!--       public_key_params()}, policy_tree()}</v> -->
-<!--       </type> -->
+  <func>
+    <name>pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded()</name>
+    <fsummary>Der encodes a pkix x509 certificate or part of such a
+    certificate.</fsummary>
+    <type>
+      <v>Asn1Type = atom()</v>
+      <d>The asn1 type can be 'Certificate', 'OTPCertificate' or a subtype of either .</d>
+  </type> 
+  <desc> 
+    <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 on the otp format, whereas for the plain format this
+    function will directly call der_encode/2. </p> 
+  </desc> 
+  </func>
+
+ <func>
+    <name>pkix_is_issuer(Cert, IssuerCert) -> boolean()</name>
+    <fsummary> Checks if <c>IssuerCert</c> issued <c>Cert</c> </fsummary>
+    <type>
+      <v>Cert = der_encode() | #'OTPCertificate'{}</v> 
+      <v>IssuerCert = der_encode() | #'OTPCertificate'{}</v> 
+  </type> 
+  <desc> 
+    <p> Checks if <c>IssuerCert</c> issued <c>Cert</c> </p> 
+  </desc> 
+  </func>
+  
+  <func>
+    <name>pkix_is_fixed_dh_cert(Cert) -> boolean()</name>
+    <fsummary> Checks if a Certificate is a fixed Diffie-Hellman Cert.</fsummary>
+    <type>
+        <v>Cert = der_encode() | #'OTPCertificate'{}</v> 
+  </type> 
+  <desc> 
+    <p> Checks if a Certificate is a fixed Diffie-Hellman Cert.</p> 
+  </desc> 
+  </func>  
+  
+  <func>
+    <name>pkix_is_self_signed(Cert) -> boolean()</name>
+    <fsummary> Checks if a Certificate is self signed.</fsummary>
+    <type>
+       <v>Cert = der_encode() | #'OTPCertificate'{}</v> 
+  </type> 
+  <desc> 
+    <p> Checks if a Certificate is self signed.</p> 
+  </desc> 
+  </func>
+
+  <func>
+    <name>pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason}</name>
+    <fsummary> Returns the issuer id.</fsummary>
+    <type>
+        <v>Cert = der_encode() | #'OTPCertificate'{}</v>
+	<v>IssuedBy = self | other</v>
+	<v>IssuerID = {integer(), {rdnSequence, [#'AttributeTypeAndValue'{}]}}</v>
+	<d>The issuer id consists of the serial number and the issuers name.</d>
+	<v>Reason = term()</v>
+  </type> 
+  <desc> 
+    <p> Returns the issuer id.</p> 
+  </desc> 
+  </func>
 
-<!--       <desc>  -->
-<!-- 	 <p>Available options are: </p> -->
-<!--       <taglist> -->
-<!-- 	    <tag>{validate_extension_fun, fun()}</tag> -->
-<!-- 	    <item> A fun behaving according to the following outline: -->
-<!-- 	    <code> -->
-<!-- [...] -->
-<!-- ValidateExtensionFun = fun(Extensions, UserState) -> -->
-<!--                            validate_extensions(Extensions, UserState, []) -->
-<!--                        end, -->
-<!-- [...] -->
+  <func>
+    <name>pkix_normalize_name(Issuer) -> Normalized</name>
+    <fsummary>Normalizes a issuer name so that it can be easily
+    compared to another issuer name. </fsummary>
+    <type>
+      <v>Issuer = {rdnSequence,[#'AttributeTypeAndValue'{}]}</v>
+      <v>Normalized = {rdnSequence, [#'AttributeTypeAndValue'{}]}</v>
+  </type> 
+  <desc> 
+    <p>Normalizes a issuer name so that it can be easily
+    compared to another issuer name.</p> 
+  </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> -->
 
-<!-- validate_extensions([], UserState, UnknowExtension) -> -->
-<!--     {UserState, UnknowExtension}; -->
-<!-- validate_extensions([#'Extension'{} = Ext | Rest], UserState, UnknowExtension) -> -->
-<!--     case valid_extension(Ext) of -->
-<!-- 	{true, NewUserState} ->  -->
-<!-- 	    validate_extensions(Rest, NewUserState, UnknowExtension); -->
-<!-- 	unknown -> -->
-<!-- 	    validate_extensions(Rest, UserState, [Ext | UnknowExtension]); -->
-<!-- 	{false, Reason} -> -->
-<!-- 	    throw(bad_cert, Reason) -->
-<!--     end.				    -->
-<!-- 	    </code> -->
-	    
-<!-- 	    </item> -->
-	    
-<!-- 	    <tag>{policy_set, [oid()]}</tag> -->
-<!-- 	    <item>A set of certificate policy -->
-<!-- 	    identifiers naming the policies that are acceptable to the -->
-<!-- 	    certificate user. If the user is not concerned about -->
-<!-- 	    certificate policy there is no need -->
-<!-- 	    to set this option. Defaults to the -->
-<!-- 	    special value [?anyPolicy]. -->
-<!-- 	    </item> -->
-	    
-<!-- 	    <tag>{policy_mapping, boolean()}</tag> -->
-<!-- 	    <item>Indicates if policy -->
-<!-- 	    mapping, initially, is allowed in the certification path. -->
-<!-- 	    Defaults to false. -->
-<!-- 	    </item> -->
-	    
-<!-- 	    <tag> {explicit_policy, boolean()}</tag> -->
-<!-- 	    <item>Indicates if the path, initially, must be -->
-<!-- 	    valid for at least one of the certificate policies in the user -->
-<!-- 	    specified policy set. -->
-<!-- 	    Defaults to false. -->
-<!-- 	    </item>  -->
+  
+  <func>
+    <name>pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encode()</name>
+    <fsummary>Signs certificate.</fsummary>
+    <type>
+      <v>Key = rsa_public_key() | dsa_public_key()</v> 
+    </type> 
+    <desc> 
+      <p>Signs a 'OTPTBSCertificate'. Returns the corresponding
+      der encoded certificate.</p> 
+    </desc> 
+  </func> 
 
-<!-- 	    <tag>{inhibit_any_policy, boolean()}</tag> -->
-<!-- 	    <item>Indicates whether the anyPolicy OID, initially, should -->
-<!-- 	    be processed if it is included in a certificate. -->
-<!-- 	    Defaults to false. -->
-<!-- 	    </item> -->
-	    
-<!-- 	  </taglist> -->
- 
-<!-- 	<p>Performs a basic path validation according to RFC 3280, -->
-<!-- 	e.i. signature validation, time validation, issuer validation, -->
-<!-- 	alternative subject name validation, CRL validation, policy -->
-<!-- 	validation and checks that no unknown extensions -->
-<!-- 	are marked as critical. The option <c>validate_extension_fun</c> -->
-<!-- 	may be used to validate application specific extensions. If -->
-<!-- 	a validation criteria is found to be invalid the validation process -->
-<!-- 	will immediately be stopped and this functions will return -->
-<!-- 	{error, Reason}. -->
-<!-- 	</p> -->
-<!--       </desc> -->
-<!--     </func> -->
+  <func>  
+    <name>pkix_verify(Cert, Key) -> boolean()</name>
+    <fsummary> Verify pkix x.509 certificate signature.</fsummary>
+    <type>
+      <v>Cert = der_encode()</v> 
+      <v>Key = rsa_public_key() | dsa_public_key()</v> 
+    </type> 
+  <desc> 
+    <p> Verify pkix x.509 certificate signature.</p> 
+  </desc> 
+  </func> 
 
-<!--     <func> -->
-<!--       <name>sign(DigestOrTBSCert, Key) -> </name> -->
-<!--       <name>sign(DigestOrTBSCert, Key, KeyParams) -> {ok, SignatureOrDerCert} | {error, Reason}</name> -->
-<!--       <fsummary>Signs Digest/Certificate using Key.</fsummary> -->
-<!--       <type> -->
-<!-- 	<v>DigestOrTBSCert = binary() | x509_tbs_certificate()</v> -->
-<!-- 	<v>Key = private_key()</v> -->
-<!-- 	<v>SignatureORDerCert = binary() | der_bin() </v> -->
-<!-- 	<v>Reason = term() </v> -->
-<!--       </type> -->
-<!--       <desc> -->
-<!-- 	<p> Signs Digest/Certificate using Key, in the later -->
-<!-- 	case a der encoded x509_certificate() will be returned. </p> -->
-<!--       </desc> -->
-<!--     </func> -->
+  <func>
+    <name>sign(Msg, DigestType, Key) -> binary()</name>
+    <fsummary> Create digital signature.</fsummary>
+    <type>
+       <v>Msg = binary()</v>
+       <d>The msg is either the binary "plain text" data to be
+       signed or in the case that digest type is <c>none</c>
+       it is the hashed value of "plain text" i.e. the digest.</d>
+       <v>DigestType = rsa_digest_type() | dsa_digest_type()</v>
+       <v>Key = rsa_public_key() | dsa_public_key()</v> 
+  </type> 
+  <desc> 
+    <p> Creates a digital signature.</p> 
+  </desc> 
+  </func>   
 
-<!--     <func> -->
-<!--      <name>verify_signature(Digest, Signature, Key) -> </name> -->
-<!--      <name>verify_signature(DerCert, Key, KeyParams) -> </name> -->
-<!--      <name>verify_signature(Digest, Signature, Key, Params) -> Verified </name> -->
-<!--       <fsummary> Verifies the signature. </fsummary> -->
-<!--       <type> -->
-<!-- 	<v>Digest = binary() </v> -->
-<!-- 	<v>DerCert = der_bin() </v> -->
-<!-- 	<v>Signature = binary() </v> -->
-<!-- 	<v>Key = public_key() </v> -->
-<!-- 	<v>Params = key_params()</v> -->
-<!-- 	<v>Verified = boolean()</v> -->
-<!--       </type> -->
-<!--       <desc> -->
-<!-- 	<p> Verifies the signature Signature. If the key is an rsa-key no -->
-<!-- 	paramters are neeed.</p> -->
-<!--       </desc> -->
-<!--     </func> -->
+  <func>
+    <name>verify(Msg, DigestType, Signature, Key) -> boolean()</name>
+    <fsummary>Verifies a digital signature.</fsummary>
+    <type>
+      <v>Msg = binary()</v>
+       <d>The msg is either the binary "plain text" data 
+        or in the case that digest type is <c>none</c>
+	it is the hashed value of "plain text" i.e. the digest.</d>
+      <v>DigestType = rsa_digest_type() | dsa_digest_type()</v>
+      <v>Signature = binary()</v>
+      <v>Key = rsa_public_key() | dsa_public_key()</v> 
+  </type> 
+  <desc> 
+    <p>Verifies a digital signature</p> 
+  </desc> 
+  </func>
+  
 </funcs>
 
 </erlref>