From: Richard Levitte Date: Fri, 6 Mar 2020 13:29:00 +0000 (+0100) Subject: DOCS: Move implementation specific docs away from provider-digest(7) X-Git-Tag: openssl-3.0.0-alpha1~298 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=1e55cbc874826af63e178a3fd26d23981599effe;p=oweals%2Fopenssl.git 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 (Merged from https://github.com/openssl/openssl/pull/11270) --- diff --git a/doc/man7/EVP_MD-BLAKE2.pod b/doc/man7/EVP_MD-BLAKE2.pod new file mode 100644 index 0000000000..be3b0b9286 --- /dev/null +++ b/doc/man7/EVP_MD-BLAKE2.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +EVP_MD-BLAKE2 - The BLAKE2 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing SHA2 digests through the B API. + +=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 + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-MD2.pod b/doc/man7/EVP_MD-MD2.pod new file mode 100644 index 0000000000..61fc42fc4d --- /dev/null +++ b/doc/man7/EVP_MD-MD2.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +EVP_MD-MD2 - The MD2 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing MD2 digests through the B API. + +=head2 Identity + +This implementation is only available with the legacy provider, and is +identified with the name "MD2". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-MD4.pod b/doc/man7/EVP_MD-MD4.pod new file mode 100644 index 0000000000..0a3f97c47b --- /dev/null +++ b/doc/man7/EVP_MD-MD4.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +EVP_MD-MD4 - The MD4 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing MD4 digests through the B API. + +=head2 Identity + +This implementation is only available with the legacy provider, and is +identified with the name "MD4". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-MD5-SHA1.pod b/doc/man7/EVP_MD-MD5-SHA1.pod new file mode 100644 index 0000000000..61652ad5c6 --- /dev/null +++ b/doc/man7/EVP_MD-MD5-SHA1.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +EVP_MD-MD5-SHA1 - The MD5-SHA1 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing MD5-SHA1 digests through the B API. + +MD5-SHA1 is a rather special digest that's used with SSLv3. + +=head2 Identity + +This implementation is only available with the default provider, and is +identified with the name "MD5-SHA1". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head2 Settable Context Parameters + +This implementation supports the following L entries, +settable for an B with L: + +=over 4 + +=item "ssl3-ms" (B) + +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per RFC6101. +It is only set after all handshake messages have already been digested via +OP_digest_update() calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per RFC6101 +section 5.6.8. +The next call after setting this parameter should be OP_digest_final(). + +=back + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-MD5.pod b/doc/man7/EVP_MD-MD5.pod new file mode 100644 index 0000000000..98ae2c5be5 --- /dev/null +++ b/doc/man7/EVP_MD-MD5.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +EVP_MD-MD5 - The MD5 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing MD5 digests through the B API. + +=head2 Identity + +This implementation is only available with the default provider, and is +identified with the name "MD5". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-MDC2.pod b/doc/man7/EVP_MD-MDC2.pod new file mode 100644 index 0000000000..516e19da19 --- /dev/null +++ b/doc/man7/EVP_MD-MDC2.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +EVP_MD-MDC2 - The MDC2 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing MDC2 digests through the B API. + +=head2 Identity + +This implementation is only available with the legacy provider, and is +identified with the name "MDC2". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head2 Settable Context Parameters + +This implementation supports the following L entries, +settable for an B with L: + +=over 4 + +=item "pad_type" (B) + +Sets the padding type to be used. +Normally the final MDC2 block is padded with zeros. +If the pad type is set to 2 then the final block is padded with 0x80 followed by +zeros. + +=back + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-RIPEMD160.pod b/doc/man7/EVP_MD-RIPEMD160.pod new file mode 100644 index 0000000000..0504e9b302 --- /dev/null +++ b/doc/man7/EVP_MD-RIPEMD160.pod @@ -0,0 +1,35 @@ +=pod + +=head1 NAME + +EVP_MD-RIPEMD160 - The RIPEMD160 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing RIPEMD160 digests through the B API. + +=head2 Identities + +This implementation is only available with the legacy provider, and is +identified with any of the names "RIPEMD-160", "RIPEMD160", "RIPEMD" and +"RMD160". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-SHA1.pod b/doc/man7/EVP_MD-SHA1.pod new file mode 100644 index 0000000000..5fd94df4ce --- /dev/null +++ b/doc/man7/EVP_MD-SHA1.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +EVP_MD-SHA1 - The SHA1 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing SHA1 digests through the B API. + +=head2 Identities + +This implementation is available with the FIPS provider as well as the +default provider, and is identified with the names "SHA1" and "SHA-1". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head2 Settable Context Parameters + +This implementation supports the following L entries, +settable for an B with L: + +=over 4 + +=item "ssl3-ms" (B) + +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per RFC6101. +It is only set after all handshake messages have already been digested via +OP_digest_update() calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per RFC6101 +section 5.6.8. +The next call after setting this parameter should be OP_digest_final(). + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-SHA2.pod b/doc/man7/EVP_MD-SHA2.pod new file mode 100644 index 0000000000..2a2e799d89 --- /dev/null +++ b/doc/man7/EVP_MD-SHA2.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +EVP_MD-SHA2 - The SHA2 EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing SHA2 digests through the B API. + +=head2 Identities + +This implementation includes the following varieties: + +=over 4 + +=item * + +Available with the FIPS provider as well as the default provider: + +=over 4 + +=item SHA2-224 + +Known names are "SHA2-224", "SHA-224" and "SHA224". + +=item SHA2-256 + +Known names are "SHA2-256", "SHA-256" and "SHA256". + +=item SHA2-384 + +Known names are "SHA2-384", "SHA-384" and "SHA384". + +=item SHA2-512 + +Known names are "SHA2-512", "SHA-512" and "SHA512". + +=back + +=item * + +Available with the default provider: + +=over 4 + +=item SHA2-512/224 + +Known names are "SHA2-512/224", "SHA-512/224" and "SHA512-224". + +=item SHA2-512/256 + +Known names are "SHA2-512/256", "SHA-512/256" and "SHA512-256". + +=back + +=back + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-SHA3.pod b/doc/man7/EVP_MD-SHA3.pod new file mode 100644 index 0000000000..bc5c3508be --- /dev/null +++ b/doc/man7/EVP_MD-SHA3.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +EVP_MD-SHA3 - The SHA3 EVP_MD implementations + +=head1 DESCRIPTION + +Support for computing SHA3 digests through the B API. + +=head2 Identities + +This implementation is available with the FIPS provider as well as the +default provider, and includes the following varieties: + +=over 4 + +=item "SHA3-224" + +=item "SHA3-256" + +=item "SHA3-384" + +=item "SHA3-512" + +=back + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-SHAKE.pod b/doc/man7/EVP_MD-SHAKE.pod new file mode 100644 index 0000000000..2426d5a4a2 --- /dev/null +++ b/doc/man7/EVP_MD-SHAKE.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +EVP_MD-SHAKE, EVP_MD-KECCAK-KMAC +- The SHAKE / KECCAK family EVP_MD implementations + +=head1 DESCRIPTION + +Support for computing SHAKE or KECCAK-KMAC digests through the +B API. + +KECCAK-KMAC is a special digest that's used by the KMAC EVP_MAC +implementation (see L). + +=head2 Identities + +This implementation is only available with the default provider, and +includes the following varieties: + +=over 4 + +=item KECCAK-KMAC-128 + +Known names are "KECCAK-KMAC-128" and "KECCAK-KMAC128" + +=item KECCAK-KMAC-256 + +Known names are "KECCAK-KMAC-256" and "KECCAK-KMAC256" + +=item SHAKE-128 + +Known names are "SHAKE-128" and "SHAKE128" + +=item SHAKE-256 + +Known names are "SHAKE-256" and "SHAKE256" + +=back + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head2 Settable Context Parameters + +These implementations support the following L entries, +settable for an B with L: + +=over 4 + +=item "xoflen" (B) + +Sets the digest length for extendable output functions. +The length of the "xoflen" parameter should not exceed that of a B. + +=back + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-SM3.pod b/doc/man7/EVP_MD-SM3.pod new file mode 100644 index 0000000000..355c52ec84 --- /dev/null +++ b/doc/man7/EVP_MD-SM3.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +EVP_MD-SM3 - The SM3 EVP_MD implementations + +=head1 DESCRIPTION + +Support for computing SM3 digests through the B API. + +=head2 Identity + +This implementation is only available with the default provider, and is +identified with the name "SM3". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-WHIRLPOOL.pod b/doc/man7/EVP_MD-WHIRLPOOL.pod new file mode 100644 index 0000000000..2252ab2dba --- /dev/null +++ b/doc/man7/EVP_MD-WHIRLPOOL.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +EVP_MD-WHIRLPOOL - The WHIRLPOOL EVP_MD implementation + +=head1 DESCRIPTION + +Support for computing WHIRLPOOL digests through the B API. + +=head2 Identity + +This implementation is only available with the legacy provider, and is +identified with the name "WHIRLPOOL". + +=head2 Gettable Parameters + +This implementation supports the common gettable parameters described +in L. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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_MD-common.pod b/doc/man7/EVP_MD-common.pod new file mode 100644 index 0000000000..783844988b --- /dev/null +++ b/doc/man7/EVP_MD-common.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +EVP_MD-common - The OpenSSL EVP_MD implementations, common things + +=head1 DESCRIPTION + +All the OpenSSL EVP_MD implementations understand the following +L entries: + +=over 4 + +Gettable with L: + +=over 4 + +=item "blocksize" (B) + +The digest block size. +The length of the "blocksize" parameter should not exceed that of a +B. + +This value can also be retrieved with L. + +=item "size" (B) + +The digest output size. +The length of the "size" parameter should not exceed that of a B. + +This value can also be retrieved with L. + +=item "flags" (B) + +Diverse flags that describe exceptional behaviour for the digest. +These flags are described in L. + +The length of the "flags" parameter should equal that of an +B. + +=begin comment + +The description of these flags should probably be moved. Also, +EVP_MD_FLAG_FIPS isn't relevant any more. + +=end comment + +This value can also be retrieved with L. + +=back + +=back + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2020 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/provider-digest.pod b/doc/man7/provider-digest.pod index 576ea581b4..1cac58b4bb 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -227,44 +227,6 @@ values associated with the give provider side digest context I and stores them in I. See L for further details on the parameters structure. -Parameters currently recognised by built-in digests are as follows. Not all -parameters are relevant to, or are understood by all digests: - -=over 4 - -=item "xoflen" (B) - -Sets the digest length for extendable output functions. -The length of the "xoflen" parameter should not exceed that of a B. - -=item "ssl3-ms" (B) - -This parameter is set by libssl in order to calculate a signature hash for an -SSLv3 CertificateVerify message as per RFC6101. -It is only set after all handshake messages have already been digested via -OP_digest_update() calls. -The parameter provides the master secret value to be added to the digest. -The digest implementation should calculate the complete digest as per RFC6101 -section 5.6.8. -The next call after setting this parameter will be OP_digest_final(). -This is only relevant for implementations of SHA1 or MD5_SHA1. - -=item "pad_type" (B) - -Sets the pad type to be used. -The only built-in digest that uses this is MDC2. -Normally the final MDC2 block is padded with 0s. -If the pad type is set to 2 then the final block is padded with 0x80 followed by -0s. - -=item "micalg" (B) - -Gets the digest Message Integrity Check algorithm string. -This is used when creating S/MIME multipart/signed messages, as specified in -RFC 5751. - -=back - =head1 RETURN VALUES OP_digest_newctx() and OP_digest_dupctx() should return the newly created @@ -281,7 +243,8 @@ algorithm. =head1 SEE ALSO -L +L, L, L, +L =head1 HISTORY diff --git a/providers/implementations/digests/sha3_prov.c b/providers/implementations/digests/sha3_prov.c index 44471959a7..e6b9ba7a3d 100644 --- a/providers/implementations/digests/sha3_prov.c +++ b/providers/implementations/digests/sha3_prov.c @@ -247,7 +247,7 @@ static void *keccak_dupctx(void *ctx) } static const OSSL_PARAM known_shake_settable_ctx_params[] = { - {OSSL_DIGEST_PARAM_SSL3_MS, OSSL_PARAM_OCTET_STRING, NULL, 0, 0}, + {OSSL_DIGEST_PARAM_XOFLEN, OSSL_PARAM_UNSIGNED_INTEGER, NULL, 0, 0}, OSSL_PARAM_END }; static const OSSL_PARAM *shake_settable_ctx_params(void)