From: Vladimir Kotal <vladimir.kotal@oracle.com>
Date: Tue, 5 Sep 2023 09:13:47 +0000 (+0200)
Subject: augment man pages with information about PKCS12KDF in FIPS mode
X-Git-Tag: openssl-3.1.3~23
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=838173b614938dac84cb5273dc4e6e5acd92649e;p=thirdparty%2Fopenssl.git

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 dc0f06d9d32..f528330c04d 100644
--- 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 c4610ecaa47..07f8855ecf7 100644
--- 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 8b256af39ae..ecca1dc637f 100644
--- 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 11a849b7feb..d9e4b37b2bf 100644
--- 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