1=pod 2 3=head1 NAME 4 5PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv, 6PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt, 7PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex, 8PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex, 9PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex, 10PKCS5_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); 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); 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 86PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password I<pass> of 87length I<passlen>, parameters I<param> and a message digest function I<md_type> 88and performs a key derivation according to PKCS#5 PBES1. The resulting key is 89then used to initialise the cipher context I<ctx> with a cipher I<cipher> for 90encryption (I<en_de>=1) or decryption (I<en_de>=0). 91 92I<pass> is an optional parameter and can be NULL. If I<passlen> is -1, then the 93function will calculate the length of I<pass> using strlen(). 94 95PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above 96but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied 97parameters. 98 99PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the 100key derivation part of the encryption algorithm. 101 102I<salt> is the salt used in the derivation of length I<saltlen>. If the 103I<salt> is NULL, then I<saltlen> must be 0. The function will not 104attempt to calculate the length of the I<salt> because it is not assumed to 105be NULL terminated. 106 107I<iter> is the iteration count and its value should be greater than or 108equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any 109I<iter> less than 1 is treated as a single iteration. 110 111I<digest> is the message digest function used in the derivation. 112 113Functions ending in _ex() take optional parameters I<libctx> and I<propq> which 114are used to select appropriate algorithm implementations. 115 116=head2 Algorithm Identifier Creation 117 118PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), 119PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an B<X509_ALGOR> 120object which represents an AlgorithmIdentifier containing the algorithm OID and 121associated parameters for the PBE algorithm. 122 123PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an B<X509_ALGOR> 124object which represents an AlgorithmIdentifier containing the algorithm OID and 125associated parameters for the PBKDF2 algorithm. 126 127PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and 128parameters into the supplied B<X509_ALGOR>. 129 130If I<salt> is NULL, then I<saltlen> specifies the size in bytes of the random salt to 131generate. If I<saltlen> is 0 then a default size is used. 132For PBE related functions such as PKCS5_pbe_set_ex() the default salt length is 8 bytes. 133For PBE2 related functions that use PBKDF2 such as PKCS5_pbkdf2_set(), 134PKCS5_pbe2_set_scrypt() and PKCS5_pbe2_set() the default salt length is 16 bytes. 135 136=head1 NOTES 137 138The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects. 139 140These functions make no assumption regarding the given password. 141It will simply be treated as a byte sequence. 142 143=head1 RETURN VALUES 144 145PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(), 146PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(), 147PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and 148PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs. 149 150PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), 151PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(), 152PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an B<X509_ALGOR> object or 153NULL if an error occurs. 154 155=head1 CONFORMING TO 156 157IETF RFC 8018 (L<https://tools.ietf.org/html/rfc8018>) 158 159=head1 SEE ALSO 160 161L<EVP_PBE_CipherInit_ex(3)>, 162L<PKCS12_pbe_crypt_ex(3)>, 163L<passphrase-encoding(7)> 164 165=head1 HISTORY 166 167PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(), 168PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and 169PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0. 170 171From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and 172PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF. 173 174In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2 175related functions such as PKCS5_pbe2_set(). 176This is required for PBKDF2 FIPS compliance. 177 178=head1 COPYRIGHT 179 180Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved. 181 182Licensed under the Apache License 2.0 (the "License"). You may not use 183this file except in compliance with the License. You can obtain a copy 184in the file LICENSE in the source distribution or at 185L<https://www.openssl.org/source/license.html>. 186 187=cut 188
