root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man7/EVP_MD-BLAKE2.pod

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

85 lines
2.0 KiB
Plaintext
Raw Normal View History

DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
=pod
=head1 NAME
EVP_MD-BLAKE2 - The BLAKE2 EVP_MD implementation
=head1 DESCRIPTION
Fix typo in EVP_MD-BLAKE2(7) Reviewed-by: Todd Short <todd.short@me.com> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/17790)
2022-03-02 01:48:11 +08:00
Support for computing BLAKE2 digests through the B<EVP_MD> API.
DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
=head2 Identities
This implementation is only available with the default provider, and
includes the following varieties:
=over 4
=item BLAKE2S-256
Known names are "BLAKE2S-256" and "BLAKE2s256".
=item BLAKE2B-512
Known names are "BLAKE2B-512" and "BLAKE2b512".
=back
Add EVP_DigestSqueeze() API. Fixes #7894 This allows SHAKE to squeeze multiple times with different output sizes. The existing EVP_DigestFinalXOF() API has been left as a one shot operation. A similar interface is used by another toolkit. The low level SHA3_Squeeze() function needed to change slightly so that it can handle multiple squeezes. This involves changing the assembler code so that it passes a boolean to indicate whether the Keccak function should be called on entry. At the provider level, the squeeze is buffered, so that it only requests a multiple of the blocksize when SHA3_Squeeze() is called. On the first call the value is zero, on subsequent calls the value passed is 1. This PR is derived from the excellent work done by @nmathewson in https://github.com/openssl/openssl/pull/7921 Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/21511)
2023-07-21 13:05:38 +08:00
=head2 Settable Parameters
"BLAKE2B-512" supports the following EVP_MD_CTX_set_params() key
XOF / EVP_MD_size() changes. Added the function EVP_MD_CTX_get_size_ex() which checks for XOF and does a ctx get rather than just returning EVP_MD_size(). SHAKE did not have a get_ctx_params() so that had to be added to return the xoflen. Added a helper function EVP_MD_xof() EVP_MD_CTX_size() was just an aliased macro for EVP_MD_size(), so to keep it the same I added an extra function. EVP_MD_size() always returns 0 for SHAKE now, since it caches the value of md_size at the time of an EVP_MD_fetch(). This is probably better than returning the incorrect initial value it was before e.g (16 for SHAKE128) and returning tht always instead of the set xoflen. Note BLAKE2B uses "size" instead of "xoflen" to do a similar thing. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/25285)
2024-08-26 07:38:56 +08:00
described in L<EVP_DigestInit(3)/PARAMETERS>.
Add EVP_DigestSqueeze() API. Fixes #7894 This allows SHAKE to squeeze multiple times with different output sizes. The existing EVP_DigestFinalXOF() API has been left as a one shot operation. A similar interface is used by another toolkit. The low level SHA3_Squeeze() function needed to change slightly so that it can handle multiple squeezes. This involves changing the assembler code so that it passes a boolean to indicate whether the Keccak function should be called on entry. At the provider level, the squeeze is buffered, so that it only requests a multiple of the blocksize when SHA3_Squeeze() is called. On the first call the value is zero, on subsequent calls the value passed is 1. This PR is derived from the excellent work done by @nmathewson in https://github.com/openssl/openssl/pull/7921 Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/21511)
2023-07-21 13:05:38 +08:00
=over 4
XOF / EVP_MD_size() changes. Added the function EVP_MD_CTX_get_size_ex() which checks for XOF and does a ctx get rather than just returning EVP_MD_size(). SHAKE did not have a get_ctx_params() so that had to be added to return the xoflen. Added a helper function EVP_MD_xof() EVP_MD_CTX_size() was just an aliased macro for EVP_MD_size(), so to keep it the same I added an extra function. EVP_MD_size() always returns 0 for SHAKE now, since it caches the value of md_size at the time of an EVP_MD_fetch(). This is probably better than returning the incorrect initial value it was before e.g (16 for SHAKE128) and returning tht always instead of the set xoflen. Note BLAKE2B uses "size" instead of "xoflen" to do a similar thing. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/25285)
2024-08-26 07:38:56 +08:00
=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer>
Add EVP_DigestSqueeze() API. Fixes #7894 This allows SHAKE to squeeze multiple times with different output sizes. The existing EVP_DigestFinalXOF() API has been left as a one shot operation. A similar interface is used by another toolkit. The low level SHA3_Squeeze() function needed to change slightly so that it can handle multiple squeezes. This involves changing the assembler code so that it passes a boolean to indicate whether the Keccak function should be called on entry. At the provider level, the squeeze is buffered, so that it only requests a multiple of the blocksize when SHA3_Squeeze() is called. On the first call the value is zero, on subsequent calls the value passed is 1. This PR is derived from the excellent work done by @nmathewson in https://github.com/openssl/openssl/pull/7921 Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/21511)
2023-07-21 13:05:38 +08:00
=back
DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
=head2 Gettable Parameters
This implementation supports the common gettable parameters described
in L<EVP_MD-common(7)>.
Blake2b: Use OSSL_DIGEST_PARAM_SIZE as settable instead of XOFLEN BLAKE2 is not really an extensible output function unlike SHAKE as the digest size must be set during the context initialization. Thus it makes no sense to use OSSL_DIGEST_PARAM_XOFLEN. We also need to adjust EVP_DigestFinal_ex() to query the OSSL_DIGEST_PARAM_SIZE as gettable ctx param for the size. Fixes #22488 Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tim Hudson <tjh@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/22491)
2023-10-24 19:44:26 +08:00
=head2 Settable Context Parameters
Properly limit the variable output size for BLAKE2 The upper limit of the output size is the default output size of the respective algorithm variants. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/22659)
2023-11-08 17:14:08 +08:00
The implementation supports the following L<OSSL_PARAM(3)> entries which
are settable for an B<EVP_MD_CTX> with L<EVP_DigestInit_ex2(3)> or
L<EVP_MD_CTX_set_params(3)>:
Blake2b: Use OSSL_DIGEST_PARAM_SIZE as settable instead of XOFLEN BLAKE2 is not really an extensible output function unlike SHAKE as the digest size must be set during the context initialization. Thus it makes no sense to use OSSL_DIGEST_PARAM_XOFLEN. We also need to adjust EVP_DigestFinal_ex() to query the OSSL_DIGEST_PARAM_SIZE as gettable ctx param for the size. Fixes #22488 Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tim Hudson <tjh@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/22491)
2023-10-24 19:44:26 +08:00
=over 4
=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer>
Sets a different digest length for the L<EVP_DigestFinal(3)> output.
Properly limit the variable output size for BLAKE2 The upper limit of the output size is the default output size of the respective algorithm variants. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/22659)
2023-11-08 17:14:08 +08:00
The value of the "size" parameter must not exceed the default digest length
of the respective BLAKE2 algorithm variants, 64 for BLAKE2B-512 and
32 for BLAKE2S-256. The parameter must be set with the
L<EVP_DigestInit_ex2(3)> call to have an immediate effect. When set with
L<EVP_MD_CTX_set_params(3)> it will have an effect only if the B<EVP_MD_CTX>
context is reinitialized.
Blake2b: Use OSSL_DIGEST_PARAM_SIZE as settable instead of XOFLEN BLAKE2 is not really an extensible output function unlike SHAKE as the digest size must be set during the context initialization. Thus it makes no sense to use OSSL_DIGEST_PARAM_XOFLEN. We also need to adjust EVP_DigestFinal_ex() to query the OSSL_DIGEST_PARAM_SIZE as gettable ctx param for the size. Fixes #22488 Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tim Hudson <tjh@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/22491)
2023-10-24 19:44:26 +08:00
=back
DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
Properly limit the variable output size for BLAKE2 The upper limit of the output size is the default output size of the respective algorithm variants. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/22659)
2023-11-08 17:14:08 +08:00
=head1 HISTORY
This functionality was added in OpenSSL 3.0.
The variable size support was added in OpenSSL 3.2 for BLAKE2B-512 and
in OpenSSL 3.3 for BLAKE2S-256.
DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
=head1 COPYRIGHT
Copyright year updates Reviewed-by: Neil Horman <nhorman@openssl.org> Release: yes
2024-09-05 15:35:49 +08:00
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
DOCS: Move implementation specific docs away from provider-digest(7) The provider- manuals are meant to describe the general interface for their respective operation. This is not the place to describe implementation specific details. This change creates a number of doc/man7/EVP_MD manuals, one for each algorithm or set of algorithms, as well as doc/man7/EVP_MD-common.pod to describe what's common to them all. While we're at it, correct the SHA3 settable context params array to match what's actually settable. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11270)
2020-03-06 21:29:00 +08:00
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