From e592dbde6ff177a43cf66a95c59d101afb74cf5d Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 28 Aug 2019 09:13:21 +0200 Subject: [PATCH] Rework the documentation of our individual MAC implementations 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 (Merged from https://github.com/openssl/openssl/pull/9713) --- doc/man3/EVP_MAC.pod | 29 +++++---- doc/man7/EVP_MAC-BLAKE2.pod | 79 +++++++++++++++++++++++ doc/man7/EVP_MAC-CMAC.pod | 66 ++++++++++++++++++++ doc/man7/EVP_MAC-GMAC.pod | 68 ++++++++++++++++++++ doc/man7/EVP_MAC-HMAC.pod | 70 +++++++++++++++++++++ doc/man7/EVP_MAC-KMAC.pod | 64 +++++++++++++++++++ doc/man7/EVP_MAC-Poly1305.pod | 60 ++++++++++++++++++ doc/man7/EVP_MAC-Siphash.pod | 54 ++++++++++++++++ doc/man7/EVP_MAC_BLAKE2.pod | 114 ---------------------------------- doc/man7/EVP_MAC_CMAC.pod | 65 ------------------- doc/man7/EVP_MAC_GMAC.pod | 83 ------------------------- doc/man7/EVP_MAC_HMAC.pod | 71 --------------------- doc/man7/EVP_MAC_KMAC.pod | 94 ---------------------------- doc/man7/EVP_MAC_POLY1305.pod | 55 ---------------- doc/man7/EVP_MAC_SIPHASH.pod | 61 ------------------ 15 files changed, 479 insertions(+), 554 deletions(-) create mode 100644 doc/man7/EVP_MAC-BLAKE2.pod create mode 100644 doc/man7/EVP_MAC-CMAC.pod create mode 100644 doc/man7/EVP_MAC-GMAC.pod create mode 100644 doc/man7/EVP_MAC-HMAC.pod create mode 100644 doc/man7/EVP_MAC-KMAC.pod create mode 100644 doc/man7/EVP_MAC-Poly1305.pod create mode 100644 doc/man7/EVP_MAC-Siphash.pod delete mode 100644 doc/man7/EVP_MAC_BLAKE2.pod delete mode 100644 doc/man7/EVP_MAC_CMAC.pod delete mode 100644 doc/man7/EVP_MAC_GMAC.pod delete mode 100644 doc/man7/EVP_MAC_HMAC.pod delete mode 100644 doc/man7/EVP_MAC_KMAC.pod delete mode 100644 doc/man7/EVP_MAC_POLY1305.pod delete mode 100644 doc/man7/EVP_MAC_SIPHASH.pod diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 5fa498a471..6daa82d753 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -167,49 +167,56 @@ and the given I as argument. =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") +=item B ("key") 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") +=item B ("iv") Some MAC implementations require an IV, this parameter sets the IV. -=item OSSL_MAC_PARAM_CUSTOM ("custom") +=item B ("custom") 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") +=item B ("salt") This option is used by BLAKE2 MAC. -=item OSSL_MAC_PARAM_XOF ("xof") +=item B ("xof") It's a simple flag, the value 0 or 1 are expected. This option is used by KMAC. -=item OSSL_MAC_PARAM_FLAGS ("flags") +=item B ("flags") These will set the MAC flags to the given numbers. Some MACs do not support this option. -=item OSSL_MAC_PARAM_ENGINE ("engine") +=item B ("engine") -=item OSSL_MAC_PARAM_PROPERTIES ("properties") +=item B ("properties") -=item OSSL_MAC_PARAM_DIGEST ("digest") +=item B ("digest") -=item OSSL_MAC_PARAM_CIPHER ("cipher") +=item B ("cipher") For MAC implementations that use an underlying computation cipher or digest, these parameters set what the algorithm should be, and the @@ -223,7 +230,7 @@ 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 +=item B ("size") For MAC implementations that support it, set the output size that EVP_MAC_final() should produce. diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod new file mode 100644 index 0000000000..6ceb65d9e9 --- /dev/null +++ b/doc/man7/EVP_MAC-BLAKE2.pod @@ -0,0 +1,79 @@ +=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 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. + +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 ("key") + +This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and +at least 1 byte in both cases. + +=item B ("custom") + +This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for +BLAKE2SMAC. +It is empty by default. + +=item B ("salt") + +This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for +BLAKE2SMAC. +It is empty by default. + +=item B ("size") + +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, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod new file mode 100644 index 0000000000..e7675e2f7a --- /dev/null +++ b/doc/man7/EVP_MAC-CMAC.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +EVP_MAC-CMAC - The CMAC EVP_MAC implementation + +=head1 DESCRIPTION + +Support for computing CMAC MACs through the B 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. + +The following parameter can be set with EVP_MAC_CTX_set_params(): + +=over 4 + +=item B ("key") + +=item B ("engine") + +=item B ("cipher") + +=item B ("properties") + +=back + +The following parameters can be retrieved with +EVP_MAC_CTX_get_params(): + +=over 4 + +=item B ("size") + +=back + +The "size" parameter can also be retrieved with with EVP_MAC_size(). + +=head1 SEE ALSO + +L, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-GMAC.pod b/doc/man7/EVP_MAC-GMAC.pod new file mode 100644 index 0000000000..fcd9c9625a --- /dev/null +++ b/doc/man7/EVP_MAC-GMAC.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +EVP_MAC-GMAC - The GMAC EVP_MAC implementation + +=head1 DESCRIPTION + +Support for computing GMAC MACs through the B 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. + +The following parameter can be set with EVP_MAC_CTX_set_params(): + +=over 4 + +=item B ("key") + +=item B ("iv") + +=item B ("engine") + +=item B ("cipher") + +=item B ("properties") + +=back + +The following parameters can be retrieved with +EVP_MAC_CTX_get_params(): + +=over 4 + +=item B ("size") + +=back + +The "size" parameter can also be retrieved with EVP_MAC_size(). + +=head1 SEE ALSO + +L, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod new file mode 100644 index 0000000000..0fb92d329e --- /dev/null +++ b/doc/man7/EVP_MAC-HMAC.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +EVP_MAC-HMAC - The HMAC EVP_MAC implementation + +=head1 DESCRIPTION + +Support for computing HMAC MACs through the B 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. + +The following parameter can be set with EVP_MAC_CTX_set_params(): + +=over 4 + +=item B ("key") + +=item B ("flags") + +=item B ("engine") + +=item B ("digest") + +=item B ("properties") + +=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 ("size") + +=back + +The "size" parameter can also be retrieved with EVP_MAC_size(). + +=head1 SEE ALSO + +L, L, +L, L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod new file mode 100644 index 0000000000..71a3bf21c2 --- /dev/null +++ b/doc/man7/EVP_MAC-KMAC.pod @@ -0,0 +1,64 @@ +=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 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. + +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 ("key") + +=item B ("custom") + +=item B ("size") + +=item B + +=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, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod new file mode 100644 index 0000000000..02cbe0e4b4 --- /dev/null +++ b/doc/man7/EVP_MAC-Poly1305.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +EVP_MAC-Poly1305 - The Poly1305 EVP_MAC implementation + +=head1 DESCRIPTION + +Support for computing Poly1305 MACs through the B 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. + +The following parameter can be set with EVP_MAC_CTX_set_params(): + +=over 4 + +=item B ("key") + +=back + +The following parameters can be retrieved with +EVP_MAC_CTX_get_params(): + +=over 4 + +=item B ("size") + +=back + +The "size" parameter can also be retrieved with with EVP_MAC_size(). + +=head1 SEE ALSO + +L, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod new file mode 100644 index 0000000000..25e0a8fa38 --- /dev/null +++ b/doc/man7/EVP_MAC-Siphash.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +EVP_MAC-Siphash - The SipHash EVP_MAC implementation + +=head1 DESCRIPTION + +Support for computing SipHash MACs through the B 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. + +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 ("key") + +=item B ("size") + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=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. + +=cut diff --git a/doc/man7/EVP_MAC_BLAKE2.pod b/doc/man7/EVP_MAC_BLAKE2.pod deleted file mode 100644 index 2fc8051475..0000000000 --- a/doc/man7/EVP_MAC_BLAKE2.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_BLAKE2 - The BLAKE2 EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing BLAKE2 MACs through the B API. - -=head2 Numeric identity - -B and B 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 - -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 - -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 - -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_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, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_CMAC.pod b/doc/man7/EVP_MAC_CMAC.pod deleted file mode 100644 index cda3f3f515..0000000000 --- a/doc/man7/EVP_MAC_CMAC.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_CMAC - The CMAC EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing CMAC MACs through the B API. - -=head2 Numeric identity - -B 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_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 - -=item B - -These work as described in L. - -EVP_MAC_ctrl_str() type string for B: "cipher" - -The value is expected to be the name of a cipher. - -=back - -=head1 SEE ALSO - -L, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_GMAC.pod b/doc/man7/EVP_MAC_GMAC.pod deleted file mode 100644 index 6e4ba1a740..0000000000 --- a/doc/man7/EVP_MAC_GMAC.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_GMAC - The GMAC EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing GMAC MACs through the B API. - -=head2 Numeric identity - -B 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_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_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 - -=item B - -These work as described in L with the restriction that the -cipher must be an AEAD one. - -EVP_MAC_ctrl_str() type string for B: "cipher" - -The value is expected to be the name of a cipher. - -=back - -=head1 SEE ALSO - -L, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_HMAC.pod b/doc/man7/EVP_MAC_HMAC.pod deleted file mode 100644 index c8aa04756d..0000000000 --- a/doc/man7/EVP_MAC_HMAC.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_HMAC - The HMAC EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing HMAC MACs through the B API. - -=head2 Numeric identity - -B 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_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 - -Sets HMAC flags. This is passed directly to HMAC_CTX_set_flags(). - -There are no corresponding string control types. - -=item B - -=item B - -These work as described in L. - -EVP_MAC_ctrl_str() type string for B: "digest" - -The value is expected to be the name of a cipher. - -=back - -=head1 SEE ALSO - -L, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_KMAC.pod b/doc/man7/EVP_MAC_KMAC.pod deleted file mode 100644 index 4ccaabe6cb..0000000000 --- a/doc/man7/EVP_MAC_KMAC.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_KMAC - The KMAC EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing KMAC MACs through the B API. - -=head2 Numeric identity - -B and B 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 - -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 - -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_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_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, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_POLY1305.pod b/doc/man7/EVP_MAC_POLY1305.pod deleted file mode 100644 index 89234b74a4..0000000000 --- a/doc/man7/EVP_MAC_POLY1305.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_POLY1305 - The Poly1305 EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing Poly1305 MACs through the B API. - -=head2 Numeric identity - -B 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_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, L - -=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. - -=cut diff --git a/doc/man7/EVP_MAC_SIPHASH.pod b/doc/man7/EVP_MAC_SIPHASH.pod deleted file mode 100644 index eeb0cfd148..0000000000 --- a/doc/man7/EVP_MAC_SIPHASH.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -EVP_MAC_SIPHASH - The SipHash EVP_MAC implementation - -=head1 DESCRIPTION - -Support for computing SipHash MACs through the B API. - -=head2 Numeric identity - -B 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_str() type string: "digestsize" - -The value string is expected to contain a decimal number. - -=item B - -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, L - -=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. - -=cut -- 2.25.1