doc: note the additional parameters to EVP_MAC_init()

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14310)

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index b32415aac5cb82c51a4afe684e9ea0a604f7bf6c..928ef524073f39a8422e259e370b5031d703188d 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -40,7 +40,8 @@ EVP_MAC_do_all_provided - EVP MAC routines
  int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
 
  size_t EVP_MAC_CTX_get_mac_size(EVP_MAC_CTX *ctx);
- int EVP_MAC_init(EVP_MAC_CTX *ctx);
+ int EVP_MAC_init(EVP_MAC_CTX *ctx, const unsigned char *key, size_t keylen,
+                  const OSSL_PARAM params[]);
  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
  int EVP_MAC_final(EVP_MAC_CTX *ctx,
                    unsigned char *out, size_t *outl, size_t outsize);
@@ -117,9 +118,11 @@ I<ctx>.
 =head2 Computing functions
 
 EVP_MAC_init() sets up the underlying context with information given
-through diverse controls.
-This should be called before calling EVP_MAC_update() and
-EVP_MAC_final().
+via the I<key> and I<params> arguments.  The MAC I<key> has a length of
+I<keylen> and the parameters in I<params> are processed before setting
+the key.  If I<key> is NULL, the key must be set via params either
+as part of this call or separately using EVP_MAC_CTX_set_params().
+This should be called before calling EVP_MAC_update() and EVP_MAC_final().
 
 EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
 
@@ -362,7 +365,7 @@ EVP_MAC_do_all_provided() returns nothing at all.
 
       size_t i;
 
-      OSSL_PARAM params[4];
+      OSSL_PARAM params[3];
       size_t params_n = 0;
 
       if (cipher != NULL)
@@ -371,17 +374,13 @@ EVP_MAC_do_all_provided() returns nothing at all.
       if (digest != NULL)
           params[params_n++] =
               OSSL_PARAM_construct_utf8_string("digest", (char*)digest, 0);
-      params[params_n++] =
-          OSSL_PARAM_construct_octet_string("key", (void*)key, strlen(key));
       params[params_n] = OSSL_PARAM_construct_end();
 
       if (mac == NULL
           || key == NULL
           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
-          || EVP_MAC_CTX_set_params(ctx, params) <= 0)
-          goto err;
-
-      if (!EVP_MAC_init(ctx))
+          || !EVP_MAC_init(ctx, (const unsigned char *)key, strlen(key),
+                           params))
           goto err;
 
       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {