Add library context and property query support into the PKCS12 API

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

15 files changed, 992 insertions, 18 deletions

diff --git a/doc/man3/EVP_PBE_CipherInit.pod b/doc/man3/EVP_PBE_CipherInit.pod
new file mode 100644
index 0000000000..8f2a53397e
--- /dev/null
+++ b/doc/man3/EVP_PBE_CipherInit.pod
@@ -0,0 +1,99 @@
+=pod
+
+=head1 NAME
+
+EVP_PBE_CipherInit, EVP_PBE_CipherInit_ex,
+EVP_PBE_find, EVP_PBE_find_ex - Password based encryption routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PBE_CipherInit(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,
+                        ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de);
+ int EVP_PBE_CipherInit_ex(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,
+                           ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de,
+                           OSSL_LIB_CTX *libctx, const char *propq);
+
+ int EVP_PBE_find(int type, int pbe_nid, int *pcnid, int *pmnid,
+                  EVP_PBE_KEYGEN **pkeygen);
+ int EVP_PBE_find_ex(int type, int pbe_nid, int *pcnid, int *pmnid,
+                     EVP_PBE_KEYGEN **pkeygen, EVP_PBE_KEYGEN_EX **keygen_ex);
+
+=head1 DESCRIPTION
+
+=head2 PBE operations
+
+EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() initialise an B<EVP_CIPHER_CTX>
+I<ctx> for encryption (I<en_de>=1) or decryption (I<en_de>=0) using the password
+I<pass> of length I<passlen>. The PBE algorithm type and parameters are extracted
+from an OID I<pbe_obj> and parameters I<param>.
+
+EVP_PBE_CipherInit_ex() also allows the application to specify a library context
+I<libctx> and property query I<propq> to select appropriate algorithm
+implementations.
+
+=head2 PBE algorithm search
+
+EVP_PBE_find() and EVP_PBE_find_ex() search for a matching algorithm using two parameters:
+
+1. An algorithm type I<type> which can be:
+
+=over 4
+
+=item *
+
+EVP_PBE_TYPE_OUTER - A PBE algorithm
+
+=item *
+
+EVP_PBE_TYPE_PRF - A pseudo-random function
+
+=item *
+
+EVP_PBE_TYPE_KDF - A key derivation function
+
+=back
+
+2. A I<pbe_nid> which can represent the algorithm identifier with parameters e.g.
+B<NID_pbeWithSHA1AndRC2_CBC> or an algorithm class e.g. B<NID_pbes2>.
+
+They return the algorithm's cipher ID I<pcnid>, digest ID I<pmnid> and a key
+generation function for the algorithm I<pkeygen>. EVP_PBE_CipherInit_ex() also
+returns an extended key generation function I<keygen_ex> which takes a library
+context and property query.
+
+If a NULL is supplied for any of I<pcnid>, I<pmnid>, I<pkeygen> or I<pkeygen_ex>
+then this parameter is not returned.
+
+=head1 NOTES
+
+The arguments I<pbe_obj> and I<param> to EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex()
+together form an B<X509_ALGOR> and can often be extracted directly from this structure.
+
+=head1 RETURN VALUES
+
+Return value is 1 for success and 0 if an error occurred.
+
+=head1 SEE ALSO
+
+L<PKCS5_PBE_keyivgen(3)>,
+L<PKCS12_PBE_keyivgen_ex(3)>,
+L<PKCS5_v2_PBE_keyivgen_ex(3)>,
+L<PKCS12_pbe_crypt_ex(3)>,
+L<PKCS12_create_ex(3)>
+
+=head1 HISTORY
+
+EVP_PBE_CipherInit_ex() and EVP_PBE_find_ex() were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_PBE_keyivgen.pod b/doc/man3/PKCS12_PBE_keyivgen.pod
new file mode 100644
index 0000000000..b0edb81c6c
--- /dev/null
+++ b/doc/man3/PKCS12_PBE_keyivgen.pod
@@ -0,0 +1,108 @@
+=pod
+
+=head1 NAME
+
+PKCS12_PBE_keyivgen, PKCS12_PBE_keyivgen_ex, 
+PKCS12_pbe_crypt, PKCS12_pbe_crypt_ex - PKCS#12 Password based encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int PKCS12_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
+                         ASN1_TYPE *param, const EVP_CIPHER *cipher,
+                         const EVP_MD *md_type, int en_de);
+ int PKCS12_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
+                            ASN1_TYPE *param, const EVP_CIPHER *cipher,
+                            const EVP_MD *md_type, int en_de,
+                            OSSL_LIB_CTX *libctx, const char *propq);
+ unsigned char *PKCS12_pbe_crypt(const X509_ALGOR *algor,
+                                 const char *pass, int passlen,
+                                 const unsigned char *in, int inlen,
+                                 unsigned char **data, int *datalen,
+                                 int en_de);
+ unsigned char *PKCS12_pbe_crypt_ex(const X509_ALGOR *algor,
+                                    const char *pass, int passlen,
+                                    const unsigned char *in, int inlen,
+                                    unsigned char **data, int *datalen,
+                                    int en_de, OSSL_LIB_CTX *libctx,
+                                    const char *propq);
+
+=head1 DESCRIPTION
+
+PKCS12_PBE_keyivgen() and PKCS12_PBE_keyivgen_ex() take a password I<pass> of
+length I<passlen>, parameters I<param> and a message digest function I<md_type>
+and perform a key derivation according to PKCS#12. The resulting key is
+then used to initialise the cipher context I<ctx> with a cipher I<cipher> for
+encryption (I<en_de>=1) or decryption (I<en_de>=0).
+
+PKCS12_PBE_keyivgen_ex() also allows the application to specify a library context
+I<libctx> and property query I<propq> to select appropriate algorithm
+implementations.
+
+PKCS12_pbe_crypt() and PKCS12_pbe_crypt_ex() will encrypt or decrypt a buffer
+based on the algorithm in I<algor> and password I<pass> of length I<passlen>.
+The input is from I<in> of length I<inlen> and output is into a malloc'd buffer
+returned in I<*data> of length I<datalen>. The operation is determined by I<en_de>,
+encryption (I<en_de>=1) or decryption (I<en_de>=0).
+
+PKCS12_pbe_crypt_ex() allows the application to specify a library context
+I<libctx> and property query I<propq> to select appropriate algorithm
+implementations.
+
+I<pass> is the password used in the derivation of length I<passlen>. I<pass>
+is an optional parameter and can be NULL. If I<passlen> is -1, then the
+function will calculate the length of I<pass> using strlen().
+
+I<salt> is the salt used in the derivation of length I<saltlen>. If the
+I<salt> is NULL, then I<saltlen> must be 0. The function will not
+attempt to calculate the length of the I<salt> because it is not assumed to
+be NULL terminated.
+
+I<iter> is the iteration count and its value should be greater than or
+equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
+I<iter> less than 1 is treated as a single iteration.
+
+I<digest> is the message digest function used in the derivation.
+
+Functions ending in _ex() take optional parameters I<libctx> and I<propq> which
+are used to select appropriate algorithm implementations.
+
+=head1 NOTES
+
+The functions are typically used in PKCS#12 to encrypt objects.
+
+These functions make no assumption regarding the given password.
+It will simply be treated as a byte sequence.
+
+=head1 RETURN VALUES
+
+PKCS12_PBE_keyivgen(), PKCS12_PBE_keyivgen_ex() return 1 on success or 0 on error.
+
+PKCS12_pbe_crypt() and PKCS12_pbe_crypt_ex() return a buffer containing the
+output or NULL if an error occurred.
+
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
+=head1 SEE ALSO
+
+L<EVP_PBE_CipherInit_ex(3)>,
+L<PKCS8_encrypt_ex(3)>,
+L<passphrase-encoding(7)>
+
+=head1 HISTORY
+
+PKCS12_PBE_keyivgen_ex() and PKCS12_pbe_crypt_ex() were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2014-2021 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/man3/PKCS12_SAFEBAG_create_cert.pod b/doc/man3/PKCS12_SAFEBAG_create_cert.pod
index be0aee4226..07ba1425e7 100644
--- a/doc/man3/PKCS12_SAFEBAG_create_cert.pod
+++ b/doc/man3/PKCS12_SAFEBAG_create_cert.pod
@@ -4,8 +4,8 @@
 
 PKCS12_SAFEBAG_create_cert, PKCS12_SAFEBAG_create_crl,
 PKCS12_SAFEBAG_create_secret, PKCS12_SAFEBAG_create0_p8inf, 
-PKCS12_SAFEBAG_create0_pkcs8, PKCS12_SAFEBAG_create_pkcs8_encrypt - Create
-PKCS#12 safeBag objects
+PKCS12_SAFEBAG_create0_pkcs8, PKCS12_SAFEBAG_create_pkcs8_encrypt,
+PKCS12_SAFEBAG_create_pkcs8_encrypt_ex - Create PKCS#12 safeBag objects
 
 =head1 SYNOPSIS
 
@@ -24,6 +24,14 @@ PKCS#12 safeBag objects
                                                      unsigned char *salt,
                                                      int saltlen, int iter,
                                                      PKCS8_PRIV_KEY_INFO *p8inf);
+ PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(int pbe_nid,
+                                                        const char *pass,
+                                                        int passlen,
+                                                        unsigned char *salt,
+                                                        int saltlen, int iter,
+                                                        PKCS8_PRIV_KEY_INFO *p8inf,
+                                                        OSSL_LIB_CTX *ctx,
+                                                        const char *propq);
 
 =head1 DESCRIPTION
 
@@ -34,7 +42,7 @@ PKCS12_SAFEBAG_create_crl() creates a new B<PKCS12_SAFEBAG> of type B<NID_crlBag
 containing the supplied crl.
 
 PKCS12_SAFEBAG_create_secret() creates a new B<PKCS12_SAFEBAG> of type
-corresponding to a PKCS#12 I<secretBag>. The I<secretBag> contents are tagged as
+corresponding to a PKCS#12 B<secretBag>. The B<secretBag> contents are tagged as
 I<type> with an ASN1 value of type I<vtype> constructed using the bytes in
 I<value> of length I<len>.
 
@@ -50,6 +58,10 @@ If I<pbe_nid> is 0, a default encryption algorithm is used. I<pass> is the
 passphrase and I<iter> is the iteration count. If I<iter> is zero then a default
 value of 2048 is used. If I<salt> is NULL then a salt is generated randomly.
 
+PKCS12_SAFEBAG_create_pkcs8_encrypt_ex() is identical to PKCS12_SAFEBAG_create_pkcs8_encrypt()
+but allows for a library context I<ctx> and property query I<propq> to be used to select
+algorithm implementations.
+
 =head1 NOTES
 
 PKCS12_SAFEBAG_create_pkcs8_encrypt() makes assumptions regarding the encoding of the given pass
@@ -62,15 +74,23 @@ PKCS12_SAFEBAG_create_secret() was added in OpenSSL 3.0.
 
 All of these functions return a valid B<PKCS12_SAFEBAG> structure or NULL if an error occurred.
 
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
 =head1 SEE ALSO
 
 L<PKCS12_create(3)>,
 L<PKCS12_add_safe(3)>,
 L<PKCS12_add_safes(3)>
 
+=head1 HISTORY
+
+PKCS12_SAFEBAG_create_pkcs8_encrypt_ex() was added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2021 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
diff --git a/doc/man3/PKCS12_add_cert.pod b/doc/man3/PKCS12_add_cert.pod
index bb326f7f4c..39d4779d11 100644
--- a/doc/man3/PKCS12_add_cert.pod
+++ b/doc/man3/PKCS12_add_cert.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-PKCS12_add_cert, PKCS12_add_key,
+PKCS12_add_cert, PKCS12_add_key, PKCS12_add_key_ex, 
 PKCS12_add_secret - Add an object to a set of PKCS#12 safeBags
 
 =head1 SYNOPSIS
@@ -13,6 +13,11 @@ PKCS12_add_secret - Add an object to a set of PKCS#12 safeBags
  PKCS12_SAFEBAG *PKCS12_add_key(STACK_OF(PKCS12_SAFEBAG) **pbags,
                                EVP_PKEY *key, int key_usage, int iter,
                                int key_nid, const char *pass);
+ PKCS12_SAFEBAG *PKCS12_add_key_ex(STACK_OF(PKCS12_SAFEBAG) **pbags,
+                                   EVP_PKEY *key, int key_usage, int iter,
+                                   int key_nid, const char *pass,
+                                   OSSL_LIB_CTX *ctx, const char *propq);
+
  PKCS12_SAFEBAG *PKCS12_add_secret(STACK_OF(PKCS12_SAFEBAG) **pbags,
                                   int nid_type, const unsigned char *value, int len);
 
@@ -30,13 +35,17 @@ safeBags. If I<key_nid> is not -1 then the key is encrypted with the supplied
 algorithm, using I<pass> as the passphrase and I<iter> as the iteration count. If
 I<iter> is zero then a default value for iteration count of 2048 is used.
 
+PKCS12_add_key_ex() is identical to PKCS12_add_key() but allows for a library
+context I<ctx> and property query I<propq> to be used to select algorithm
+implementations.
+
 PKCS12_add_secret() creates a PKCS#12 secretBag with an OID corresponding to
-the supplied B<nid_type> containing the supplied value as an ASN1 octet string.
+the supplied I<nid_type> containing the supplied value as an ASN1 octet string.
 This is then added to the set of PKCS#12 safeBags.
 
 =head1 NOTES
 
-If a certificate contains an B<alias> or a B<keyid> then this will be
+If a certificate contains an I<alias> or a I<keyid> then this will be
 used for the corresponding B<friendlyName> or B<localKeyID> in the
 PKCS12 structure.
 
@@ -44,19 +53,25 @@ PKCS12_add_key() makes assumptions regarding the encoding of the given pass
 phrase.
 See L<passphrase-encoding(7)> for more information.
 
-PKCS12_add_secret() was added in OpenSSL 3.0.
-
 =head1 RETURN VALUES
 
 A valid B<PKCS12_SAFEBAG> structure or NULL if an error occurred.
 
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
 =head1 SEE ALSO
 
 L<PKCS12_create(3)>
 
+=head1 HISTORY
+
+PKCS12_add_secret() and PKCS12_add_key_ex() were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2020-2021 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
diff --git a/doc/man3/PKCS12_add_safe.pod b/doc/man3/PKCS12_add_safe.pod
index ec657aaa07..881ab1d75c 100644
--- a/doc/man3/PKCS12_add_safe.pod
+++ b/doc/man3/PKCS12_add_safe.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-PKCS12_add_safe, PKCS12_add_safes - Create and add objects to a PKCS#12 structure
+PKCS12_add_safe, PKCS12_add_safe_ex,
+PKCS12_add_safes, PKCS12_add_safes_ex - Create and add objects to a PKCS#12 structure
 
 =head1 SYNOPSIS
 
@@ -10,7 +11,13 @@ PKCS12_add_safe, PKCS12_add_safes - Create and add objects to a PKCS#12 structur
 
  int PKCS12_add_safe(STACK_OF(PKCS7) **psafes, STACK_OF(PKCS12_SAFEBAG) *bags,
                     int safe_nid, int iter, const char *pass);
+ int PKCS12_add_safe_ex(STACK_OF(PKCS7) **psafes, STACK_OF(PKCS12_SAFEBAG) *bags,
+                        int safe_nid, int iter, const char *pass,
+                        OSSL_LIB_CTX *ctx, const char *propq);
+
  PKCS12 *PKCS12_add_safes(STACK_OF(PKCS7) *safes, int p7_nid);
+ PKCS12 *PKCS12_add_safes_ex(STACK_OF(PKCS7) *safes, int p7_nid,
+                             OSSL_LIB_CTX *ctx, const char *propq);
 
 =head1 DESCRIPTION
 
@@ -32,10 +39,18 @@ a default encryption algorithm, currently B<NID_pbe_WithSHA1And3_Key_TripleDES_C
 
 =back
 
+PKCS12_add_safe_ex() is identical to PKCS12_add_safe() but allows for a library
+context I<ctx> and property query I<propq> to be used to select algorithm
+implementations.
+
 PKCS12_add_safes() creates a B<PKCS12> structure containing the supplied set of
 PKCS7 contentInfos. The I<safes> are enclosed first within a PKCS7 contentInfo
 of type I<p7_nid>. Currently the only supported type is B<NID_pkcs7_data>.
 
+PKCS12_add_safes_ex() is identical to PKCS12_add_safes() but allows for a
+library context I<ctx> and property query I<propq> to be used to select
+algorithm implementations.
+
 =head1 NOTES
 
 PKCS12_add_safe() makes assumptions regarding the encoding of the given pass
@@ -48,13 +63,21 @@ PKCS12_add_safe() returns a value of 1 indicating success or 0 for failure.
 
 PKCS12_add_safes() returns a valid B<PKCS12> structure or NULL if an error occurred.
 
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
 =head1 SEE ALSO
 
 L<PKCS12_create(3)>
 
+=head1 HISTORY
+
+PKCS12_add_safe_ex() and PKCS12_add_safes_ex() were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2020-2021 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
diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod
index be898c6795..dc0f06d9d3 100644
--- a/doc/man3/PKCS12_create.pod
+++ b/doc/man3/PKCS12_create.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-PKCS12_create - create a PKCS#12 structure
+PKCS12_create, PKCS12_create_ex - create a PKCS#12 structure
 
 =head1 SYNOPSIS
 
@@ -11,6 +11,10 @@ PKCS12_create - create a PKCS#12 structure
  PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey,
                        X509 *cert, STACK_OF(X509) *ca,
                        int nid_key, int nid_cert, int iter, int mac_iter, int keytype);
+ PKCS12 *PKCS12_create_ex(const char *pass, const char *name, EVP_PKEY *pkey,
+                          X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert,
+                          int iter, int mac_iter, int keytype,
+                          OSSL_LIB_CTX *ctx, const char *propq);
 
 =head1 DESCRIPTION
 
@@ -18,7 +22,7 @@ PKCS12_create() creates a PKCS#12 structure.
 
 I<pass> is the passphrase to use. I<name> is the B<friendlyName> to use for
 the supplied certificate and key. I<pkey> is the private key to include in
-the structure and I<cert> its corresponding certificates. I<ca>, if not NULL
+the structure and I<cert> its corresponding certificates. I<ca>, if not B<NULL>
 is an optional set of certificates to also include in the structure.
 
 I<nid_key> and I<nid_cert> are the encryption algorithms that should be used
@@ -27,6 +31,9 @@ GCM, CCM, XTS, and OCB are unsupported. I<iter> is the encryption algorithm
 iteration count to use and I<mac_iter> is the MAC iteration count to use.
 I<keytype> is the type of key.
 
+PKCS12_create_ex() is identical to PKCS12_create() but allows for a library context
+I<ctx> and property query I<propq> to be used to select algorithm implementations.
+
 =head1 NOTES
 
 The parameters I<nid_key>, I<nid_cert>, I<iter>, I<mac_iter> and I<keytype>
@@ -37,6 +44,10 @@ 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.
 
+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
+is not required then I<mac_iter> should be set to PKCS12_DEFAULT_ITER.
+
 I<keytype> adds a flag to the store private key. This is a non standard extension
 that is only currently interpreted by MSIE. If set to zero the flag is omitted,
 if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX>
@@ -49,7 +60,7 @@ If a certificate contains an I<alias> or I<keyid> then this will be
 used for the corresponding B<friendlyName> or B<localKeyID> in the
 PKCS12 structure.
 
-Either I<pkey>, I<cert> or both can be NULL to indicate that no key or
+Either I<pkey>, I<cert> or both can be B<NULL> to indicate that no key or
 certificate is required. In previous versions both had to be present or
 a fatal error is returned.
 
@@ -66,6 +77,10 @@ See L<passphrase-encoding(7)> for more information.
 
 PKCS12_create() returns a valid B<PKCS12> structure or NULL if an error occurred.
 
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
 =head1 SEE ALSO
 
 L<d2i_PKCS12(3)>,
@@ -73,6 +88,8 @@ L<passphrase-encoding(7)>
 
 =head1 HISTORY
 
+PKCS12_create_ex() was added in OpenSSL 3.0.
+
 The defaults for encryption algorithms, MAC algorithm, and the MAC key
 derivation iteration count were changed in OpenSSL 3.0 to more modern
 standards.
diff --git a/doc/man3/PKCS12_decrypt_skey.pod b/doc/man3/PKCS12_decrypt_skey.pod
new file mode 100644
index 0000000000..79296c681a
--- /dev/null
+++ b/doc/man3/PKCS12_decrypt_skey.pod
@@ -0,0 +1,55 @@
+=pod
+
+=head1 NAME
+
+PKCS12_decrypt_skey, PKCS12_decrypt_skey_ex - PKCS12 shrouded keyBag
+decrypt functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ PKCS8_PRIV_KEY_INFO *PKCS12_decrypt_skey(const PKCS12_SAFEBAG *bag,
+                                          const char *pass, int passlen);
+ PKCS8_PRIV_KEY_INFO *PKCS12_decrypt_skey_ex(const PKCS12_SAFEBAG *bag,
+                                             const char *pass, int passlen,
+                                             OSSL_LIB_CTX *ctx,
+                                             const char *propq);
+
+=head1 DESCRIPTION
+
+PKCS12_decrypt_skey() Decrypt the PKCS#8 shrouded keybag contained within I<bag>
+using the supplied password I<pass> of length I<passlen>.
+
+PKCS12_decrypt_skey_ex() is similar to the above but allows for a library context 
+I<ctx> and property query I<propq> to be used to select algorithm implementations.
+
+=head1 RETURN VALUES
+
+Both functions will return the decrypted key or NULL if an error occurred.
+
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
+=head1 SEE ALSO
+
+L<PKCS8_decrypt_ex(3)>,
+L<PKCS8_encrypt_ex(3)>,
+L<PKCS12_add_key_ex(3)>,
+L<PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(3)>
+
+=head1 HISTORY
+
+PKCS12_decrypt_skey_ex() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_gen_mac.pod b/doc/man3/PKCS12_gen_mac.pod
new file mode 100644
index 0000000000..21854627a5
--- /dev/null
+++ b/doc/man3/PKCS12_gen_mac.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+PKCS12_gen_mac, PKCS12_setup_mac, PKCS12_set_mac, 
+PKCS12_verify_mac - Functions to create and manipulate a PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ int PKCS12_gen_mac(PKCS12 *p12, const char *pass, int passlen,
+                    unsigned char *mac, unsigned int *maclen);
+ int PKCS12_verify_mac(PKCS12 *p12, const char *pass, int passlen);
+ int PKCS12_set_mac(PKCS12 *p12, const char *pass, int passlen,
+                    unsigned char *salt, int saltlen, int iter,
+                    const EVP_MD *md_type);
+ int PKCS12_setup_mac(PKCS12 *p12, int iter, unsigned char *salt,
+                      int saltlen, const EVP_MD *md_type);
+
+=head1 DESCRIPTION
+
+PKCS12_gen_mac() generates an HMAC over the entire PKCS#12 object using the
+supplied password along with a set of already configured paramters.
+
+PKCS12_verify_mac() verifies the PKCS#12 object's HMAC using the supplied
+password.
+
+PKCS12_setup_mac() sets the MAC part of the PKCS#12 structure with the supplied
+parameters.
+
+PKCS12_set_mac() sets the MAC and MAC parameters into the PKCS#12 object.
+
+I<pass> is the passphrase to use in the HMAC. I<salt> is the salt value to use,
+I<iter> is the iteration count and I<md_type> is the message digest
+function to use.
+
+=head1 NOTES
+
+If I<salt> is NULL then a suitable salt will be generated and used.
+
+If I<iter> is 1 then an iteration count will be omitted from the PKCS#12
+structure.
+
+PKCS12_gen_mac(), PKCS12_verify_mac() and PKCS12_set_mac() make assumptions
+regarding the encoding of the given passphrase. See L<passphrase-encoding(7)>
+for more information.
+
+=head1 RETURN VALUES
+
+All functions return 1 on success and 0 if an error occurred.
+
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)>,
+L<PKCS12_create(3)>,
+L<passphrase-encoding(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_init.pod b/doc/man3/PKCS12_init.pod
new file mode 100644
index 0000000000..b0d3aa5fa9
--- /dev/null
+++ b/doc/man3/PKCS12_init.pod
@@ -0,0 +1,48 @@
+=pod
+
+=head1 NAME
+
+PKCS12_init, PKCS12_init_ex - Create a new empty PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ PKCS12 *PKCS12_init(int mode);
+ PKCS12 *PKCS12_init_ex(int mode, OSSL_LIB_CTX *ctx, const char *propq);
+
+=head1 DESCRIPTION
+
+PKCS12_init() creates an empty PKCS#12 structure. Any PKCS#7 authSafes added
+to this structure are enclosed first within a single PKCS#7 contentInfo
+of type I<mode>. Currently the only supported type is B<NID_pkcs7_data>.
+
+PKCS12_init_ex() creates an empty PKCS#12 structure and assigns the supplied
+I<ctx> and I<propq> to be used to select algorithm implementations for
+operations performed on the B<PKCS12> object.
+
+=head1 RETURN VALUES
+
+PKCS12_init() and PKCS12_init_ex() return a valid B<PKCS12> structure or NULL
+if an error occurred.
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)>,
+L<PKCS12_create(3)>,
+L<passphrase-encoding(7)>
+
+=head1 HISTORY
+
+PKCS12_init_ex() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_item_decrypt_d2i.pod b/doc/man3/PKCS12_item_decrypt_d2i.pod
new file mode 100644
index 0000000000..cd5a993c7e
--- /dev/null
+++ b/doc/man3/PKCS12_item_decrypt_d2i.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+PKCS12_item_decrypt_d2i, PKCS12_item_decrypt_d2i_ex,
+PKCS12_item_i2d_encrypt, PKCS12_item_i2d_encrypt_ex - PKCS12 item
+encrypt/decrypt functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ void *PKCS12_item_decrypt_d2i(const X509_ALGOR *algor, const ASN1_ITEM *it,
+                               const char *pass, int passlen,
+                               const ASN1_OCTET_STRING *oct, int zbuf);
+ void *PKCS12_item_decrypt_d2i_ex(const X509_ALGOR *algor, const ASN1_ITEM *it,
+                                  const char *pass, int passlen,
+                                  const ASN1_OCTET_STRING *oct, int zbuf,
+                                  OSSL_LIB_CTX *libctx,
+                                  const char *propq);
+ ASN1_OCTET_STRING *PKCS12_item_i2d_encrypt(X509_ALGOR *algor,
+                                            const ASN1_ITEM *it,
+                                            const char *pass, int passlen,
+                                            void *obj, int zbuf);
+ ASN1_OCTET_STRING *PKCS12_item_i2d_encrypt_ex(X509_ALGOR *algor,
+                                               const ASN1_ITEM *it,
+                                               const char *pass, int passlen,
+                                               void *obj, int zbuf,
+                                               OSSL_LIB_CTX *ctx,
+                                               const char *propq);
+
+=head1 DESCRIPTION
+
+PKCS12_item_decrypt_d2i() and PKCS12_item_decrypt_d2i_ex() decrypt an octet
+string containing an ASN.1 encoded object using the algorithm I<algor> and 
+password I<pass> of length I<passlen>. If I<zbuf> is nonzero then the output
+buffer will zeroed after the decrypt.
+
+PKCS12_item_i2d_encrypt() and PKCS12_item_i2d_encrypt_ex() encrypt an ASN.1
+object I<it> using the algorithm I<algor> and password I<pass> of length
+I<passlen>, returning an encoded object in I<obj>. If I<zbuf> is nonzero then
+the buffer containing the input encoding will be zeroed after the encrypt.
+
+Functions ending in _ex() allow for a library context I<ctx> and property query
+I<propq> to be used to select algorithm implementations.
+
+=head1 RETURN VALUES
+
+PKCS12_item_decrypt_d2i() and PKCS12_item_decrypt_d2i_ex() return the decrypted
+object or NULL if an error occurred.
+
+PKCS12_item_i2d_encrypt() and PKCS12_item_i2d_encrypt_ex() return the encrypted
+data as an ASN.1 Octet String or NULL if an error occurred.
+
+=head1 SEE ALSO
+
+L<PKCS12_pbe_crypt_ex(3)>,
+L<PKCS8_encrypt_ex(3)>
+
+=head1 HISTORY
+
+PKCS12_item_decrypt_d2i_ex() and PKCS12_item_i2d_encrypt_ex() were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_key_gen_utf8_ex.pod b/doc/man3/PKCS12_key_gen_utf8_ex.pod
new file mode 100644
index 0000000000..d66f8c7000
--- /dev/null
+++ b/doc/man3/PKCS12_key_gen_utf8_ex.pod
@@ -0,0 +1,138 @@
+=pod
+
+=head1 NAME
+
+PKCS12_key_gen_asc, PKCS12_key_gen_asc_ex,
+PKCS12_key_gen_uni, PKCS12_key_gen_uni_ex,
+PKCS12_key_gen_utf8, PKCS12_key_gen_utf8_ex - PKCS#12 Password based key derivation
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ int PKCS12_key_gen_asc(const char *pass, int passlen, unsigned char *salt,
+                        int saltlen, int id, int iter, int n,
+                        unsigned char *out, const EVP_MD *md_type);
+ int PKCS12_key_gen_asc_ex(const char *pass, int passlen, unsigned char *salt,
+                           int saltlen, int id, int iter, int n,
+                           unsigned char *out, const EVP_MD *md_type,
+                           OSSL_LIB_CTX *ctx, const char *propq);
+ int PKCS12_key_gen_uni(unsigned char *pass, int passlen, unsigned char *salt,
+                        int saltlen, int id, int iter, int n,
+                        unsigned char *out, const EVP_MD *md_type);
+ int PKCS12_key_gen_uni_ex(unsigned char *pass, int passlen, unsigned char *salt,
+                           int saltlen, int id, int iter, int n,
+                           unsigned char *out, const EVP_MD *md_type,
+                           OSSL_LIB_CTX *ctx, const char *propq);
+ int PKCS12_key_gen_utf8(const char *pass, int passlen, unsigned char *salt,
+                         int saltlen, int id, int iter, int n,
+                         unsigned char *out, const EVP_MD *md_type);
+ int PKCS12_key_gen_utf8_ex(const char *pass, int passlen, unsigned char *salt,
+                            int saltlen, int id, int iter, int n,
+                            unsigned char *out, const EVP_MD *md_type,
+                            OSSL_LIB_CTX *ctx, const char *propq);
+
+=head1 DESCRIPTION
+
+These methods perform a key derivation according to PKCS#12 (RFC7292)
+with an input password I<pass> of length I<passlen>, a salt I<salt> of length
+I<saltlen>, an iteration count I<iter> and a digest algorithm I<md_type>.
+The ID byte I<id> determines how the resulting key is intended to be used:
+
+=over 4
+
+=item *
+
+If ID=1, then the pseudorandom bits being produced are to be used
+as key material for performing encryption or decryption.
+
+=item *
+
+If ID=2, then the pseudorandom bits being produced are to be used
+as an IV (Initial Value) for encryption or decryption.
+
+=item *
+
+If ID=3, then the pseudorandom bits being produced are to be used
+as an integrity key for MACing.
+
+=back
+
+The intended format of the supplied password is determined by the method chosen:
+
+=over 4
+
+=item *
+
+PKCS12_key_gen_asc() and PKCS12_key_gen_asc_ex() expect an ASCII-formatted password.
+
+=item *
+
+PKCS12_key_gen_uni() and PKCS12_key_gen_uni_ex() expect a Unicode-formatted password.
+
+=item *
+
+PKCS12_key_gen_utf8() and PKCS12_key_gen_utf8_ex() expect a UTF-8 encoded password.
+
+=back
+
+I<pass> is the password used in the derivation of length I<passlen>. I<pass>
+is an optional parameter and can be NULL. If I<passlen> is -1, then the
+function will calculate the length of I<pass> using strlen().
+
+I<salt> is the salt used in the derivation of length I<saltlen>. If the
+I<salt> is NULL, then I<saltlen> must be 0. The function will not
+attempt to calculate the length of the I<salt> because it is not assumed to
+be NULL terminated.
+
+I<iter> is the iteration count and its value should be greater than or
+equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
+I<iter> less than 1 is treated as a single iteration.
+
+I<digest> is the message digest function used in the derivation.
+
+The derived key will be written to I<out>. The size of the I<out> buffer
+is specified via I<n>.
+
+Functions ending in _ex() allow for a library context I<ctx> and property query
+I<propq> to be used to select algorithm implementations.
+
+=head1 NOTES
+
+A typical application of this function is to derive keying material for an
+encryption algorithm from a password in the I<pass>, a salt in I<salt>,
+and an iteration count.
+
+Increasing the I<iter> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+=head1 RETURN VALUES
+
+Returns 1 on success or 0 on error.
+
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
+=head1 SEE ALSO
+
+L<PKCS12_create_ex(3)>,
+L<PKCS12_pbe_crypt_ex(3)>,
+L<passphrase-encoding(7)>
+
+=head1 HISTORY
+
+PKCS12_key_gen_asc_ex(), PKCS12_key_gen_uni_ex() and PKCS12_key_gen_utf8_ex()
+were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS12_pack_p7encdata.pod b/doc/man3/PKCS12_pack_p7encdata.pod
new file mode 100644
index 0000000000..36a1d5d12d
--- /dev/null
+++ b/doc/man3/PKCS12_pack_p7encdata.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+PKCS12_pack_p7encdata, PKCS12_pack_p7encdata_ex - Pack a set of PKCS#12 safeBags
+into a PKCS#7 encrypted data object
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, const char *pass, int passlen,
+                              unsigned char *salt, int saltlen, int iter,
+                              STACK_OF(PKCS12_SAFEBAG) *bags);
+ PKCS7 *PKCS12_pack_p7encdata_ex(int pbe_nid, const char *pass, int passlen,
+                                 unsigned char *salt, int saltlen, int iter,
+                                 STACK_OF(PKCS12_SAFEBAG) *bags,
+                                 OSSL_LIB_CTX *ctx, const char *propq);
+
+=head1 DESCRIPTION
+
+PKCS12_pack_p7encdata() generates a PKCS#7 ContentInfo object of encrypted-data
+type from the set of safeBags I<bags>. The algorithm ID in I<pbe_nid> can be
+a PKCS#12 or PKCS#5 password based encryption algorithm, or a cipher algorithm.
+If a cipher algorithm is passed, the PKCS#5 PBES2 algorithm will be used with
+this cipher as a parameter.
+The password I<pass> of length I<passlen>, salt I<salt> of length I<saltlen>
+and iteration count I<iter> are inputs into the encryption operation.
+
+PKCS12_pack_p7encdata_ex() operates similar to the above but allows for a
+library context I<ctx> and property query I<propq> to be used to select the
+algorithm implementation.
+
+=head1 RETURN VALUES
+
+A B<PKCS7> object if successful, or NULL if an error occurred.
+
+=head1 CONFORMING TO
+
+IETF RFC 2315 (L<https://tools.ietf.org/html/rfc2315>)
+
+=head1 SEE ALSO
+
+L<PKCS12_pbe_crypt_ex(3)>
+
+=head1 HISTORY
+
+PKCS12_pack_p7encdata_ex() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS5_PBE_keyivgen.pod b/doc/man3/PKCS5_PBE_keyivgen.pod
new file mode 100644
index 0000000000..4515346407
--- /dev/null
+++ b/doc/man3/PKCS5_PBE_keyivgen.pod
@@ -0,0 +1,170 @@
+=pod
+
+=head1 NAME
+
+PKCS5_PBE_keyivgen, PKCS5_pbe2_set, PKCS5_pbe2_set_iv,
+PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt,
+PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex,
+PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex,
+PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex,
+PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex
+- PKCS#5 Password based encryption routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
+                        ASN1_TYPE *param, const EVP_CIPHER *cipher,
+                        const EVP_MD *md, int en_de);
+ int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
+                           ASN1_TYPE *param, const EVP_CIPHER *cipher,
+                           const EVP_MD *md, int en_de);
+ int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
+                              ASN1_TYPE *param, const EVP_CIPHER *cipher,
+                              const EVP_MD *md, int en_de,
+                              OSSL_LIB_CTX *libctx, const char *propq);
+ int EVP_PBE_scrypt(const char *pass, size_t passlen,
+                    const unsigned char *salt, size_t saltlen,
+                    uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
+                    unsigned char *key, size_t keylen);
+ int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
+                       const unsigned char *salt, size_t saltlen,
+                       uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
+                       unsigned char *key, size_t keylen,
+                       OSSL_LIB_CTX *ctx, const char *propq);
+ int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
+                              int passlen, ASN1_TYPE *param,
+                              const EVP_CIPHER *c, const EVP_MD *md, int en_de);
+ int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
+                                 int passlen, ASN1_TYPE *param,
+                                 const EVP_CIPHER *c, const EVP_MD *md, int en_de,
+                                 OSSL_LIB_CTX *libctx, const char *propq);
+
+ #include <openssl/x509.h>
+
+ int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
+                          const unsigned char *salt, int saltlen);
+ int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
+                             const unsigned char *salt, int saltlen,
+                             OSSL_LIB_CTX *libctx);
+
+ X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
+                           const unsigned char *salt, int saltlen);
+ X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
+                              const unsigned char *salt, int saltlen,
+                              OSSL_LIB_CTX *libctx);
+
+ X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
+                            unsigned char *salt, int saltlen);
+ X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
+                               unsigned char *salt, int saltlen,
+                               unsigned char *aiv, int prf_nid);
+ X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
+                                  unsigned char *salt, int saltlen,
+                                  unsigned char *aiv, int prf_nid,
+                                  OSSL_LIB_CTX *libctx);
+ X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
+                                   const unsigned char *salt, int saltlen,
+                                   unsigned char *aiv, uint64_t N, uint64_t r,
+                                   uint64_t p);
+
+ X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
+                              int prf_nid, int keylen);
+ X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
+                                 int prf_nid, int keylen,
+                                 OSSL_LIB_CTX *libctx);
+
+=head1 DESCRIPTION
+
+=head2 Key Derivation
+
+PKCS5_PBE_keyivgen() takes a password I<pass> of
+length I<passlen>, parameters I<param> and a message digest function I<md_type>
+and performs a key derivation according to PKCS#5 PBES1. The resulting key is
+then used to initialise the cipher context I<ctx> with a cipher I<cipher> for
+encryption (I<en_de>=1) or decryption (I<en_de>=0).
+
+I<pass> is an optional parameter and can be NULL. If I<passlen> is -1, then the
+function will calculate the length of I<pass> using strlen().
+
+PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above
+but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied
+parameters.
+
+PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the
+key derivation part of the encryption algorithm.
+
+I<salt> is the salt used in the derivation of length I<saltlen>. If the
+I<salt> is NULL, then I<saltlen> must be 0. The function will not
+attempt to calculate the length of the I<salt> because it is not assumed to
+be NULL terminated.
+
+I<iter> is the iteration count and its value should be greater than or
+equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
+I<iter> less than 1 is treated as a single iteration.
+
+I<digest> is the message digest function used in the derivation.
+
+Functions ending in _ex() take optional parameters I<libctx> and I<propq> which
+are used to select appropriate algorithm implementations.
+
+=head2 Algorithm Identifier Creation
+
+PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
+PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an B<X509_ALGOR>
+object which represents an AlgorithmIdentifier containing the algorithm OID and
+associated parameters for the PBE algorithm.
+
+PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an B<X509_ALGOR>
+object which represents an AlgorithmIdentifier containing the algorithm OID and
+associated parameters for the PBKDF2 algorithm.
+
+PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and
+parameters into the supplied B<X509_ALGOR>.
+
+=head1 NOTES
+
+The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects.
+
+These functions make no assumption regarding the given password.
+It will simply be treated as a byte sequence.
+
+=head1 RETURN VALUES
+
+PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(),
+PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(),
+PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and
+PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.
+
+PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
+PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(),
+PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an B<X509_ALGOR> object or
+NULL if an error occurs.
+
+=head1 CONFORMING TO
+
+IETF RFC 8018 (L<https://tools.ietf.org/html/rfc8018>)
+
+=head1 SEE ALSO
+
+L<EVP_PBE_CipherInit_ex(3)>,
+L<PKCS12_pbe_crypt_ex(3)>,
+L<passphrase-encoding(7)>
+
+=head1 HISTORY
+
+PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(),
+PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and
+PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man3/PKCS5_PBKDF2_HMAC.pod b/doc/man3/PKCS5_PBKDF2_HMAC.pod
index 51f97e7380..51c8ce8e6d 100644
--- a/doc/man3/PKCS5_PBKDF2_HMAC.pod
+++ b/doc/man3/PKCS5_PBKDF2_HMAC.pod
@@ -35,9 +35,8 @@ B<iter> is the iteration count and its value should be greater than or
 equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
 B<iter> less than 1 is treated as a single iteration.
 
-B<digest> is the message digest function used in the derivation. Values include
-any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls
-PKCS5_PBKDF2_HMAC() with EVP_sha1().
+B<digest> is the message digest function used in the derivation.
+PKCS5_PBKDF2_HMAC_SHA1() calls PKCS5_PBKDF2_HMAC() with EVP_sha1().
 
 The derived key will be written to B<out>. The size of the B<out> buffer
 is specified via B<keylen>.
diff --git a/doc/man3/PKCS8_encrypt.pod b/doc/man3/PKCS8_encrypt.pod
new file mode 100644
index 0000000000..8a42b83310
--- /dev/null
+++ b/doc/man3/PKCS8_encrypt.pod
@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+PKCS8_decrypt, PKCS8_decrypt_ex, PKCS8_encrypt, PKCS8_encrypt_ex,
+PKCS8_set0_pbe, PKCS8_set0_pbe_ex - PKCS8 encrypt/decrypt functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ PKCS8_PRIV_KEY_INFO *PKCS8_decrypt(const X509_SIG *p8, const char *pass,
+                                    int passlen);
+ PKCS8_PRIV_KEY_INFO *PKCS8_decrypt_ex(const X509_SIG *p8, const char *pass,
+                                       int passlen, OSSL_LIB_CTX *ctx,
+                                       const char *propq);
+ X509_SIG *PKCS8_encrypt(int pbe_nid, const EVP_CIPHER *cipher,
+                         const char *pass, int passlen, unsigned char *salt,
+                         int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8);
+ X509_SIG *PKCS8_encrypt_ex(int pbe_nid, const EVP_CIPHER *cipher,
+                            const char *pass, int passlen, unsigned char *salt,
+                            int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8,
+                            OSSL_LIB_CTX *ctx, const char *propq);
+ X509_SIG *PKCS8_set0_pbe(const char *pass, int passlen,
+                         PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe);
+ X509_SIG *PKCS8_set0_pbe_ex(const char *pass, int passlen,
+                             PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe,
+                             OSSL_LIB_CTX *ctx);
+
+=head1 DESCRIPTION
+
+PKCS8_encrypt() and PKCS8_encrypt_ex() perform encryption of an object I<p8> using
+the password I<pass> of length I<passlen>, salt I<salt> of length I<saltlen>
+and iteration count I<iter>.
+The resulting B<X509_SIG> contains the encoded algorithm parameters and encrypted
+key.
+
+PKCS8_decrypt() and PKCS8_decrypt_ex() perform decryption of an B<X509_SIG> in
+I<p8> using the password I<pass> of length I<passlen> along with algorithm
+parameters obtained from the I<p8>.
+
+PKCS8_set0_pbe() and PKCS8_set0_pbe_ex() perform encryption of the I<p8inf>
+using the password I<pass> of length I<passlen> and parameters I<pbe>.
+
+Functions ending in _ex() allow for a library context I<ctx> and property query
+I<propq> to be used to select algorithm implementations.
+
+=head1 RETURN VALUES
+
+PKCS8_encrypt(), PKCS8_encrypt_ex(), PKCS8_set0_pbe() and PKCS8_set0_pbe_ex()
+return an encrypted key in a B<X509_SIG> structure or NULL if an error occurs.
+
+PKCS8_decrypt() and PKCS8_decrypt_ex() return a B<PKCS8_PRIV_KEY_INFO> or NULL
+if an error occurs.
+
+=head1 CONFORMING TO
+
+IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
+
+=head1 SEE ALSO
+
+L<crypto(7)>
+
+=head1 HISTORY
+
+PKCS8_decrypt_ex(), PKCS8_encrypt_ex() and PKCS8_set0_pbe_ex() were added in
+OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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