public_key: Enhance documentation

6 files changed, 71 insertions, 49 deletions

diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml
index 6d3d4b3107..f01f7dbaf5 100644
--- a/lib/public_key/doc/src/cert_records.xml
+++ b/lib/public_key/doc/src/cert_records.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>
@@ -34,12 +34,11 @@
     <file>cert_records.xml</file>
   </header>
 
-  <p>This chapter briefly describes erlang records derived from asn1
-  specifications used to handle X509 certificates. The intent is to
-  describe the data types and not to specify the meaning of each
+  <p>This chapter briefly describes erlang records derived from ASN1
+  specifications used to handle <c> X509 certificates</c> and <c>CertificationRequest</c>.
+  The intent is to describe the data types and not to specify the meaning of each
   component for this we refer you to <url
-  href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</url>. Also
-  descirbed is <p>CertificationRequest</p> that is defined by 
+  href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</url> and
   <url href="http://www.rsa.com/rsalabs/node.asp?id=2124">PKCS-10</url>.
   </p>
 
@@ -48,7 +47,7 @@
   
   <code> -include_lib("public_key/include/public_key.hrl"). </code>
 
-  <p>The used asn1 specifications are available <c>asn1</c> subdirectory
+  <p>The used ASN1 specifications are available <c>asn1</c> subdirectory
     of the application <c>public_key</c>.
   </p>
 
@@ -62,7 +61,7 @@
     follows here.</p>
 
     <p><c>oid() - a tuple of integers 
-    as generated by the asn1 compiler.</c></p>
+    as generated by the ASN1 compiler.</c></p>
 
     <p><c>time() = uct_time() | general_time()</c></p>
     
@@ -101,7 +100,7 @@
 #'Certificate'{
 		tbsCertificate,        % #'TBSCertificate'{}
 		signatureAlgorithm,    % #'AlgorithmIdentifier'{} 
-		signature              % {0, binary()} - asn1 compact bitstring
+		signature              % {0, binary()} - ASN1 compact bitstring
 	       }.
 
 #'TBSCertificate'{
@@ -127,7 +126,7 @@
 #'OTPCertificate'{
 		tbsCertificate,        % #'OTPTBSCertificate'{}
 		signatureAlgorithm,    % #'SignatureAlgorithm'
-		signature              % {0, binary()} - asn1 compact bitstring
+		signature              % {0, binary()} - ASN1 compact bitstring
 	       }.
 
 #'OTPTBSCertificate'{
@@ -531,7 +530,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'CertificateList'{
           tbsCertList,        % #'TBSCertList{}
           signatureAlgorithm, % #'AlgorithmIdentifier'{} 
-          signature           % {0, binary()} - asn1 compact bitstring
+          signature           % {0, binary()} - ASN1 compact bitstring
 	  }).
 
 #'TBSCertList'{
@@ -643,7 +642,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 #'CertificationRequest'{
           certificationRequestInfo #'CertificationRequestInfo'{},
 	  signatureAlgorithm	   #'CertificationRequest_signatureAlgorithm'{}}.
-	  signature                {0, binary()} - asn1 compact bitstring
+	  signature                {0, binary()} - ASN1 compact bitstring
 	  }
 
 #'CertificationRequestInfo'{
@@ -655,7 +654,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'</p>
 
 #'CertificationRequestInfo_subjectPKInfo'{
           algorithm		#'CertificationRequestInfo_subjectPKInfo_algorithm'{}
-	  subjectPublicKey 	 {0, binary()} - asn1 compact bitstring
+	  subjectPublicKey 	 {0, binary()} - ASN1 compact bitstring
 	  }
 
 #'CertificationRequestInfo_subjectPKInfo_algorithm'{
diff --git a/lib/public_key/doc/src/introduction.xml b/lib/public_key/doc/src/introduction.xml
index e0dd5603f7..4b59cc2245 100644
--- a/lib/public_key/doc/src/introduction.xml
+++ b/lib/public_key/doc/src/introduction.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>
@@ -36,11 +36,13 @@
 
   <section>
     <title>Purpose</title>
-    <p> This application provides an API to public key infrastructure
-    from <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC
-    5280</url> (X.509 certificates) and public key formats defined by
-    the <url href="http://www.rsa.com/rsalabs/node.asp?id=2124">
-    PKCS-standard</url></p>
+    <p> public_key deals with public key related file formats, digital
+    signatures and <url href="http://www.ietf.org/rfc/rfc5280.txt">
+    X-509 certificates</url>. It is a library application that
+    provides encode/decode, sign/verify, encrypt/decrypt and similar
+    functionality, it does not read or write files it expects or returns
+    file contents or partial file contents as binaries.
+    </p>
   </section>
 
   <section>
@@ -51,9 +53,9 @@
 
   <section>
     <title>Performance tips</title>
-    <p>The public_key decode and encode functions will try to use the nifs
-    which are in the asn1 compilers runtime modules if they can be found.
-    So for the best  performance you want to have the asn1 application in the
+    <p>The public_key decode and encode functions will try to use the NIFs
+    which are in the ASN1 compilers runtime modules if they can be found.
+    So for the best  performance you want to have the ASN1 application in the
     path of your system. </p>
   </section>
 
diff --git a/lib/public_key/doc/src/part.xml b/lib/public_key/doc/src/part.xml
index ea3123b5bd..08fa4eec58 100644
--- a/lib/public_key/doc/src/part.xml
+++ b/lib/public_key/doc/src/part.xml
@@ -5,7 +5,7 @@
   <header>
     <copyright>
       <year>2008</year>
-      <year>2011</year>
+      <year>2013</year>
       <holder>Ericsson AB, All Rights Reserved</holder>
     </copyright>
     <legalnotice>
@@ -32,8 +32,10 @@
   </header>
   <description>
     <p> This application provides an API to public key infrastructure
-    from  RFC 3280 (X.509 certificates) and some public key formats defined
-    by the PKCS-standard. </p>
+    from <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC
+    5280</url> (X.509 certificates) and public key formats defined by
+    the <url href="http://www.rsa.com/rsalabs/node.asp?id=2124">
+    PKCS-standard</url></p>
   </description>
   <xi:include href="introduction.xml"/>
   <xi:include href="public_key_records.xml"/>
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index 93ba45e457..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 
@@ -156,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
@@ -164,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>
     
@@ -186,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> 
     
@@ -217,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> 
@@ -227,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>
@@ -241,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>
 
@@ -271,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>
@@ -285,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> 
@@ -480,7 +499,7 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
       <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> 
 
diff --git a/lib/public_key/doc/src/public_key_records.xml b/lib/public_key/doc/src/public_key_records.xml
index bb90290266..e39ad0ec64 100644
--- a/lib/public_key/doc/src/public_key_records.xml
+++ b/lib/public_key/doc/src/public_key_records.xml
@@ -1,11 +1,11 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE chapter SYSTEM "chapter.dtd">
 
 <chapter>
   <header>
     <copyright>
       <year>2008</year>
-      <year>2011</year>
+      <year>2013</year>
       <holder>Ericsson AB, All Rights Reserved</holder>
     </copyright>
     <legalnotice>
@@ -34,7 +34,7 @@
     <file>public_key_records.xml</file>
   </header>
     
-  <p>This chapter briefly describes Erlang records derived from asn1
+  <p>This chapter briefly describes Erlang records derived from ASN1
   specifications used to handle public and private keys. The intent
   is to describe the data types and not to specify the meaning of
   each component for this we refer you to the relevant standards and RFCs.</p>
@@ -67,9 +67,9 @@
 	 }.
 
 #'OtherPrimeInfo'{
-         prime,           % integer() 
- 	 exponent,        % integer()
-         coefficient      % integer() 
+	prime,           % integer()
+	exponent,        % integer()
+	coefficient      % integer()
  	 }.	 
     </code>
 
diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml
index 1224b57aed..5d9f1536d9 100644
--- a/lib/public_key/doc/src/using_public_key.xml
+++ b/lib/public_key/doc/src/using_public_key.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2011</year><year>2011</year>
+      <year>2011</year><year>2013</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -40,7 +40,7 @@
     
   <section>
     <title>PEM files</title>
-    <p> Pulic key data (keys, certificates etc) may be stored in PEM format. PEM files
+    <p> Public key data (keys, certificates etc) may be stored in PEM format. PEM files
     comes from the Private Enhanced Mail Internet standard and has a
     structure that looks like this:</p>
 
@@ -63,7 +63,7 @@
       <code>1> {ok, PemBin} = file:read_file("dsa.pem").
 {ok,&lt;&lt;"-----BEGIN DSA PRIVATE KEY-----\nMIIBuw"...&gt;&gt;}</code>
       
-      <p>This PEM file only has one entry a private DSA key.</p>
+      <p>This PEM file only has one entry, a private DSA key.</p>
       <code>2> [DSAEntry] =  public_key:pem_decode(PemBin).
 [{'DSAPrivateKey',&lt;&lt;48,130,1,187,2,1,0,2,129,129,0,183,
                     179,230,217,37,99,144,157,21,228,204,