Merge branch 'maint'

* maint:
  ssh: Use exported crypto types
  public_key: Generate refman from types and specs
  public_key: Rework -type and -spec Check existing specs with code and documentation and adjust. Prepare for doc generation
  public_key: Setup for doc generation
  public_key: Remove special type signature for one test
  crypto: Add missing documentation for enable_fips_mode/1
  crypto: Generate refman from types and specs and fix links in engine chapter for generated crypto module refman
  crypto: Rework -type and -spec Check code and documentation and write -type/-spec or adjust existing. Prepare for doc generation
  crypto: Setup for doc generation
  crypto: A user's guide chapter on algorithm details Such as keylengths, blocksizes and IV lengths are hard to find otherwise

4 files changed, 252 insertions, 444 deletions

diff --git a/lib/public_key/doc/specs/.gitignore b/lib/public_key/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/public_key/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/public_key/doc/src/Makefile b/lib/public_key/doc/src/Makefile
index 03467e9783..8575b196b7 100644
--- a/lib/public_key/doc/src/Makefile
+++ b/lib/public_key/doc/src/Makefile
@@ -77,12 +77,18 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 
 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
 
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
 XML_FLAGS +=
 DVIPS_FLAGS +=
 
+SPECS_FLAGS = -I../../include -I../../src -I../../..
+
 # ----------------------------------------------------
 # Targets
 # ----------------------------------------------------
@@ -103,6 +109,7 @@ clean clean_docs:
 	rm -f $(MAN3DIR)/*
 	rm -f $(MAN6DIR)/*
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f $(SPECS_FILES)
 	rm -f errs core *~
 
 man: $(MAN3_FILES) $(MAN6_FILES)
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index aaccb5088b..1b588018e4 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -41,7 +41,7 @@
   </description>
 
   <section>
-    <title>DATA TYPES</title> 
+    <title>Common Records and ASN.1 Types</title> 
     
     <note><p>All records used in this Reference Manual 
     <!--     except #policy_tree_node{}  -->
@@ -54,193 +54,132 @@
     records and constant macros described here and in the User's Guide:</p>
     
     <code> -include_lib("public_key/include/public_key.hrl").</code>
+  </section>
+
+  <datatypes>
+    <datatype>
+      <name name="oid"/>
+      <desc>
+	<p>Object identifier, a tuple of integers as generated by the <c>ASN.1</c> compiler.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="der_encoded"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="pki_asn1_type"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="asn1_type"/>
+      <desc>
+	<p>ASN.1 type present in the Public Key applications ASN.1 specifications.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="pem_entry"/>
+      <name name="der_or_encrypted_der"/>
+      <name name="cipher_info"/>
+      <name name="cipher"/>
+      <name name="salt"/>
+      <name name="cipher_info_params"/>
+      <desc>
+	<code>Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"</code>
+	<p><c>Salt</c> could be generated with
+	<seealso marker="crypto:crypto#strong_rand_bytes-1"><c>crypto:strong_rand_bytes(8)</c></seealso>.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="public_key"/>
+      <name name="rsa_public_key"/>
+      <name name="dsa_public_key"/>
+      <name name="ec_public_key"/>
+      <name name="ecpk_parameters"/>
+      <name name="ecpk_parameters_api"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="private_key"/>
+      <name name="rsa_private_key"/>
+      <name name="dsa_private_key"/>
+      <name name="ec_private_key"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="key_params"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="digest_type"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="crl_reason"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="issuer_id"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="issuer_name"/>
+      <desc>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="ssh_file"/>
+      <desc>
+      </desc>
+    </datatype>
+
+
+
+  </datatypes>
 
-    <p>The following data types are used in the functions for <c>public_key</c>:</p>
-
-    <taglist>
-      <tag><c>oid()</c></tag>
-      <item><p>Object identifier, a tuple of integers as generated by the <c>ASN.1</c> compiler.</p></item>
-
-      <tag><c>boolean() =</c></tag>
-      <item><p><c>true | false</c></p></item>
-      
-      <tag><c>string() =</c></tag>
-      <item><p><c>[bytes()]</c></p></item>
-
-      <tag><c>der_encoded() =</c></tag>
-      <item><p><c>binary()</c></p></item>
-
-      <tag><c>pki_asn1_type() =</c></tag>
-      <item>
-	<p><c>'Certificate'</c></p>
-	<p><c>| 'RSAPrivateKey'</c></p>
-	<p><c>| 'RSAPublicKey'</c></p>
-	<p><c>| 'DSAPrivateKey'</c></p>
-	<p><c>| 'DSAPublicKey'</c></p>
-	<p><c>| 'DHParameter'</c></p>
-	<p><c>| 'SubjectPublicKeyInfo'</c></p>
-	<p><c>| 'PrivateKeyInfo'</c></p>
-	<p><c>| 'CertificationRequest'</c></p>
-	<p><c>| 'CertificateList'</c></p>
-	<p><c>| 'ECPrivateKey'</c></p>
-	<p><c>| 'EcpkParameters'</c></p>
-      </item>
-
-      <tag><c>pem_entry () =</c></tag>
-      <item><p><c>{pki_asn1_type(), binary(), %% DER or encrypted DER</c></p>
-      <p><c> not_encrypted | cipher_info()}</c></p></item>
-      
-      <tag><c>cipher_info() = </c></tag>
-      <item><p><c>{"RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC", crypto:strong_rand_bytes(8)</c></p>
-      <p><c>| {#'PBEParameter{}, digest_type()} | #'PBES2-params'{}}</c></p>
-      </item>
-      
-      <tag><marker id="type-public_key"/>
-      <c>public_key() =</c></tag>
-      <item><p><c>rsa_public_key() | dsa_public_key() | ec_public_key()</c></p></item>
-      
-      <tag><marker id="type-private_key"/>
-      <c>private_key() =</c></tag>
-      <item><p><c>rsa_private_key() | dsa_private_key() | ec_private_key()</c></p></item>
-
-      <tag><c>rsa_public_key() =</c></tag>
-      <item><p><c>#'RSAPublicKey'{}</c></p></item>
-
-      <tag><c>rsa_private_key() =</c></tag>
-      <item><p><c>#'RSAPrivateKey'{}</c></p></item>
-
-      <tag><c>dsa_public_key() =</c></tag>
-      <item><p><c>{integer(),  #'Dss-Parms'{}}</c></p></item>
-
-      <tag><c>dsa_private_key() =</c></tag>
-      <item><p><c>#'DSAPrivateKey'{}</c></p></item>
-
-      <tag><c>ec_public_key()</c></tag>
-      <item><p>= <c>{#'ECPoint'{}, #'ECParameters'{} | {namedCurve, oid()}}</c></p></item>
-
-      <tag><c>ec_private_key() =</c></tag>
-      <item><p><c>#'ECPrivateKey'{}</c></p></item>
-
-      <tag><c>key_params() =</c></tag>
-      <item><p> #'DHParameter'{} |  {namedCurve, oid()} |  #'ECParameters'{} 
-      | {rsa, Size::integer(), PubExp::integer()} </p></item>      
-
-      <tag><c>public_crypt_options() =</c></tag>
-      <item><p><c>[{rsa_pad, rsa_padding()}]</c></p></item>
-
-      <tag><c>rsa_padding() =</c></tag>
-      <item>
-	<p><c>'rsa_pkcs1_padding'</c></p>
-	<p><c>| 'rsa_pkcs1_oaep_padding'</c></p>
-	<p><c>| 'rsa_no_padding'</c></p>
-      </item>
-
-      <tag><c>public_sign_options() =</c></tag>
-      <item><p><c>[{rsa_pad, rsa_sign_padding()} | {rsa_pss_saltlen, integer()}]</c></p></item>
-
-      <tag><c>rsa_sign_padding() =</c></tag>
-      <item>
-	<p><c>'rsa_pkcs1_padding'</c></p>
-	<p><c>| 'rsa_pkcs1_pss_padding'</c></p>
-      </item>
-
-      <tag><c>digest_type() = </c></tag>
-      <item><p>Union of <c>rsa_digest_type()</c>, <c>dss_digest_type()</c>, 
-      and <c>ecdsa_digest_type()</c>.</p></item>
-
-      <tag><c>rsa_digest_type() = </c></tag>
-      <item><p><c>'md5' | 'ripemd160' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item>
-
-      <tag><c>dss_digest_type() = </c></tag>
-      <item><p><c>'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p>
-      <p>Note that the actual supported dss_digest_type depends on the underlying crypto library.
-      In OpenSSL version >= 1.0.1 the listed digest are supported, while in 1.0.0 only
-      sha, sha224 and sha256 are supported. In version 0.9.8 only sha is supported.</p>
-      </item>
-
-      <tag><c>ecdsa_digest_type() = </c></tag>
-      <item><p><c>'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item>
-      
-      <tag><c>crl_reason() = </c></tag>
-      <item>
-	<p><c>unspecified</c></p>
-	<p><c>| keyCompromise</c></p>
-	<p><c>| cACompromise</c></p>
-	<p><c>| affiliationChanged</c></p>
-	<p><c>| superseded</c></p>
-	<p><c>| cessationOfOperation</c></p>
-	<p><c>| certificateHold</c></p>
-	<p><c>| privilegeWithdrawn</c></p>
-	<p><c>| aACompromise</c></p>
-      </item>
-
-      <tag><c>issuer_name() =</c></tag>
-      <item><p><c>{rdnSequence,[#'AttributeTypeAndValue'{}]}</c></p>  
-      </item>
-      
-      <tag><c>ssh_file() =</c></tag>
-      <item>
-	<p><c>openssh_public_key</c></p>
-	<p><c>| rfc4716_public_key</c></p>
-	<p><c>| known_hosts</c></p>
-	<p><c>| auth_keys</c></p>
-      </item>
-    </taglist>
-    
-    
-<!--     <p><code>policy_tree() = [Root, Children]</code></p> -->
-    
-<!--     <p><code>Root = #policy_tree_node{}</code></p>    -->
-
-<!--     <p><code>Children = [] | policy_tree()</code></p> -->
-	
-<!--     <p>The <c>policy_tree_node</c> record has the following fields:</p> -->
-    
-<!--     <taglist> -->
-      
-<!--       <tag>valid_policy</tag> -->
-<!--       <item>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>Indicates whether the -->
-<!--          certificate policy extension in certificate x was marked as -->
-<!--          critical.</item> -->
-      
-<!--       <tag>expected_policy_set</tag> -->
-<!--       <item>Contains one or more policy OIDs -->
-<!--          that would satisfy this policy in the certificate x+1.</item>         -->
-<!--     </taglist> -->
-  </section> 
 
 <funcs>    
 
   <func>
-    <name>compute_key(OthersKey, MyKey)-></name>
-    <name>compute_key(OthersKey, MyKey, Params)-></name>
+    <name name="compute_key" arity="2"/>
+    <fsummary>Computes shared secret.</fsummary>
+  <desc>
+    <p>Computes shared secret.</p>
+  </desc>
+  </func>
+
+  <func>
+    <name name="compute_key" arity="3"/>
     <fsummary>Computes shared secret.</fsummary>
-    <type>
-      <v>OthersKey = #'ECPoint'{} | binary(), MyKey = #'ECPrivateKey'{} | binary()</v>
-      <v>Params =  #'DHParameter'{}</v>
-    </type>
   <desc>
     <p>Computes shared secret.</p>
   </desc>
   </func>
 
   <func>
-    <name>decrypt_private(CipherText, Key) -> binary()</name>
-    <name>decrypt_private(CipherText, Key, Options) -> binary()</name>
+    <name name="decrypt_private" arity="2"/>
+    <name name="decrypt_private" arity="3"/>
     <fsummary>Public-key decryption.</fsummary>
-    <type>
-      <v>CipherText = binary()</v>
-      <v>Key = rsa_private_key()</v>
-      <v>Options = public_crypt_options()</v>
-  </type> 
   <desc> 
     <p>Public-key decryption using the private key. See also <seealso
 	marker="crypto:crypto#private_decrypt/4">crypto:private_decrypt/4</seealso></p> 
@@ -248,14 +187,9 @@
   </func>
 
   <func>
-    <name>decrypt_public(CipherText, Key) - > binary()</name>
-    <name>decrypt_public(CipherText, Key, Options) - > binary()</name>
+    <name name="decrypt_public" arity="2"/>
+    <name name="decrypt_public" arity="3"/>
     <fsummary>Public-key decryption.</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. See also <seealso
 	marker="crypto:crypto#public_decrypt/4">crypto:public_decrypt/4</seealso></p> 
@@ -263,47 +197,24 @@
   </func> 
 
   <func>
-    <name>der_decode(Asn1type, Der) -> term()</name>
+    <name name="der_decode" arity="2"/>
     <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
-      ASN.1 specifications.</d>
-      <v>Der = der_encoded()</v>
-    </type> 
-    <desc> 
+    <desc>
       <p>Decodes a public-key ASN.1 DER encoded entity.</p>
     </desc> 
   </func>
-    
+
   <func>
-    <name>der_encode(Asn1Type, Entity) -> der_encoded()</name>
+    <name name="der_encode" arity="2"/>
     <fsummary>Encodes a public-key entity with ASN.1 DER encoding.</fsummary>
-    <type>
-      <v>Asn1Type = atom()</v>
-      <d>ASN.1 type present in the Public Key applications
-	 ASN.1 specifications.</d>
-      <v>Entity = term()</v>
-      <d>Erlang representation of <c>Asn1Type</c></d>
-  </type> 
   <desc> 
     <p>Encodes a public-key entity with ASN.1 DER encoding.</p>
   </desc> 
   </func>
 
   <func>
-    <name>dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) -> {ok, {Size,Group}} | {error,Error}</name>
+    <name name="dh_gex_group" arity="4"/>
     <fsummary>Selects a group for Diffie-Hellman key exchange</fsummary>
-    <type>
-      <v>MinSize = positive_integer()</v>
-      <v>SuggestedSize = positive_integer()</v>
-      <v>MaxSize = positive_integer()</v>
-      <v>Groups = undefined | [{Size,[{G,P}]}]</v>
-      <v>Size = positive_integer()</v>
-      <v>Group = {G,P}</v>
-      <v>G = positive_integer()</v>
-      <v>P = positive_integer()</v>
-    </type>
     <desc>
       <p>Selects a group for Diffie-Hellman key exchange with the key size in the range <c>MinSize...MaxSize</c>
       and as close to <c>SuggestedSize</c> as possible. If <c>Groups == undefined</c> a default set will be
@@ -322,13 +233,10 @@
     </desc>
   </func>
 
-    <func>
-    <name>encrypt_private(PlainText, Key) -> binary()</name>
+  <func>
+    <name name="encrypt_private" arity="2"/>
+    <name name="encrypt_private" arity="3"/>
     <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.
      See also <seealso
@@ -337,12 +245,9 @@
   </func>   
 
   <func>
-    <name>encrypt_public(PlainText, Key) -> binary()</name>
+    <name name="encrypt_public" arity="2"/>
+    <name name="encrypt_public" arity="3"/>
     <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. See also <seealso
 	marker="crypto:crypto#public_encrypt/4">crypto:public_encrypt/4</seealso>.</p> 
@@ -350,11 +255,8 @@
   </func>   
   
   <func>
-    <name>generate_key(Params) -> {Public::binary(), Private::binary()}  | #'ECPrivateKey'{} | #'RSAPrivateKey'{}</name>
+    <name name="generate_key" arity="1"/>
     <fsummary>Generates a new keypair.</fsummary>
-    <type>
-      <v>Params = key_params()</v>
-    </type>
   <desc>
     <p>Generates a new keypair. Note that except for Diffie-Hellman
     the public key is included in the private key structure. See also
@@ -364,38 +266,27 @@
   </func>
 
   <func>
-    <name>pem_decode(PemBin) -> [pem_entry()]</name>
+    <name name="pem_decode" arity="1"/>
     <fsummary>Decodes PEM binary data and returns
     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>Decodes PEM binary data and returns
-    entries as ASN.1 DER encoded entities.</p>
+    <p>Decodes PEM binary data and returns entries as ASN.1 DER encoded entities.</p>
+    <p>Example <c>{ok, PemBin} = file:read_file("cert.pem").</c></p>
   </desc> 
   </func> 
     
-   <func>
-    <name>pem_encode(PemEntries) -> binary()</name>
+  <func>
+    <name name="pem_encode" arity="1"/>
     <fsummary>Creates a PEM binary.</fsummary>
-    <type>
-      <v> PemEntries = [pem_entry()] </v> 
-  </type> 
-  <desc> 
-    <p>Creates a PEM binary.</p> 
-  </desc> 
+    <desc> 
+      <p>Creates a PEM binary.</p> 
+    </desc> 
   </func>
 
-   <func>
-    <name>pem_entry_decode(PemEntry) -> term()</name>
-    <name>pem_entry_decode(PemEntry, Password) -> term()</name>
+  <func>
+    <name name="pem_entry_decode" arity="1"/>
+    <name name="pem_entry_decode" arity="2"/>
     <fsummary>Decodes a PEM entry.</fsummary>
-    <type>
-      <v>PemEntry = pem_entry()</v> 
-      <v>Password = string()</v> 
-  </type> 
   <desc> 
     <p>Decodes a PEM entry. <c>pem_decode/1</c> returns a list of PEM
     entries. Notice that if the PEM entry is of type
@@ -404,51 +295,36 @@
   </desc> 
   </func>
 
-   <func>
-    <name>pem_entry_encode(Asn1Type, Entity) -> pem_entry()</name>
-    <name>pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry()</name>
+  <func>
+    <name name="pem_entry_encode" arity="2"/>
+    <name name="pem_entry_encode" arity="3"/>
     <fsummary>Creates a PEM entry that can be fed to <c>pem_encode/1</c>.</fsummary>
-    <type>
-      <v>Asn1Type = pki_asn1_type()</v>
-      <v>Entity = term()</v>
-      <d>Erlang representation of
-      <c>Asn1Type</c>.  If <c>Asn1Type</c> is 'SubjectPublicKeyInfo',
+    <desc> 
+      <p>Creates a PEM entry that can be feed to <c>pem_encode/1</c>.</p>
+      <p>If <c>Asn1Type</c> is <c>'SubjectPublicKeyInfo'</c>,
       <c>Entity</c> must be either an <c>rsa_public_key()</c>, 
       <c>dsa_public_key()</c> or an <c>ec_public_key()</c>
       and this function creates the appropriate
-      'SubjectPublicKeyInfo' entry.
-      </d>
-      <v>CipherInfo = cipher_info()</v>
-      <v>Password = string()</v> 
-    </type> 
-  <desc> 
-    <p>Creates a PEM entry that can be feed to <c>pem_encode/1</c>.</p>
-  </desc> 
+      <c>'SubjectPublicKeyInfo'</c> entry.
+      </p>
+    </desc> 
   </func>
-  
+
   <func>
-    <name>pkix_decode_cert(Cert, otp|plain) ->  #'Certificate'{} | #'OTPCertificate'{}</name>
+    <name name="pkix_decode_cert" arity="2"/>
     <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. Option <c>otp</c>
-    uses the customized ASN.1 specification OTP-PKIX.asn1 for
-    decoding and also recursively decode most of the standard
-    parts.</p>
-  </desc> 
+    <desc> 
+      <p>Decodes an ASN.1 DER-encoded PKIX certificate. Option <c>otp</c>
+      uses the customized ASN.1 specification OTP-PKIX.asn1 for
+      decoding and also recursively decode most of the standard
+      parts.</p>
+    </desc> 
   </func>
 
   <func>
-    <name>pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded()</name>
+    <name name="pkix_encode" arity="3"/>
     <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
     certificate. This function must be used for encoding certificates or parts of certificates
@@ -458,69 +334,47 @@
   </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_encoded() | #'OTPCertificate'{} | #'CertificateList'{}</v>
-      <v>IssuerCert = der_encoded() | #'OTPCertificate'{}</v>
-  </type> 
-  <desc> 
-    <p>Checks if <c>IssuerCert</c> issued <c>Cert</c>.</p> 
-  </desc> 
-  </func>
+   <name name="pkix_is_issuer" arity="2"/>
+   <fsummary>Checks if <c>IssuerCert</c> issued <c>Cert</c>.</fsummary>
+   <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 certificate.</fsummary>
-    <type>
-        <v>Cert = der_encoded() | #'OTPCertificate'{}</v>
-  </type> 
-  <desc> 
-    <p>Checks if a certificate is a fixed Diffie-Hellman certificate.</p> 
-  </desc> 
-  </func>  
+ <func>
+   <name name="pkix_is_fixed_dh_cert" arity="1"/>
+   <fsummary>Checks if a certificate is a fixed Diffie-Hellman certificate.</fsummary>
+   <desc> 
+     <p>Checks if a certificate is a fixed Diffie-Hellman certificate.</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_encoded() | #'OTPCertificate'{}</v>
-  </type> 
-  <desc> 
-    <p>Checks if a certificate is self-signed.</p> 
-  </desc> 
-  </func>
+ <func>
+   <name name="pkix_is_self_signed" arity="1"/>
+   <fsummary>Checks if a certificate is self-signed.</fsummary>
+   <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_encoded() | #'OTPCertificate'{}</v>
-	<v>IssuedBy = self | other</v>
-	<v>IssuerID = {integer(), issuer_name()}</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>
-  
+ <func>
+   <name name="pkix_issuer_id" arity="2"/>
+   <fsummary>Returns the issuer id.</fsummary>
+   <desc> 
+     <p>Returns the issuer id.</p> 
+   </desc> 
+ </func>
  
-  <func>
-    <name>pkix_normalize_name(Issuer) -> Normalized</name>
-    <fsummary>Normalizes an issuer name so that it can be easily
-    compared to another issuer name.</fsummary>
-    <type>
-      <v>Issuer = issuer_name()</v>
-      <v>Normalized = issuer_name()</v>
-  </type> 
-  <desc> 
-    <p>Normalizes an issuer name so that it can be easily
-    compared to another issuer name.</p> 
-  </desc> 
-  </func>
-   
+ <func>
+   <name name="pkix_normalize_name" arity="1"/>
+   <fsummary>Normalizes an issuer name so that it can be easily
+   compared to another issuer name.</fsummary>
+   <desc> 
+     <p>Normalizes an issuer name so that it can be easily
+     compared to another issuer name.</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>
@@ -622,26 +476,16 @@ fun(OtpCert :: #'OTPCertificate'{},
    </func>
 
     <func>  
-      <name>pkix_crl_issuer(CRL) -> issuer_name()</name>
+      <name name="pkix_crl_issuer" arity="1"/>
       <fsummary>Returns the issuer of the <c>CRL</c>.</fsummary>
-      <type>
-	<v>CRL = der_encoded() | #'CertificateList'{} </v> 
-      </type> 
       <desc> 
 	<p>Returns the issuer of the <c>CRL</c>.</p>
       </desc> 
     </func> 
    
    <func>
-     <name>pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus()</name>
+     <name name="pkix_crls_validate" arity="3"/>
      <fsummary>Performs CRL validation.</fsummary>
-     <type>
-       <v>OTPCertificate =  #'OTPCertificate'{}</v>
-       <v>DPAndCRLs  = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] </v>
-       <v>Options = proplists:proplist()</v>
-       <v>CRLStatus() =  valid | {bad_cert, revocation_status_undetermined} |  {bad_cert, {revocation_status_undetermined,
-       {bad_crls, Details::term()}}} | {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="#pkix_path_validation-3"> pkix_path_validation/3
@@ -692,24 +536,16 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
    </func>
    
    <func>  
-     <name>pkix_crl_verify(CRL, Cert) -> boolean()</name>
+     <name name="pkix_crl_verify" arity="2"/>
      <fsummary> Verify that  <c>Cert</c>  is the <c> CRL</c>  signer. </fsummary>
-     <type>
-       <v>CRL = der_encoded() | #'CertificateList'{} </v> 
-       <v>Cert = der_encoded() | #'OTPCertificate'{} </v> 
-     </type> 
      <desc> 
        <p>Verify that <c>Cert</c> is the <c>CRL</c> signer.</p>
      </desc> 
    </func>
 
    <func>  
-     <name>pkix_dist_point(Cert) -> DistPoint</name>
+     <name name="pkix_dist_point" arity="1"/>
      <fsummary>Creates a distribution point for CRLs issued by the same issuer as <c>Cert</c>.</fsummary>
-     <type>
-       <v> Cert  = der_encoded() | #'OTPCertificate'{} </v> 
-       <v> DistPoint =  #'DistributionPoint'{}</v> 
-     </type> 
      <desc> 
        <p>Creates a distribution point for CRLs issued by the same issuer as <c>Cert</c>.
        Can be used as input to <seealso
@@ -719,26 +555,17 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
    </func>
    
    <func>  
-     <name>pkix_dist_points(Cert) -> DistPoints</name>
+     <name name="pkix_dist_points" arity="1"/>
      <fsummary> Extracts distribution points from the certificates extensions.</fsummary>
-     <type>
-       <v> Cert  = der_encoded() | #'OTPCertificate'{} </v> 
-       <v> DistPoints =  [#'DistributionPoint'{}]</v> 
-     </type> 
      <desc> 
        <p> Extracts distribution points from the certificates extensions.</p>
      </desc> 
  </func>
    
   <func>
-    <name>pkix_match_dist_point(CRL, DistPoint) -> boolean()</name>
+    <name name="pkix_match_dist_point" arity="2"/>
     <fsummary>Checks whether the given distribution point matches the
     Issuing Distribution Point of the CRL.</fsummary>
-
-    <type>
-      <v>CRL = der_encoded() | #'CertificateList'{} </v>
-      <v>DistPoint = #'DistributionPoint'{}</v>
-    </type>
     <desc>
       <p>Checks whether the given distribution point matches the
       Issuing Distribution Point of the CRL, as described in RFC 5280.
@@ -748,11 +575,8 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
   </func>
 
   <func>
-    <name>pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encoded()</name>
+    <name name="pkix_sign" arity="2"/>
     <fsummary>Signs certificate.</fsummary>
-    <type>
-      <v>Key = rsa_private_key() | dsa_private_key()</v> 
-    </type> 
     <desc> 
       <p>Signs an 'OTPTBSCertificate'. Returns the corresponding
       DER-encoded certificate.</p> 
@@ -760,17 +584,12 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
   </func> 
 
   <func>
-    <name>pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}</name>
+    <name name="pkix_sign_types" arity="1"/>
     <fsummary>Translates signature algorithm OID to Erlang digest and signature algorithm types.</fsummary>
-    <type>
-      <v>AlgorithmId = oid()</v>
-      <d>Signature OID from a certificate or a certificate revocation list.</d>
-      <v>DigestType = rsa_digest_type() | dss_digest_type()</v>
-      <v>SignatureType = rsa | dsa | ecdsa</v>
-    </type>
     <desc>
       <p>Translates signature algorithm OID to Erlang digest and signature types.
       </p>
+      <p>The <c>AlgorithmId</c> is the signature OID from a certificate or a certificate revocation list.</p>
     </desc>
   </func>
 
@@ -938,12 +757,8 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
   </func>
 
   <func>  
-    <name>pkix_verify(Cert, Key) -> boolean()</name>
+    <name name="pkix_verify" arity="2"/>
     <fsummary>Verifies PKIX x.509 certificate signature.</fsummary>
-    <type>
-      <v>Cert = der_encoded()</v>
-      <v>Key = rsa_public_key() | dsa_public_key() | ec_public_key()</v> 
-    </type> 
   <desc> 
     <p>Verifies PKIX x.509 certificate signature.</p>
   </desc> 
@@ -1059,41 +874,30 @@ end
   
 
   <func>
-    <name>sign(Msg, DigestType, Key) -> binary()</name>
-    <name>sign(Msg, DigestType, Key, Options) -> binary()</name>
+    <name name="sign" arity="3"/>
+    <name name="sign" arity="4"/>
     <fsummary>Creates a digital signature.</fsummary>
-    <type>
-       <v>Msg = binary() | {digest,binary()}</v>
-       <d>The <c>Msg</c> is either the binary "plain text" data to be
-       signed or it is the hashed value of "plain text", that is, the
-       digest.</d>
-       <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
-       <v>Key = rsa_private_key() | dsa_private_key() | ec_private_key()</v>
-       <v>Options = public_sign_options()</v>
-  </type>
   <desc>
     <p>Creates a digital signature.</p> 
+    <p>The <c>Msg</c> is either the binary "plain text" data to be
+    signed or it is the hashed value of "plain text", that is, the
+    digest.</p>
   </desc> 
   </func>   
 
   <func>
-    <name>ssh_decode(SshBin,  Type) -> [{public_key(), Attributes::list()}]</name>
+    <name name="ssh_decode" arity="2"/>
     <fsummary>Decodes an SSH file-binary.</fsummary>
-    <type>
-      <v>SshBin = binary()</v>
-      <d>Example <c>{ok, SshBin} = file:read_file("known_hosts")</c>.</d>
-      <v>Type = public_key | ssh_file()</v>
-      <d>If <c>Type</c> is <c>public_key</c> the binary can be either
-      an RFC4716 public key or an OpenSSH public key.</d>
-    </type>
-  <desc>
-    <p>Decodes an SSH file-binary. In the case of <c>known_hosts</c> or
-    <c>auth_keys</c>, the binary can include one or more lines of the
-    file. Returns a list of public keys and their attributes, possible
-    attribute values depends on the file type represented by the
-    binary.
-    </p>
-
+    <desc>
+      <p>Decodes an SSH file-binary. In the case of <c>known_hosts</c> or
+      <c>auth_keys</c>, the binary can include one or more lines of the
+      file. Returns a list of public keys and their attributes, possible
+      attribute values depends on the file type represented by the
+      binary.
+      </p>
+      <p>If the <c>Type</c> is <c>ssh2_pubkey</c>, the result will be
+      <c>Decoded_ssh2_pubkey</c>. Otherwise it will be <c>Decoded_OtherType</c>.
+      </p>
     <taglist>
       <tag>RFC4716 attributes - see RFC 4716.</tag>
       <item><p>{headers, [{string(), utf8_string()}]}</p></item>
@@ -1106,23 +910,25 @@ end
       <item>{comment, string()}</item>
       <item><p>{bits, integer()} - In SSH version 1 files.</p></item>
     </taglist>
-
+      <p>Example: <c>{ok, SshBin} = file:read_file("known_hosts")</c>.
+      </p>
+      <p>If <c>Type</c> is <c>public_key</c> the binary can be either
+      an RFC4716 public key or an OpenSSH public key.</p>
   </desc>
   </func>
 
   <func>
-    <name>ssh_encode([{Key, Attributes}], Type) -> binary()</name>
+    <name name="ssh_encode" arity="2"/>
     <fsummary>Encodes a list of SSH file entries to a binary.</fsummary>
-    <type>
-      <v>Key = public_key()</v>
-      <v>Attributes = list()</v>
-      <v>Type = ssh_file()</v>
-    </type>
-  <desc>
-    <p>Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible
-    attributes depend on the file type, see <seealso
-    marker="#ssh_decode-2"> ssh_decode/2 </seealso>.</p>
-  </desc>
+    <desc>
+      <p>Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible
+      attributes depend on the file type, see
+      <seealso marker="#ssh_decode-2"> ssh_decode/2 </seealso>.
+      </p>
+      <p>If the <c>Type</c> is <c>ssh2_pubkey</c>, the <c>InData</c> shall be
+      <c>InData_ssh2_pubkey</c>. Otherwise it shall be <c>OtherInData</c>.
+      </p>
+    </desc>
   </func>
 
   <func>
@@ -1131,8 +937,8 @@ end
     <name>ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]</name>
     <fsummary>Calculates a ssh fingerprint for a hostkey.</fsummary>
     <type>
-      <v>Key = public_key()</v>
-      <v>DigestType = digest_type()</v>
+      <v>HostKey = <seealso marker="#type-public_key">public_key()</seealso></v>
+      <v>DigestType = <seealso marker="#type-digest_type">digest_type()</seealso></v>
     </type>
   <desc>
     <p>Calculates a ssh fingerprint from a public host key as openssh does.</p>
@@ -1161,29 +967,19 @@ end
   </func>
 
   <func>
-    <name>verify(Msg, DigestType, Signature, Key) -> boolean()</name>
-    <name>verify(Msg, DigestType, Signature, Key, Options) -> boolean()</name>
+    <name name="verify" arity="4"/>
+    <name name="verify" arity="5"/>
     <fsummary>Verifies a digital signature.</fsummary>
-    <type>
-      <v>Msg = binary() | {digest,binary()}</v>
-       <d>The <c>Msg</c> is either the binary "plain text" data 
-        or it is the hashed value of "plain text", that is, the digest.</d>
-      <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
-      <v>Signature = binary()</v>
-      <v>Key = rsa_public_key() | dsa_public_key() | ec_public_key()</v>
-      <v>Options = public_sign_options()</v>
-  </type>
   <desc>
     <p>Verifies a digital signature.</p>
+    <p>The <c>Msg</c> is either the binary "plain text" data 
+    or it is the hashed value of "plain text", that is, the digest.</p>
   </desc> 
   </func>
 
   <func>
-    <name>short_name_hash(Name) -> string()</name>
+    <name name="short_name_hash" arity="1"/>
     <fsummary>Generates a short hash of an issuer name.</fsummary>
-    <type>
-      <v>Name = issuer_name()</v>
-    </type>
     <desc>
       <p>Generates a short hash of an issuer name.  The hash is
       returned as a string containing eight hexadecimal digits.</p>
diff --git a/lib/public_key/doc/src/specs.xml b/lib/public_key/doc/src/specs.xml
new file mode 100644
index 0000000000..e358ea1154
--- /dev/null
+++ b/lib/public_key/doc/src/specs.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="../specs/specs_public_key.xml"/>
+</specs>