VirtualBox

source: vbox/trunk/src/libs/openssl-3.1.2/doc/man3/PEM_read_bio_PrivateKey.pod@ 101021

Last change on this file since 101021 was 101021, checked in by vboxsync, 15 months ago

openssl-3.1.2: Applied and adjusted our OpenSSL changes to 3.1.0. bugref:10519
File size: 24.8 KB
Line 
1=pod
2
3=head1 NAME
4
5pem_password_cb,
6PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey,
7PEM_read_PrivateKey_ex, PEM_read_PrivateKey,
8PEM_write_bio_PrivateKey_ex, PEM_write_bio_PrivateKey,
9PEM_write_bio_PrivateKey_traditional,
10PEM_write_PrivateKey_ex, PEM_write_PrivateKey,
11PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
12PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
13PEM_read_bio_PUBKEY_ex, PEM_read_bio_PUBKEY,
14PEM_read_PUBKEY_ex, PEM_read_PUBKEY,
15PEM_write_bio_PUBKEY_ex, PEM_write_bio_PUBKEY,
16PEM_write_PUBKEY_ex, PEM_write_PUBKEY,
17PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
18PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
19PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
20PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
21PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
22PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
23PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
24PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters_ex, PEM_read_bio_Parameters,
25PEM_write_bio_Parameters, PEM_read_bio_DSAparams, PEM_read_DSAparams,
26PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
27PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
28PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
29PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
30PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
31PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
32PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
33PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
34PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
35
36=head1 SYNOPSIS
37
38 #include <openssl/pem.h>
39
40 typedef int pem_password_cb(char *buf, int size, int rwflag, void *u);
41
42 EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x,
43 pem_password_cb *cb, void *u,
44 OSSL_LIB_CTX *libctx, const char *propq);
45 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
46 pem_password_cb *cb, void *u);
47 EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb,
48 void *u, OSSL_LIB_CTX *libctx,
49 const char *propq);
50 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
51 pem_password_cb *cb, void *u);
52 int PEM_write_bio_PrivateKey_ex(BIO *bp, const EVP_PKEY *x,
53 const EVP_CIPHER *enc,
54 unsigned char *kstr, int klen,
55 pem_password_cb *cb, void *u,
56 OSSL_LIB_CTX *libctx, const char *propq);
57 int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
58 unsigned char *kstr, int klen,
59 pem_password_cb *cb, void *u);
60 int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x,
61 const EVP_CIPHER *enc,
62 unsigned char *kstr, int klen,
63 pem_password_cb *cb, void *u);
64 int PEM_write_PrivateKey_ex(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
65 unsigned char *kstr, int klen,
66 pem_password_cb *cb, void *u,
67 OSSL_LIB_CTX *libctx, const char *propq);
68 int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
69 unsigned char *kstr, int klen,
70 pem_password_cb *cb, void *u);
71 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
72 char *kstr, int klen,
73 pem_password_cb *cb, void *u);
74 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
75 char *kstr, int klen,
76 pem_password_cb *cb, void *u);
77 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid,
78 char *kstr, int klen,
79 pem_password_cb *cb, void *u);
80 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid,
81 char *kstr, int klen,
82 pem_password_cb *cb, void *u);
83
84 EVP_PKEY *PEM_read_bio_PUBKEY_ex(BIO *bp, EVP_PKEY **x,
85 pem_password_cb *cb, void *u,
86 OSSL_LIB_CTX *libctx, const char *propq);
87 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
88 pem_password_cb *cb, void *u);
89 EVP_PKEY *PEM_read_PUBKEY_ex(FILE *fp, EVP_PKEY **x,
90 pem_password_cb *cb, void *u,
91 OSSL_LIB_CTX *libctx, const char *propq);
92 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
93 pem_password_cb *cb, void *u);
94 int PEM_write_bio_PUBKEY_ex(BIO *bp, EVP_PKEY *x,
95 OSSL_LIB_CTX *libctx, const char *propq);
96 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
97 int PEM_write_PUBKEY_ex(FILE *fp, EVP_PKEY *x,
98 OSSL_LIB_CTX *libctx, const char *propq);
99 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
100
101 EVP_PKEY *PEM_read_bio_Parameters_ex(BIO *bp, EVP_PKEY **x,
102 OSSL_LIB_CTX *libctx, const char *propq);
103 EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
104 int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);
105
106 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
107 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
108 int PEM_write_bio_X509(BIO *bp, X509 *x);
109 int PEM_write_X509(FILE *fp, X509 *x);
110
111 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
112 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
113 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
114 int PEM_write_X509_AUX(FILE *fp, X509 *x);
115
116 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
117 pem_password_cb *cb, void *u);
118 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
119 pem_password_cb *cb, void *u);
120 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
121 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
122 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
123 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
124
125 X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
126 pem_password_cb *cb, void *u);
127 X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
128 pem_password_cb *cb, void *u);
129 int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
130 int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
131
132 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
133 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
134 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
135 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
136
137The following functions have been deprecated since OpenSSL 3.0, and can be
138hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
139see L<openssl_user_macros(7)>:
140
141 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
142 pem_password_cb *cb, void *u);
143 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
144 pem_password_cb *cb, void *u);
145 int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
146 unsigned char *kstr, int klen,
147 pem_password_cb *cb, void *u);
148 int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
149 unsigned char *kstr, int klen,
150 pem_password_cb *cb, void *u);
151
152 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
153 pem_password_cb *cb, void *u);
154 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
155 pem_password_cb *cb, void *u);
156 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
157 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
158
159 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
160 pem_password_cb *cb, void *u);
161 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
162 pem_password_cb *cb, void *u);
163 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
164 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
165
166 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
167 pem_password_cb *cb, void *u);
168 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
169 pem_password_cb *cb, void *u);
170 int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
171 unsigned char *kstr, int klen,
172 pem_password_cb *cb, void *u);
173 int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
174 unsigned char *kstr, int klen,
175 pem_password_cb *cb, void *u);
176
177 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
178 pem_password_cb *cb, void *u);
179 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
180 pem_password_cb *cb, void *u);
181 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
182 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
183 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
184 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
185 int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
186 int PEM_write_DSAparams(FILE *fp, DSA *x);
187
188 DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
189 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
190 int PEM_write_bio_DHparams(BIO *bp, DH *x);
191 int PEM_write_DHparams(FILE *fp, DH *x);
192
193=head1 DESCRIPTION
194
195All of the functions described on this page that have a I<TYPE> of B<DH>, B<DSA>
196and B<RSA> are deprecated. Applications should use L<OSSL_ENCODER_to_bio(3)> and
197L<OSSL_DECODER_from_bio(3)> instead.
198
199The PEM functions read or write structures in PEM format. In
200this sense PEM format is simply base64 encoded data surrounded
201by header lines.
202
203For more details about the meaning of arguments see the
204B<PEM FUNCTION ARGUMENTS> section.
205
206Each operation has four functions associated with it. For
207brevity the term "B<I<TYPE>> functions" will be used below to collectively
208refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(),
209B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions.
210
211Some operations have additional variants that take a library context I<libctx>
212and a property query string I<propq>. The B<X509>, B<X509_REQ> and B<X509_CRL>
213objects may have an associated library context or property query string but
214there are no variants of these functions that take a library context or property
215query string parameter. In this case it is possible to set the appropriate
216library context or property query string by creating an empty B<X509>,
217B<X509_REQ> or B<X509_CRL> object using L<X509_new_ex(3)>, L<X509_REQ_new_ex(3)>
218or L<X509_CRL_new_ex(3)> respectively. Then pass the empty object as a parameter
219to the relevant PEM function. See the L</EXAMPLES> section below.
220
221The B<PrivateKey> functions read or write a private key in PEM format using
222an EVP_PKEY structure. The write routines use PKCS#8 private key format and are
223equivalent to PEM_write_bio_PKCS8PrivateKey(). The read functions transparently
224handle traditional and PKCS#8 format encrypted and unencrypted keys.
225
226PEM_write_bio_PrivateKey_traditional() writes out a private key in the
227"traditional" format with a simple private key marker and should only
228be used for compatibility with legacy programs.
229
230PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
231key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
232PKCS#5 v2.0 password based encryption algorithms. The I<cipher> argument
233specifies the encryption algorithm to use: unlike some other PEM routines the
234encryption is applied at the PKCS#8 level and not in the PEM headers. If
235I<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
236structure is used instead.
237
238PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
239also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
240it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
241to use is specified in the I<nid> parameter and should be the NID of the
242corresponding OBJECT IDENTIFIER (see NOTES section).
243
244The B<PUBKEY> functions process a public key using an EVP_PKEY
245structure. The public key is encoded as a SubjectPublicKeyInfo
246structure.
247
248The B<RSAPrivateKey> functions process an RSA private key using an
249RSA structure. The write routines uses traditional format. The read
250routines handles the same formats as the B<PrivateKey>
251functions but an error occurs if the private key is not RSA.
252
253The B<RSAPublicKey> functions process an RSA public key using an
254RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
255structure.
256
257The B<RSA_PUBKEY> functions also process an RSA public key using
258an RSA structure. However, the public key is encoded using a
259SubjectPublicKeyInfo structure and an error occurs if the public
260key is not RSA.
261
262The B<DSAPrivateKey> functions process a DSA private key using a
263DSA structure. The write routines uses traditional format. The read
264routines handles the same formats as the B<PrivateKey>
265functions but an error occurs if the private key is not DSA.
266
267The B<DSA_PUBKEY> functions process a DSA public key using
268a DSA structure. The public key is encoded using a
269SubjectPublicKeyInfo structure and an error occurs if the public
270key is not DSA.
271
272The B<Parameters> functions read or write key parameters in PEM format using
273an EVP_PKEY structure. The encoding depends on the type of key; for DSA key
274parameters, it will be a Dss-Parms structure as defined in RFC2459, and for DH
275key parameters, it will be a PKCS#3 DHparameter structure. I<These functions
276only exist for the B<BIO> type>.
277
278The B<DSAparams> functions process DSA parameters using a DSA
279structure. The parameters are encoded using a Dss-Parms structure
280as defined in RFC2459.
281
282The B<DHparams> functions process DH parameters using a DH
283structure. The parameters are encoded using a PKCS#3 DHparameter
284structure.
285
286The B<X509> functions process an X509 certificate using an X509
287structure. They will also process a trusted X509 certificate but
288any trust settings are discarded.
289
290The B<X509_AUX> functions process a trusted X509 certificate using
291an X509 structure.
292
293The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
294certificate request using an X509_REQ structure. The B<X509_REQ>
295write functions use B<CERTIFICATE REQUEST> in the header whereas
296the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
297(as required by some CAs). The B<X509_REQ> read functions will
298handle either form so there are no B<X509_REQ_NEW> read functions.
299
300The B<X509_CRL> functions process an X509 CRL using an X509_CRL
301structure.
302
303The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
304structure.
305
306=head1 PEM FUNCTION ARGUMENTS
307
308The PEM functions have many common arguments.
309
310The I<bp> BIO parameter (if present) specifies the BIO to read from
311or write to.
312
313The I<fp> FILE parameter (if present) specifies the FILE pointer to
314read from or write to.
315
316The PEM read functions all take an argument I<B<TYPE> **x> and return
317a I<B<TYPE> *> pointer. Where I<B<TYPE>> is whatever structure the function
318uses. If I<x> is NULL then the parameter is ignored. If I<x> is not
319NULL but I<*x> is NULL then the structure returned will be written
320to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made
321to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections).
322Irrespective of the value of I<x> a pointer to the structure is always
323returned (or NULL if an error occurred).
324
325The PEM functions which write private keys take an I<enc> parameter
326which specifies the encryption algorithm to use, encryption is done
327at the PEM level. If this parameter is set to NULL then the private
328key is written in unencrypted form.
329
330The I<cb> argument is the callback to use when querying for the pass
331phrase used for encrypted PEM structures (normally only private keys).
332
333For the PEM write routines if the I<kstr> parameter is not NULL then
334I<klen> bytes at I<kstr> are used as the passphrase and I<cb> is
335ignored.
336
337If the I<cb> parameters is set to NULL and the I<u> parameter is not
338NULL then the I<u> parameter is interpreted as a NUL terminated string
339to use as the passphrase. If both I<cb> and I<u> are NULL then the
340default callback routine is used which will typically prompt for the
341passphrase on the current terminal with echoing turned off.
342
343The default passphrase callback is sometimes inappropriate (for example
344in a GUI application) so an alternative can be supplied. The callback
345routine has the following form:
346
347 int cb(char *buf, int size, int rwflag, void *u);
348
349I<buf> is the buffer to write the passphrase to. I<size> is the maximum
350length of the passphrase (i.e. the size of buf). I<rwflag> is a flag
351which is set to 0 when reading and 1 when writing. A typical routine
352will ask the user to verify the passphrase (for example by prompting
353for it twice) if I<rwflag> is 1. The I<u> parameter has the same
354value as the I<u> parameter passed to the PEM routine. It allows
355arbitrary data to be passed to the callback by the application
356(for example a window handle in a GUI application). The callback
357I<must> return the number of characters in the passphrase or -1 if
358an error occurred. The passphrase can be arbitrary data; in the case where it
359is a string, it is not NUL terminated. See the L</EXAMPLES> section below.
360
361Some implementations may need to use cryptographic algorithms during their
362operation. If this is the case and I<libctx> and I<propq> parameters have been
363passed then any algorithm fetches will use that library context and property
364query string. Otherwise the default library context and property query string
365will be used.
366
367=head1 NOTES
368
369The PEM reading functions will skip any extraneous content or PEM data of
370a different type than they expect. This allows for example having a certificate
371(or multiple certificates) and a key in the PEM format in a single file.
372
373The old B<PrivateKey> write routines are retained for compatibility.
374New applications should write private keys using the
375PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
376because they are more secure (they use an iteration count of 2048 whereas
377the traditional routines use a count of 1) unless compatibility with older
378versions of OpenSSL is important.
379
380The B<PrivateKey> read routines can be used in all applications because
381they handle all formats transparently.
382
383A frequent cause of problems is attempting to use the PEM routines like
384this:
385
386 X509 *x;
387
388 PEM_read_bio_X509(bp, &x, 0, NULL);
389
390this is a bug because an attempt will be made to reuse the data at I<x>
391which is an uninitialised pointer.
392
393These functions make no assumption regarding the pass phrase received from the
394password callback.
395It will simply be treated as a byte sequence.
396
397=head1 PEM ENCRYPTION FORMAT
398
399These old B<PrivateKey> routines use a non standard technique for encryption.
400
401The private key (or other data) takes the following form:
402
403 -----BEGIN RSA PRIVATE KEY-----
404 Proc-Type: 4,ENCRYPTED
405 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
406
407 ...base64 encoded data...
408 -----END RSA PRIVATE KEY-----
409
410The line beginning with I<Proc-Type> contains the version and the
411protection on the encapsulated data. The line beginning I<DEK-Info>
412contains two comma separated values: the encryption algorithm name as
413used by EVP_get_cipherbyname() and an initialization vector used by the
414cipher encoded as a set of hexadecimal digits. After those two lines is
415the base64-encoded encrypted data.
416
417The encryption key is derived using EVP_BytesToKey(). The cipher's
418initialization vector is passed to EVP_BytesToKey() as the I<salt>
419parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
420(regardless of the size of the initialization vector). The user's
421password is passed to EVP_BytesToKey() using the I<data> and I<datal>
422parameters. Finally, the library uses an iteration count of 1 for
423EVP_BytesToKey().
424
425The I<key> derived by EVP_BytesToKey() along with the original initialization
426vector is then used to decrypt the encrypted data. The I<iv> produced by
427EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
428the function.
429
430The pseudo code to derive the key would look similar to:
431
432 EVP_CIPHER* cipher = EVP_des_ede3_cbc();
433 EVP_MD* md = EVP_md5();
434
435 unsigned int nkey = EVP_CIPHER_get_key_length(cipher);
436 unsigned int niv = EVP_CIPHER_get_iv_length(cipher);
437 unsigned char key[nkey];
438 unsigned char iv[niv];
439
440 memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
441 rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
442 if (rc != nkey)
443 /* Error */
444
445 /* On success, use key and iv to initialize the cipher */
446
447=head1 BUGS
448
449The PEM read routines in some versions of OpenSSL will not correctly reuse
450an existing structure. Therefore, the following:
451
452 PEM_read_bio_X509(bp, &x, 0, NULL);
453
454where I<x> already contains a valid certificate, may not work, whereas:
455
456 X509_free(x);
457 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
458
459is guaranteed to work. It is always acceptable for I<x> to contain a newly
460allocated, empty B<X509> object (for example allocated via L<X509_new_ex(3)>).
461
462=head1 RETURN VALUES
463
464The read routines return either a pointer to the structure read or NULL
465if an error occurred.
466
467The write routines return 1 for success or 0 for failure.
468
469=head1 EXAMPLES
470
471Although the PEM routines take several arguments in almost all applications
472most of them are set to 0 or NULL.
473
474To read a certificate with a library context in PEM format from a BIO:
475
476 X509 *x = X509_new_ex(libctx, NULL);
477
478 if (x == NULL)
479 /* Error */
480
481 if (PEM_read_bio_X509(bp, &x, 0, NULL) == NULL)
482 /* Error */
483
484Read a certificate in PEM format from a BIO:
485
486 X509 *x;
487
488 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
489 if (x == NULL)
490 /* Error */
491
492Alternative method:
493
494 X509 *x = NULL;
495
496 if (!PEM_read_bio_X509(bp, &x, 0, NULL))
497 /* Error */
498
499Write a certificate to a BIO:
500
501 if (!PEM_write_bio_X509(bp, x))
502 /* Error */
503
504Write a private key (using traditional format) to a BIO using
505triple DES encryption, the pass phrase is prompted for:
506
507 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
508 /* Error */
509
510Write a private key (using PKCS#8 format) to a BIO using triple
511DES encryption, using the pass phrase "hello":
512
513 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
514 NULL, 0, 0, "hello"))
515 /* Error */
516
517Read a private key from a BIO using a pass phrase callback:
518
519 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
520 if (key == NULL)
521 /* Error */
522
523Skeleton pass phrase callback:
524
525 int pass_cb(char *buf, int size, int rwflag, void *u)
526 {
527
528 /* We'd probably do something else if 'rwflag' is 1 */
529 printf("Enter pass phrase for \"%s\"\n", (char *)u);
530
531 /* get pass phrase, length 'len' into 'tmp' */
532 char *tmp = "hello";
533 if (tmp == NULL) /* An error occurred */
534 return -1;
535
536 size_t len = strlen(tmp);
537
538 if (len > size)
539 len = size;
540 memcpy(buf, tmp, len);
541 return len;
542 }
543
544=head1 SEE ALSO
545
546L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>,
547L<passphrase-encoding(7)>
548
549=head1 HISTORY
550
551The old Netscape certificate sequences were no longer documented
552in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
553as they will be formally deprecated in a future releases.
554
555PEM_read_bio_PrivateKey_ex(), PEM_read_PrivateKey_ex(),
556PEM_read_bio_PUBKEY_ex(), PEM_read_PUBKEY_ex() and
557PEM_read_bio_Parameters_ex() were introduced in OpenSSL 3.0.
558
559The functions PEM_read_bio_RSAPrivateKey(), PEM_read_RSAPrivateKey(),
560PEM_write_bio_RSAPrivateKey(), PEM_write_RSAPrivateKey(),
561PEM_read_bio_RSAPublicKey(), PEM_read_RSAPublicKey(),
562PEM_write_bio_RSAPublicKey(), PEM_write_RSAPublicKey(),
563PEM_read_bio_RSA_PUBKEY(), PEM_read_RSA_PUBKEY(),
564PEM_write_bio_RSA_PUBKEY(), PEM_write_RSA_PUBKEY(),
565PEM_read_bio_DSAPrivateKey(), PEM_read_DSAPrivateKey(),
566PEM_write_bio_DSAPrivateKey(), PEM_write_DSAPrivateKey(),
567PEM_read_bio_DSA_PUBKEY(), PEM_read_DSA_PUBKEY(),
568PEM_write_bio_DSA_PUBKEY(), PEM_write_DSA_PUBKEY();
569PEM_read_bio_DSAparams(), PEM_read_DSAparams(),
570PEM_write_bio_DSAparams(), PEM_write_DSAparams(),
571PEM_read_bio_DHparams(), PEM_read_DHparams(),
572PEM_write_bio_DHparams() and PEM_write_DHparams() were deprecated in 3.0.
573
574
575=head1 COPYRIGHT
576
577Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved.
578
579Licensed under the Apache License 2.0 (the "License"). You may not use
580this file except in compliance with the License. You can obtain a copy
581in the file LICENSE in the source distribution or at
582L<https://www.openssl.org/source/license.html>.
583
584=cut
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette