Get rid of the diversity of names for MAC parameters

The EVP_PKEY MAC implementations had a diversity of controls that were
really the same thing.  We did reproduce that for the provider based
MACs, but are changing our minds on this.  Instead of that, we now use
one parameter name for passing the name of the underlying ciphers or
digests to a MAC implementation, "cipher" and "digest", and one
parameter name for passing the output size of the MAC, "size".

Then we leave it to the EVP_PKEY->EVP_MAC bridge to translate "md"
to "digest", and "digestsize" to "size".

Reviewed-by: Shane Lontis <[email protected]>
(Merged from openssl#9667)

crypto/crmf/crmf_pbm.c

@@ -207,7 +207,7 @@ int OSSL_CRMF_pbm_new(const OSSL_CRMF_PBMPARAMETER *pbmp,
     }
 
     macparams[0] =
-        OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+        OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                          (char *)mdname, strlen(mdname) + 1);
     macparams[1] =
         OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, basekey, bklen);

crypto/evp/mac_lib.c

@@ -89,7 +89,7 @@ size_t EVP_MAC_size(EVP_MAC_CTX *ctx)
     if (ctx->data != NULL) {
         OSSL_PARAM params[2] = { OSSL_PARAM_END, OSSL_PARAM_END };
 
-        params[0] = OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_OUTLEN, &sz);
+        params[0] = OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_SIZE, &sz);
         if (ctx->meth->get_ctx_params != NULL) {
             if (ctx->meth->get_ctx_params(ctx->data, params))
                 return sz;

crypto/evp/p_lib.c

@@ -345,7 +345,7 @@ EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
                                              (char *)engine_name,
                                              strlen(engine_name) + 1);
     params[paramsn++] =
-        OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+        OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_CIPHER,
                                          (char *)cipher_name,
                                          strlen(cipher_name) + 1);
     params[paramsn++] =

crypto/evp/pkey_mac.c

@@ -281,7 +281,7 @@ static int pkey_mac_ctrl(EVP_PKEY_CTX *ctx, int type, int p1, void *p2)
                                                      engineid,
                                                      strlen(engineid) + 1);
                 params[params_n++] =
-                    OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+                    OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_CIPHER,
                                                      ciphname,
                                                      strlen(ciphname) + 1);
                 params[params_n] = OSSL_PARAM_construct_end();
@@ -336,13 +336,13 @@ static int pkey_mac_ctrl(EVP_PKEY_CTX *ctx, int type, int p1, void *p2)
              */
 
             params[0] =
-                OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_OUTLEN, &size);
+                OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_SIZE, &size);
 
             if (!EVP_MAC_CTX_set_params(hctx->ctx, params))
                 return 0;
 
             params[0] =
-                OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_OUTLEN, &verify);
+                OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_SIZE, &verify);
 
             if (!EVP_MAC_CTX_get_params(hctx->ctx, params))
                 return 0;
@@ -407,7 +407,7 @@ static int pkey_mac_ctrl(EVP_PKEY_CTX *ctx, int type, int p1, void *p2)
                                                          engineid_l);
                 }
                 params[params_n++] =
-                    OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+                    OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                      mdname,
                                                      strlen(mdname) + 1);
                 params[params_n++] =
@@ -441,6 +441,20 @@ static int pkey_mac_ctrl_str(EVP_PKEY_CTX *ctx,
     OSSL_PARAM params[2];
     int ok = 0;
 
+    /*
+     * Translation of some control names that are equivalent to a single
+     * parameter name.
+     *
+     * "md" and "digest" are the same thing, we use the single "digest"
+     *
+     * "digestsize" was a setting control in siphash, but naming wise,
+     * it's really the same as "size".
+     */
+    if (strcmp(type, "md") == 0)
+        type = OSSL_MAC_PARAM_DIGEST;
+    else if (strcmp(type, "digestsize") == 0)
+        type = OSSL_MAC_PARAM_SIZE;
+
     if (!OSSL_PARAM_allocate_from_text(&params[0],
                                        EVP_MAC_CTX_settable_params(mac),
                                        type, value, strlen(value) + 1))

crypto/kdf/sskdf.c

@@ -168,7 +168,7 @@ static int kmac_init(EVP_MAC_CTX *ctx, const unsigned char *custom,
             || kmac_out_len == 64))
         return 0;
 
-    params[0] = OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_OUTLEN,
+    params[0] = OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_SIZE,
                                             &kmac_out_len);
 
     if (EVP_MAC_CTX_set_params(ctx, params) <= 0)
@@ -222,7 +222,7 @@ static int SSKDF_mac_kdm(EVP_MAC *kdf_mac, const EVP_MD *hmac_md,
     if (hmac_md != NULL) {
         const char *mdname = EVP_MD_name(hmac_md);
         params[params_n++] =
-            OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+            OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                              (char *)mdname,
                                              strlen(mdname) + 1);
     }

crypto/kdf/tls1_prf.c

@@ -251,7 +251,7 @@ static int tls1_prf_P_hash(const EVP_MD *md,
     /* TODO(3.0) rethink "flags", also see hmac.c in providers */
     mac_flags = EVP_MD_CTX_FLAG_NON_FIPS_ALLOW;
     params[0] = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_FLAGS, &mac_flags);
-    params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+    params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                  (char *)mdname,
                                                  strlen(mdname) + 1);
     params[2] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,

crypto/modes/siv128.c

@@ -172,7 +172,7 @@ int CRYPTO_siv128_init(SIV128_CONTEXT *ctx, const unsigned char *key, int klen,
     OSSL_PARAM params[3];
     const char *cbc_name = EVP_CIPHER_name(cbc);
 
-    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_ALGORITHM,
+    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_CIPHER,
                                                  (char *)cbc_name,
                                                  strlen(cbc_name) + 1);
     params[1] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,

doc/man7/provider-mac.pod

@@ -178,21 +178,12 @@ Gets flags associated with the MAC.
 
 =for comment We need to investigate if this is the right approach
 
-=item B<OSSL_MAC_PARAM_ALGORITHM> (utf8 string)
-
-Sets the name of the underlying algorithm to be used.
-It must name a suitable algorithm for the MAC that's being used.
-
-=item B<OSSL_MAC_PARAM_MD> (utf8 string)
+=item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
 
 =item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
 
-=item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
-
-These have the same meaning as B<OSSL_MAC_PARAM_ALGORITHM>, but specify
-the expected operation for the underlying algorithm.
-These are regarded as antiquated, but are kept for easier transition from
-legacy MAC implementations.
+Sets the name of the underlying cipher or digest to be used.
+It must name a suitable algorithm for the MAC that's being used.
 
 =item B<OSSL_MAC_PARAM_ENGINE> (utf8 string)
 
@@ -212,13 +203,11 @@ and engine, or a built in legacy function depends on what is available.
 
 =item B<OSSL_MAC_PARAM_SIZE> (int)
 
-=item B<OSSL_MAC_PARAM_DIGESTSIZE> (int)
-
-=item B<OSSL_MAC_PARAM_OUTLEN> (int)
+Can be used to get the resulting MAC size.
 
-All three names are considered the same.
-B<OSSL_MAC_PARAM_SIZE> and B<OSSL_MAC_PARAM_DIGESTSIZE> are considered
-antiquated, but are kept for easier transition from legacy MAC implementations.
+With some MAC algorithms, it can also be used to set the size that the
+resulting MAC should have.
+Allowable sizes are decided within each implementation.
 
 =back
 

include/openssl/core_names.h

@@ -75,18 +75,15 @@ extern "C" {
 #define OSSL_MAC_PARAM_SALT         "salt"      /* octet string */
 #define OSSL_MAC_PARAM_XOF          "xof"       /* int, 0 or 1 */
 #define OSSL_MAC_PARAM_FLAGS        "flags"     /* int */
-/* Note that "md" and "digest" are equivalent */
-#define OSSL_MAC_PARAM_MD           "md"        /* utf8 string */
-#define OSSL_MAC_PARAM_DIGEST       "digest"    /* utf8 string */
+/*
+ * If "engine" or "properties" are specified, they should always be paired
+ * with "cipher" or "digest".
+ */
 #define OSSL_MAC_PARAM_CIPHER       "cipher"    /* utf8 string */
-/* Note that "algorithm" can be used instead of "md", "digest" or "cipher" */
-#define OSSL_MAC_PARAM_ALGORITHM    "algorithm" /* utf8 string */
+#define OSSL_MAC_PARAM_DIGEST       "digest"    /* utf8 string */
 #define OSSL_MAC_PARAM_ENGINE       "engine"    /* utf8 string */
 #define OSSL_MAC_PARAM_PROPERTIES   "properties" /* utf8 string */
-/* Note that "size", "digestsize" and "outlen" are equivalent */
 #define OSSL_MAC_PARAM_SIZE         "size"      /* size_t */
-#define OSSL_MAC_PARAM_DIGESTSIZE   "digestsize" /* size_t */
-#define OSSL_MAC_PARAM_OUTLEN       "outlen"    /* size_t */
 
 /* Known MAC names (not a complete list) */
 #define OSSL_MAC_NAME_CMAC          "CMAC"

providers/common/macs/cmac_prov.c

@@ -140,8 +140,7 @@ static int cmac_final(void *vmacctx, unsigned char *out, size_t *outl,
 }
 
 static const OSSL_PARAM known_gettable_ctx_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL), /* Same as "outlen" */
+    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_END
 };
 static const OSSL_PARAM *cmac_gettable_ctx_params(void)
@@ -153,16 +152,13 @@ static int cmac_get_ctx_params(void *vmacctx, OSSL_PARAM params[])
 {
     OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         return OSSL_PARAM_set_size_t(p, cmac_size(vmacctx));
 
     return 1;
 }
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
-    /* "algorithm" and "cipher" are the same parameter */
-    OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ALGORITHM, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_CIPHER, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ENGINE, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_PROPERTIES, NULL, 0),
@@ -182,9 +178,7 @@ static int cmac_set_ctx_params(void *vmacctx, const OSSL_PARAM params[])
     struct cmac_data_st *macctx = vmacctx;
     const OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_CIPHER)) != NULL
-        || ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_ALGORITHM))
-            != NULL)) {
+    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_CIPHER)) != NULL) {
         if (p->data_type != OSSL_PARAM_UTF8_STRING)
             return 0;
 

providers/common/macs/gmac_prov.c

@@ -53,7 +53,7 @@ struct gmac_data_st {
     /*
      * Conditions for legacy EVP_CIPHER uses.
      */
-    ENGINE *engine;              /* Engine implementing the algorithm */
+    ENGINE *engine;              /* Engine implementing the cipher */
 };
 
 static size_t gmac_size(void);
@@ -150,8 +150,7 @@ static size_t gmac_size(void)
 }
 
 static const OSSL_PARAM known_gettable_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL), /* Same as "outlen" */
+    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_END
 };
 static const OSSL_PARAM *gmac_gettable_params(void)
@@ -163,16 +162,13 @@ static int gmac_get_params(OSSL_PARAM params[])
 {
     OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         return OSSL_PARAM_set_size_t(p, gmac_size());
 
     return 1;
 }
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
-    /* "algorithm" and "cipher" are the same parameter */
-    OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ALGORITHM, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_CIPHER, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ENGINE, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_PROPERTIES, NULL, 0),
@@ -194,9 +190,7 @@ static int gmac_set_ctx_params(void *vmacctx, const OSSL_PARAM params[])
     EVP_CIPHER_CTX *ctx = macctx->ctx;
     const OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_CIPHER)) != NULL
-        || (p = OSSL_PARAM_locate_const(params,
-                                        OSSL_MAC_PARAM_ALGORITHM)) != NULL) {
+    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_CIPHER)) != NULL) {
         if (p->data_type != OSSL_PARAM_UTF8_STRING)
             return 0;
 

providers/common/macs/hmac_prov.c

@@ -151,8 +151,7 @@ static int hmac_final(void *vmacctx, unsigned char *out, size_t *outl,
 }
 
 static const OSSL_PARAM known_gettable_ctx_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL), /* Same as "outlen" */
+    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_END
 };
 static const OSSL_PARAM *hmac_gettable_ctx_params(void)
@@ -164,16 +163,13 @@ static int hmac_get_ctx_params(void *vmacctx, OSSL_PARAM params[])
 {
     OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         return OSSL_PARAM_set_size_t(p, hmac_size(vmacctx));
 
     return 1;
 }
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
-    /* "algorithm" and "digest" are the same parameter */
-    OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ALGORITHM, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_DIGEST, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_ENGINE, NULL, 0),
     OSSL_PARAM_utf8_string(OSSL_MAC_PARAM_PROPERTIES, NULL, 0),
@@ -194,9 +190,7 @@ static int hmac_set_ctx_params(void *vmacctx, const OSSL_PARAM params[])
     struct hmac_data_st *macctx = vmacctx;
     const OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_DIGEST)) != NULL
-        || (p = OSSL_PARAM_locate_const(params,
-                                        OSSL_MAC_PARAM_ALGORITHM)) != NULL) {
+    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_DIGEST)) != NULL) {
         if (p->data_type != OSSL_PARAM_UTF8_STRING)
             return 0;
 

providers/common/macs/kmac_prov.c

@@ -311,9 +311,7 @@ static int kmac_final(void *vmacctx, unsigned char *out, size_t *outl,
 }
 
 static const OSSL_PARAM known_gettable_ctx_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL), /* Same as "outlen" */
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_DIGESTSIZE, NULL), /* Same as "outlen" */
+    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_END
 };
 static const OSSL_PARAM *kmac_gettable_ctx_params(void)
@@ -325,17 +323,14 @@ static int kmac_get_ctx_params(void *vmacctx, OSSL_PARAM params[])
 {
     OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_DIGESTSIZE)) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         return OSSL_PARAM_set_size_t(p, kmac_size(vmacctx));
 
     return 1;
 }
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
     OSSL_PARAM_int(OSSL_MAC_PARAM_XOF, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
     OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_octet_string(OSSL_MAC_PARAM_KEY, NULL, 0),
     OSSL_PARAM_octet_string(OSSL_MAC_PARAM_CUSTOM, NULL, 0),
@@ -363,9 +358,7 @@ static int kmac_set_ctx_params(void *vmacctx, const OSSL_PARAM *params)
     if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_XOF)) != NULL
         && !OSSL_PARAM_get_int(p, &kctx->xof_mode))
         return 0;
-    if (((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-         ||
-         (p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_SIZE)) != NULL)
+    if (((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         && !OSSL_PARAM_get_size_t(p, &kctx->out_len))
         return 0;
     if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_KEY)) != NULL) {

providers/default/macs/blake2_mac_impl.c

@@ -108,8 +108,7 @@ static int blake2_mac_final(void *vmacctx,
 }
 
 static const OSSL_PARAM known_gettable_ctx_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL), /* Same as "outlen" */
+    OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_END
 };
 static const OSSL_PARAM *blake2_gettable_ctx_params(void)
@@ -121,15 +120,13 @@ static int blake2_get_ctx_params(void *vmacctx, OSSL_PARAM params[])
 {
     OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        || (p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
         return OSSL_PARAM_set_size_t(p, blake2_mac_size(vmacctx));
 
     return 1;
 }
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
-    OSSL_PARAM_size_t(OSSL_MAC_PARAM_OUTLEN, NULL),
     OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
     OSSL_PARAM_octet_string(OSSL_MAC_PARAM_KEY, NULL, 0),
     OSSL_PARAM_octet_string(OSSL_MAC_PARAM_CUSTOM, NULL, 0),
@@ -149,9 +146,7 @@ static int blake2_mac_set_ctx_params(void *vmacctx, const OSSL_PARAM params[])
     struct blake2_mac_data_st *macctx = vmacctx;
     const OSSL_PARAM *p;
 
-    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_OUTLEN)) != NULL
-        ||
-        (p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_SIZE)) != NULL) {
+    if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_SIZE)) != NULL) {
         size_t size;
 
         if (!OSSL_PARAM_get_size_t(p, &size)