EVP_PBE_CipherInit.pod 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
  1. =pod
  2. =head1 NAME
  3. EVP_PBE_CipherInit, EVP_PBE_CipherInit_ex,
  4. EVP_PBE_find, EVP_PBE_find_ex - Password based encryption routines
  5. =head1 SYNOPSIS
  6. #include <openssl/evp.h>
  7. int EVP_PBE_CipherInit(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,
  8. ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de);
  9. int EVP_PBE_CipherInit_ex(ASN1_OBJECT *pbe_obj, const char *pass, int passlen,
  10. ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de,
  11. OSSL_LIB_CTX *libctx, const char *propq);
  12. int EVP_PBE_find(int type, int pbe_nid, int *pcnid, int *pmnid,
  13. EVP_PBE_KEYGEN **pkeygen);
  14. int EVP_PBE_find_ex(int type, int pbe_nid, int *pcnid, int *pmnid,
  15. EVP_PBE_KEYGEN **pkeygen, EVP_PBE_KEYGEN_EX **keygen_ex);
  16. =head1 DESCRIPTION
  17. =head2 PBE operations
  18. EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex() initialise an B<EVP_CIPHER_CTX>
  19. I<ctx> for encryption (I<en_de>=1) or decryption (I<en_de>=0) using the password
  20. I<pass> of length I<passlen>. The PBE algorithm type and parameters are extracted
  21. from an OID I<pbe_obj> and parameters I<param>.
  22. EVP_PBE_CipherInit_ex() also allows the application to specify a library context
  23. I<libctx> and property query I<propq> to select appropriate algorithm
  24. implementations.
  25. =head2 PBE algorithm search
  26. EVP_PBE_find() and EVP_PBE_find_ex() search for a matching algorithm using two parameters:
  27. 1. An algorithm type I<type> which can be:
  28. =over 4
  29. =item *
  30. EVP_PBE_TYPE_OUTER - A PBE algorithm
  31. =item *
  32. EVP_PBE_TYPE_PRF - A pseudo-random function
  33. =item *
  34. EVP_PBE_TYPE_KDF - A key derivation function
  35. =back
  36. 2. A I<pbe_nid> which can represent the algorithm identifier with parameters e.g.
  37. B<NID_pbeWithSHA1AndRC2_CBC> or an algorithm class e.g. B<NID_pbes2>.
  38. They return the algorithm's cipher ID I<pcnid>, digest ID I<pmnid> and a key
  39. generation function for the algorithm I<pkeygen>. EVP_PBE_CipherInit_ex() also
  40. returns an extended key generation function I<keygen_ex> which takes a library
  41. context and property query.
  42. If a NULL is supplied for any of I<pcnid>, I<pmnid>, I<pkeygen> or I<pkeygen_ex>
  43. then this parameter is not returned.
  44. =head1 NOTES
  45. The arguments I<pbe_obj> and I<param> to EVP_PBE_CipherInit() and EVP_PBE_CipherInit_ex()
  46. together form an B<X509_ALGOR> and can often be extracted directly from this structure.
  47. =head1 RETURN VALUES
  48. Return value is 1 for success and 0 if an error occurred.
  49. =head1 SEE ALSO
  50. L<PKCS5_PBE_keyivgen(3)>,
  51. L<PKCS12_PBE_keyivgen_ex(3)>,
  52. L<PKCS5_v2_PBE_keyivgen_ex(3)>,
  53. L<PKCS12_pbe_crypt_ex(3)>,
  54. L<PKCS12_create_ex(3)>
  55. =head1 HISTORY
  56. EVP_PBE_CipherInit_ex() and EVP_PBE_find_ex() were added in OpenSSL 3.0.
  57. =head1 COPYRIGHT
  58. Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
  59. Licensed under the Apache License 2.0 (the "License"). You may not use
  60. this file except in compliance with the License. You can obtain a copy
  61. in the file LICENSE in the source distribution or at
  62. L<https://www.openssl.org/source/license.html>.
  63. =cut