Commit 70cda24a33 for openssl.org
commit 70cda24a338e101eb53988ebd8b582fab03ad674
Author: slontis <shane.lontis@oracle.com>
Date: Tue Mar 10 14:17:55 2026 +1100
Deprecate EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num().
Suggested to be added in OpenSSL 4.1.
Since engines have been removed, these are redundant functions.
End users should not generally be accessing this internal field.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Frederik Wedel-Heinen <fwh.openssl@gmail.com>
Reviewed-by: Norbert Pocs <norbertp@openssl.org>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
MergeDate: Wed Apr 8 10:02:58 2026
(Merged from https://github.com/openssl/openssl/pull/30335)
diff --git a/CHANGES.md b/CHANGES.md
index 80e506160e..e232f1a740 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,12 @@ OpenSSL Releases
*Tong Li*
+ * `EVP_CIPHER_CTX_get_num()` and `EVP_CIPHER_CTX_set_num()' have been deprecated.
+
+ Refer to ossl-migration-guide(7) for more info.
+
+ *Shane Lontis*
+
* The `openssl pkeyutl` command now uses memory-mapped I/O when reading
raw input from a file for oneshot sign/verify operations (such as Ed25519,
Ed448, and ML-DSA) on platforms that support it (Unix-like). The
diff --git a/crypto/evp/evp_lib.c b/crypto/evp/evp_lib.c
index cc0d7426b1..35719410b9 100644
--- a/crypto/evp/evp_lib.c
+++ b/crypto/evp/evp_lib.c
@@ -590,6 +590,7 @@ unsigned char *EVP_CIPHER_CTX_buf_noconst(EVP_CIPHER_CTX *ctx)
return ctx->buf;
}
+#ifndef OPENSSL_NO_DEPRECATED_4_1
int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx)
{
int ok;
@@ -615,6 +616,7 @@ int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num)
ctx->num = (int)n;
return ok != 0;
}
+#endif /* OPENSSL_NO_DEPRECATED_4_1 */
int EVP_CIPHER_get_key_length(const EVP_CIPHER *cipher)
{
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 0e4ccadb6f..8c57d756ce 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -228,8 +228,6 @@ EVP_CIPHER_CTX_mode
int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
@@ -253,10 +251,17 @@ EVP_CIPHER_CTX_mode
#define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length
#define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length
#define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length
- #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
#define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type
#define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode
+The following functions and alias have been deprecated since OpenSSL 4.1, and
+can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version
+value, see L<openssl_user_macros(7)>:
+
+ int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
+ #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
+
The following function has been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
see L<openssl_user_macros(7)>:
@@ -840,6 +845,7 @@ Gets or sets the cipher specific "num" parameter for the cipher context I<ctx>.
Built-in ciphers typically use this to track how much of the current underlying
block has been "used" already.
See also EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num().
+This parameter was deprecated in OpenSSL 4.1.
=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer>
@@ -1945,6 +1951,9 @@ EVP_CIPHER_CTX_reset().
The EVP_CIPHER_CTX_cipher() function was deprecated in OpenSSL 3.0; use
EVP_CIPHER_CTX_get0_cipher() instead.
+The EVP_CIPHER_CTX_get_num(), EVP_CIPHER_CTX_set_num() functions and the
+EVP_CIPHER_CTX_num() macro were deprecated in OpenSSL 4.1.
+
The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(),
EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(),
diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod
index bf1947d361..4cadf4abca 100644
--- a/doc/man7/ossl-guide-migration.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -17,6 +17,19 @@ L<https://github.com/openssl/openssl/blob/master/CHANGES.md>.
For an overview of some of the key concepts introduced in OpenSSL 3.0 see
L<crypto(7)>.
+=head1 OPENSSL 4.1
+
+=head2 Main Changes from OpenSSL 4.0
+
+=head3 Deprecation of EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()
+
+These functions have been deprecated in OpenSSL 4.1 since they were primarily
+used by engines, which were removed in OpenSSL 4.0.
+OpenSSL Provider algorithms maintain their state internally and should not
+expose this information. If required the state should be set and get
+via an OSSL_PARAM, bearing in mind that the bounds must be checked if setting
+this value.
+
=head1 OPENSSL 4.0
=head2 Main Changes from OpenSSL 3.6
diff --git a/include/openssl/evp.h b/include/openssl/evp.h
index 39a6204545..2fefb1bd93 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -552,9 +552,12 @@ int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
OSSL_DEPRECATEDIN_3_0
unsigned char *EVP_CIPHER_CTX_buf_noconst(EVP_CIPHER_CTX *ctx);
#endif
-int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
+#ifndef OPENSSL_NO_DEPRECATED_4_1
+OSSL_DEPRECATEDIN_4_1 int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
#define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
-int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
+OSSL_DEPRECATEDIN_4_1 int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
+#endif
+
EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);
int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);
void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
diff --git a/util/libcrypto.num b/util/libcrypto.num
index aa1b05cbd3..a99907f14e 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -878,8 +878,8 @@ EVP_CIPHER_CTX_iv_noconst 876 4_0_0 EXIST::FUNCTION:DEPRECATEDIN_3
EVP_CIPHER_CTX_get_updated_iv 877 4_0_0 EXIST::FUNCTION:
EVP_CIPHER_CTX_get_original_iv 878 4_0_0 EXIST::FUNCTION:
EVP_CIPHER_CTX_buf_noconst 879 4_0_0 EXIST::FUNCTION:DEPRECATEDIN_3_0
-EVP_CIPHER_CTX_get_num 880 4_0_0 EXIST::FUNCTION:
-EVP_CIPHER_CTX_set_num 881 4_0_0 EXIST::FUNCTION:
+EVP_CIPHER_CTX_get_num 880 4_0_0 EXIST::FUNCTION:DEPRECATEDIN_4_1
+EVP_CIPHER_CTX_set_num 881 4_0_0 EXIST::FUNCTION:DEPRECATEDIN_4_1
EVP_CIPHER_CTX_dup 882 4_0_0 EXIST::FUNCTION:
EVP_CIPHER_CTX_copy 883 4_0_0 EXIST::FUNCTION:
EVP_CIPHER_CTX_get_app_data 884 4_0_0 EXIST::FUNCTION: