The R13B03 release.OTP_R13B03

1 files changed, 317 insertions, 0 deletions

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
new file mode 100644
index 0000000000..dc9a96906f
--- /dev/null
+++ b/lib/public_key/doc/src/public_key.xml
@@ -0,0 +1,317 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2008</year>
+      <year>2008</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>public_key</title>
+    <prepared>Ingela Anderton Andin</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>public_key</module>
+  <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.
+    </p>
+  </description>
+
+  <section>
+    <title>COMMON DATA TYPES </title> 
+    
+    <note><p>All records used in this manual 
+    <!--     except #policy_tree_node{}  -->
+    are generated from asn1 specifications
+    and are documented in the User's Guide. See <seealso 
+    marker="public_key_records">Public key records</seealso> and <seealso 
+    marker="cert_records">X.509 Certificate records</seealso>. 
+    </p></note>
+    
+    <p>Use the following include directive to get access to the 
+    records and constant macros described here and in the User's Guide.</p>
+    
+    <code> -include_lib("public_key/include/public_key.hrl"). </code>
+
+    <p><em>Data Types </em></p> 
+    
+    <p><c>boolean() = true | false</c></p> 
+
+    <p><c>string = [bytes()]</c></p> 
+     
+    <p><c>asn1_der_encoded() = binary() | [bytes()]</c></p> 
+
+    <p><c>der_bin() = 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>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>rsa_private_key() = #'RSAPrivateKey'{} </c></p> 
+    
+    <p><c>dsa_private_key() = #'DSAPrivateKey'{}</c></p>
+
+    <p><c>x509_certificate() = "#Certificate{}"</c></p>
+
+    <p><c>x509_tbs_certificate() = #'TBSCertificate'{} </c></p> 
+
+<!--     <p><c>policy_tree() = [Root, Children]</c></p> -->
+    
+<!--     <p><c>Root = #policy_tree_node{}</c></p>    -->
+
+<!--     <p><c>Children = [] | policy_tree()</c></p> -->
+	
+<!--     <p> The policy_tree_node record has the following fields:</p> -->
+    
+<!--     <taglist> -->
+      
+<!--       <tag>valid_policy</tag> -->
+<!--       <item> Is a single policy OID representing a -->
+<!--          valid policy for the path of length x.</item> -->
+      
+<!--       <tag>qualifier_set</tag> -->
+<!--       <item>A set of policy qualifiers associated -->
+<!--          with the valid policy in certificate x.</item> -->
+      
+<!--       <tag>critically_indicator</tag> -->
+<!--       <item>The critically_indicator indicates whether the -->
+<!--          certificate policy extension in certificate x was marked as -->
+<!--          critical. </item> -->
+      
+<!--       <tag>expected_policy_set</tag> -->
+<!--       <item>The expected_policy_set contains one or more policy OIDs -->
+<!--          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> 
+     
+  <func>
+    <name>pem_to_der(File) -> {ok, [Entry]}</name>
+    <fsummary>Reads a PEM file and translates it into its asn1 der
+    encoded parts.</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>
+  </type> 
+  <desc> 
+    <p>Reads a PEM file and translates it into its asn1 der 
+    encoded parts.</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> 
+    </type> 
+    <desc>
+      <p> Decodes an asn1 encoded pkix certificate.</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_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> -->
+
+<!--       <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, -->
+<!-- [...] -->
+
+<!-- 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>  -->
+
+<!-- 	    <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>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>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> -->
+</funcs>
+
+</erlref>