Debian Codegraph @

upstream/debian-unstable/man3/PKCS5_PBE_keyivgen.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PKCS5_PBE_KEYIVGEN 3SSL"
58 .TH PKCS5_PBE_KEYIVGEN 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv,
65 PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt,
66 PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex,
67 PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex,
68 PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex,
69 PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex
70 \&\- PKCS#5 Password based encryption routines
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& #include <openssl/evp.h>
75 \&
76 \& int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
77 \& ASN1_TYPE *param, const EVP_CIPHER *cipher,
78 \& const EVP_MD *md, int en_de);
79 \& int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen,
80 \& ASN1_TYPE *param, const EVP_CIPHER *cipher,
81 \& const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx,
82 \& const char *propq);
83 \& int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
84 \& ASN1_TYPE *param, const EVP_CIPHER *cipher,
85 \& const EVP_MD *md, int en_de);
86 \& int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
87 \& ASN1_TYPE *param, const EVP_CIPHER *cipher,
88 \& const EVP_MD *md, int en_de,
89 \& OSSL_LIB_CTX *libctx, const char *propq);
90 \& int EVP_PBE_scrypt(const char *pass, size_t passlen,
91 \& const unsigned char *salt, size_t saltlen,
92 \& uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
93 \& unsigned char *key, size_t keylen);
94 \& int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
95 \& const unsigned char *salt, size_t saltlen,
96 \& uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
97 \& unsigned char *key, size_t keylen,
98 \& OSSL_LIB_CTX *ctx, const char *propq);
99 \& int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
100 \& int passlen, ASN1_TYPE *param,
101 \& const EVP_CIPHER *c, const EVP_MD *md, int en_de);
102 \& int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
103 \& int passlen, ASN1_TYPE *param,
104 \& const EVP_CIPHER *c, const EVP_MD *md, int en_de,
105 \& OSSL_LIB_CTX *libctx, const char *propq);
106 \&
107 \& #include <openssl/x509.h>
108 \&
109 \& int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
110 \& const unsigned char *salt, int saltlen);
111 \& int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
112 \& const unsigned char *salt, int saltlen,
113 \& OSSL_LIB_CTX *libctx);
114 \&
115 \& X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
116 \& const unsigned char *salt, int saltlen);
117 \& X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
118 \& const unsigned char *salt, int saltlen,
119 \& OSSL_LIB_CTX *libctx);
120 \&
121 \& X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
122 \& unsigned char *salt, int saltlen);
123 \& X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
124 \& unsigned char *salt, int saltlen,
125 \& unsigned char *aiv, int prf_nid);
126 \& X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
127 \& unsigned char *salt, int saltlen,
128 \& unsigned char *aiv, int prf_nid,
129 \& OSSL_LIB_CTX *libctx);
130 \& X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
131 \& const unsigned char *salt, int saltlen,
132 \& unsigned char *aiv, uint64_t N, uint64_t r,
133 \& uint64_t p);
134 \&
135 \& X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
136 \& int prf_nid, int keylen);
137 \& X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
138 \& int prf_nid, int keylen,
139 \& OSSL_LIB_CTX *libctx);
140 .Ve
141 .SH DESCRIPTION
142 .IX Header "DESCRIPTION"
143 .SS "Key Derivation"
144 .IX Subsection "Key Derivation"
145 \&\fBPKCS5_PBE_keyivgen()\fR and \fBPKCS5_PBE_keyivgen_ex()\fR take a password \fIpass\fR of
146 length \fIpasslen\fR, parameters \fIparam\fR and a message digest function \fImd_type\fR
147 and performs a key derivation according to PKCS#5 PBES1. The resulting key is
148 then used to initialise the cipher context \fIctx\fR with a cipher \fIcipher\fR for
149 encryption (\fIen_de\fR=1) or decryption (\fIen_de\fR=0).
150 .PP
151 \&\fIpass\fR is an optional parameter and can be NULL. If \fIpasslen\fR is \-1, then the
152 function will calculate the length of \fIpass\fR using \fBstrlen()\fR.
153 .PP
154 \&\fBPKCS5_v2_PBE_keyivgen()\fR and \fBPKCS5_v2_PBE_keyivgen_ex()\fR are similar to the above
155 but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied
156 parameters.
157 .PP
158 \&\fBPKCS5_v2_scrypt_keyivgen()\fR and \fBPKCS5_v2_scrypt_keyivgen_ex()\fR use SCRYPT as the
159 key derivation part of the encryption algorithm.
160 .PP
161 \&\fIsalt\fR is the salt used in the derivation of length \fIsaltlen\fR. If the
162 \&\fIsalt\fR is NULL, then \fIsaltlen\fR must be 0. The function will not
163 attempt to calculate the length of the \fIsalt\fR because it is not assumed to
164 be NULL terminated.
165 .PP
166 \&\fIiter\fR is the iteration count and its value should be greater than or
167 equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
168 \&\fIiter\fR less than 1 is treated as a single iteration.
169 .PP
170 \&\fIdigest\fR is the message digest function used in the derivation.
171 .PP
172 \&\fIaiv\fR is the initialization vector (IV) to use for the encryption algorithm.
173 If \fIaiv\fR is NULL, then a random IV will be generated.
174 .PP
175 \&\fIprf_nid\fR is the numeric identifier (NID) for the pseudo-random function to
176 use with PBKDF2. If \fIprf_nid\fR is not specified (for example, \fIprf_nid\fR is set to 0),
177 a default PRF is used, which is currently set to SHA\-256 (NID_hmacWithSHA256).
178 .PP
179 Functions ending in \fB_ex()\fR take optional parameters \fIlibctx\fR and \fIpropq\fR which
180 are used to select appropriate algorithm implementations.
181 .SS "Algorithm Identifier Creation"
182 .IX Subsection "Algorithm Identifier Creation"
183 \&\fBPKCS5_pbe_set()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set()\fR, \fBPKCS5_pbe2_set_iv()\fR,
184 \&\fBPKCS5_pbe2_set_iv_ex()\fR and \fBPKCS5_pbe2_set_scrypt()\fR generate an \fBX509_ALGOR\fR
185 object which represents an AlgorithmIdentifier containing the algorithm OID and
186 associated parameters for the PBE algorithm. These functions encode the
187 key derivation parameters (such as salt and iteration count) and the
188 encryption parameters (such as the IV) into the ASN.1 structure.
189 .PP
190 \&\fBPKCS5_pbkdf2_set()\fR and \fBPKCS5_pbkdf2_set_ex()\fR generate an \fBX509_ALGOR\fR
191 object which represents an AlgorithmIdentifier containing the algorithm OID and
192 associated parameters for the PBKDF2 algorithm.
193 .PP
194 \&\fBPKCS5_pbe_set0_algor()\fR and \fBPKCS5_pbe_set0_algor_ex()\fR set the PBE algorithm OID and
195 parameters into the supplied \fBX509_ALGOR\fR.
196 .PP
197 If \fIsalt\fR is NULL, then \fIsaltlen\fR specifies the size in bytes of the random salt to
198 generate. If \fIsaltlen\fR is 0 then a default size is used.
199 For PBE related functions such as \fBPKCS5_pbe_set_ex()\fR the default salt length is 8 bytes.
200 For PBE2 related functions that use PBKDF2 such as \fBPKCS5_pbkdf2_set()\fR,
201 \&\fBPKCS5_pbe2_set_scrypt()\fR and \fBPKCS5_pbe2_set()\fR the default salt length is 16 bytes.
202 .SH NOTES
203 .IX Header "NOTES"
204 The *\fB_keyivgen()\fR functions are typically used in PKCS#12 to encrypt objects.
205 .PP
206 These functions make no assumption regarding the given password.
207 It will simply be treated as a byte sequence.
208 .SH "RETURN VALUES"
209 .IX Header "RETURN VALUES"
210 \&\fBPKCS5_PBE_keyivgen()\fR, \fBPKCS5_v2_PBE_keyivgen()\fR,
211 \&\fBPKCS5_v2_PBE_keyivgen_ex()\fR, \fBPKCS5_v2_scrypt_keyivgen()\fR,
212 \&\fBPKCS5_v2_scrypt_keyivgen_ex()\fR, \fBPKCS5_pbe_set0_algor()\fR and
213 \&\fBPKCS5_pbe_set0_algor_ex()\fR return 1 for success and 0 if an error occurs.
214 .PP
215 \&\fBPKCS5_pbe_set()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set()\fR, \fBPKCS5_pbe2_set_iv()\fR,
216 \&\fBPKCS5_pbe2_set_iv_ex()\fR, \fBPKCS5_pbe2_set_scrypt()\fR,
217 \&\fBPKCS5_pbkdf2_set()\fR and \fBPKCS5_pbkdf2_set_ex()\fR return an \fBX509_ALGOR\fR object or
218 NULL if an error occurs.
219 .SH "CONFORMING TO"
220 .IX Header "CONFORMING TO"
221 IETF RFC 8018 (<https://tools.ietf.org/html/rfc8018>)
222 .SH "SEE ALSO"
223 .IX Header "SEE ALSO"
224 \&\fBEVP_PBE_CipherInit_ex\fR\|(3),
225 \&\fBPKCS12_pbe_crypt_ex\fR\|(3),
226 \&\fBpassphrase\-encoding\fR\|(7)
227 .SH HISTORY
228 .IX Header "HISTORY"
229 \&\fBPKCS5_v2_PBE_keyivgen_ex()\fR, \fBEVP_PBE_scrypt_ex()\fR, \fBPKCS5_v2_scrypt_keyivgen_ex()\fR,
230 \&\fBPKCS5_pbe_set0_algor_ex()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set_iv_ex()\fR and
231 \&\fBPKCS5_pbkdf2_set_ex()\fR were added in OpenSSL 3.0.
232 .PP
233 From OpenSSL 3.0 the PBKDF1 algorithm used in \fBPKCS5_PBE_keyivgen()\fR and
234 \&\fBPKCS5_PBE_keyivgen_ex()\fR has been moved to the legacy provider as an EVP_KDF.
235 .PP
236 In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2
237 related functions such as \fBPKCS5_pbe2_set()\fR.
238 This is required for PBKDF2 FIPS compliance.
239 .SH COPYRIGHT
240 .IX Header "COPYRIGHT"
241 Copyright 2021\-2026 The OpenSSL Project Authors. All Rights Reserved.
242 .PP
243 Licensed under the Apache License 2.0 (the "License"). You may not use
244 this file except in compliance with the License. You can obtain a copy
245 in the file LICENSE in the source distribution or at
246 <https://www.openssl.org/source/license.html>.