doc/man3/PKCS5_PBE_keyivgen.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv,
   6 PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt,
   7 PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex,
   8 PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex,
   9 PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex,
  10 PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex
  11 - PKCS#5 Password based encryption routines
  12
  13 =head1 SYNOPSIS
  14
  15  #include <openssl/evp.h>
  16
  17  int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  18                         ASN1_TYPE *param, const EVP_CIPHER *cipher,
  19                         const EVP_MD *md, int en_de);
  20  int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen,
  21                            ASN1_TYPE *param, const EVP_CIPHER *cipher,
  22                            const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx,
  23                            const char *propq);
  24  int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  25                            ASN1_TYPE *param, const EVP_CIPHER *cipher,
  26                            const EVP_MD *md, int en_de);
  27  int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  28                               ASN1_TYPE *param, const EVP_CIPHER *cipher,
  29                               const EVP_MD *md, int en_de,
  30                               OSSL_LIB_CTX *libctx, const char *propq);
  31  int EVP_PBE_scrypt(const char *pass, size_t passlen,
  32                     const unsigned char *salt, size_t saltlen,
  33                     uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
  34                     unsigned char *key, size_t keylen);
  35  int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
  36                        const unsigned char *salt, size_t saltlen,
  37                        uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
  38                        unsigned char *key, size_t keylen,
  39                        OSSL_LIB_CTX *ctx, const char *propq);
  40  int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
  41                               int passlen, ASN1_TYPE *param,
  42                               const EVP_CIPHER *c, const EVP_MD *md, int en_de);
  43  int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
  44                                  int passlen, ASN1_TYPE *param,
  45                                  const EVP_CIPHER *c, const EVP_MD *md, int en_de,
  46                                  OSSL_LIB_CTX *libctx, const char *propq);
  47
  48  #include <openssl/x509.h>
  49
  50  int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
  51                           const unsigned char *salt, int saltlen);
  52  int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
  53                              const unsigned char *salt, int saltlen,
  54                              OSSL_LIB_CTX *libctx);
  55
  56  X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
  57                            const unsigned char *salt, int saltlen);
  58  X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
  59                               const unsigned char *salt, int saltlen,
  60                               OSSL_LIB_CTX *libctx);
  61
  62  X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
  63                             unsigned char *salt, int saltlen);
  64  X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
  65                                unsigned char *salt, int saltlen,
  66                                unsigned char *aiv, int prf_nid);
  67  X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
  68                                   unsigned char *salt, int saltlen,
  69                                   unsigned char *aiv, int prf_nid,
  70                                   OSSL_LIB_CTX *libctx);
  71  X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
  72                                    const unsigned char *salt, int saltlen,
  73                                    unsigned char *aiv, uint64_t N, uint64_t r,
  74                                    uint64_t p);
  75
  76  X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
  77                               int prf_nid, int keylen);
  78  X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
  79                                  int prf_nid, int keylen,
  80                                  OSSL_LIB_CTX *libctx);
  81
  82 =head1 DESCRIPTION
  83
  84 =head2 Key Derivation
  85
  86 PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password I<pass> of
  87 length I<passlen>, parameters I<param> and a message digest function I<md_type>
  88 and performs a key derivation according to PKCS#5 PBES1. The resulting key is
  89 then used to initialise the cipher context I<ctx> with a cipher I<cipher> for
  90 encryption (I<en_de>=1) or decryption (I<en_de>=0).
  91
  92 I<pass> is an optional parameter and can be NULL. If I<passlen> is -1, then the
  93 function will calculate the length of I<pass> using strlen().
  94
  95 PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above
  96 but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied
  97 parameters.
  98
  99 PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the
 100 key derivation part of the encryption algorithm.
 101
 102 I<salt> is the salt used in the derivation of length I<saltlen>. If the
 103 I<salt> is NULL, then I<saltlen> must be 0. The function will not
 104 attempt to calculate the length of the I<salt> because it is not assumed to
 105 be NULL terminated.
 106
 107 I<iter> is the iteration count and its value should be greater than or
 108 equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
 109 I<iter> less than 1 is treated as a single iteration.
 110
 111 I<digest> is the message digest function used in the derivation.
 112
 113 Functions ending in _ex() take optional parameters I<libctx> and I<propq> which
 114 are used to select appropriate algorithm implementations.
 115
 116 =head2 Algorithm Identifier Creation
 117
 118 PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
 119 PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an B<X509_ALGOR>
 120 object which represents an AlgorithmIdentifier containing the algorithm OID and
 121 associated parameters for the PBE algorithm.
 122
 123 PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an B<X509_ALGOR>
 124 object which represents an AlgorithmIdentifier containing the algorithm OID and
 125 associated parameters for the PBKDF2 algorithm.
 126
 127 PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and
 128 parameters into the supplied B<X509_ALGOR>.
 129
 130 =head1 NOTES
 131
 132 The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects.
 133
 134 These functions make no assumption regarding the given password.
 135 It will simply be treated as a byte sequence.
 136
 137 =head1 RETURN VALUES
 138
 139 PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(),
 140 PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(),
 141 PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and
 142 PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.
 143
 144 PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
 145 PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(),
 146 PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an B<X509_ALGOR> object or
 147 NULL if an error occurs.
 148
 149 =head1 CONFORMING TO
 150
 151 IETF RFC 8018 (L<https://tools.ietf.org/html/rfc8018>)
 152
 153 =head1 SEE ALSO
 154
 155 L<EVP_PBE_CipherInit_ex(3)>,
 156 L<PKCS12_pbe_crypt_ex(3)>,
 157 L<passphrase-encoding(7)>
 158
 159 =head1 HISTORY
 160
 161 PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(),
 162 PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and
 163 PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.
 164
 165 From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and
 166 PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF.
 167
 168 =head1 COPYRIGHT
 169
 170 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
 171
 172 Licensed under the Apache License 2.0 (the "License").  You may not use
 173 this file except in compliance with the License.  You can obtain a copy
 174 in the file LICENSE in the source distribution or at
 175 L<https://www.openssl.org/source/license.html>.
 176
 177 =cut