doc/man3/EVP_PBE_CipherInit.pod

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