From 90167202a4ce3dc6d4822fad04c51cc35913d796 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Wed, 27 Jun 2012 15:35:26 +0200
Subject: crypto: Redo interface for rsa and dss hash signing

Replace _hash functions with {digest,_} argument
to existing sign/verify functions.
---
 lib/crypto/doc/src/crypto.xml | 66 +++++++++++++++++++++++++------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

(limited to 'lib/crypto/doc')

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 19db6c9dd4..36f8bc6deb 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -865,11 +865,13 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
     </func>
 
     <func>
-      <name>rsa_sign(Data, Key) -> Signature</name>
-      <name>rsa_sign(DigestType, Data, Key) -> Signature</name> 
+      <name>rsa_sign(DataOrDigest, Key) -> Signature</name>
+      <name>rsa_sign(DigestType, DataOrDigest, Key) -> Signature</name>
       <fsummary>Sign the data using rsa with the given key.</fsummary>
       <type>
+        <v>DataOrDigest = Data | {digest,Digest}</v>
         <v>Data = Mpint</v>
+	<v>Digest = binary()</v>
         <v>Key = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]</v>
         <v>E, N, D = Mpint</v>
         <d>Where <c>E</c> is the public exponent, <c>N</c> is public modulus and 
@@ -879,37 +881,40 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
 	   the calculation faster. <c>P1,P2</c> are first and second prime factors.
            <c>E1,E2</c> are first and second exponents. <c>C</c> is the CRT coefficient.
            Terminology is taken from RFC 3447.</d>
-	<v>DigestType = md5 | sha</v>
+	<v>DigestType = md5 | sha | sha256 | sha384 | sha512</v>
 	<d>The default <c>DigestType</c> is sha.</d>
         <v>Mpint = binary()</v>
         <v>Signature = binary()</v>
       </type>
       <desc>
-        <p>Calculates a <c>DigestType</c> digest of the <c>Data</c>
-	  and creates a RSA signature with the private key <c>Key</c>
-	  of the digest.</p>
+        <p>Creates a RSA signature with the private key <c>Key</c>
+	  of a digest. The digest is either calculated as a
+	  <c>DigestType</c> digest of <c>Data</c> or a precalculated
+	  binary <c>Digest</c>.</p>
       </desc>
     </func>
 
     <func>
-      <name>rsa_verify(Data, Signature, Key) -> Verified</name>
-      <name>rsa_verify(DigestType, Data, Signature, Key) -> Verified </name> 
+      <name>rsa_verify(DataOrDigest, Signature, Key) -> Verified</name>
+      <name>rsa_verify(DigestType, DataOrDigest, Signature, Key) -> Verified </name>
       <fsummary>Verify the digest and signature using rsa with given public key.</fsummary>
       <type>
         <v>Verified = boolean()</v>
+	<v>DataOrDigest = Data | {digest|Digest}</v>
         <v>Data, Signature = Mpint</v>
+	<v>Digest = binary()</v>
         <v>Key = [E, N]</v>
         <v>E, N = Mpint</v>
         <d>Where <c>E</c> is the public exponent and <c>N</c> is public modulus.</d>
 	<v>DigestType = md5 | sha | sha256 | sha384 | sha512</v>
-	<d> The default <c>DigestType</c> is sha.</d>
+	<d>The default <c>DigestType</c> is sha.</d>
         <v>Mpint = binary()</v>
       </type>
       <desc>
-        <p>Calculates a <c>DigestType</c> digest of the <c>Data</c>
-          and verifies that the digest matches the RSA signature using the
+	<p>Verifies that a digest matches the RSA signature using the
           signer's public key <c>Key</c>.
-	</p>
+	  The digest is either calculated as a <c>DigestType</c>
+	  digest of <c>Data</c> or a precalculated binary <c>Digest</c>.</p>
 	<p>May throw exception <c>notsup</c> in case the chosen <c>DigestType</c>
 	is not supported by the underlying OpenSSL implementation.</p>
       </desc>
@@ -1022,45 +1027,52 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
     </func>
       
     <func>
-      <name>dss_sign(Data, Key) -> Signature</name>
-      <name>dss_sign(DigestType, Data, Key) -> Signature</name>
+      <name>dss_sign(DataOrDigest, Key) -> Signature</name>
+      <name>dss_sign(DigestType, DataOrDigest, Key) -> Signature</name>
       <fsummary>Sign the data using dsa with given private key.</fsummary>
       <type>
-        <v>DigestType = sha | none (default is sha)</v>
-        <v>Data = Mpint | ShaDigest</v>
+        <v>DigestType = sha</v>
+        <v>DataOrDigest = Mpint | {digest,Digest}</v>
         <v>Key = [P, Q, G, X]</v>
         <v>P, Q, G, X = Mpint</v>
 	<d> Where <c>P</c>, <c>Q</c> and <c>G</c> are the dss
 	  parameters and <c>X</c> is the private key.</d>
-        <v>ShaDigest = binary() with length 20 bytes</v>
+        <v>Digest = binary() with length 20 bytes</v>
         <v>Signature = binary()</v>
       </type>
       <desc>
-        <p>Creates a DSS signature with the private key <c>Key</c> of a digest.
-        If <c>DigestType</c> is 'sha', the digest is calculated as SHA1 of <c>Data</c>.
-        If <c>DigestType</c> is 'none', <c>Data</c> is the precalculated SHA1 digest.</p>
+        <p>Creates a DSS signature with the private key <c>Key</c> of
+	a digest. The digest is either calculated as a SHA1
+	  digest of <c>Data</c> or a precalculated binary <c>Digest</c>.</p>
+	<p>A deprecated feature is having <c>DigestType = 'none'</c>
+	in which case <c>DataOrDigest</c> is a precalculated SHA1
+	digest.</p>
       </desc>
     </func>
 
     <func>
-      <name>dss_verify(Data, Signature, Key) -> Verified</name>
-      <name>dss_verify(DigestType, Data, Signature, Key) -> Verified</name>
+      <name>dss_verify(DataOrDigest, Signature, Key) -> Verified</name>
+      <name>dss_verify(DigestType, DataOrDigest, Signature, Key) -> Verified</name>
       <fsummary>Verify the data and signature using dsa with given public key.</fsummary>
       <type>
         <v>Verified = boolean()</v>
-        <v>DigestType = sha | none</v>
+        <v>DigestType = sha</v>
+	<v>DataOrDigest = Mpint | {digest,Digest}</v>
         <v>Data = Mpint | ShaDigest</v>
         <v>Signature = Mpint</v>
         <v>Key = [P, Q, G, Y]</v>
         <v>P, Q, G, Y = Mpint</v>
 	<d> Where <c>P</c>, <c>Q</c> and <c>G</c> are the dss
 	  parameters and <c>Y</c> is the public key.</d>
-        <v>ShaDigest = binary() with length 20 bytes</v>
+        <v>Digest = binary() with length 20 bytes</v>
       </type>
       <desc>
-        <p>Verifies that a digest matches the DSS signature using the public key <c>Key</c>.
-        If <c>DigestType</c> is 'sha', the digest is calculated as SHA1 of <c>Data</c>.
-        If <c>DigestType</c> is 'none', <c>Data</c> is the precalculated SHA1 digest.</p>
+        <p>Verifies that a digest matches the DSS signature using the
+	public key <c>Key</c>. The digest is either calculated as a SHA1
+	digest of <c>Data</c> or is a precalculated binary <c>Digest</c>.</p>
+	<p>A deprecated feature is having <c>DigestType = 'none'</c>
+	in which case <c>DataOrDigest</c> is a precalculated SHA1
+	digest binary.</p>
       </desc>
     </func>
 
-- 
cgit v1.2.3