[thirdparty/openssl.git] / doc / man3 / PKCS5_PBE_keyivgen.pod

=pod

=head1 NAME

PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, 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_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, 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 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() and PKCS5_PBE_keyivgen_ex() take 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>.

If I<salt> is NULL, then I<saltlen> specifies the size in bytes of the random salt to
generate. If I<saltlen> is 0 then a default size is used.
For PBE related functions such as PKCS5_pbe_set_ex() the default salt length is 8 bytes.
For PBE2 related functions that use PBKDF2 such as PKCS5_pbkdf2_set(),
PKCS5_pbe2_set_scrypt() and PKCS5_pbe2_set() the default salt length is 16 bytes.

=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.

From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and
PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF.

In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2
related functions such as PKCS5_pbe2_set().
This is required for PBKDF2 FIPS compliance.

=head1 COPYRIGHT

Copyright 2021-2023 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
Commit	Line	Data
b536880c JS	1	=pod
	2
	3	=head1 NAME
	4
8bb6fdfc	5	PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv,
b536880c JS	6	PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt,
	7	PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex,
	8	PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex,
	9	PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex,
	10	PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex
	11	- PKCS#5 Password based encryption routines
	12
	13	=head1 SYNOPSIS
	14
	15	#include <openssl/evp.h>
	16
	17	int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX ctx, const char pass, int passlen,
	18	ASN1_TYPE param, const EVP_CIPHER cipher,
	19	const EVP_MD *md, int en_de);
8bb6fdfc JS	20	int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX cctx, const char pass, int passlen,
	21	ASN1_TYPE param, const EVP_CIPHER cipher,
	22	const EVP_MD md, int en_de, OSSL_LIB_CTX libctx,
	23	const char *propq);
b536880c JS	24	int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX ctx, const char pass, int passlen,
	25	ASN1_TYPE param, const EVP_CIPHER cipher,
	26	const EVP_MD *md, int en_de);
	27	int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX ctx, const char pass, int passlen,
	28	ASN1_TYPE param, const EVP_CIPHER cipher,
	29	const EVP_MD *md, int en_de,
	30	OSSL_LIB_CTX libctx, const char propq);
	31	int EVP_PBE_scrypt(const char *pass, size_t passlen,
	32	const unsigned char *salt, size_t saltlen,
	33	uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
	34	unsigned char *key, size_t keylen);
	35	int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
	36	const unsigned char *salt, size_t saltlen,
	37	uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
	38	unsigned char *key, size_t keylen,
	39	OSSL_LIB_CTX ctx, const char propq);
	40	int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX ctx, const char pass,
	41	int passlen, ASN1_TYPE *param,
	42	const EVP_CIPHER c, const EVP_MD md, int en_de);
	43	int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX ctx, const char pass,
	44	int passlen, ASN1_TYPE *param,
	45	const EVP_CIPHER c, const EVP_MD md, int en_de,
	46	OSSL_LIB_CTX libctx, const char propq);
	47
	48	#include <openssl/x509.h>
	49
	50	int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
	51	const unsigned char *salt, int saltlen);
	52	int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
	53	const unsigned char *salt, int saltlen,
	54	OSSL_LIB_CTX *libctx);
	55
	56	X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
	57	const unsigned char *salt, int saltlen);
	58	X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
	59	const unsigned char *salt, int saltlen,
	60	OSSL_LIB_CTX *libctx);
	61
	62	X509_ALGOR PKCS5_pbe2_set(const EVP_CIPHER cipher, int iter,
	63	unsigned char *salt, int saltlen);
	64	X509_ALGOR PKCS5_pbe2_set_iv(const EVP_CIPHER cipher, int iter,
	65	unsigned char *salt, int saltlen,
	66	unsigned char *aiv, int prf_nid);
	67	X509_ALGOR PKCS5_pbe2_set_iv_ex(const EVP_CIPHER cipher, int iter,
	68	unsigned char *salt, int saltlen,
	69	unsigned char *aiv, int prf_nid,
	70	OSSL_LIB_CTX *libctx);
	71	X509_ALGOR PKCS5_pbe2_set_scrypt(const EVP_CIPHER cipher,
	72	const unsigned char *salt, int saltlen,
	73	unsigned char *aiv, uint64_t N, uint64_t r,
	74	uint64_t p);
	75
	76	X509_ALGOR PKCS5_pbkdf2_set(int iter, unsigned char salt, int saltlen,
	77	int prf_nid, int keylen);
	78	X509_ALGOR PKCS5_pbkdf2_set_ex(int iter, unsigned char salt, int saltlen,
	79	int prf_nid, int keylen,
	80	OSSL_LIB_CTX *libctx);
	81
	82	=head1 DESCRIPTION
	83
	84	=head2 Key Derivation
	85
8bb6fdfc	86	PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password I<pass> of
b536880c JS	87	length I<passlen>, parameters I<param> and a message digest function I<md_type>
	88	and performs a key derivation according to PKCS#5 PBES1. The resulting key is
	89	then used to initialise the cipher context I<ctx> with a cipher I<cipher> for
	90	encryption (I<en_de>=1) or decryption (I<en_de>=0).
	91
	92	I<pass> is an optional parameter and can be NULL. If I<passlen> is -1, then the
	93	function will calculate the length of I<pass> using strlen().
	94
	95	PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above
	96	but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied
	97	parameters.
	98
	99	PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the
	100	key derivation part of the encryption algorithm.
	101
	102	I<salt> is the salt used in the derivation of length I<saltlen>. If the
	103	I<salt> is NULL, then I<saltlen> must be 0. The function will not
	104	attempt to calculate the length of the I<salt> because it is not assumed to
	105	be NULL terminated.
	106
	107	I<iter> is the iteration count and its value should be greater than or
	108	equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
	109	I<iter> less than 1 is treated as a single iteration.
	110
	111	I<digest> is the message digest function used in the derivation.
	112
	113	Functions ending in _ex() take optional parameters I<libctx> and I<propq> which
	114	are used to select appropriate algorithm implementations.
	115
	116	=head2 Algorithm Identifier Creation
	117
	118	PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
	119	PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an B<X509_ALGOR>
	120	object which represents an AlgorithmIdentifier containing the algorithm OID and
	121	associated parameters for the PBE algorithm.
	122
	123	PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an B<X509_ALGOR>
	124	object which represents an AlgorithmIdentifier containing the algorithm OID and
	125	associated parameters for the PBKDF2 algorithm.
	126
	127	PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and
	128	parameters into the supplied B<X509_ALGOR>.
	129
3859a027	130	If I<salt> is NULL, then I<saltlen> specifies the size in bytes of the random salt to
	131	generate. If I<saltlen> is 0 then a default size is used.
	132	For PBE related functions such as PKCS5_pbe_set_ex() the default salt length is 8 bytes.
	133	For PBE2 related functions that use PBKDF2 such as PKCS5_pbkdf2_set(),
	134	PKCS5_pbe2_set_scrypt() and PKCS5_pbe2_set() the default salt length is 16 bytes.
	135
b536880c JS	136	=head1 NOTES
	137
	138	The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects.
	139
	140	These functions make no assumption regarding the given password.
	141	It will simply be treated as a byte sequence.
	142
	143	=head1 RETURN VALUES
	144
	145	PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(),
	146	PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(),
	147	PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and
	148	PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.
	149
	150	PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
	151	PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(),
	152	PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an B<X509_ALGOR> object or
	153	NULL if an error occurs.
	154
	155	=head1 CONFORMING TO
	156
	157	IETF RFC 8018 (L<https://tools.ietf.org/html/rfc8018>)
	158
	159	=head1 SEE ALSO
	160
	161	L<EVP_PBE_CipherInit_ex(3)>,
	162	L<PKCS12_pbe_crypt_ex(3)>,
	163	L<passphrase-encoding(7)>
	164
	165	=head1 HISTORY
	166
	167	PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(),
	168	PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and
	169	PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.
	170
0f183675 JS	171	From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and
	172	PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF.
	173
3859a027	174	In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2
	175	related functions such as PKCS5_pbe2_set().
	176	This is required for PBKDF2 FIPS compliance.
	177
b536880c JS	178	=head1 COPYRIGHT
b536880c JS	179
3859a027	180	Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
b536880c JS	181
	182	Licensed under the Apache License 2.0 (the "License"). You may not use
	183	this file except in compliance with the License. You can obtain a copy
	184	in the file LICENSE in the source distribution or at
	185	L<https://www.openssl.org/source/license.html>.
	186
	187	=cut