From 13b3cd7bc77d5d9297a755727100aee22d3e22b6 Mon Sep 17 00:00:00 2001 From: Antoine Salon Date: Thu, 20 Dec 2018 15:34:22 -0800 Subject: [PATCH] blake2: add EVP_MAC man page Signed-off-by: Antoine Salon Reviewed-by: Richard Levitte Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/7726) --- doc/man3/EVP_MAC.pod | 17 +++--- doc/man7/EVP_MAC_BLAKE2.pod | 114 ++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 7 deletions(-) create mode 100644 doc/man7/EVP_MAC_BLAKE2.pod 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 bytes from C 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 -This control expects two arguments: C, C +This control expects two arguments: C, C -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 + +This control expects two arguments: C, C + +This option is used by BLAKE2 MAC. + =item B This control expects one argument: C This option is used by KMAC. - =item B This control expects one argument: C @@ -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, L, L, L, 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 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.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 -- 2.25.1