diff options
| -rw-r--r-- | doc/man3/EVP_MAC.pod | 17 | ||||
| -rw-r--r-- | doc/man7/EVP_MAC_BLAKE2.pod | 114 |
2 files changed, 124 insertions, 7 deletions
diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 0e0d749b51..32bf5896f8 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -87,9 +87,6 @@ through diverse controls. This should be called before calling EVP_MAC_update() and EVP_MAC_final(). -EVP_MAC_reset() resets the computation for the given context. -This may not be supported by the MAC implementation. - EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input. EVP_MAC_final() does the final computation and stores the result in @@ -171,18 +168,23 @@ Some MAC implementations require an IV, this control sets the IV. =item B<EVP_MAC_CTRL_SET_CUSTOM> -This control expects two arguments: C<unsigned char *key>, C<size_t keylen> +This control expects two arguments: C<unsigned char *custom>, C<size_t customlen> -Some MAC implementations (KMAC) require an Customization String, +Some MAC implementations (KMAC, BLAKE2) accept a Customization String, this control sets the Customization String. The default value is "". +=item B<EVP_MAC_CTRL_SET_SALT> + +This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen> + +This option is used by BLAKE2 MAC. + =item B<EVP_MAC_CTRL_SET_XOF> This control expects one argument: C<int xof> This option is used by KMAC. - =item B<EVP_MAC_CTRL_SET_FLAGS> This control expects one argument: C<unsigned long flags> @@ -231,7 +233,7 @@ created EVP_MAC_CTX, or NULL if allocation failed. EVP_MAC_CTX_free() returns nothing at all. -EVP_MAC_CTX_copy(), EVP_MAC_reset(), EVP_MAC_init(), EVP_MAC_update(), +EVP_MAC_CTX_copy(), EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0 on error. EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and @@ -346,6 +348,7 @@ F<./foo>) =head1 SEE ALSO +L<EVP_MAC_BLAKE2(7)>, L<EVP_MAC_CMAC(7)>, L<EVP_MAC_GMAC(7)>, L<EVP_MAC_HMAC(7)>, diff --git a/doc/man7/EVP_MAC_BLAKE2.pod b/doc/man7/EVP_MAC_BLAKE2.pod new file mode 100644 index 0000000000..58b4f99373 --- /dev/null +++ b/doc/man7/EVP_MAC_BLAKE2.pod @@ -0,0 +1,114 @@ +=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.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 |