We now describe parameters instead of controls.
Also, since macros like EVP_MAC_CMAC do not exist any more, we rename
the pod files from EVP_MAC_{algo}.pod to EVP_MAC-{algo}.pod. This
allows getting the documentation like this:
man EVP_MAC CMAC
[skip ci]
Fixes #9709
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9713)
=head1 PARAMETER NAMES
+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") <int>
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") <int>
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") <utf8string>
-=item OSSL_MAC_PARAM_PROPERTIES ("properties") <utf8string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8string>
-=item OSSL_MAC_PARAM_DIGEST ("digest") <utf8string>
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <utf8string>
-=item OSSL_MAC_PARAM_CIPHER ("cipher") <utf8string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8string>
For MAC implementations that use an underlying computation cipher or
digest, these parameters set what the algorithm should be, and the
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 int>
For MAC implementations that support it, set the output size that
EVP_MAC_final() should produce.
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-BLAKE2, EVP_MAC-BLAKE2BMAC, EVP_MAC-BLAKE2SMAC
+- The BLAKE2 EVP_MAC implementations
+
+=head1 DESCRIPTION
+
+Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+These implementations are identified with one of these names and
+properties, to be used with EVP_MAC_fetch():
+
+=over 4
+
+=item "BLAKE2BMAC", "default=yes"
+
+=item "BLAKE2SMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+All these parameters can be set with EVP_MAC_CTX_set_params().
+Furthermore, the "size" parameter can be retrieved with
+EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and
+at least 1 byte in both cases.
+
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
+
+This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
+BLAKE2SMAC.
+It is empty by default.
+
+=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
+
+This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
+BLAKE2SMAC.
+It is empty by default.
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+
+When set, this can be any number between between 1 and 32 for
+EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
+It is 32 and 64 respectively by default.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 HISTORY
+
+The macros and functions described here were added to OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-CMAC - The CMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing CMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "CMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-GMAC - The GMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing GMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "GMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-HMAC - The HMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing HMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "HMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+
+=back
+
+The "flags" parameter is passed directly to HMAC_CTX_set_flags().
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>, L<HMAC(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-KMAC, EVP_MAC-KMAC256, EVP_MAC-KMAC256
+- The KMAC EVP_MAC implementations
+
+=head1 DESCRIPTION
+
+Support for computing KMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+These implementations are identified with one of these names and
+properties, to be used with EVP_MAC_fetch():
+
+=over 4
+
+=item "KMAC128", "default=yes"
+
+=item "KMAC256", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+All these parameters can be set with EVP_MAC_CTX_set_params().
+Furthermore, the "size" parameter can be retrieved with
+EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+
+=item B<OSSL_MAC_PARAM_XOF>
+
+=back
+
+The "xof" parameter value is exptect to be 1 or 0. Use 1 to enable XOF
+mode. If XOF is enabled then the output len that is encoded as part of
+the input stream is set to zero.
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-Poly1305 - The Poly1305 EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing Poly1305 MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "Poly1305", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MAC-Siphash - The SipHash EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing SipHash MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "Siphash", "default=yes"
+
+=back
+
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+All these parameters can be set with EVP_MAC_CTX_set_params().
+Furthermore, the "size" parameter can be retrieved with
+EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_BLAKE2 - The BLAKE2 EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_BLAKE2B> and B<EVP_MAC_BLAKE2S> are the numeric identities for this
-implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-This is a string value of at most 64 bytes for EVP_MAC_BLAKE2B
-or 32 for EVP_MAC_BLAKE2S and at least 1 byte in both cases.
-This must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_CUSTOM>
-
-This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
-or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
-If used this must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "custom"
-
-The value string is used as is.
-
-=item "hexcustom"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SALT>
-
-This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
-or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
-If used this must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "salt"
-
-The value string is used as is.
-
-=item "hexsalt"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "outlen"
-
-This is an optional value string containing a decimal number between 1 and
-32 for EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
-If it is not set it uses the default digest size of 32 and 64 respectively.
-If used this must be set before calling EVP_MAC_init().
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 HISTORY
-
-The macros and functions described here were added to OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_CMAC - The CMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing CMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_CMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_CIPHER>
-
-These work as described in L<EVP_MAC(3)/CONTROLS>.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_GMAC - The GMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing GMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_GMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_IV>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "iv"
-
-The value string is used as is.
-
-=item "hexiv"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_CIPHER>
-
-These work as described in L<EVP_MAC(3)/CONTROLS> with the restriction that the
-cipher must be an AEAD one.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_HMAC - The HMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing HMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_HMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_FLAGS>
-
-Sets HMAC flags. This is passed directly to HMAC_CTX_set_flags().
-
-There are no corresponding string control types.
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_MD>
-
-These work as described in L<EVP_MAC(3)/CONTROLS>.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_MD>: "digest"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_KMAC - The KMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing KMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_KMAC128> and B<EVP_MAC_KMAC256> are the numeric identities for this
-implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-This must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_CUSTOM>
-
-This is an optional string value that can be set before calling EVP_MAC_init().
-If it is not set it uses the default value "".
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "custom"
-
-The value string is used as is.
-
-=item "hexcustom"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "outlen"
-
-This is an optional value string containing a decimal number. If it is not set
-it uses the default value of 32 for EVP_MAC_KMAC128 and 64 for EVP_MAC_KMAC256.
-This can be called any time before EVP_MAC_final().
-
-=item B<EVP_MAC_CTRL_SET_XOF>
-
-EVP_MAC_ctrl_str() type string: "xof"
-
-The value string is expected to be an integer value of 1 or 0. Use 1 to enable
-XOF mode. If XOF is enabled then the output len that is encoded as part of the
-input stream is set to zero.
-This can be called any time before EVP_MAC_final().
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_POLY1305 - The Poly1305 EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing Poly1305 MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_POLY1305> is the numeric identity for this implementation,
-and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MAC_SIPHASH - The SipHash EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing SipHash MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_SIPHASH> is the numeric identity for this implementation,
-and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "digestsize"
-
-The value string is expected to contain a decimal number.
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
projects / oweals / openssl.git / commitdiff