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)

(cherry picked from commit 4ee8c1fb51687ea811fc2abf87e173c70d018bc2)

diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod
index dc0f06d9d323c73d3a46416fd7b4af3e37e8d599..f528330c04d0b873d6dee8310dfd8d474e1f8a0c 100644 (file)
--- a/doc/man3/PKCS12_create.pod
+++ b/doc/man3/PKCS12_create.pod
@@ -42,7 +42,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
@@ -68,6 +69,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.
@@ -83,7 +86,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 8b256af39ae6fe9fd982e8c3f3baa6171a1005b6..ecca1dc637fd008cdd4fa5dd948b0af420c52351 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/migration_guide.pod b/doc/man7/migration_guide.pod
index 11a849b7febc166f4c3b38ac95cc94c773268c9e..d9e4b37b2bf393318323e0fd7ab668854e1a4d87 100644 (file)
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -326,6 +326,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