1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryPKCS12_key_gen_asc, PKCS12_key_gen_asc_ex, 6*b077aed3SPierre ProncheryPKCS12_key_gen_uni, PKCS12_key_gen_uni_ex, 7*b077aed3SPierre ProncheryPKCS12_key_gen_utf8, PKCS12_key_gen_utf8_ex - PKCS#12 Password based key derivation 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery=head1 SYNOPSIS 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery #include <openssl/pkcs12.h> 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery int PKCS12_key_gen_asc(const char *pass, int passlen, unsigned char *salt, 14*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 15*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type); 16*b077aed3SPierre Pronchery int PKCS12_key_gen_asc_ex(const char *pass, int passlen, unsigned char *salt, 17*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 18*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type, 19*b077aed3SPierre Pronchery OSSL_LIB_CTX *ctx, const char *propq); 20*b077aed3SPierre Pronchery int PKCS12_key_gen_uni(unsigned char *pass, int passlen, unsigned char *salt, 21*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 22*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type); 23*b077aed3SPierre Pronchery int PKCS12_key_gen_uni_ex(unsigned char *pass, int passlen, unsigned char *salt, 24*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 25*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type, 26*b077aed3SPierre Pronchery OSSL_LIB_CTX *ctx, const char *propq); 27*b077aed3SPierre Pronchery int PKCS12_key_gen_utf8(const char *pass, int passlen, unsigned char *salt, 28*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 29*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type); 30*b077aed3SPierre Pronchery int PKCS12_key_gen_utf8_ex(const char *pass, int passlen, unsigned char *salt, 31*b077aed3SPierre Pronchery int saltlen, int id, int iter, int n, 32*b077aed3SPierre Pronchery unsigned char *out, const EVP_MD *md_type, 33*b077aed3SPierre Pronchery OSSL_LIB_CTX *ctx, const char *propq); 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=head1 DESCRIPTION 36*b077aed3SPierre Pronchery 37*b077aed3SPierre ProncheryThese methods perform a key derivation according to PKCS#12 (RFC7292) 38*b077aed3SPierre Proncherywith an input password I<pass> of length I<passlen>, a salt I<salt> of length 39*b077aed3SPierre ProncheryI<saltlen>, an iteration count I<iter> and a digest algorithm I<md_type>. 40*b077aed3SPierre ProncheryThe ID byte I<id> determines how the resulting key is intended to be used: 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Pronchery=over 4 43*b077aed3SPierre Pronchery 44*b077aed3SPierre Pronchery=item * 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryIf ID=1, then the pseudorandom bits being produced are to be used 47*b077aed3SPierre Proncheryas key material for performing encryption or decryption. 48*b077aed3SPierre Pronchery 49*b077aed3SPierre Pronchery=item * 50*b077aed3SPierre Pronchery 51*b077aed3SPierre ProncheryIf ID=2, then the pseudorandom bits being produced are to be used 52*b077aed3SPierre Proncheryas an IV (Initial Value) for encryption or decryption. 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=item * 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryIf ID=3, then the pseudorandom bits being produced are to be used 57*b077aed3SPierre Proncheryas an integrity key for MACing. 58*b077aed3SPierre Pronchery 59*b077aed3SPierre Pronchery=back 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryThe intended format of the supplied password is determined by the method chosen: 62*b077aed3SPierre Pronchery 63*b077aed3SPierre Pronchery=over 4 64*b077aed3SPierre Pronchery 65*b077aed3SPierre Pronchery=item * 66*b077aed3SPierre Pronchery 67*b077aed3SPierre ProncheryPKCS12_key_gen_asc() and PKCS12_key_gen_asc_ex() expect an ASCII-formatted password. 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery=item * 70*b077aed3SPierre Pronchery 71*b077aed3SPierre ProncheryPKCS12_key_gen_uni() and PKCS12_key_gen_uni_ex() expect a Unicode-formatted password. 72*b077aed3SPierre Pronchery 73*b077aed3SPierre Pronchery=item * 74*b077aed3SPierre Pronchery 75*b077aed3SPierre ProncheryPKCS12_key_gen_utf8() and PKCS12_key_gen_utf8_ex() expect a UTF-8 encoded password. 76*b077aed3SPierre Pronchery 77*b077aed3SPierre Pronchery=back 78*b077aed3SPierre Pronchery 79*b077aed3SPierre ProncheryI<pass> is the password used in the derivation of length I<passlen>. I<pass> 80*b077aed3SPierre Proncheryis an optional parameter and can be NULL. If I<passlen> is -1, then the 81*b077aed3SPierre Proncheryfunction will calculate the length of I<pass> using strlen(). 82*b077aed3SPierre Pronchery 83*b077aed3SPierre ProncheryI<salt> is the salt used in the derivation of length I<saltlen>. If the 84*b077aed3SPierre ProncheryI<salt> is NULL, then I<saltlen> must be 0. The function will not 85*b077aed3SPierre Proncheryattempt to calculate the length of the I<salt> because it is not assumed to 86*b077aed3SPierre Proncherybe NULL terminated. 87*b077aed3SPierre Pronchery 88*b077aed3SPierre ProncheryI<iter> is the iteration count and its value should be greater than or 89*b077aed3SPierre Proncheryequal to 1. RFC 2898 suggests an iteration count of at least 1000. Any 90*b077aed3SPierre ProncheryI<iter> less than 1 is treated as a single iteration. 91*b077aed3SPierre Pronchery 92*b077aed3SPierre ProncheryI<digest> is the message digest function used in the derivation. 93*b077aed3SPierre Pronchery 94*b077aed3SPierre ProncheryThe derived key will be written to I<out>. The size of the I<out> buffer 95*b077aed3SPierre Proncheryis specified via I<n>. 96*b077aed3SPierre Pronchery 97*b077aed3SPierre ProncheryFunctions ending in _ex() allow for a library context I<ctx> and property query 98*b077aed3SPierre ProncheryI<propq> to be used to select algorithm implementations. 99*b077aed3SPierre Pronchery 100*b077aed3SPierre Pronchery=head1 NOTES 101*b077aed3SPierre Pronchery 102*b077aed3SPierre ProncheryA typical application of this function is to derive keying material for an 103*b077aed3SPierre Proncheryencryption algorithm from a password in the I<pass>, a salt in I<salt>, 104*b077aed3SPierre Proncheryand an iteration count. 105*b077aed3SPierre Pronchery 106*b077aed3SPierre ProncheryIncreasing the I<iter> parameter slows down the algorithm which makes it 107*b077aed3SPierre Proncheryharder for an attacker to perform a brute force attack using a large number 108*b077aed3SPierre Proncheryof candidate passwords. 109*b077aed3SPierre Pronchery 110*b077aed3SPierre Pronchery=head1 RETURN VALUES 111*b077aed3SPierre Pronchery 112*b077aed3SPierre ProncheryReturns 1 on success or 0 on error. 113*b077aed3SPierre Pronchery 114*b077aed3SPierre Pronchery=head1 CONFORMING TO 115*b077aed3SPierre Pronchery 116*b077aed3SPierre ProncheryIETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>) 117*b077aed3SPierre Pronchery 118*b077aed3SPierre Pronchery=head1 SEE ALSO 119*b077aed3SPierre Pronchery 120*b077aed3SPierre ProncheryL<PKCS12_create_ex(3)>, 121*b077aed3SPierre ProncheryL<PKCS12_pbe_crypt_ex(3)>, 122*b077aed3SPierre ProncheryL<passphrase-encoding(7)> 123*b077aed3SPierre Pronchery 124*b077aed3SPierre Pronchery=head1 HISTORY 125*b077aed3SPierre Pronchery 126*b077aed3SPierre ProncheryPKCS12_key_gen_asc_ex(), PKCS12_key_gen_uni_ex() and PKCS12_key_gen_utf8_ex() 127*b077aed3SPierre Proncherywere added in OpenSSL 3.0. 128*b077aed3SPierre Pronchery 129*b077aed3SPierre Pronchery=head1 COPYRIGHT 130*b077aed3SPierre Pronchery 131*b077aed3SPierre ProncheryCopyright 2021 The OpenSSL Project Authors. All Rights Reserved. 132*b077aed3SPierre Pronchery 133*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 134*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 135*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 136*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 137*b077aed3SPierre Pronchery 138*b077aed3SPierre Pronchery=cut 139