PEM_read_bio_PrivateKey.pod@ 87083

Last change on this file since 87083 was 87083, checked in by vboxsync, 4 years ago
openssl-1.1.1i: Applied and adjusted our OpenSSL changes to 1.1.1i. bugref:9885
File size: 19.8 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/openssl-1.1.1i/doc/man3/PEM_read_bio_PrivateKey.pod@ 87083

Download in other formats: