Modify providers that keep track of underlying algorithms

[openssl.git] / doc / man3 / EVP_MAC.pod

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 5fa498a4712977f0f0501e6f1f6d5b3e14e201e1..df15a907ecbe2a1a4ba665fc6d7929931e62b40f 100644 (file)
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free, EVP_MAC_name,
+EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
+EVP_MAC_is_a, EVP_MAC_name,
 EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
 EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
 EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
@@ -21,6 +22,7 @@ EVP_MAC_do_all_ex - EVP MAC routines
                         const char *properties);
  int EVP_MAC_up_ref(EVP_MAC *mac);
  void EVP_MAC_free(EVP_MAC *mac);
+ int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
  const char *EVP_MAC_name(const EVP_MAC *mac);
  const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
  int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
@@ -157,6 +159,9 @@ EVP_MAC_size() returns the MAC output size for the given context.
 
 EVP_MAC_name() returns the name of the given MAC implementation.
 
+EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
+algorithm that's identifiable with I<name>.
+
 EVP_MAC_provider() returns the provider that holds the implementation
 of the given I<mac>.
 
@@ -165,51 +170,58 @@ providers in the given library context I<libctx>, and for each of the
 implementations, calls the given function I<fn> with the implementation method
 and the given I<arg> as argument.
 
-=head1 PARAMETER NAMES
+=head1 PARAMETERS
+
+Parameters are identified by name as strings, and have an expected
+data type and maximum size.
+OpenSSL has a set of macros for parameter names it expects to see in
+its own MAC implementations.
+Here, we show all three, the OpenSSL macro for the parameter name, the
+name in string form, and a type description.
 
 The standard parameter names are:
 
 =over 4
 
-=item OSSL_MAC_PARAM_KEY ("key") <octet string>
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
 
 Its value is the MAC key as an array of bytes.
 
 For MACs that use an underlying computation algorithm, the algorithm
 must be set first, see parameter names "algorithm" below.
 
-=item OSSL_MAC_PARAM_IV ("iv") <octet string>
+=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
 
 Some MAC implementations require an IV, this parameter sets the IV.
 
-=item OSSL_MAC_PARAM_CUSTOM ("custom") <octet string>
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
 
 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
 this parameter sets the Customization String. The default value is the
 empty string.
 
-=item OSSL_MAC_PARAM_SALT ("salt") <octet string>
+=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
 
 This option is used by BLAKE2 MAC.
 
-=item OSSL_MAC_PARAM_XOF ("xof") <int>
+=item B<OSSL_MAC_PARAM_XOF> ("xof") <integer>
 
 It's a simple flag, the value 0 or 1 are expected.
 
 This option is used by KMAC.
 
-=item OSSL_MAC_PARAM_FLAGS ("flags") <int>
+=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <integer>
 
 These will set the MAC flags to the given numbers.
 Some MACs do not support this option.
 
-=item OSSL_MAC_PARAM_ENGINE ("engine") <utf8string>
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
 
-=item OSSL_MAC_PARAM_PROPERTIES ("properties") <utf8string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
-=item OSSL_MAC_PARAM_DIGEST ("digest") <utf8string>
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
 
-=item OSSL_MAC_PARAM_CIPHER ("cipher") <utf8string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
 
 For MAC implementations that use an underlying computation cipher or
 digest, these parameters set what the algorithm should be, and the
@@ -223,11 +235,12 @@ Note that not all algorithms may support all digests.
 HMAC does not support variable output length digests such as SHAKE128
 or SHAKE256.
 
-=item OSSL_MAC_PARAM_SIZE <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 For MAC implementations that support it, set the output size that
 EVP_MAC_final() should produce.
-The allowed sizes vary between MAC implementations.
+The allowed sizes vary between MAC implementations, but must never exceed
+what can be given with a B<size_t>.
 
 =back
 
@@ -248,6 +261,9 @@ EVP_MAC_free() returns nothing at all.
 EVP_MAC_name() returns the name of the MAC, or NULL if NULL was
 passed.
 
+EVP_MAC_is_a() returns 1 if the given method can be identified with
+the given name, otherwise 0.
+
 EVP_MAC_provider() returns a pointer to the provider for the MAC, or
 NULL on error.
 
@@ -298,12 +314,10 @@ EVP_MAC_do_all_ex() returns nothing at all.
 
       if (cipher != NULL)
           params[params_n++] =
-              OSSL_PARAM_construct_utf8_string("cipher", cipher,
-                                               strlen(cipher) + 1, NULL);
+              OSSL_PARAM_construct_utf8_string("cipher", cipher, 0, NULL);
       if (digest != NULL)
           params[params_n++] =
-              OSSL_PARAM_construct_utf8_string("digest", digest,
-                                               strlen(digest) + 1, NULL);
+              OSSL_PARAM_construct_utf8_string("digest", digest, 0, NULL);
       params[params_n++] =
           OSSL_PARAM_construct_octet_string("key", key, strlen(key), NULL);
       params[params_n] = OSSL_PARAM_construct_end();