DOCS: Start restructuring our provider and implementation documentation
authorRichard Levitte <levitte@openssl.org>
Fri, 6 Mar 2020 13:25:42 +0000 (14:25 +0100)
committerRichard Levitte <levitte@openssl.org>
Tue, 10 Mar 2020 12:31:06 +0000 (13:31 +0100)
This adds doc/man7/OSSL_PROVIDER-default.pod and OSSL_PROVIDER-legacy.pod,
and fills in currently implemented operations and algorithms in them, as
well as in doc/man7/OSSL_PROVIDER-FIPS.pod, with links to documentation to
come.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11270)

doc/man7/OSSL_PROVIDER-FIPS.pod
doc/man7/OSSL_PROVIDER-default.pod [new file with mode: 0644]
doc/man7/OSSL_PROVIDER-legacy.pod [new file with mode: 0644]

index 1cb75e7..56844de 100644 (file)
 
 =head1 NAME
 
 
 =head1 NAME
 
-OSSL_PROVIDER-FIPS - OPENSSL FIPS provider
+OSSL_PROVIDER-FIPS - OpenSSL FIPS provider
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 
-The OPENSSL FIPS provider is a special provider that conforms to the Federal 
+The OpenSSL FIPS provider is a special provider that conforms to the Federal 
 Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module'
 contains an approved set of cryptographic algorithms that is validated by an
 accredited testing laboratory.
 
 Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module'
 contains an approved set of cryptographic algorithms that is validated by an
 accredited testing laboratory.
 
+=head2 Properties
+
+The implementations in this provider specifically have these properties
+defined:
+
+=over 4
+
+"provider=default"
+
+"fips=yes"
+
+=back
+
+It may be used in a property query string with fetching functions such as
+L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other
+functions that take a property query string, such as
+L<EVP_PKEY_CTX_new_from_name(3)>.
+
+It isn't mandatory to query for any of these properties, except to
+make sure to get implementations of this provider and none other.
+
+The "fips=yes" property can be use to make sure only FIPS approved
+implementations are used for crypto operations.  This may also include
+other non-crypto support operations that are not in the fips provider,
+such as asymmetric key serializers,
+see L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>.
+
+=head1 OPERATIONS AND ALGORITHMS
+
+The OpenSSL FIPS provider supports these operations and algorithms:
+
+=head2 Hashing Algorithms / Message Digests
+
+=over 4
+
+=item SHA1, see L<EVP_MD-SHA1(7)>
+
+=item SHA2, see L<EVP_MD-SHA2(7)>
+
+=item SHA3, see L<EVP_MD-SHA3(7)>
+
+=item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)>
+
+=back
+
+=head2 Symmetric Ciphers
+
+=over 4
+
+=item AES, see L<EVP_CIPHER-AES(7)>
+
+=item DES-EDE3 (TrippleDES), see L<EVP_CIPHER-DES(7)>
+
+=back
+
+=head2 Message Authentication Code (MAC)
+
+=over 4
+
+=item CMAC, see L<EVP_MAC-CMAC(7)>
+
+=item GMAC, see L<EVP_MAC-GMAC(7)>
+
+=item HMAC, see L<EVP_MAC-HMAC(7)>
+
+=item KMAC, see L<EVP_MAC-KMAC(7)>
+
+=back
+
+=head2 Key Derivation Function (KDF)
+
+=over 4
+
+=item HKDF, see L<EVP_KDF-HKDF(7)>
+
+=item SSKDF, see L<EVP_KDF-SSKDF(7)>
+
+=item PBKDF2, see L<EVP_KDF-PBKDF2(7)>
+
+=item TLS1-PRF, see L<EVP_KDF-TLS1-PRF(7)>
+
+=item KBKDF, see L<EVP_KDF-KBKDF(7)>
+
+=back
+
+=head2 Key Exchange
+
+=over 4
+
+=item DH, see L<EVP_KEYEXCH-DH(7)>
+
+=back
+
+=head2 Asymmetric Signature
+
+=over 4
+
+=item DSA, see L<EVP_KEYEXCH-DSA(7)>
+
+=back
+
+=head2 Asymmetric Cipher
+
+=over 4
+
+=item RSA, see L<EVP_KEYEXCH-RSA(7)>
+
+=back
+
+=head2 Asymmetric Key Management
+
+=over 4
+
+=item DH, see L<EVP_KEYMGMT-DH(7)>
+
+=item DSA, see L<EVP_KEYMGMT-DSA(7)>
+
+=item RSA, see L<EVP_KEYMGMT-RSA(7)>
+
+=back
+
 =head1 SELF TESTING
 
 One of the requirements for the FIPS module is self testing. An optional callback
 =head1 SELF TESTING
 
 One of the requirements for the FIPS module is self testing. An optional callback
@@ -19,7 +140,7 @@ L<OSSL_SELF_TEST_set_callback(3)>.
 
 The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)>
 
 
 The parameters passed to the callback are described in L<OSSL_SELF_TEST_new(3)>
 
-The OPENSSL FIPS module uses the following mechanism to provide information
+The OpenSSL FIPS module uses the following mechanism to provide information
 about the self tests as they run.
 This is useful for debugging if a self test is failing.
 The callback also allows forcing any self test to fail, in order to check that
 about the self tests as they run.
 This is useful for debugging if a self test is failing.
 The callback also allows forcing any self test to fail, in order to check that
@@ -196,7 +317,9 @@ L<fips_config(5)>,
 L<OSSL_SELF_TEST_set_callback(3)>,
 L<OSSL_SELF_TEST_new(3)>,
 L<OSSL_PARAM(3)>,
 L<OSSL_SELF_TEST_set_callback(3)>,
 L<OSSL_SELF_TEST_new(3)>,
 L<OSSL_PARAM(3)>,
-L<openssl-core.h(7)>
+L<openssl-core.h(7)>,
+L<openssl-core_numbers.h(7)>,
+L<provider(7)>
 
 =head1 HISTORY
 
 
 =head1 HISTORY
 
diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod
new file mode 100644 (file)
index 0000000..acfd4d0
--- /dev/null
@@ -0,0 +1,226 @@
+=pod
+
+=head1 NAME
+
+OSSL_PROVIDER-default - OpenSSL default provider
+
+=head1 DESCRIPTION
+
+The OpenSSL default provider supplies the majority of OpenSSL's diverse
+algorithm implementations.  It also acts as a fallback when no other
+provider has been loaded.
+
+=head2 Properties
+
+The implementations in this provider specifically have this property
+defined:
+
+=over 4
+
+"provider=default"
+
+=back
+
+It may be used in a property query string with fetching functions such as
+L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other
+functions that take a property query string, such as
+L<EVP_PKEY_CTX_new_from_name(3)>.
+
+It isn't mandatory to query for this property, except to make sure to get
+implementations of this provider and none other.
+
+Some implementations may define additional properties.  Exact information is
+listed below
+
+=head1 OPERATIONS AND ALGORITHMS
+
+The OpenSSL default provider supports these operations and algorithms:
+
+=head2 Hashing Algorithms / Message Digests
+
+=over 4
+
+=item SHA1, see L<EVP_MD-SHA1(7)>
+
+=item SHA2, see L<EVP_MD-SHA2(7)>
+
+=item SHA3, see L<EVP_MD-SHA3(7)>
+
+=item KECCAK-KMAC, see L<EVP_MD-KECCAK-KMAC(7)>
+
+=item SHAKE, see L<EVP_MD-SHAKE(7)>
+
+=item BLAKE2, see L<EVP_MD-BLAKE2(7)>
+
+=item SM3, see L<EVP_MD-SM3(7)>
+
+=item MD5, see L<EVP_MD-MD5(7)>
+
+=item MD5-SHA1, see L<EVP_MD-MD5-SHA1(7)>
+
+=back
+
+=head2 Symmetric Ciphers
+
+=over 4
+
+=item AES, see L<EVP_CIPHER-AES(7)>
+
+=item ARIA, see L<EVP_CIPHER-ARIA(7)>
+
+=item CAMELLIA, see L<EVP_CIPHER-CAMELLIA(7)>
+
+=item DES, see L<EVP_CIPHER-DES(7)>
+
+=item BF, see L<EVP_CIPHER-BF(7)>
+
+=item IDEA, see L<EVP_CIPHER-IDEA(7)>
+
+=item CAST5, see L<EVP_CIPHER-CAST5(7)>
+
+=item SEED, see L<EVP_CIPHER-SEED(7)>
+
+=item SM4, see L<EVP_CIPHER-SM4(7)>
+
+=item RC2, see L<EVP_CIPHER-RC2(7)>
+
+=item RC4, see L<EVP_CIPHER-RC4(7)>
+
+=item RC5, see L<EVP_CIPHER-RC5(7)>
+
+=item ChaCha20, see L<EVP_CIPHER-ChaCha20(7)>
+
+=item ChaCha20-Poly1305, see L<EVP_CIPHER-ChaCha20-Poly1305(7)>
+
+=back
+
+=head2 Message Authentication Code (MAC)
+
+=over 4
+
+=item BLAKE2, see L<EVP_MAC-BLAKE2(7)>
+
+=item CMAC, see L<EVP_MAC-CMAC(7)>
+
+=item GMAC, see L<EVP_MAC-GMAC(7)>
+
+=item HMAC, see L<EVP_MAC-HMAC(7)>
+
+=item KMAC, see L<EVP_MAC-KMAC(7)>
+
+=item SIPHASH, see L<EVP_MAC-Siphash(7)>
+
+=item POLY1305, see L<EVP_MAC-Poly1305(7)>
+
+=back
+
+=head2 Key Derivation Function (KDF)
+
+=over 4
+
+=item HKDF, see L<EVP_KDF-HKDF(7)>
+
+=item SSKDF, see L<EVP_KDF-SS(7)>
+
+=item PBKDF2, see L<EVP_KDF-PBKDF2(7)>
+
+=item SSHKDF, see L<EVP_KDF-SSHKDF(7)>
+
+=item TLS1-PRF, see L<EVP_KDF-TLS1_PRF(7)>
+
+=item KBKDF, see L<EVP_KDF-KB(7)>
+
+=item X942KDF, see L<EVP_KDF-X942(7)>
+
+=item SCRYPT, see L<EVP_KDF-SCRYPT(7)>
+
+=item KRB5KDF, see L<EVP_KDF-KRB5KDF(7)>
+
+=back
+
+=head2 Key Exchange
+
+=over 4
+
+=item DH, see L<EVP_KEYEXCH-DH(7)>
+
+=item ECDH, see L<EVP_KEYEXCH-ECDH(7)>
+
+=item X25519, see L<EVP_KEYEXCH-X25519(7)>
+
+=item X448, see L<EVP_KEYEXCH-X448(7)>
+
+=back
+
+=head2 Asymmetric Signature
+
+=over 4
+
+=item DSA, see L<EVP_SIGNATURE-DSA(7)>
+
+=item RSA, see L<EVP_SIGNATURE-RSA(7)>
+
+=back
+
+=head2 Asymmetric Cipher
+
+=over 4
+
+=item RSA, see L<EVP_ASYM_CIPHER-RSA(7)>
+
+=back
+
+=head2 Asymmetric Key Management
+
+=over 4
+
+=item DH, see L<EVP_KEYMGMT-DH(7)>
+
+=item DSA, see L<EVP_KEYMGMT-DSA(7)>
+
+=item RSA, see L<EVP_KEYMGMT-RSA(7)>
+
+=item EC, see L<EVP_KEYMGMT-EC(7)>
+
+=item X25519, see L<EVP_KEYMGMT-X25519(7)>
+
+=item X448, see L<EVP_KEYMGMT-X448(7)>
+
+=back
+
+=head2 Asymmetric Key Serializer
+
+In addition to "provider=default", this set of implementations define the
+property "fips=yes", to allow them to be used together with the FIPS
+provider.
+
+=over 4
+
+=item RSA, see L<OSSL_SERIALIZER-RSA(7)>
+
+=item DH, see L<OSSL_SERIALIZER-DH(7)>
+
+=item DSA, see L<OSSL_SERIALIZER-DSA(7)>
+
+=item EC, see L<OSSL_SERIALIZER-EC(7)>
+
+=item X25519, see L<OSSL_SERIALIZER-X25519(7)>
+
+=item X448, see L<OSSL_SERIALIZER-X448(7)>
+
+=back
+
+=head1 SEE ALSO
+
+L<openssl-core.h(7)>, L<openssl-core_numbers.h(7)>, L<provider(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
diff --git a/doc/man7/OSSL_PROVIDER-legacy.pod b/doc/man7/OSSL_PROVIDER-legacy.pod
new file mode 100644 (file)
index 0000000..27ed308
--- /dev/null
@@ -0,0 +1,92 @@
+=pod
+
+=head1 NAME
+
+OSSL_PROVIDER-legacy - OpenSSL legacy provider
+
+=head1 DESCRIPTION
+
+The OpenSSL legacy provider supplies OpenSSL implementations of algorithms
+that have been deemed legacy.  Such algorithms have commonly fallen out of
+use, have been deemed insecure by the cryptography community, or something
+similar.
+
+We can consider this the retirement home of cryptographic algorithms.
+
+=head2 Properties
+
+The implementations in this provider specifically have these property
+defined:
+
+=over 4
+
+"provider=legacy"
+
+=back
+
+It may be used in a property query string with fetching functions such as
+L<EVP_MD_fetch(3)> or L<EVP_CIPHER_fetch(3)>, as well as with other
+functions that take a property query string, such as
+L<EVP_PKEY_CTX_new_from_name(3)>.
+
+It isn't mandatory to query for any of these properties, except to
+make sure to get implementations of this provider and none other.
+
+=head1 OPERATIONS AND ALGORITHMS
+
+The OpenSSL legacy provider supports these operations and algorithms:
+
+=head2 Hashing Algorithms / Message Digests
+
+=over 4
+
+=item MD2, see L<EVP_MD-MD2(7)>
+
+=item MD4, see L<EVP_MD-MD4(7)>
+
+=item MDC2, see L<EVP_MD-MDC2(7)>
+
+=item WHIRLPOOL, see L<EVP_MD-WHIRLPOOL(7)>
+
+=item RIPEMD160, see L<EVP_MD-RIPEMD160(7)>
+
+=back
+
+=begin comment
+
+When algorithms for other operations start appearing, the
+following =head2 titles are appropriate to use:
+
+- Symmetric Ciphers
+
+- Message Authentication Code (MAC)
+
+- Key Derivation Function (KDF)
+
+- Key Exchange
+
+- Signature
+
+- Asymmetric Cipher
+
+- Asymmetric Key Management
+
+=end comment
+
+=head1 SEE ALSO
+
+L<OSSL_PARAM(3)>,
+L<openssl-core.h(7)>,
+L<openssl-core_numbers.h(7)>,
+L<provider(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