Browse Source

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)
master
Richard Levitte 2 years ago
parent
commit
1e55cbc874
16 changed files with 678 additions and 40 deletions
  1. +46
    -0
      doc/man7/EVP_MD-BLAKE2.pod
  2. +34
    -0
      doc/man7/EVP_MD-MD2.pod
  3. +34
    -0
      doc/man7/EVP_MD-MD4.pod
  4. +56
    -0
      doc/man7/EVP_MD-MD5-SHA1.pod
  5. +34
    -0
      doc/man7/EVP_MD-MD5.pod
  6. +50
    -0
      doc/man7/EVP_MD-MDC2.pod
  7. +35
    -0
      doc/man7/EVP_MD-RIPEMD160.pod
  8. +55
    -0
      doc/man7/EVP_MD-SHA1.pod
  9. +77
    -0
      doc/man7/EVP_MD-SHA2.pod
  10. +46
    -0
      doc/man7/EVP_MD-SHA3.pod
  11. +73
    -0
      doc/man7/EVP_MD-SHAKE.pod
  12. +34
    -0
      doc/man7/EVP_MD-SM3.pod
  13. +34
    -0
      doc/man7/EVP_MD-WHIRLPOOL.pod
  14. +67
    -0
      doc/man7/EVP_MD-common.pod
  15. +2
    -39
      doc/man7/provider-digest.pod
  16. +1
    -1
      providers/implementations/digests/sha3_prov.c

+ 46
- 0
doc/man7/EVP_MD-BLAKE2.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 34
- 0
doc/man7/EVP_MD-MD2.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 34
- 0
doc/man7/EVP_MD-MD4.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 56
- 0
doc/man7/EVP_MD-MD5-SHA1.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head2 Settable Context Parameters
This implementation supports the following L<OSSL_PARAM(3)> entries,
settable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>:
=over 4
=item "ssl3-ms" (B<OSSL_DIGEST_PARAM_SSL3_MS>) <octet string>
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<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 34
- 0
doc/man7/EVP_MD-MD5.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 50
- 0
doc/man7/EVP_MD-MDC2.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head2 Settable Context Parameters
This implementation supports the following L<OSSL_PARAM(3)> entries,
settable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>:
=over 4
=item "pad_type" (B<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer>
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<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-legacy(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 35
- 0
doc/man7/EVP_MD-RIPEMD160.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 55
- 0
doc/man7/EVP_MD-SHA1.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head2 Settable Context Parameters
This implementation supports the following L<OSSL_PARAM(3)> entries,
settable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>:
=over 4
=item "ssl3-ms" (B<OSSL_DIGEST_PARAM_SSL3_MS>) <octet string>
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<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>,
L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 77
- 0
doc/man7/EVP_MD-SHA2.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 46
- 0
doc/man7/EVP_MD-SHA3.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 73
- 0
doc/man7/EVP_MD-SHAKE.pod View File

@ -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<EVP_MD> API.
KECCAK-KMAC is a special digest that's used by the KMAC EVP_MAC
implementation (see L<EVP_MAC-KMAC(7)>).
=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<EVP_MD-common(7)>.
=head2 Settable Context Parameters
These implementations support the following L<OSSL_PARAM(3)> entries,
settable for an B<EVP_MD_CTX> with L<EVP_MD_CTX_set_params(3)>:
=over 4
=item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer>
Sets the digest length for extendable output functions.
The length of the "xoflen" parameter should not exceed that of a B<size_t>.
=back
=head1 SEE ALSO
L<EVP_MD_CTX_set_params(3)>, L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 34
- 0
doc/man7/EVP_MD-SM3.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 34
- 0
doc/man7/EVP_MD-WHIRLPOOL.pod View File

@ -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<EVP_MD> 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<EVP_MD-common(7)>.
=head1 SEE ALSO
L<provider-digest(7)>, L<OSSL_PROVIDER-default(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 67
- 0
doc/man7/EVP_MD-common.pod View File

@ -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<OSSL_PARAM(3)> entries:
=over 4
Gettable with L<EVP_MD_get_params(3)>:
=over 4
=item "blocksize" (B<OSSL_DIGEST_PARAM_BLOCK_SIZE>) <unsigned integer>
The digest block size.
The length of the "blocksize" parameter should not exceed that of a
B<size_t>.
This value can also be retrieved with L<EVP_MD_block_size(3)>.
=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer>
The digest output size.
The length of the "size" parameter should not exceed that of a B<size_t>.
This value can also be retrieved with L<EVP_MD_size(3)>.
=item "flags" (B<OSSL_DIGEST_PARAM_FLAGS>) <unsigned integer>
Diverse flags that describe exceptional behaviour for the digest.
These flags are described in L<EVP_MD_meth_set_flags(3)/DESCRIPTION>.
The length of the "flags" parameter should equal that of an
B<unsigned long int>.
=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<EVP_MD_flags(3)>.
=back
=back
=head1 SEE ALSO
L<EVP_MD_get_params(3)>, L<provider-digest(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

+ 2
- 39
doc/man7/provider-digest.pod View File

@ -227,44 +227,6 @@ values associated with the give provider side digest context I<dctx>
and stores them in I<params>.
See L<OSSL_PARAM(3)> 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<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer>
Sets the digest length for extendable output functions.
The length of the "xoflen" parameter should not exceed that of a B<size_t>.
=item "ssl3-ms" (B<OSSL_DIGEST_PARAM_SSL3_MS>) <octet string>
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<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer>
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<OSSL_DIGEST_PARAM_MICALG>) <UTF8 string>
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<provider(7)>
L<provider(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>,
L<OSSL_PROVIDER-legacy(7)>
=head1 HISTORY


+ 1
- 1
providers/implementations/digests/sha3_prov.c View File

@ -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)


Loading…
Cancel
Save