=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,
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[]);
EVP_MAC_gettable_params(), EVP_MAC_CTX_gettable_params() and
EVP_MAC_CTX_settable_params() get a constant B<OSSL_PARAM> array that
decribes the retrievable and settable parameters, i.e. parameters that
-can be used with EVP_MAC_CTX_get_params(), EVP_MAC_CTX_get_params()
+can be used with EVP_MAC_get_params(), EVP_MAC_CTX_get_params()
and EVP_MAC_CTX_set_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
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>.
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 OSSL_MAC_PARAM_MD ("md") <utf8string>
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
-=item OSSL_MAC_PARAM_DIGEST ("digest") <utf8string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
-=item OSSL_MAC_PARAM_CIPHER ("cipher") <utf8string>
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
-=item OSSL_MAC_PARAM_ALGORITHM ("algorithm") <utf8string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
-For MAC implementations that use an underlying computation algorithm,
-these parameters set what the algorithm should be, and the engine that
-implements the algorithm if needed.
+For MAC implementations that use an underlying computation cipher or
+digest, these parameters set what the algorithm should be, and the
+engine that implements the algorithm or the properties to fetch it
+by if needed.
-The value is always the name of the intended engine or algorithm.
+The value is always the name of the intended engine, algorithm,
+or the properties.
Note that not all algorithms may support all digests.
HMAC does not support variable output length digests such as SHAKE128
or SHAKE256.
-Also note that OSSL_MAC_PARAM_ALGORITHM can be use generically instead
-of OSSL_MAC_PARAM_MD, OSSL_MAC_PARAM_DIGEST or OSSL_MAC_PARAM_CIPHER,
-and that OSSL_MAC_PARAM_MD and OSSL_MAC_PARAM_DIGEST are also interchangable.
-
-=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
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.
EVP_MAC_do_all_ex() returns nothing at all.
-=head1 EXAMPLE
+=head1 EXAMPLES
#include <stdlib.h>
#include <stdio.h>
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();
projects / openssl.git / blobdiff