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