Deprecate the low level CMAC functions

Use of the low level CMAC functions has been informally discouraged for a
long time.  We now formally deprecate them.

Applications should instead use EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3),
EVP_MAC_init(3), EVP_MAC_update(3) and EVP_MAC_final(3).

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10836)

diff --git a/CHANGES b/CHANGES
index d64163d4e0cb6497e0441455771008e8f8ffcf0e..fe99dec0e2d8d673a454b72e7c1ebc5f999f2aca 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -21,6 +21,15 @@
      as well as words of caution.
      [Richard Levitte]
 
+  *) All of the low level CMAC functions have been deprecated including:
+     CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, CMAC_CTX_get0_cipher_ctx,
+     CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final and CMAC_resume.
+     Use of these low level functions has been informally discouraged for a long
+     time.  Instead applications should use L<EVP_MAC_CTX_new(3)>,
+     L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>, L<EVP_MAC_update(3)>
+     and L<EVP_MAC_final(3)>.
+     [Paul Dale]
+
   *) All of the low level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224, SHA256,
      SHA384, SHA512 and Whirlpool digest functions have been deprecated.
      These include:
@@ -35,6 +44,7 @@
          SHA512, SHA512_Init, SHA512_Update, SHA512_Final, SHA512_Transform,
          WHIRLPOOL, WHIRLPOOL_Init, WHIRLPOOL_Update, WHIRLPOOL_BitUpdate
          and WHIRLPOOL_Final.
+
      Use of these low level functions has been informally discouraged for a long
      time.  Instead applications should instead use the EVP_DigestInit_ex,
      EVP_DigestUpdate(3) and EVP_DigestFinal_ex(3) functions.

diff --git a/apps/speed.c b/apps/speed.c
index 86cb9ff151b4bc19644cf57d3ee8867571d457a9..40c8eacbaeabb53cb638caf0cb74032df2147658 100644 (file)
--- a/apps/speed.c
+++ b/apps/speed.c
@@ -280,7 +280,7 @@ const OPTIONS speed_options[] = {
     OPT_SECTION("Selection"),
     {"evp", OPT_EVP, 's', "Use EVP-named cipher or digest"},
     {"hmac", OPT_HMAC, 's', "HMAC using EVP-named digest"},
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
     {"cmac", OPT_CMAC, 's', "CMAC using EVP-named cipher"},
 #endif
     {"decrypt", OPT_DECRYPT, '-',
@@ -559,7 +559,7 @@ typedef struct loopargs_st {
 #endif
     EVP_CIPHER_CTX *ctx;
     HMAC_CTX *hctx;
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
     CMAC_CTX *cmac_ctx;
 #endif
     GCM128_CONTEXT *gcm_ctx;
@@ -987,7 +987,7 @@ static int EVP_HMAC_loop(void *args)
     return count;
 }
 
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
 static const EVP_CIPHER *evp_cmac_cipher = NULL;
 static char *evp_cmac_name = NULL;
 
@@ -1626,7 +1626,7 @@ int speed_main(int argc, char **argv)
             doit[D_EVP_HMAC] = 1;
             break;
         case OPT_CMAC:
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
             evp_cmac_cipher = EVP_get_cipherbyname(opt_arg());
             if (evp_cmac_cipher == NULL) {
                 BIO_printf(bio_err, "%s: %s is an unknown cipher\n",
@@ -2808,7 +2808,7 @@ int speed_main(int argc, char **argv)
         }
     }
 
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
     if (doit[D_EVP_CMAC] && evp_cmac_cipher != NULL) {
         const char *cipher_name = OBJ_nid2ln(EVP_CIPHER_type(evp_cmac_cipher));
 
@@ -3710,7 +3710,7 @@ int speed_main(int argc, char **argv)
 #endif
     }
     OPENSSL_free(evp_hmac_name);
-#ifndef OPENSSL_NO_CMAC
+#if !defined(OPENSSL_NO_CMAC) && !defined(OPENSSL_NO_DEPRECATED_3_0)
     OPENSSL_free(evp_cmac_name);
 #endif
 

diff --git a/crypto/cmac/cm_ameth.c b/crypto/cmac/cm_ameth.c
index 9db2562157238c058ecf33e1931af1238d47d0bf..d46cf07fac524d866559e458a128d36bae1f60e2 100644 (file)
--- a/crypto/cmac/cm_ameth.c
+++ b/crypto/cmac/cm_ameth.c
@@ -7,6 +7,12 @@
  * https://www.openssl.org/source/license.html
  */
 
+/*
+ * CMAC low level APIs are deprecated for public use, but still ok for internal
+ * use.
+ */
+#include "internal/deprecated.h"
+
 #include <stdio.h>
 #include "internal/cryptlib.h"
 #include <openssl/evp.h>

diff --git a/crypto/cmac/cmac.c b/crypto/cmac/cmac.c
index ec12970cb2382a0ce5e99d2b96f1ece6c3ec6149..b10c29c2671bc5425ec58aba78e5215cc10d4414 100644 (file)
--- a/crypto/cmac/cmac.c
+++ b/crypto/cmac/cmac.c
@@ -7,6 +7,12 @@
  * https://www.openssl.org/source/license.html
  */
 
+/*
+ * CMAC low level APIs are deprecated for public use, but still ok for internal
+ * use.
+ */
+#include "internal/deprecated.h"
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

diff --git a/include/openssl/cmac.h b/include/openssl/cmac.h
index ef0ab3a36acace7d4d0bd1035bbb65ba89ac1ac3..2f43eced3c87493b0745ab9d0111ff8ddd8e880e 100644 (file)
--- a/include/openssl/cmac.h
+++ b/include/openssl/cmac.h
@@ -24,20 +24,23 @@ extern "C" {
 
 #  include <openssl/evp.h>
 
+#  ifndef OPENSSL_NO_DEPRECATED_3_0
 /* Opaque */
 typedef struct CMAC_CTX_st CMAC_CTX;
+#  endif
 
-CMAC_CTX *CMAC_CTX_new(void);
-void CMAC_CTX_cleanup(CMAC_CTX *ctx);
-void CMAC_CTX_free(CMAC_CTX *ctx);
-EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);
-int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);
-
-int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,
-              const EVP_CIPHER *cipher, ENGINE *impl);
-int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);
-int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);
-int CMAC_resume(CMAC_CTX *ctx);
+DEPRECATEDIN_3_0(CMAC_CTX *CMAC_CTX_new(void))
+DEPRECATEDIN_3_0(void CMAC_CTX_cleanup(CMAC_CTX *ctx))
+DEPRECATEDIN_3_0(void CMAC_CTX_free(CMAC_CTX *ctx))
+DEPRECATEDIN_3_0(EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx))
+DEPRECATEDIN_3_0(int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in))
+
+DEPRECATEDIN_3_0(int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,
+              const EVP_CIPHER *cipher, ENGINE *impl))
+DEPRECATEDIN_3_0(int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen))
+DEPRECATEDIN_3_0(int CMAC_Final(CMAC_CTX *ctx, unsigned char *out,
+                                size_t *poutlen))
+DEPRECATEDIN_3_0(int CMAC_resume(CMAC_CTX *ctx))
 
 #  ifdef  __cplusplus
 }

diff --git a/providers/implementations/macs/cmac_prov.c b/providers/implementations/macs/cmac_prov.c
index f3dbe1f2e74debe601b4579042438d5956549211..6caec1b6667086ecf6efad5612af51a101d8cdab 100644 (file)
--- a/providers/implementations/macs/cmac_prov.c
+++ b/providers/implementations/macs/cmac_prov.c
@@ -7,6 +7,12 @@
  * https://www.openssl.org/source/license.html
  */
 
+/*
+ * CMAC low level APIs are deprecated for public use, but still ok for internal
+ * use.
+ */
+#include "internal/deprecated.h"
+
 #include <openssl/core_numbers.h>
 #include <openssl/core_names.h>
 #include <openssl/params.h>

diff --git a/util/libcrypto.num b/util/libcrypto.num
index 64b2ed277cddb68701baa6d937a1a6f7f11879d2..2f4403effe80a9541e2abba78339189e0a43136b 100644 (file)
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -137,7 +137,7 @@ OCSP_REQ_CTX_free                       138 3_0_0   EXIST::FUNCTION:OCSP
 X509_STORE_new                          140    3_0_0   EXIST::FUNCTION:
 ASN1_TYPE_free                          141    3_0_0   EXIST::FUNCTION:
 PKCS12_BAGS_new                         142    3_0_0   EXIST::FUNCTION:
-CMAC_CTX_new                            143    3_0_0   EXIST::FUNCTION:CMAC
+CMAC_CTX_new                            143    3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 ASIdentifierChoice_new                  144    3_0_0   EXIST::FUNCTION:RFC3779
 EVP_PKEY_asn1_set_public                145    3_0_0   EXIST::FUNCTION:
 IDEA_set_decrypt_key                    146    3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3_0,IDEA
@@ -561,7 +561,7 @@ EVP_PKEY_meth_get_cleanup               572 3_0_0   EXIST::FUNCTION:
 d2i_X509                                574    3_0_0   EXIST::FUNCTION:
 a2i_ASN1_STRING                         575    3_0_0   EXIST::FUNCTION:
 EC_GROUP_get_mont_data                  576    3_0_0   EXIST::FUNCTION:EC
-CMAC_CTX_copy                           577    3_0_0   EXIST::FUNCTION:CMAC
+CMAC_CTX_copy                           577    3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 EVP_camellia_128_cfb128                 579    3_0_0   EXIST::FUNCTION:CAMELLIA
 DH_compute_key_padded                   580    3_0_0   EXIST::FUNCTION:DH
 ERR_load_CONF_strings                   581    3_0_0   EXIST::FUNCTION:
@@ -1707,7 +1707,7 @@ EC_POINT_cmp                            1745      3_0_0   EXIST::FUNCTION:EC
 ASN1_buf_print                          1746   3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_hex2ctrl                   1747   3_0_0   EXIST::FUNCTION:
 PEM_write_bio_PKCS8PrivateKey           1748   3_0_0   EXIST::FUNCTION:
-CMAC_Update                             1749   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_Update                             1749   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 d2i_ASN1_UTCTIME                        1750   3_0_0   EXIST::FUNCTION:
 OPENSSL_sk_insert                       1751   3_0_0   EXIST::FUNCTION:
 DSO_up_ref                              1752   3_0_0   EXIST::FUNCTION:
@@ -2122,7 +2122,7 @@ AUTHORITY_INFO_ACCESS_it                2167      3_0_0   EXIST::FUNCTION:
 X509_EXTENSION_create_by_NID            2168   3_0_0   EXIST::FUNCTION:
 i2d_RSAPrivateKey                       2169   3_0_0   EXIST::FUNCTION:RSA
 d2i_CERTIFICATEPOLICIES                 2170   3_0_0   EXIST::FUNCTION:
-CMAC_CTX_get0_cipher_ctx                2171   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_CTX_get0_cipher_ctx                2171   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 X509_STORE_load_locations               2172   3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3_0
 OBJ_find_sigid_algs                     2173   3_0_0   EXIST::FUNCTION:
 TS_RESP_CTX_set_accuracy                2174   3_0_0   EXIST::FUNCTION:TS
@@ -2152,7 +2152,7 @@ X509_STORE_CTX_set_depth                2199      3_0_0   EXIST::FUNCTION:
 X509v3_delete_ext                       2200   3_0_0   EXIST::FUNCTION:
 ASN1_STRING_set0                        2201   3_0_0   EXIST::FUNCTION:
 BN_GF2m_add                             2202   3_0_0   EXIST::FUNCTION:EC2M
-CMAC_resume                             2203   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_resume                             2203   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 TS_ACCURACY_set_millis                  2204   3_0_0   EXIST::FUNCTION:TS
 X509V3_EXT_conf                         2205   3_0_0   EXIST::FUNCTION:
 i2d_DHxparams                           2206   3_0_0   EXIST::FUNCTION:DH
@@ -3083,7 +3083,7 @@ BF_cfb64_encrypt                        3147      3_0_0   EXIST::FUNCTION:BF,DEPRECATED
 ASN1_GENERALIZEDTIME_adj                3148   3_0_0   EXIST::FUNCTION:
 ECDSA_verify                            3149   3_0_0   EXIST::FUNCTION:EC
 EVP_camellia_256_cfb128                 3150   3_0_0   EXIST::FUNCTION:CAMELLIA
-CMAC_Init                               3151   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_Init                               3151   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 OCSP_basic_add1_status                  3152   3_0_0   EXIST::FUNCTION:OCSP
 X509_CRL_get0_by_cert                   3153   3_0_0   EXIST::FUNCTION:
 TS_TST_INFO_set_tsa                     3154   3_0_0   EXIST::FUNCTION:TS
@@ -3404,14 +3404,14 @@ ASYNC_WAIT_CTX_get_changed_fds          3474    3_0_0   EXIST::FUNCTION:
 EVP_PKEY_save_parameters                3475   3_0_0   EXIST::FUNCTION:
 SCT_set_source                          3476   3_0_0   EXIST::FUNCTION:CT
 DES_set_odd_parity                      3477   3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3_0,DES
-CMAC_CTX_free                           3478   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_CTX_free                           3478   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 d2i_ESS_ISSUER_SERIAL                   3479   3_0_0   EXIST::FUNCTION:
 HMAC_CTX_set_flags                      3480   3_0_0   EXIST::FUNCTION:
 d2i_PKCS8_bio                           3481   3_0_0   EXIST::FUNCTION:
 OCSP_ONEREQ_get_ext_count               3482   3_0_0   EXIST::FUNCTION:OCSP
 PEM_read_bio_PKCS8_PRIV_KEY_INFO        3483   3_0_0   EXIST::FUNCTION:
 i2d_OCSP_BASICRESP                      3484   3_0_0   EXIST::FUNCTION:OCSP
-CMAC_Final                              3485   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_Final                              3485   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 X509V3_EXT_add_alias                    3486   3_0_0   EXIST::FUNCTION:
 BN_get_params                           3487   3_0_0   EXIST::FUNCTION:DEPRECATEDIN_0_9_8
 PKCS5_pbkdf2_set                        3488   3_0_0   EXIST::FUNCTION:
@@ -3640,7 +3640,7 @@ TS_RESP_verify_response                 3719      3_0_0   EXIST::FUNCTION:TS
 X509_REVOKED_get0_serialNumber          3720   3_0_0   EXIST::FUNCTION:
 X509_VERIFY_PARAM_free                  3721   3_0_0   EXIST::FUNCTION:
 ASN1_TYPE_new                           3722   3_0_0   EXIST::FUNCTION:
-CMAC_CTX_cleanup                        3723   3_0_0   EXIST::FUNCTION:CMAC
+CMAC_CTX_cleanup                        3723   3_0_0   EXIST::FUNCTION:CMAC,DEPRECATEDIN_3_0
 i2d_PKCS7_NDEF                          3724   3_0_0   EXIST::FUNCTION:
 OPENSSL_sk_pop_free                     3725   3_0_0   EXIST::FUNCTION:
 X509_STORE_CTX_get0_policy_tree         3726   3_0_0   EXIST::FUNCTION: