diff mbox series

[API-NEXT,v2,1/16] api: crypto: clarify special nature of gcm and gmac

Message ID 1517130009-11837-2-git-send-email-odpbot@yandex.ru
State Superseded
Headers show
Series [API-NEXT,v2,1/16] api: crypto: clarify special nature of gcm and gmac | expand

Commit Message

Github ODP bot Jan. 28, 2018, 8:59 a.m. UTC 
From: Petri Savolainen <petri.savolainen@linaro.org>


Reword specification text to be more clear about special
nature of GCM (authenticate encryption in general) and
GMAC (cannot be paired with cipher) algorithms.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>

---
/** Email created from pull request 434 (lumag:crypto-upd)
 ** https://github.com/Linaro/odp/pull/434
 ** Patch: https://github.com/Linaro/odp/pull/434.patch
 ** Base sha: 0bdad6d2562166eec4abeb957b6bb5067de9fe94
 ** Merge commit sha: 8947b874421e06f87f32ec66357967a71e46e986
 **/
 include/odp/api/spec/crypto.h | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)
diff mbox series

Patch

diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h
index 77ea317b8..e4b0e8cef 100644
--- a/include/odp/api/spec/crypto.h
+++ b/include/odp/api/spec/crypto.h
@@ -83,9 +83,12 @@  typedef enum {
 	/** AES with counter mode */
 	ODP_CIPHER_ALG_AES_CTR,
 
-	/** AES in Galois/Counter Mode
+	/** AES-GCM
 	 *
-	 *  @note Must be paired with cipher ODP_AUTH_ALG_AES_GCM
+	 *  AES in Galois/Counter Mode (GCM) algorithm. GCM provides both
+	 *  authentication and ciphering of data (authenticated encryption)
+	 *  in the same operation. Hence this algorithm must be paired always
+	 *  with ODP_AUTH_ALG_AES_GCM authentication.
 	 */
 	ODP_CIPHER_ALG_AES_GCM,
 
@@ -128,23 +131,29 @@  typedef enum {
 	 */
 	ODP_AUTH_ALG_SHA512_HMAC,
 
-	/** AES in Galois/Counter Mode
+	/** AES-GCM
 	 *
-	 *  @note Must be paired with cipher ODP_CIPHER_ALG_AES_GCM
+	 *  AES in Galois/Counter Mode (GCM) algorithm. GCM provides both
+	 *  authentication and ciphering of data (authenticated encryption)
+	 *  in the same operation. Hence this algorithm must be paired always
+	 *  with ODP_CIPHER_ALG_AES_GCM cipher.
 	 */
 	ODP_AUTH_ALG_AES_GCM,
 
-	/** AES in Galois/Counter MAC Mode
+	/** AES-GMAC
 	 *
-	 * NIST and RFC specifications of GCM/GMAC refer to all data to be
-	 * authenticated as AAD. In constrast to that, ODP API specifies the
-	 * bulk of authenticated data to be located in packet payload for all
-	 * authentication algorithms, including GMAC. Thus for GMAC application
-	 * should also pass all data to be authenticated as packet data. AAD is
-	 * not used for GMAC. GMAC IV should be passed via session IV or
-	 * per-packet IV override.
+	 *  AES Galois Message Authentication Code (GMAC) algorithm. AES-GMAC
+	 *  is based on AES-GCM operation, but provides authentication only.
+	 *  Hence this algorithm can be paired only with ODP_CIPHER_ALG_NULL
+	 *  cipher.
 	 *
-	 * @note Must be paired with cipher ODP_CIPHER_ALG_NULL
+	 *  NIST and RFC specifications of GMAC refer to all data to be
+	 *  authenticated as AAD. In constrast to that, ODP API specifies
+	 *  the bulk of authenticated data to be located in packet payload for
+	 *  all authentication algorithms. Thus GMAC operation authenticates
+	 *  only packet payload and AAD is not used. GMAC needs
+	 *  an initialization vector, which can be passed via session (auth_iv)
+	 *  or packet (auth_iv_ptr) level parameters.
 	 */
 	ODP_AUTH_ALG_AES_GMAC,