diff options
author | Jon Spillett <jon.spillett@oracle.com> | 2021-02-17 17:56:36 +1000 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2021-04-30 09:15:50 +1000 |
commit | b536880c45722777df5ebe62897a6efcef757945 (patch) | |
tree | 015ad29f74586e3407079864fa686ffcde658fad /doc/man3 | |
parent | d77ba503a2cf1c83098baca345327761b991d191 (diff) |
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)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/EVP_PBE_CipherInit.pod | 99 | ||||
-rw-r--r-- | doc/man3/PKCS12_PBE_keyivgen.pod | 108 | ||||
-rw-r--r-- | doc/man3/PKCS12_SAFEBAG_create_cert.pod | 28 | ||||
-rw-r--r-- | doc/man3/PKCS12_add_cert.pod | 27 | ||||
-rw-r--r-- | doc/man3/PKCS12_add_safe.pod | 27 | ||||
-rw-r--r-- | doc/man3/PKCS12_create.pod | 23 | ||||
-rw-r--r-- | doc/man3/PKCS12_decrypt_skey.pod | 55 | ||||
-rw-r--r-- | doc/man3/PKCS12_gen_mac.pod | 72 | ||||
-rw-r--r-- | doc/man3/PKCS12_init.pod | 48 | ||||
-rw-r--r-- | doc/man3/PKCS12_item_decrypt_d2i.pod | 73 | ||||
-rw-r--r-- | doc/man3/PKCS12_key_gen_utf8_ex.pod | 138 | ||||
-rw-r--r-- | doc/man3/PKCS12_pack_p7encdata.pod | 59 | ||||
-rw-r--r-- | doc/man3/PKCS5_PBE_keyivgen.pod | 170 | ||||
-rw-r--r-- | doc/man3/PKCS5_PBKDF2_HMAC.pod | 5 | ||||
-rw-r--r-- | doc/man3/PKCS8_encrypt.pod | 78 |
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, i |