Rename EVP_CIPHER_CTX_get_iv and EVP_CIPHER_CTX_get_iv_state for clarity

To clarify the purpose of these two calls rename them to
EVP_CIPHER_CTX_get_original_iv and EVP_CIPHER_CTX_get_updated_iv.

Also rename the OSSL_CIPHER_PARAM_IV_STATE to OSSL_CIPHER_PARAM_UPDATED_IV
to better align with the function name.

Fixes #13411

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #13870)

crypto/evp/evp_lib.c

@@ -511,8 +511,8 @@ const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx)
     OSSL_PARAM params[2] = { OSSL_PARAM_END, OSSL_PARAM_END };
 
     params[0] =
-        OSSL_PARAM_construct_octet_ptr(OSSL_CIPHER_PARAM_IV_STATE, (void **)&v,
-                                       sizeof(ctx->iv));
+        OSSL_PARAM_construct_octet_ptr(OSSL_CIPHER_PARAM_UPDATED_IV,
+                                       (void **)&v, sizeof(ctx->iv));
     ok = evp_do_ciph_ctx_getparams(ctx->cipher, ctx->provctx, params);
 
     return ok != 0 ? v : NULL;
@@ -525,24 +525,24 @@ unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx)
     OSSL_PARAM params[2] = { OSSL_PARAM_END, OSSL_PARAM_END };
 
     params[0] =
-        OSSL_PARAM_construct_octet_ptr(OSSL_CIPHER_PARAM_IV_STATE, (void **)&v,
-                                       sizeof(ctx->iv));
+        OSSL_PARAM_construct_octet_ptr(OSSL_CIPHER_PARAM_UPDATED_IV,
+                                       (void **)&v, sizeof(ctx->iv));
     ok = evp_do_ciph_ctx_getparams(ctx->cipher, ctx->provctx, params);
 
     return ok != 0 ? v : NULL;
 }
 #endif /* OPENSSL_NO_DEPRECATED_3_0_0 */
 
-int EVP_CIPHER_CTX_get_iv_state(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
+int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
 {
     OSSL_PARAM params[2] = { OSSL_PARAM_END, OSSL_PARAM_END };
 
     params[0] =
-        OSSL_PARAM_construct_octet_string(OSSL_CIPHER_PARAM_IV_STATE, buf, len);
+        OSSL_PARAM_construct_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, buf, len);
     return evp_do_ciph_ctx_getparams(ctx->cipher, ctx->provctx, params);
 }
 
-int EVP_CIPHER_CTX_get_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
+int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
 {
     OSSL_PARAM params[2] = { OSSL_PARAM_END, OSSL_PARAM_END };
 

doc/man3/EVP_CIPHER_CTX_get_iv.pod → doc/man3/EVP_CIPHER_CTX_get_original_iv.pod

@@ -2,29 +2,36 @@
 
 =head1 NAME
 
-EVP_CIPHER_CTX_get_iv, EVP_CIPHER_CTX_get_iv_state, EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv, EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data
+EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv,
+EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv,
+EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
- int EVP_CIPHER_CTX_get_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
- int EVP_CIPHER_CTX_get_iv_state(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+ int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+ int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);
  const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);
  unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);
 
 =head1 DESCRIPTION
 
-EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() copy initialization
-vector (IV) information from the B<EVP_CIPHER_CTX> into the caller-supplied
-buffer.  L<EVP_CIPHER_CTX_iv_length(3)> can be used to determine an
-appropriate buffer size, and if the supplied buffer is too small, an error
-will be returned (and no data copied).  EVP_CIPHER_CTX_get_iv() accesses the
-("original") IV that was supplied when the B<EVP_CIPHER_CTX> was created, and
-EVP_CIPHER_CTX_get_iv_state() accesses the current "IV state" of the cipher,
-which is updated during cipher operation for certain cipher modes (e.g., CBC
-and OFB).
+EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() copy
+initialization vector (IV) information from the B<EVP_CIPHER_CTX> into the
+caller-supplied buffer. L<EVP_CIPHER_CTX_iv_length(3)> can be used to determine
+an appropriate buffer size, and if the supplied buffer is too small, an error
+will be returned (and no data copied).  EVP_CIPHER_CTX_get_original_iv()
+accesses the ("original") IV that was supplied when the B<EVP_CIPHER_CTX> was
+initialized, and EVP_CIPHER_CTX_get_updated_iv() accesses the current "IV state"
+of the cipher, which is updated during cipher operation for certain cipher modes
+(e.g., CBC and OFB).
 
 The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
 EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at
@@ -38,25 +45,25 @@ different return type for the pointer.
 
 =head1 RETURN VALUES
 
-EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() return 1 on success
-and 0 on failure.
+EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() return 1
+on success and 0 on failure.
 
 The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
 EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on
 success, and NULL on failure.
 
 =head1 HISTORY
 
-EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() were added in
-OpenSSL 3.0.0.
+EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() were added
+in OpenSSL 3.0.0.
 
 EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
 EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated
 in OpenSSL 3.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man7/provider-cipher.pod

@@ -242,9 +242,9 @@ The length of the "ivlen" parameter should not exceed that of a B<size_t>.
 
 Gets the IV used to initialize the associated cipher ctx.
 
-=item "iv-state" (B<OSSL_CIPHER_PARAM_IV_STATE>) <octet string OR octet ptr>
+=item "updated-iv" (B<OSSL_CIPHER_PARAM_UPDATED_IV>) <octet string OR octet ptr>
 
-Gets the current pseudo-IV state for the associated cipher ctx, e.g.,
+Gets the updated pseudo-IV state for the associated cipher ctx, e.g.,
 the previous ciphertext block for CBC mode or the iteratively encrypted IV
 value for OFB mode.  Note that octet pointer access is deprecated and is
 provided only for backwards compatibility with historical libcrypto APIs.

include/openssl/core_names.h

@@ -73,7 +73,7 @@ extern "C" {
 #define OSSL_CIPHER_PARAM_KEYLEN               "keylen"       /* size_t */
 #define OSSL_CIPHER_PARAM_IVLEN                "ivlen"        /* size_t */
 #define OSSL_CIPHER_PARAM_IV                   "iv"           /* octet_string OR octet_ptr */
-#define OSSL_CIPHER_PARAM_IV_STATE             "iv-state"     /* octet_string OR octet_ptr */
+#define OSSL_CIPHER_PARAM_UPDATED_IV           "updated-iv"   /* octet_string OR octet_ptr */
 #define OSSL_CIPHER_PARAM_NUM                  "num"          /* uint */
 #define OSSL_CIPHER_PARAM_ROUNDS               "rounds"       /* uint */
 #define OSSL_CIPHER_PARAM_AEAD_TAG             "tag"          /* octet_string */

include/openssl/evp.h

@@ -573,8 +573,8 @@ OSSL_DEPRECATEDIN_3_0 const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CT
 OSSL_DEPRECATEDIN_3_0 const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);
 OSSL_DEPRECATEDIN_3_0 unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);
 # endif
-int EVP_CIPHER_CTX_get_iv_state(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
-int EVP_CIPHER_CTX_get_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
 unsigned char *EVP_CIPHER_CTX_buf_noconst(EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_num(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);

providers/implementations/ciphers/cipher_aes_cbc_hmac_sha.c

@@ -257,9 +257,10 @@ static int aes_get_ctx_params(void *vctx, OSSL_PARAM params[])
         ERR_raise(ERR_LIB_PROV, PROV_R_FAILED_TO_SET_PARAMETER);
         return 0;
     }
-    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_IV_STATE);
+    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_UPDATED_IV);
     if (p != NULL
-        && !OSSL_PARAM_set_octet_string(p, ctx->base.iv, ctx->base.ivlen)) {
+        && !OSSL_PARAM_set_octet_string(p, ctx->base.iv, ctx->base.ivlen)
+        && !OSSL_PARAM_set_octet_ptr(p, &ctx->base.iv, ctx->base.ivlen)) {
         ERR_raise(ERR_LIB_PROV, PROV_R_FAILED_TO_SET_PARAMETER);
         return 0;
     }
@@ -277,7 +278,7 @@ static const OSSL_PARAM cipher_aes_known_gettable_ctx_params[] = {
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_KEYLEN, NULL),
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_IVLEN, NULL),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV, NULL, 0),
-    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV_STATE, NULL, 0),
+    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, NULL, 0),
     OSSL_PARAM_END
 };
 const OSSL_PARAM *aes_gettable_ctx_params(ossl_unused void *provctx)

providers/implementations/ciphers/cipher_aes_ocb.c

@@ -432,7 +432,7 @@ static int aes_ocb_get_ctx_params(void *vctx, OSSL_PARAM params[])
             return 0;
         }
     }
-    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_IV_STATE);
+    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_UPDATED_IV);
     if (p != NULL) {
         if (ctx->base.ivlen > p->data_size) {
             ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_IV_LENGTH);
@@ -464,7 +464,7 @@ static const OSSL_PARAM cipher_ocb_known_gettable_ctx_params[] = {
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_IVLEN, NULL),
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_AEAD_TAGLEN, NULL),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV, NULL, 0),
-    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV_STATE, NULL, 0),
+    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, NULL, 0),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_AEAD_TAG, NULL, 0),
     OSSL_PARAM_END
 };

providers/implementations/ciphers/ciphercommon.c

@@ -113,7 +113,7 @@ static const OSSL_PARAM cipher_aead_known_gettable_ctx_params[] = {
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_IVLEN, NULL),
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_AEAD_TAGLEN, NULL),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV, NULL, 0),
-    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV_STATE, NULL, 0),
+    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, NULL, 0),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_AEAD_TAG, NULL, 0),
     OSSL_PARAM_size_t(OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD, NULL),
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN, NULL, 0),
@@ -519,7 +519,7 @@ int ossl_cipher_generic_get_ctx_params(void *vctx, OSSL_PARAM params[])
         ERR_raise(ERR_LIB_PROV, PROV_R_FAILED_TO_SET_PARAMETER);
         return 0;
     }
-    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_IV_STATE);
+    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_UPDATED_IV);
     if (p != NULL
         && !OSSL_PARAM_set_octet_ptr(p, &ctx->iv, ctx->ivlen)
         && !OSSL_PARAM_set_octet_string(p, &ctx->iv, ctx->ivlen)) {

providers/implementations/ciphers/ciphercommon_ccm.c

@@ -172,7 +172,7 @@ int ccm_get_ctx_params(void *vctx, OSSL_PARAM params[])
         }
     }
 
-    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_IV_STATE);
+    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_UPDATED_IV);
     if (p != NULL) {
         if (ccm_get_ivlen(ctx) > p->data_size) {
             ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_IVLEN);

providers/implementations/ciphers/ciphercommon_gcm.c

@@ -171,7 +171,7 @@ int gcm_get_ctx_params(void *vctx, OSSL_PARAM params[])
         }
     }
 
-    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_IV_STATE);
+    p = OSSL_PARAM_locate(params, OSSL_CIPHER_PARAM_UPDATED_IV);
     if (p != NULL) {
         if (ctx->iv_state == IV_STATE_UNINITIALISED)
             return 0;

providers/implementations/include/prov/ciphercommon.h

@@ -317,7 +317,7 @@ static const OSSL_PARAM name##_known_gettable_ctx_params[] = {                 \
     OSSL_PARAM_uint(OSSL_CIPHER_PARAM_PADDING, NULL),                          \
     OSSL_PARAM_uint(OSSL_CIPHER_PARAM_NUM, NULL),                              \
     OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV, NULL, 0),                    \
-    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_IV_STATE, NULL, 0),
+    OSSL_PARAM_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, NULL, 0),
 
 #define CIPHER_DEFAULT_GETTABLE_CTX_PARAMS_END(name)                           \
     OSSL_PARAM_END                                                             \

ssl/ktls.c

@@ -158,9 +158,9 @@ int ktls_configure_crypto(const SSL *s, const EVP_CIPHER *c, EVP_CIPHER_CTX *dd,
 
     if (s->version == TLS1_2_VERSION &&
         EVP_CIPHER_mode(c) == EVP_CIPH_GCM_MODE) {
-        if (!EVP_CIPHER_CTX_get_iv_state(dd, geniv,
-                                         EVP_GCM_TLS_FIXED_IV_LEN
-                                         + EVP_GCM_TLS_EXPLICIT_IV_LEN))
+        if (!EVP_CIPHER_CTX_get_updated_iv(dd, geniv,
+                                           EVP_GCM_TLS_FIXED_IV_LEN
+                                           + EVP_GCM_TLS_EXPLICIT_IV_LEN))
             return 0;
         iiv = geniv;
     }

test/aesgcmtest.c

@@ -58,7 +58,7 @@ static int do_encrypt(unsigned char *iv_gen, unsigned char *ct, int *ct_len,
           && TEST_true(EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, 16,
                                            tag) > 0)
           && TEST_true(iv_gen == NULL
-                  || EVP_CIPHER_CTX_get_iv(ctx, iv_gen, 12));
+                  || EVP_CIPHER_CTX_get_original_iv(ctx, iv_gen, 12));
     EVP_CIPHER_CTX_free(ctx);
     return ret;
 }

test/evp_extra_test.c

@@ -2266,8 +2266,8 @@ static int test_evp_iv(int idx)
             || !TEST_true(EVP_EncryptInit_ex(ctx, type, NULL, key, init_iv))
             || !TEST_true(EVP_EncryptUpdate(ctx, ciphertext, &len, msg,
                           (int)sizeof(msg)))
-            || !TEST_true(EVP_CIPHER_CTX_get_iv(ctx, oiv, sizeof(oiv)))
-            || !TEST_true(EVP_CIPHER_CTX_get_iv_state(ctx, iv, sizeof(iv)))
+            || !TEST_true(EVP_CIPHER_CTX_get_original_iv(ctx, oiv, sizeof(oiv)))
+            || !TEST_true(EVP_CIPHER_CTX_get_updated_iv(ctx, iv, sizeof(iv)))
             || !TEST_true(EVP_EncryptFinal_ex(ctx, ciphertext, &len)))
         goto err;
     ivlen = EVP_CIPHER_CTX_iv_length(ctx);

test/evp_test.c

@@ -764,7 +764,7 @@ static int cipher_test_enc(EVP_TEST *t, int enc,
     if (expected->iv != NULL) {
         /* Some (e.g., GCM) tests use IVs longer than EVP_MAX_IV_LENGTH. */
         unsigned char iv[128];
-        if (!TEST_true(EVP_CIPHER_CTX_get_iv_state(ctx_base, iv, sizeof(iv)))
+        if (!TEST_true(EVP_CIPHER_CTX_get_updated_iv(ctx_base, iv, sizeof(iv)))
                 || ((EVP_CIPHER_flags(expected->cipher) & EVP_CIPH_CUSTOM_IV) == 0
                     && !TEST_mem_eq(expected->iv, expected->iv_len, iv,
                                     expected->iv_len))) {

util/libcrypto.num

@@ -5191,8 +5191,8 @@ EVP_PKEY_CTX_set_dh_kdf_outlen          ?	3_0_0	EXIST::FUNCTION:
 EVP_PKEY_CTX_get_dh_kdf_outlen          ?	3_0_0	EXIST::FUNCTION:
 EVP_PKEY_CTX_set0_dh_kdf_ukm            ?	3_0_0	EXIST::FUNCTION:
 EVP_PKEY_CTX_get0_dh_kdf_ukm            ?	3_0_0	EXIST::FUNCTION:
-EVP_CIPHER_CTX_get_iv_state             ?	3_0_0	EXIST::FUNCTION:
-EVP_CIPHER_CTX_get_iv                   ?	3_0_0	EXIST::FUNCTION:
+EVP_CIPHER_CTX_get_updated_iv           ?	3_0_0	EXIST::FUNCTION:
+EVP_CIPHER_CTX_get_original_iv          ?	3_0_0	EXIST::FUNCTION:
 EVP_KEYMGMT_gettable_params             ?	3_0_0	EXIST::FUNCTION:
 EVP_KEYMGMT_settable_params             ?	3_0_0	EXIST::FUNCTION:
 EVP_KEYMGMT_gen_settable_params         ?	3_0_0	EXIST::FUNCTION: