1PKCS5_PBE_KEYIVGEN(3ossl)           OpenSSL          PKCS5_PBE_KEYIVGEN(3ossl)
2
3
4

NAME

6       PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set,
7       PKCS5_pbe2_set_iv, PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set,
8       PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt, PKCS5_pbe_set0_algor,
9       PKCS5_pbe_set0_algor_ex, PKCS5_v2_PBE_keyivgen,
10       PKCS5_v2_PBE_keyivgen_ex, PKCS5_v2_scrypt_keyivgen,
11       PKCS5_v2_scrypt_keyivgen_ex, PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex,
12       EVP_PBE_scrypt, EVP_PBE_scrypt_ex - PKCS#5 Password based encryption
13       routines
14

SYNOPSIS

16        #include <openssl/evp.h>
17
18        int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
19                               ASN1_TYPE *param, const EVP_CIPHER *cipher,
20                               const EVP_MD *md, int en_de);
21        int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen,
22                                  ASN1_TYPE *param, const EVP_CIPHER *cipher,
23                                  const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx,
24                                  const char *propq);
25        int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
26                                  ASN1_TYPE *param, const EVP_CIPHER *cipher,
27                                  const EVP_MD *md, int en_de);
28        int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
29                                     ASN1_TYPE *param, const EVP_CIPHER *cipher,
30                                     const EVP_MD *md, int en_de,
31                                     OSSL_LIB_CTX *libctx, const char *propq);
32        int EVP_PBE_scrypt(const char *pass, size_t passlen,
33                           const unsigned char *salt, size_t saltlen,
34                           uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
35                           unsigned char *key, size_t keylen);
36        int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
37                              const unsigned char *salt, size_t saltlen,
38                              uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
39                              unsigned char *key, size_t keylen,
40                              OSSL_LIB_CTX *ctx, const char *propq);
41        int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
42                                     int passlen, ASN1_TYPE *param,
43                                     const EVP_CIPHER *c, const EVP_MD *md, int en_de);
44        int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
45                                        int passlen, ASN1_TYPE *param,
46                                        const EVP_CIPHER *c, const EVP_MD *md, int en_de,
47                                        OSSL_LIB_CTX *libctx, const char *propq);
48
49        #include <openssl/x509.h>
50
51        int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
52                                 const unsigned char *salt, int saltlen);
53        int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
54                                    const unsigned char *salt, int saltlen,
55                                    OSSL_LIB_CTX *libctx);
56
57        X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
58                                  const unsigned char *salt, int saltlen);
59        X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
60                                     const unsigned char *salt, int saltlen,
61                                     OSSL_LIB_CTX *libctx);
62
63        X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
64                                   unsigned char *salt, int saltlen);
65        X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
66                                      unsigned char *salt, int saltlen,
67                                      unsigned char *aiv, int prf_nid);
68        X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
69                                         unsigned char *salt, int saltlen,
70                                         unsigned char *aiv, int prf_nid,
71                                         OSSL_LIB_CTX *libctx);
72        X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
73                                          const unsigned char *salt, int saltlen,
74                                          unsigned char *aiv, uint64_t N, uint64_t r,
75                                          uint64_t p);
76
77        X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
78                                     int prf_nid, int keylen);
79        X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
80                                        int prf_nid, int keylen,
81                                        OSSL_LIB_CTX *libctx);
82

DESCRIPTION

84   Key Derivation
85       PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password pass
86       of length passlen, parameters param and a message digest function
87       md_type and performs a key derivation according to PKCS#5 PBES1. The
88       resulting key is then used to initialise the cipher context ctx with a
89       cipher cipher for encryption (en_de=1) or decryption (en_de=0).
90
91       pass is an optional parameter and can be NULL. If passlen is -1, then
92       the function will calculate the length of pass using strlen().
93
94       PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to
95       the above but instead use PKCS#5 PBES2 as the encryption algorithm
96       using the supplied parameters.
97
98       PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT
99       as the key derivation part of the encryption algorithm.
100
101       salt is the salt used in the derivation of length saltlen. If the salt
102       is NULL, then saltlen must be 0. The function will not attempt to
103       calculate the length of the salt because it is not assumed to be NULL
104       terminated.
105
106       iter is the iteration count and its value should be greater than or
107       equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
108       iter less than 1 is treated as a single iteration.
109
110       digest is the message digest function used in the derivation.
111
112       Functions ending in _ex() take optional parameters libctx and propq
113       which are used to select appropriate algorithm implementations.
114
115   Algorithm Identifier Creation
116       PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(),
117       PKCS5_pbe2_set_iv(), PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt()
118       generate an X509_ALGOR object which represents an AlgorithmIdentifier
119       containing the algorithm OID and associated parameters for the PBE
120       algorithm.
121
122       PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an X509_ALGOR
123       object which represents an AlgorithmIdentifier containing the algorithm
124       OID and associated parameters for the PBKDF2 algorithm.
125
126       PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE
127       algorithm OID and parameters into the supplied X509_ALGOR.
128

NOTES

130       The *_keyivgen() functions are typically used in PKCS#12 to encrypt
131       objects.
132
133       These functions make no assumption regarding the given password.  It
134       will simply be treated as a byte sequence.
135

RETURN VALUES

137       PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(),
138       PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(),
139       PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and
140       PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error
141       occurs.
142
143       PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(),
144       PKCS5_pbe2_set_iv(), PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(),
145       PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an X509_ALGOR
146       object or NULL if an error occurs.
147

CONFORMING TO

149       IETF RFC 8018 (<https://tools.ietf.org/html/rfc8018>)
150

SEE ALSO

152       EVP_PBE_CipherInit_ex(3), PKCS12_pbe_crypt_ex(3),
153       passphrase-encoding(7)
154

HISTORY

156       PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(),
157       PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor_ex(),
158       PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and PKCS5_pbkdf2_set_ex()
159       were added in OpenSSL 3.0.
160
161       From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and
162       PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an
163       EVP_KDF.
164
166       Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
167
168       Licensed under the Apache License 2.0 (the "License").  You may not use
169       this file except in compliance with the License.  You can obtain a copy
170       in the file LICENSE in the source distribution or at
171       <https://www.openssl.org/source/license.html>.
172
173
174
1753.0.5                             2022-11-01         PKCS5_PBE_KEYIVGEN(3ossl)
Impressum