From 5010b791378f4af46176f297888c30ad010a3e83 Mon Sep 17 00:00:00 2001
From: Andreas Schultz <aschultz@tpip.net>
Date: Mon, 4 Mar 2013 20:37:14 +0100
Subject: crypto: add AES128-GCM cipher support

---
 lib/crypto/doc/src/crypto.xml | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

(limited to 'lib/crypto/doc')

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 7712173ed8..5f19c5cce3 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -41,7 +41,7 @@
       </item>
       <item>
         <p>Block ciphers - <url href="http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html"> </url> DES and AES in
-        Block Cipher Modes - <url href="http://csrc.nist.gov/groups/ST/toolkit/BCM/index.html"> ECB, CBC, CFB, OFB and CTR </url></p>
+        Block Cipher Modes - <url href="http://csrc.nist.gov/groups/ST/toolkit/BCM/index.html"> ECB, CBC, CFB, OFB, CTR and GCM </url></p>
       </item>
       <item>
         <p><url href="http://www.ietf.org/rfc/rfc1321.txt"> RSA encryption RFC 1321 </url> </p>
@@ -53,6 +53,12 @@
       <item>
         <p><url href="http://www.ietf.org/rfc/rfc2945.txt"> Secure Remote Password Protocol (SRP - RFC 2945) </url></p>
       </item>
+      <item>
+        <p>gcm: Dworkin, M., "Recommendation for Block Cipher Modes of
+        Operation: Galois/Counter Mode (GCM) and GMAC",
+        National Institute of Standards and Technology SP 800-
+        38D, November 2007.</p>
+      </item>
     </list>
   </description>
 
@@ -130,7 +136,7 @@
 
      <p><code>block_cipher() =  aes_cbc128 | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc |
      blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cbf
-     | des_ede3 | rc2_cbc </code></p>
+     | des_ede3 | rc2_cbc | aes_gcm </code></p>
 
      <p><code>stream_key() =  aes_key() | rc4_key() </code></p>
 
@@ -152,7 +158,7 @@
      Note that both md4 and md5 are recommended only for compatibility with existing applications.
      </p>
      <p><code> cipher_algorithms() = des_cbc | des_cfb |  des3_cbc | des3_cbf | des_ede3 |
-     blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb8 | aes_cfb128| aes_cbc256 | aes_ige256 | rc2_cbc | aes_ctr| rc4  </code> </p>
+     blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb8 | aes_cfb128| aes_cbc256 | aes_ige256 | aes_gcm | rc2_cbc | aes_ctr| rc4  </code> </p>
      <p><code> public_key_algorithms() =   rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code>
      Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported
      with ecdsa and ecdh.
@@ -161,18 +167,22 @@
  </section>
 
   <funcs>
-      <func>
+    <func>
       <name>block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name>
-      <fsummary>Encrypt <c>PlainText</c>according to <c>Type</c> block cipher</fsummary>
+      <name>block_encrypt(aes_gcm, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag}</name>
+      <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary>
       <type>
 	<v>Type = block_cipher() </v>
 	<v>Key = block_key() </v>
         <v>PlainText = iodata() </v>
-        <v>IVec = CipherText = binary()</v>
+        <v>AAD = IVec = CipherText = CipherTag = binary()</v>
       </type>
       <desc>
         <p>Encrypt <c>PlainText</c>according to <c>Type</c> block cipher.
 	<c>IVec</c> is an arbitrary initializing vector.</p>
+	<p>In AEAD (Authenticated Encryption with Associated Data) mode, encrypt
+	<c>PlainText</c>according to <c>Type</c> block cipher and calculate
+	<c>CipherTag</c> that also authenticates the <c>AAD</c> (Associated Authenticated Data).</p>
 	<p>May throw exception <c>notsup</c> in case the chosen <c>Type</c>
 	is not supported by the underlying OpenSSL implementation.</p>
       </desc>
@@ -180,16 +190,21 @@
 
     <func>
       <name>block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name>
-      <fsummary>Decrypt <c>CipherText</c>according to <c>Type</c> block cipher</fsummary>
+      <name>block_decrypt(aes_gcm, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error</name>
+      <fsummary>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher</fsummary>
       <type>
 	<v>Type = block_cipher() </v>
 	<v>Key = block_key() </v>
         <v>PlainText = iodata() </v>
-        <v>IVec = CipherText = binary()</v>
+        <v>AAD = IVec = CipherText = CipherTag = binary()</v>
       </type>
       <desc>
         <p>Decrypt <c>CipherText</c>according to <c>Type</c> block cipher.
 	<c>IVec</c> is an arbitrary initializing vector.</p>
+        <p>In AEAD (Authenticated Encryption with Associated Data) mode, decrypt
+	<c>CipherText</c>according to <c>Type</c> block cipher and check the authenticity
+	the <c>PlainText</c> and <c>AAD</c> (Associated Authenticated Data) using the
+	<c>CipherTag</c>. May return <c>error</c> if the decryption or validation fail's</p>
 	<p>May throw exception <c>notsup</c> in case the chosen <c>Type</c>
 	is not supported by the underlying OpenSSL implementation.</p>
       </desc>
-- 
cgit v1.2.3