Harmonise use of EVP_CTRL_GET_TAG/EVP_CTRL_SET_TAG/EVP_CTRL_SET_IVLEN
authorMatt Caswell <matt@openssl.org>
Tue, 27 Jan 2015 14:05:07 +0000 (14:05 +0000)
committerMatt Caswell <matt@openssl.org>
Wed, 28 Jan 2015 10:39:01 +0000 (10:39 +0000)
Reviewed-by: Tim Hudson <tjh@openssl.org>
crypto/evp/e_aes.c
crypto/evp/evp.h
crypto/evp/evp_test.c
demos/evp/aesccm.c
demos/evp/aesgcm.c
doc/crypto/EVP_EncryptInit.pod

index 435d9ea..15b233c 100644 (file)
@@ -1271,7 +1271,7 @@ static int aes_gcm_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         gctx->tls_aad_len = -1;
         return 1;
 
-    case EVP_CTRL_GCM_SET_IVLEN:
+    case EVP_CTRL_AEAD_SET_IVLEN:
         if (arg <= 0)
             return 0;
         /* Allocate memory for IV if needed */
@@ -1285,14 +1285,14 @@ static int aes_gcm_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         gctx->ivlen = arg;
         return 1;
 
-    case EVP_CTRL_GCM_SET_TAG:
+    case EVP_CTRL_AEAD_SET_TAG:
         if (arg <= 0 || arg > 16 || c->encrypt)
             return 0;
         memcpy(c->buf, ptr, arg);
         gctx->taglen = arg;
         return 1;
 
-    case EVP_CTRL_GCM_GET_TAG:
+    case EVP_CTRL_AEAD_GET_TAG:
         if (arg <= 0 || arg > 16 || !c->encrypt || gctx->taglen < 0)
             return 0;
         memcpy(ptr, c->buf, arg);
@@ -1870,7 +1870,7 @@ static int aes_ccm_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         cctx->len_set = 0;
         return 1;
 
-    case EVP_CTRL_CCM_SET_IVLEN:
+    case EVP_CTRL_AEAD_SET_IVLEN:
         arg = 15 - arg;
     case EVP_CTRL_CCM_SET_L:
         if (arg < 2 || arg > 8)
@@ -1878,7 +1878,7 @@ static int aes_ccm_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         cctx->L = arg;
         return 1;
 
-    case EVP_CTRL_CCM_SET_TAG:
+    case EVP_CTRL_AEAD_SET_TAG:
         if ((arg & 1) || arg < 4 || arg > 16)
             return 0;
         if ((c->encrypt && ptr) || (!c->encrypt && !ptr))
@@ -1890,7 +1890,7 @@ static int aes_ccm_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         cctx->M = arg;
         return 1;
 
-    case EVP_CTRL_CCM_GET_TAG:
+    case EVP_CTRL_AEAD_GET_TAG:
         if (!c->encrypt || !cctx->tag_set)
             return 0;
         if (!CRYPTO_ccm128_tag(&cctx->ccm, ptr, (size_t)arg))
@@ -2217,7 +2217,7 @@ static int aes_ocb_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         octx->aad_buf_len = 0;
         return 1;
 
-    case EVP_CTRL_SET_IVLEN:
+    case EVP_CTRL_AEAD_SET_IVLEN:
         /* IV len must be 1 to 15 */
         if (arg <= 0 || arg > 15)
             return 0;
@@ -2225,7 +2225,7 @@ static int aes_ocb_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         octx->ivlen = arg;
         return 1;
 
-    case EVP_CTRL_SET_TAG:
+    case EVP_CTRL_AEAD_SET_TAG:
         if (!ptr) {
             /* Tag len must be 0 to 16 */
             if (arg < 0 || arg > 16)
@@ -2239,7 +2239,7 @@ static int aes_ocb_ctrl(EVP_CIPHER_CTX *c, int type, int arg, void *ptr)
         memcpy(octx->tag, ptr, arg);
         return 1;
 
-    case EVP_CTRL_GET_TAG:
+    case EVP_CTRL_AEAD_GET_TAG:
         if (arg != octx->taglen || !c->encrypt)
             return 0;
 
index 3101905..ff6665d 100644 (file)
@@ -397,14 +397,17 @@ struct evp_cipher_st {
 # define         EVP_CTRL_RAND_KEY               0x6
 # define         EVP_CTRL_PBE_PRF_NID            0x7
 # define         EVP_CTRL_COPY                   0x8
-# define         EVP_CTRL_GCM_SET_IVLEN          0x9
-# define         EVP_CTRL_GCM_GET_TAG            0x10
-# define         EVP_CTRL_GCM_SET_TAG            0x11
+# define         EVP_CTRL_AEAD_SET_IVLEN         0x9
+# define         EVP_CTRL_AEAD_GET_TAG           0x10
+# define         EVP_CTRL_AEAD_SET_TAG           0x11
+# define         EVP_CTRL_GCM_SET_IVLEN          EVP_CTRL_AEAD_SET_IVLEN
+# define         EVP_CTRL_GCM_GET_TAG            EVP_CTRL_AEAD_GET_TAG
+# define         EVP_CTRL_GCM_SET_TAG            EVP_CTRL_AEAD_SET_TAG
 # define         EVP_CTRL_GCM_SET_IV_FIXED       0x12
 # define         EVP_CTRL_GCM_IV_GEN             0x13
-# define         EVP_CTRL_CCM_SET_IVLEN          EVP_CTRL_GCM_SET_IVLEN
-# define         EVP_CTRL_CCM_GET_TAG            EVP_CTRL_GCM_GET_TAG
-# define         EVP_CTRL_CCM_SET_TAG            EVP_CTRL_GCM_SET_TAG
+# define         EVP_CTRL_CCM_SET_IVLEN          EVP_CTRL_AEAD_SET_IVLEN
+# define         EVP_CTRL_CCM_GET_TAG            EVP_CTRL_AEAD_GET_TAG
+# define         EVP_CTRL_CCM_SET_TAG            EVP_CTRL_AEAD_SET_TAG
 # define         EVP_CTRL_CCM_SET_L              0x14
 # define         EVP_CTRL_CCM_SET_MSGLEN         0x15
 /*
@@ -430,10 +433,6 @@ typedef struct {
     unsigned int interleave;
 } EVP_CTRL_TLS1_1_MULTIBLOCK_PARAM;
 
-# define         EVP_CTRL_SET_IVLEN                      EVP_CTRL_GCM_SET_IVLEN
-# define         EVP_CTRL_GET_TAG                        EVP_CTRL_GCM_GET_TAG
-# define         EVP_CTRL_SET_TAG                        EVP_CTRL_GCM_SET_TAG
-
 /* GCM TLS constants */
 /* Length of fixed part of IV derived from PRF */
 # define EVP_GCM_TLS_FIXED_IV_LEN                        4
index 5784874..47067e9 100644 (file)
@@ -179,13 +179,13 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
                 ERR_print_errors_fp(stderr);
                 test1_exit(10);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, in, NULL)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, in, NULL)) {
                 fprintf(stderr, "IV length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
             }
             if ((mode == EVP_CIPH_OCB_MODE) &&
-                !EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, tn, NULL)) {
+                !EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, tn, NULL)) {
                 fprintf(stderr, "Tag length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(15);
@@ -206,12 +206,12 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
                 ERR_print_errors_fp(stderr);
                 test1_exit(10);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, in, NULL)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, in, NULL)) {
                 fprintf(stderr, "IV length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, tn, NULL)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, tn, NULL)) {
                 fprintf(stderr, "Tag length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
@@ -273,7 +273,7 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
             || (mode == EVP_CIPH_CCM_MODE)) {
             unsigned char rtag[16];
 
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_TAG, tn, rtag)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, tn, rtag)) {
                 fprintf(stderr, "Get tag failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(14);
@@ -294,13 +294,13 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
                 ERR_print_errors_fp(stderr);
                 test1_exit(10);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, in, NULL)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, in, NULL)) {
                 fprintf(stderr, "IV length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
             }
             if ((mode == EVP_CIPH_OCB_MODE) &&
-                !EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, tn, NULL)) {
+                !EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, tn, NULL)) {
                 fprintf(stderr, "Tag length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(15);
@@ -310,7 +310,8 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
                 ERR_print_errors_fp(stderr);
                 test1_exit(12);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, tn, (void *)tag)) {
+            if (!EVP_CIPHER_CTX_ctrl
+                (ctx, EVP_CTRL_AEAD_SET_TAG, tn, (void *)tag)) {
                 fprintf(stderr, "Set tag failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(14);
@@ -326,13 +327,13 @@ static void test1(const EVP_CIPHER *c, const unsigned char *key, int kn,
                 ERR_print_errors_fp(stderr);
                 test1_exit(10);
             }
-            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, in, NULL)) {
+            if (!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, in, NULL)) {
                 fprintf(stderr, "IV length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
             }
             if (!EVP_CIPHER_CTX_ctrl
-                (ctx, EVP_CTRL_CCM_SET_TAG, tn, (void *)tag)) {
+                (ctx, EVP_CTRL_AEAD_SET_TAG, tn, (void *)tag)) {
                 fprintf(stderr, "Tag length set failed\n");
                 ERR_print_errors_fp(stderr);
                 test1_exit(11);
index 1810a51..e0240e5 100644 (file)
@@ -50,9 +50,10 @@ void aes_ccm_encrypt(void)
     /* Set cipher type and mode */
     EVP_EncryptInit_ex(ctx, EVP_aes_192_ccm(), NULL, NULL, NULL);
     /* Set nonce length if default 96 bits is not appropriate */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, sizeof(ccm_nonce), NULL);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, sizeof(ccm_nonce),
+                        NULL);
     /* Set tag length */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, sizeof(ccm_tag), NULL);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, sizeof(ccm_tag), NULL);
     /* Initialise key and IV */
     EVP_EncryptInit_ex(ctx, NULL, NULL, ccm_key, ccm_nonce);
     /* Set plaintext length: only needed if AAD is used */
@@ -67,7 +68,7 @@ void aes_ccm_encrypt(void)
     /* Finalise: note get no output for CCM */
     EVP_EncryptFinal_ex(ctx, outbuf, &outlen);
     /* Get tag */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, 16, outbuf);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, 16, outbuf);
     /* Output tag */
     printf("Tag:\n");
     BIO_dump_fp(stdout, outbuf, 16);
@@ -86,9 +87,10 @@ void aes_ccm_decrypt(void)
     /* Select cipher */
     EVP_DecryptInit_ex(ctx, EVP_aes_192_ccm(), NULL, NULL, NULL);
     /* Set nonce length, omit for 96 bits */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, sizeof(ccm_nonce), NULL);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, sizeof(ccm_nonce),
+                        NULL);
     /* Set expected tag value */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG,
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG,
                         sizeof(ccm_tag), (void *)ccm_tag);
     /* Specify key and IV */
     EVP_DecryptInit_ex(ctx, NULL, NULL, ccm_key, ccm_nonce);
index 12d4192..9159c5c 100644 (file)
@@ -50,7 +50,7 @@ void aes_gcm_encrypt(void)
     /* Set cipher type and mode */
     EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL);
     /* Set IV length if default 96 bits is not appropriate */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, sizeof(gcm_iv), NULL);
     /* Initialise key and IV */
     EVP_EncryptInit_ex(ctx, NULL, NULL, gcm_key, gcm_iv);
     /* Zero or more calls to specify any AAD */
@@ -63,7 +63,7 @@ void aes_gcm_encrypt(void)
     /* Finalise: note get no output for GCM */
     EVP_EncryptFinal_ex(ctx, outbuf, &outlen);
     /* Get tag */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, outbuf);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, 16, outbuf);
     /* Output tag */
     printf("Tag:\n");
     BIO_dump_fp(stdout, outbuf, 16);
@@ -82,7 +82,7 @@ void aes_gcm_decrypt(void)
     /* Select cipher */
     EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL);
     /* Set IV length, omit for 96 bits */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, sizeof(gcm_iv), NULL);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, sizeof(gcm_iv), NULL);
     /* Specify key and IV */
     EVP_DecryptInit_ex(ctx, NULL, NULL, gcm_key, gcm_iv);
 #if 0
@@ -90,7 +90,7 @@ void aes_gcm_decrypt(void)
      * Set expected tag value. A restriction in OpenSSL 1.0.1c and earlier
      * required the tag before any AAD or ciphertext
      */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, sizeof(gcm_tag), gcm_tag);
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, sizeof(gcm_tag), gcm_tag);
 #endif
     /* Zero or more calls to specify any AAD */
     EVP_DecryptUpdate(ctx, NULL, &outlen, gcm_aad, sizeof(gcm_aad));
@@ -99,8 +99,11 @@ void aes_gcm_decrypt(void)
     /* Output decrypted block */
     printf("Plaintext:\n");
     BIO_dump_fp(stdout, outbuf, outlen);
-    /* Set expected tag value. Works in OpenSSL 1.0.1d and later */
-    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, sizeof(gcm_tag), gcm_tag);
+    /*
+     * Set expected tag value. Works in OpenSSL 1.0.1d and later
+     * In versions prior to OpenSSL 1.1.0 you should use EVP_CTRL_GCM_SET_TAG
+     */
+    EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, sizeof(gcm_tag), gcm_tag);
     /* Finalise: note get no output for GCM */
     rv = EVP_DecryptFinal_ex(ctx, outbuf, &outlen);
     /*
index 6940de6..6d897da 100644 (file)
@@ -399,41 +399,38 @@ indicates if the operation was successful. If it does not indicate success
 the authentication operation has failed and any output data B<MUST NOT>
 be used as it is corrupted.
 
-The following ctrl is supported in OCB mode only:
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_OCB_SET_TAGLEN, taglen, NULL);
-
-Sets the tag length: this call can only be made before specifying an IV. If
-not called a default tag length is used. For OCB AES the default is 16 (i.e. 128
-bits). This is also the maximum tag length.
-
 The following ctrls are supported in both GCM and OCB modes:
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, ivlen, NULL);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
 
 Sets the IV length: this call can only be made before specifying an IV. If
 not called a default IV length is used. For GCM AES and OCB AES the default is
 12 (i.e. 96 bits). For OCB mode the maximum is 15.
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_TAG, taglen, tag);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
 
 Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
 This call can only be made when encrypting data and B<after> all data has been
 processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must
 either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, taglen, tag);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
 
 Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
 when decrypting data and must be made B<before> any data is processed (e.g.
 before any EVP_DecryptUpdate() call). For OCB mode the taglen must
-either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
+either be 16 or the value previously set via EVP_CTRL_AEAD_SET_TAG.
+
+In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag
+length can only be set before specifying an IV. If not called a default tag
+length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the
+maximum tag length for OCB.
 
 See L<EXAMPLES> below for an example of the use of GCM mode.
 
 =head1 CCM Mode
 
-The behaviour of CCM mode ciphers is similar to CCM mode but with a few
+The behaviour of CCM mode ciphers is similar to GCM mode but with a few
 additional requirements and different ctrl values.
 
 Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling
@@ -445,7 +442,7 @@ set to B<NULL> and the length passed in the B<inl> parameter.
 
 The following ctrls are supported in CCM mode:
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
 
 This call is made to set the expected B<CCM> tag value when decrypting or
 the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
@@ -456,7 +453,7 @@ used (12 for AES).
 
 Sets the CCM B<L> value. If not set a default is used (8 for AES).
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
 
 Sets the CCM nonce (IV) length: this call can only be made before specifying
 an nonce value. The nonce length is given by B<15 - L> so it is 7 by default