diff options
author | Tomas Mraz <tomas@openssl.org> | 2021-03-05 22:11:49 +0100 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2021-03-10 17:12:48 +0100 |
commit | 762970bd686c4aa8ea7169e7f76d5a4ce665da93 (patch) | |
tree | acf287acb8166e12129047e936b517a2d01c2542 /doc | |
parent | 18fdebf1743bc89bf82a205468c56c274e7baf3b (diff) |
Change default algorithms in PKCS12_create() and PKCS12_set_mac()
Use the modern defaults as now set in the pkcs12 app. This also
allows modifying the application to not override the default values
when calling the API.
Fixes #14034
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/14450)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/PKCS12_create.pod | 43 |
1 files changed, 23 insertions, 20 deletions
diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod index 58e1437bc2..994ff9f9e3 100644 --- a/doc/man3/PKCS12_create.pod +++ b/doc/man3/PKCS12_create.pod @@ -16,31 +16,28 @@ PKCS12_create - create a PKCS#12 structure PKCS12_create() creates a PKCS#12 structure. -B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for -the supplied certificate and key. B<pkey> is the private key to include in -the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL> +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 is an optional set of certificates to also include in the structure. -B<nid_key> and B<nid_cert> are the encryption algorithms that should be used +I<nid_key> and I<nid_cert> are the encryption algorithms that should be used for the key and certificate respectively. The modes -GCM, CCM, XTS, and OCB are unsupported. B<iter> is the encryption algorithm -iteration count to use and B<mac_iter> is the MAC iteration count to use. -B<keytype> is the type of key. +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. =head1 NOTES -The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype> +The parameters I<nid_key>, I<nid_cert>, I<iter>, I<mac_iter> and I<keytype> can all be set to zero and sensible defaults will be used. -These defaults are: 40 bit RC2 encryption for certificates, triple DES -encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER -(currently 2048) and a MAC iteration count of 1. +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. -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 B<mac_iter> should be set to PKCS12_DEFAULT_ITER. - -B<keytype> adds a flag to the store private key. This is a non standard extension +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> it can be used for signing and encryption. This option was useful for old @@ -48,18 +45,18 @@ export grade software which could use signing only keys of arbitrary size but had restrictions on the permissible sizes of keys which could be used for encryption. -If a certificate contains an B<alias> or B<keyid> then this will be +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 B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or +Either I<pkey>, I<cert> or both can be NULL to indicate that no key or certificate is required. In previous versions both had to be present or a fatal error is returned. -B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption +I<nid_key> or I<nid_cert> can be set to -1 indicating that no encryption should be used. -B<mac_iter> can be set to -1 and the MAC will then be omitted entirely. +I<mac_iter> can be set to -1 and the MAC will then be omitted entirely. PKCS12_create() makes assumptions regarding the encoding of the given pass phrase. @@ -74,6 +71,12 @@ PKCS12_create() returns a valid B<PKCS12> structure or NULL if an error occurred L<d2i_PKCS12(3)>, L<passphrase-encoding(7)> +=head1 HISTORY + +The defaults for encryption algorithms, MAC algorithm, and the MAC key +derivation iteration count were changed in OpenSSL 3.0 to more modern +standards. + =head1 COPYRIGHT Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |