1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_PBE_CipherInit, EVP_PBE_CipherInit_ex, 6*b077aed3SPierre ProncheryEVP_PBE_find, EVP_PBE_find_ex, 7*b077aed3SPierre ProncheryEVP_PBE_alg_add_type, EVP_PBE_alg_add - Password based encryption routines 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery=head1 SYNOPSIS 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery #include <openssl/evp.h> 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery int EVP_PBE_CipherInit(ASN1_OBJECT *pbe_obj, const char *pass, int passlen, 14*b077aed3SPierre Pronchery ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de); 15*b077aed3SPierre Pronchery int EVP_PBE_CipherInit_ex(ASN1_OBJECT *pbe_obj, const char *pass, int passlen, 16*b077aed3SPierre Pronchery ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de, 17*b077aed3SPierre Pronchery OSSL_LIB_CTX *libctx, const char *propq); 18*b077aed3SPierre Pronchery 19*b077aed3SPierre Pronchery int EVP_PBE_find(int type, int pbe_nid, int *pcnid, int *pmnid, 20*b077aed3SPierre Pronchery EVP_PBE_KEYGEN **pkeygen); 21*b077aed3SPierre Pronchery int EVP_PBE_find_ex(int type, int pbe_nid, int *pcnid, int *pmnid, 22*b077aed3SPierre Pronchery EVP_PBE_KEYGEN **pkeygen, EVP_PBE_KEYGEN_EX **keygen_ex); 23*b077aed3SPierre Pronchery 24*b077aed3SPierre Pronchery int EVP_PBE_alg_add_type(int pbe_type, int pbe_nid, int cipher_nid, 25*b077aed3SPierre Pronchery int md_nid, EVP_PBE_KEYGEN *keygen); 26*b077aed3SPierre Pronchery int EVP_PBE_alg_add(int nid, const EVP_CIPHER *cipher, const EVP_MD *md, 27*b077aed3SPierre Pronchery EVP_PBE_KEYGEN *keygen); 28*b077aed3SPierre Pronchery 29*b077aed3SPierre Pronchery=head1 DESCRIPTION 30*b077aed3SPierre Pronchery 31*b077aed3SPierre Pronchery=head2 PBE operations 32*b077aed3SPierre Pronchery 33*b077aed3SPierre ProncheryEVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() initialise an B<EVP_CIPHER_CTX> 34*b077aed3SPierre ProncheryI<ctx> for encryption (I<en_de>=1) or decryption (I<en_de>=0) using the password 35*b077aed3SPierre ProncheryI<pass> of length I<passlen>. The PBE algorithm type and parameters are extracted 36*b077aed3SPierre Proncheryfrom an OID I<pbe_obj> and parameters I<param>. 37*b077aed3SPierre Pronchery 38*b077aed3SPierre ProncheryEVP_PBE_CipherInit_ex() also allows the application to specify a library context 39*b077aed3SPierre ProncheryI<libctx> and property query I<propq> to select appropriate algorithm 40*b077aed3SPierre Proncheryimplementations. 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Pronchery=head2 PBE algorithm search 43*b077aed3SPierre Pronchery 44*b077aed3SPierre ProncheryEVP_PBE_find() and EVP_PBE_find_ex() search for a matching algorithm using two parameters: 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery1. An algorithm type I<type> which can be: 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery=over 4 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Pronchery=item * 51*b077aed3SPierre Pronchery 52*b077aed3SPierre ProncheryEVP_PBE_TYPE_OUTER - A PBE algorithm 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=item * 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryEVP_PBE_TYPE_PRF - A pseudo-random function 57*b077aed3SPierre Pronchery 58*b077aed3SPierre Pronchery=item * 59*b077aed3SPierre Pronchery 60*b077aed3SPierre ProncheryEVP_PBE_TYPE_KDF - A key derivation function 61*b077aed3SPierre Pronchery 62*b077aed3SPierre Pronchery=back 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery2. A I<pbe_nid> which can represent the algorithm identifier with parameters e.g. 65*b077aed3SPierre ProncheryB<NID_pbeWithSHA1AndRC2_CBC> or an algorithm class e.g. B<NID_pbes2>. 66*b077aed3SPierre Pronchery 67*b077aed3SPierre ProncheryThey return the algorithm's cipher ID I<pcnid>, digest ID I<pmnid> and a key 68*b077aed3SPierre Proncherygeneration function for the algorithm I<pkeygen>. EVP_PBE_CipherInit_ex() also 69*b077aed3SPierre Proncheryreturns an extended key generation function I<keygen_ex> which takes a library 70*b077aed3SPierre Proncherycontext and property query. 71*b077aed3SPierre Pronchery 72*b077aed3SPierre ProncheryIf a NULL is supplied for any of I<pcnid>, I<pmnid>, I<pkeygen> or I<pkeygen_ex> 73*b077aed3SPierre Proncherythen this parameter is not returned. 74*b077aed3SPierre Pronchery 75*b077aed3SPierre Pronchery=head2 PBE algorithm add 76*b077aed3SPierre Pronchery 77*b077aed3SPierre ProncheryEVP_PBE_alg_add_type() and EVP_PBE_alg_add() add an algorithm to the list 78*b077aed3SPierre Proncheryof known algorithms. Their parameters have the same meaning as for 79*b077aed3SPierre ProncheryEVP_PBE_find() and EVP_PBE_find_ex() functions. 80*b077aed3SPierre Pronchery 81*b077aed3SPierre Pronchery=head1 NOTES 82*b077aed3SPierre Pronchery 83*b077aed3SPierre ProncheryThe arguments I<pbe_obj> and I<param> to EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() 84*b077aed3SPierre Proncherytogether form an B<X509_ALGOR> and can often be extracted directly from this structure. 85*b077aed3SPierre Pronchery 86*b077aed3SPierre Pronchery=head1 RETURN VALUES 87*b077aed3SPierre Pronchery 88*b077aed3SPierre ProncheryReturn value is 1 for success and 0 if an error occurred. 89*b077aed3SPierre Pronchery 90*b077aed3SPierre Pronchery=head1 SEE ALSO 91*b077aed3SPierre Pronchery 92*b077aed3SPierre ProncheryL<PKCS5_PBE_keyivgen(3)>, 93*b077aed3SPierre ProncheryL<PKCS12_PBE_keyivgen_ex(3)>, 94*b077aed3SPierre ProncheryL<PKCS5_v2_PBE_keyivgen_ex(3)>, 95*b077aed3SPierre ProncheryL<PKCS12_pbe_crypt_ex(3)>, 96*b077aed3SPierre ProncheryL<PKCS12_create_ex(3)> 97*b077aed3SPierre Pronchery 98*b077aed3SPierre Pronchery=head1 HISTORY 99*b077aed3SPierre Pronchery 100*b077aed3SPierre ProncheryEVP_PBE_CipherInit_ex() and EVP_PBE_find_ex() were added in OpenSSL 3.0. 101*b077aed3SPierre Pronchery 102*b077aed3SPierre Pronchery=head1 COPYRIGHT 103*b077aed3SPierre Pronchery 104*b077aed3SPierre ProncheryCopyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved. 105*b077aed3SPierre Pronchery 106*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 107*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 108*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 109*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 110*b077aed3SPierre Pronchery 111*b077aed3SPierre Pronchery=cut 112