augment man pages with information about PKCS12KDF in FIPS mode

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21965)

diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod
index 224ae6418063ad293a705964190c5b3f2dcd9e1f..993e50777e1d9bb154a47d2be5ee5900c2c11f2b 100644 (file)
--- a/doc/man3/PKCS12_create.pod
+++ b/doc/man3/PKCS12_create.pod
@@ -57,7 +57,8 @@ can all be set to zero and sensible defaults will be used.
 These defaults are: AES password based encryption (PBES2 with PBKDF2 and
 AES-256-CBC) for private keys and certificates, the PBKDF2 and MAC key
 derivation iteration count of B<PKCS12_DEFAULT_ITER> (currently 2048), and
-MAC algorithm HMAC with SHA2-256.
+MAC algorithm HMAC with SHA2-256. The MAC key derivation algorithm used
+for the outer PKCS#12 structure is PKCS12KDF.
 
 The default MAC iteration count is 1 in order to retain compatibility with
 old software which did not interpret MAC iteration counts. If such compatibility
@@ -83,6 +84,8 @@ I<nid_key> or I<nid_cert> can be set to -1 indicating that no encryption
 should be used.
 
 I<mac_iter> can be set to -1 and the MAC will then be omitted entirely.
+This can be useful when running with the FIPS provider as the PKCS12KDF
+is not a FIPS approvable algorithm.
 
 PKCS12_create() makes assumptions regarding the encoding of the given pass
 phrase.
@@ -101,7 +104,9 @@ IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
 
 =head1 SEE ALSO
 
+L<EVP_KDF-PKCS12KDF(7)>,
 L<d2i_PKCS12(3)>,
+L<OSSL_PROVIDER-FIPS(7)>,
 L<passphrase-encoding(7)>
 
 =head1 HISTORY

diff --git a/doc/man3/PKCS12_gen_mac.pod b/doc/man3/PKCS12_gen_mac.pod
index c4610ecaa47fe189bda3dd41474b10a8935bb60a..07f8855ecf7f62e86fd1b2b5909747bacbea7283 100644 (file)
--- a/doc/man3/PKCS12_gen_mac.pod
+++ b/doc/man3/PKCS12_gen_mac.pod
@@ -22,6 +22,7 @@ PKCS12_verify_mac - Functions to create and manipulate a PKCS#12 structure
 
 PKCS12_gen_mac() generates an HMAC over the entire PKCS#12 object using the
 supplied password along with a set of already configured parameters.
+The default key generation mechanism used is PKCS12KDF.
 
 PKCS12_verify_mac() verifies the PKCS#12 object's HMAC using the supplied
 password.
@@ -57,6 +58,7 @@ IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
 =head1 SEE ALSO
 
 L<d2i_PKCS12(3)>,
+L<EVP_KDF-PKCS12KDF(7)>,
 L<PKCS12_create(3)>,
 L<passphrase-encoding(7)>
 

diff --git a/doc/man7/EVP_KDF-PKCS12KDF.pod b/doc/man7/EVP_KDF-PKCS12KDF.pod
index 7edde1dc9bf7f010e4cd7865df750bbec8ecf492..05d4e902bd30f0b00db1c1f5bdad59f58fde04cd 100644 (file)
--- a/doc/man7/EVP_KDF-PKCS12KDF.pod
+++ b/doc/man7/EVP_KDF-PKCS12KDF.pod
@@ -46,6 +46,9 @@ RFC 7292 section B.3.
 
 =head1 NOTES
 
+This algorithm is not available in the FIPS provider as it is not FIPS
+approvable.
+
 A typical application of this algorithm is to derive keying material for an
 encryption algorithm from a password in the "pass", a salt in "salt",
 and an iteration count.
@@ -68,7 +71,8 @@ L<EVP_KDF_CTX_new(3)>,
 L<EVP_KDF_CTX_free(3)>,
 L<EVP_KDF_CTX_set_params(3)>,
 L<EVP_KDF_derive(3)>,
-L<EVP_KDF(3)/PARAMETERS>
+L<EVP_KDF(3)/PARAMETERS>,
+L<OSSL_PROVIDER-FIPS(7)>
 
 =head1 HISTORY
 

diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod
index 064ad21789511e2a232cbcf3928bf2a0ed081191..fc3acef6d94134c46b1b21cf125ee464373e9d8b 100644 (file)
--- a/doc/man7/ossl-guide-migration.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -327,6 +327,15 @@ context and property query and will call an extended version of the key/IV
 derivation function which supports these parameters. This includes
 L<EVP_PBE_CipherInit_ex(3)>, L<EVP_PBE_find_ex(3)> and L<EVP_PBE_scrypt_ex(3)>.
 
+=head4 PKCS#12 KDF versus FIPS
+
+Unlike in 1.x.y, the PKCS12KDF algorithm used when a PKCS#12 structure
+is created with a MAC that does not work with the FIPS provider as the PKCS12KDF
+is not a FIPS approvable mechanism.
+
+See L<EVP_KDF-PKCS12KDF(7)>, L<PKCS12_create(3)>, L<openssl-pkcs12(1)>,
+L<OSSL_PROVIDER-FIPS(7)>.
+
 =head4 Windows thread synchronization changes
 
 Windows thread synchronization uses read/write primitives (SRWLock) when