summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3')
-rw-r--r--src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3997
1 files changed, 997 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
new file mode 100644
index 0000000000..7dcea6dbe1
--- /dev/null
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -0,0 +1,997 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PEM_READ_BIO_PRIVATEKEY 3
3.Os
4.Sh NAME
5.Nm PEM ,
6.Nm PEM_read_bio_PrivateKey ,
7.Nm PEM_read_PrivateKey ,
8.Nm PEM_write_bio_PrivateKey ,
9.Nm PEM_write_PrivateKey ,
10.Nm PEM_write_bio_PKCS8PrivateKey ,
11.Nm PEM_write_PKCS8PrivateKey ,
12.Nm PEM_write_bio_PKCS8PrivateKey_nid ,
13.Nm PEM_write_PKCS8PrivateKey_nid ,
14.Nm PEM_read_bio_PUBKEY ,
15.Nm PEM_read_PUBKEY ,
16.Nm PEM_write_bio_PUBKEY ,
17.Nm PEM_write_PUBKEY ,
18.Nm PEM_read_bio_RSAPrivateKey ,
19.Nm PEM_read_RSAPrivateKey ,
20.Nm PEM_write_bio_RSAPrivateKey ,
21.Nm PEM_write_RSAPrivateKey ,
22.Nm PEM_read_bio_RSAPublicKey ,
23.Nm PEM_read_RSAPublicKey ,
24.Nm PEM_write_bio_RSAPublicKey ,
25.Nm PEM_write_RSAPublicKey ,
26.Nm PEM_read_bio_RSA_PUBKEY ,
27.Nm PEM_read_RSA_PUBKEY ,
28.Nm PEM_write_bio_RSA_PUBKEY ,
29.Nm PEM_write_RSA_PUBKEY ,
30.Nm PEM_read_bio_DSAPrivateKey ,
31.Nm PEM_read_DSAPrivateKey ,
32.Nm PEM_write_bio_DSAPrivateKey ,
33.Nm PEM_write_DSAPrivateKey ,
34.Nm PEM_read_bio_DSA_PUBKEY ,
35.Nm PEM_read_DSA_PUBKEY ,
36.Nm PEM_write_bio_DSA_PUBKEY ,
37.Nm PEM_write_DSA_PUBKEY ,
38.Nm PEM_read_bio_DSAparams ,
39.Nm PEM_read_DSAparams ,
40.Nm PEM_write_bio_DSAparams ,
41.Nm PEM_write_DSAparams ,
42.Nm PEM_read_bio_DHparams ,
43.Nm PEM_read_DHparams ,
44.Nm PEM_write_bio_DHparams ,
45.Nm PEM_write_DHparams ,
46.Nm PEM_read_bio_X509 ,
47.Nm PEM_read_X509 ,
48.Nm PEM_write_bio_X509 ,
49.Nm PEM_write_X509 ,
50.Nm PEM_read_bio_X509_AUX ,
51.Nm PEM_read_X509_AUX ,
52.Nm PEM_write_bio_X509_AUX ,
53.Nm PEM_write_X509_AUX ,
54.Nm PEM_read_bio_X509_REQ ,
55.Nm PEM_read_X509_REQ ,
56.Nm PEM_write_bio_X509_REQ ,
57.Nm PEM_write_X509_REQ ,
58.Nm PEM_write_bio_X509_REQ_NEW ,
59.Nm PEM_write_X509_REQ_NEW ,
60.Nm PEM_read_bio_X509_CRL ,
61.Nm PEM_read_X509_CRL ,
62.Nm PEM_write_bio_X509_CRL ,
63.Nm PEM_write_X509_CRL ,
64.Nm PEM_read_bio_PKCS7 ,
65.Nm PEM_read_PKCS7 ,
66.Nm PEM_write_bio_PKCS7 ,
67.Nm PEM_write_PKCS7 ,
68.Nm PEM_read_bio_NETSCAPE_CERT_SEQUENCE ,
69.Nm PEM_read_NETSCAPE_CERT_SEQUENCE ,
70.Nm PEM_write_bio_NETSCAPE_CERT_SEQUENCE ,
71.Nm PEM_write_NETSCAPE_CERT_SEQUENCE
72.Nd PEM routines
73.Sh SYNOPSIS
74.In openssl/pem.h
75.Ft EVP_PKEY *
76.Fo PEM_read_bio_PrivateKey
77.Fa "BIO *bp"
78.Fa "EVP_PKEY **x"
79.Fa "pem_password_cb *cb"
80.Fa "void *u"
81.Fc
82.Ft EVP_PKEY *
83.Fo PEM_read_PrivateKey
84.Fa "FILE *fp"
85.Fa "EVP_PKEY **x"
86.Fa "pem_password_cb *cb"
87.Fa "void *u"
88.Fc
89.Ft int
90.Fo PEM_write_bio_PrivateKey
91.Fa "BIO *bp"
92.Fa "EVP_PKEY *x"
93.Fa "const EVP_CIPHER *enc"
94.Fa "unsigned char *kstr"
95.Fa "int klen"
96.Fa "pem_password_cb *cb"
97.Fa "void *u"
98.Fc
99.Ft int
100.Fo PEM_write_PrivateKey
101.Fa "FILE *fp"
102.Fa "EVP_PKEY *x"
103.Fa "const EVP_CIPHER *enc"
104.Fa "unsigned char *kstr"
105.Fa "int klen"
106.Fa "pem_password_cb *cb"
107.Fa "void *u"
108.Fc
109.Ft int
110.Fo PEM_write_bio_PKCS8PrivateKey
111.Fa "BIO *bp"
112.Fa "EVP_PKEY *x"
113.Fa "const EVP_CIPHER *enc"
114.Fa "char *kstr"
115.Fa "int klen"
116.Fa "pem_password_cb *cb"
117.Fa "void *u"
118.Fc
119.Ft int
120.Fo PEM_write_PKCS8PrivateKey
121.Fa "FILE *fp"
122.Fa "EVP_PKEY *x"
123.Fa "const EVP_CIPHER *enc"
124.Fa "char *kstr"
125.Fa "int klen"
126.Fa "pem_password_cb *cb"
127.Fa "void *u"
128.Fc
129.Ft int
130.Fo PEM_write_bio_PKCS8PrivateKey_nid
131.Fa "BIO *bp"
132.Fa "EVP_PKEY *x"
133.Fa "int nid"
134.Fa "char *kstr"
135.Fa "int klen"
136.Fa "pem_password_cb *cb"
137.Fa "void *u"
138.Fc
139.Ft int
140.Fo PEM_write_PKCS8PrivateKey_nid
141.Fa "FILE *fp"
142.Fa "EVP_PKEY *x"
143.Fa "int nid"
144.Fa "char *kstr"
145.Fa "int klen"
146.Fa "pem_password_cb *cb"
147.Fa "void *u"
148.Fc
149.Ft EVP_PKEY *
150.Fo PEM_read_bio_PUBKEY
151.Fa "BIO *bp"
152.Fa "EVP_PKEY **x"
153.Fa "pem_password_cb *cb"
154.Fa "void *u"
155.Fc
156.Ft EVP_PKEY *
157.Fo PEM_read_PUBKEY
158.Fa "FILE *fp"
159.Fa "EVP_PKEY **x"
160.Fa "pem_password_cb *cb"
161.Fa "void *u"
162.Fc
163.Ft int
164.Fo PEM_write_bio_PUBKEY
165.Fa "BIO *bp"
166.Fa "EVP_PKEY *x"
167.Fc
168.Ft int
169.Fo PEM_write_PUBKEY
170.Fa "FILE *fp"
171.Fa "EVP_PKEY *x"
172.Fc
173.Ft RSA *
174.Fo PEM_read_bio_RSAPrivateKey
175.Fa "BIO *bp"
176.Fa "RSA **x"
177.Fa "pem_password_cb *cb"
178.Fa "void *u"
179.Fc
180.Ft RSA *
181.Fo PEM_read_RSAPrivateKey
182.Fa "FILE *fp"
183.Fa "RSA **x"
184.Fa "pem_password_cb *cb"
185.Fa "void *u"
186.Fc
187.Ft int
188.Fo PEM_write_bio_RSAPrivateKey
189.Fa "BIO *bp"
190.Fa "RSA *x"
191.Fa "const EVP_CIPHER *enc"
192.Fa "unsigned char *kstr"
193.Fa "int klen"
194.Fa "pem_password_cb *cb"
195.Fa "void *u"
196.Fc
197.Ft int
198.Fo PEM_write_RSAPrivateKey
199.Fa "FILE *fp"
200.Fa "RSA *x"
201.Fa "const EVP_CIPHER *enc"
202.Fa "unsigned char *kstr"
203.Fa "int klen"
204.Fa "pem_password_cb *cb"
205.Fa "void *u"
206.Fc
207.Ft RSA *
208.Fo PEM_read_bio_RSAPublicKey
209.Fa "BIO *bp"
210.Fa "RSA **x"
211.Fa "pem_password_cb *cb"
212.Fa "void *u"
213.Fc
214.Ft RSA *
215.Fo PEM_read_RSAPublicKey
216.Fa "FILE *fp"
217.Fa "RSA **x"
218.Fa "pem_password_cb *cb"
219.Fa "void *u"
220.Fc
221.Ft int
222.Fo PEM_write_bio_RSAPublicKey
223.Fa "BIO *bp"
224.Fa "RSA *x"
225.Fc
226.Ft int
227.Fo PEM_write_RSAPublicKey
228.Fa "FILE *fp"
229.Fa "RSA *x"
230.Fc
231.Ft RSA *
232.Fo PEM_read_bio_RSA_PUBKEY
233.Fa "BIO *bp"
234.Fa "RSA **x"
235.Fa "pem_password_cb *cb"
236.Fa "void *u"
237.Fc
238.Ft RSA *
239.Fo PEM_read_RSA_PUBKEY
240.Fa "FILE *fp"
241.Fa "RSA **x"
242.Fa "pem_password_cb *cb"
243.Fa "void *u"
244.Fc
245.Ft int
246.Fo PEM_write_bio_RSA_PUBKEY
247.Fa "BIO *bp"
248.Fa "RSA *x"
249.Fc
250.Ft int
251.Fo PEM_write_RSA_PUBKEY
252.Fa "FILE *fp"
253.Fa "RSA *x"
254.Fc
255.Ft DSA *
256.Fo PEM_read_bio_DSAPrivateKey
257.Fa "BIO *bp"
258.Fa "DSA **x"
259.Fa "pem_password_cb *cb"
260.Fa "void *u"
261.Fc
262.Ft DSA *
263.Fo PEM_read_DSAPrivateKey
264.Fa "FILE *fp"
265.Fa "DSA **x"
266.Fa "pem_password_cb *cb"
267.Fa "void *u"
268.Fc
269.Ft int
270.Fo PEM_write_bio_DSAPrivateKey
271.Fa "BIO *bp"
272.Fa "DSA *x"
273.Fa "const EVP_CIPHER *enc"
274.Fa "unsigned char *kstr"
275.Fa "int klen"
276.Fa "pem_password_cb *cb"
277.Fa "void *u"
278.Fc
279.Ft int
280.Fo PEM_write_DSAPrivateKey
281.Fa "FILE *fp"
282.Fa "DSA *x"
283.Fa "const EVP_CIPHER *enc"
284.Fa "unsigned char *kstr"
285.Fa "int klen"
286.Fa "pem_password_cb *cb"
287.Fa "void *u"
288.Fc
289.Ft DSA *
290.Fo PEM_read_bio_DSA_PUBKEY
291.Fa "BIO *bp"
292.Fa "DSA **x"
293.Fa "pem_password_cb *cb"
294.Fa "void *u"
295.Fc
296.Ft DSA *
297.Fo PEM_read_DSA_PUBKEY
298.Fa "FILE *fp"
299.Fa "DSA **x"
300.Fa "pem_password_cb *cb"
301.Fa "void *u"
302.Fc
303.Ft int
304.Fo PEM_write_bio_DSA_PUBKEY
305.Fa "BIO *bp"
306.Fa "DSA *x"
307.Fc
308.Ft int
309.Fo PEM_write_DSA_PUBKEY
310.Fa "FILE *fp"
311.Fa "DSA *x"
312.Fc
313.Ft DSA *
314.Fo PEM_read_bio_DSAparams
315.Fa "BIO *bp"
316.Fa "DSA **x"
317.Fa "pem_password_cb *cb"
318.Fa "void *u"
319.Fc
320.Ft DSA *
321.Fo PEM_read_DSAparams
322.Fa "FILE *fp"
323.Fa "DSA **x"
324.Fa "pem_password_cb *cb"
325.Fa "void *u"
326.Fc
327.Ft int
328.Fo PEM_write_bio_DSAparams
329.Fa "BIO *bp"
330.Fa "DSA *x"
331.Fc
332.Ft int
333.Fo PEM_write_DSAparams
334.Fa "FILE *fp"
335.Fa "DSA *x"
336.Fc
337.Ft DH *
338.Fo PEM_read_bio_DHparams
339.Fa "BIO *bp"
340.Fa "DH **x"
341.Fa "pem_password_cb *cb"
342.Fa "void *u"
343.Fc
344.Ft DH *
345.Fo PEM_read_DHparams
346.Fa "FILE *fp"
347.Fa "DH **x"
348.Fa "pem_password_cb *cb"
349.Fa "void *u"
350.Fc
351.Ft int
352.Fo PEM_write_bio_DHparams
353.Fa "BIO *bp"
354.Fa "DH *x"
355.Fc
356.Ft int
357.Fo PEM_write_DHparams
358.Fa "FILE *fp"
359.Fa "DH *x"
360.Fc
361.Ft X509 *
362.Fo PEM_read_bio_X509
363.Fa "BIO *bp"
364.Fa "X509 **x"
365.Fa "pem_password_cb *cb"
366.Fa "void *u"
367.Fc
368.Ft X509 *
369.Fo PEM_read_X509
370.Fa "FILE *fp"
371.Fa "X509 **x"
372.Fa "pem_password_cb *cb"
373.Fa "void *u"
374.Fc
375.Ft int
376.Fo PEM_write_bio_X509
377.Fa "BIO *bp"
378.Fa "X509 *x"
379.Fc
380.Ft int
381.Fo PEM_write_X509
382.Fa "FILE *fp"
383.Fa "X509 *x"
384.Fc
385.Ft X509 *
386.Fo PEM_read_bio_X509_AUX
387.Fa "BIO *bp"
388.Fa "X509 **x"
389.Fa "pem_password_cb *cb"
390.Fa "void *u"
391.Fc
392.Ft X509 *
393.Fo PEM_read_X509_AUX
394.Fa "FILE *fp"
395.Fa "X509 **x"
396.Fa "pem_password_cb *cb"
397.Fa "void *u"
398.Fc
399.Ft int
400.Fo PEM_write_bio_X509_AUX
401.Fa "BIO *bp"
402.Fa "X509 *x"
403.Fc
404.Ft int
405.Fo PEM_write_X509_AUX
406.Fa "FILE *fp"
407.Fa "X509 *x"
408.Fc
409.Ft X509_REQ *
410.Fo PEM_read_bio_X509_REQ
411.Fa "BIO *bp"
412.Fa "X509_REQ **x"
413.Fa "pem_password_cb *cb"
414.Fa "void *u"
415.Fc
416.Ft X509_REQ *
417.Fo PEM_read_X509_REQ
418.Fa "FILE *fp"
419.Fa "X509_REQ **x"
420.Fa "pem_password_cb *cb"
421.Fa "void *u"
422.Fc
423.Ft int
424.Fo PEM_write_bio_X509_REQ
425.Fa "BIO *bp"
426.Fa "X509_REQ *x"
427.Fc
428.Ft int
429.Fo PEM_write_X509_REQ
430.Fa "FILE *fp"
431.Fa "X509_REQ *x"
432.Fc
433.Ft int
434.Fo PEM_write_bio_X509_REQ_NEW
435.Fa "BIO *bp"
436.Fa "X509_REQ *x"
437.Fc
438.Ft int
439.Fo PEM_write_X509_REQ_NEW
440.Fa "FILE *fp"
441.Fa "X509_REQ *x"
442.Fc
443.Ft X509_CRL *
444.Fo PEM_read_bio_X509_CRL
445.Fa "BIO *bp"
446.Fa "X509_CRL **x"
447.Fa "pem_password_cb *cb"
448.Fa "void *u"
449.Fc
450.Ft X509_CRL *
451.Fo PEM_read_X509_CRL
452.Fa "FILE *fp"
453.Fa "X509_CRL **x"
454.Fa "pem_password_cb *cb"
455.Fa "void *u"
456.Fc
457.Ft int
458.Fo PEM_write_bio_X509_CRL
459.Fa "BIO *bp"
460.Fa "X509_CRL *x"
461.Fc
462.Ft int
463.Fo PEM_write_X509_CRL
464.Fa "FILE *fp"
465.Fa "X509_CRL *x"
466.Fc
467.Ft PKCS7 *
468.Fo PEM_read_bio_PKCS7
469.Fa "BIO *bp"
470.Fa "PKCS7 **x"
471.Fa "pem_password_cb *cb"
472.Fa "void *u"
473.Fc
474.Ft PKCS7 *
475.Fo PEM_read_PKCS7
476.Fa "FILE *fp"
477.Fa "PKCS7 **x"
478.Fa "pem_password_cb *cb"
479.Fa "void *u"
480.Fc
481.Ft int
482.Fo PEM_write_bio_PKCS7
483.Fa "BIO *bp"
484.Fa "PKCS7 *x"
485.Fc
486.Ft int
487.Fo PEM_write_PKCS7
488.Fa "FILE *fp"
489.Fa "PKCS7 *x"
490.Fc
491.Ft NETSCAPE_CERT_SEQUENCE *
492.Fo PEM_read_bio_NETSCAPE_CERT_SEQUENCE
493.Fa "BIO *bp"
494.Fa "NETSCAPE_CERT_SEQUENCE **x"
495.Fa "pem_password_cb *cb"
496.Fa "void *u"
497.Fc
498.Ft NETSCAPE_CERT_SEQUENCE *
499.Fo PEM_read_NETSCAPE_CERT_SEQUENCE
500.Fa "FILE *fp"
501.Fa "NETSCAPE_CERT_SEQUENCE **x"
502.Fa "pem_password_cb *cb"
503.Fa "void *u"
504.Fc
505.Ft int
506.Fo PEM_write_bio_NETSCAPE_CERT_SEQUENCE
507.Fa "BIO *bp"
508.Fa "NETSCAPE_CERT_SEQUENCE *x"
509.Fc
510.Ft int
511.Fo PEM_write_NETSCAPE_CERT_SEQUENCE
512.Fa "FILE *fp"
513.Fa "NETSCAPE_CERT_SEQUENCE *x"
514.Fc
515.Sh DESCRIPTION
516The PEM functions read or write structures in PEM format.
517In this sense PEM format is simply base64 encoded data surrounded by
518header lines.
519.Pp
520For more details about the meaning of arguments see the
521.Sx PEM function arguments
522section.
523.Pp
524Each operation has four functions associated with it.
525For clarity the term
526.Dq Sy foobar No functions
527will be used to collectively refer to the
528.Fn PEM_read_bio_foobar ,
529.Fn PEM_read_foobar ,
530.Fn PEM_write_bio_foobar ,
531and
532.Fn PEM_write_foobar
533functions.
534.Pp
535The
536.Sy PrivateKey
537functions read or write a private key in PEM format using an
538.Vt EVP_PKEY
539structure.
540The write routines use "traditional" private key format and can handle
541both RSA and DSA private keys.
542The read functions can additionally transparently handle PKCS#8 format
543encrypted and unencrypted keys, too.
544.Pp
545.Fn PEM_write_bio_PKCS8PrivateKey
546and
547.Fn PEM_write_PKCS8PrivateKey
548write a private key in an
549.Vt EVP_PKEY
550structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5
551v2.0 password based encryption algorithms.
552The
553.Fa enc
554argument specifies the encryption algorithm to use: unlike all other PEM
555routines, the encryption is applied at the PKCS#8 level and not in the
556PEM headers.
557If
558.Fa enc
559is
560.Dv NULL ,
561then no encryption is used and a PKCS#8 PrivateKeyInfo structure
562is used instead.
563.Pp
564.Fn PEM_write_bio_PKCS8PrivateKey_nid
565and
566.Fn PEM_write_PKCS8PrivateKey_nid
567also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo.
568However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead.
569The algorithm to use is specified in the
570.Fa nid
571parameter and should be the NID of the corresponding OBJECT IDENTIFIER
572(see NOTES section).
573.Pp
574The
575.Sy PUBKEY
576functions process a public key using an
577.Vt EVP_PKEY
578structure.
579The public key is encoded as a SubjectPublicKeyInfo structure.
580.Pp
581The
582.Sy RSAPrivateKey
583functions process an RSA private key using an
584.Vt RSA
585structure.
586They handle the same formats as the
587.Sy PrivateKey
588functions, but an error occurs if the private key is not RSA.
589.Pp
590The
591.Sy RSAPublicKey
592functions process an RSA public key using an
593.Vt RSA
594structure.
595The public key is encoded using a PKCS#1 RSAPublicKey structure.
596.Pp
597The
598.Sy RSA_PUBKEY
599functions also process an RSA public key using an
600.Vt RSA
601structure.
602However the public key is encoded using a SubjectPublicKeyInfo structure
603and an error occurs if the public key is not RSA.
604.Pp
605The
606.Sy DSAPrivateKey
607functions process a DSA private key using a
608.Vt DSA
609structure.
610They handle the same formats as the
611.Sy PrivateKey
612functions but an error occurs if the private key is not DSA.
613.Pp
614The
615.Sy DSA_PUBKEY
616functions process a DSA public key using a
617.Vt DSA
618structure.
619The public key is encoded using a SubjectPublicKeyInfo structure and an
620error occurs if the public key is not DSA.
621.Pp
622The
623.Sy DSAparams
624functions process DSA parameters using a
625.Vt DSA
626structure.
627The parameters are encoded using a Dss-Parms structure as defined in RFC 2459.
628.Pp
629The
630.Sy DHparams
631functions process DH parameters using a
632.Vt DH
633structure.
634The parameters are encoded using a PKCS#3 DHparameter structure.
635.Pp
636The
637.Sy X509
638functions process an X509 certificate using an
639.Vt X509
640structure.
641They will also process a trusted X509 certificate but any trust settings
642are discarded.
643.Pp
644The
645.Sy X509_AUX
646functions process a trusted X509 certificate using an
647.Vt X509
648structure.
649.Pp
650The
651.Sy X509_REQ
652and
653.Sy X509_REQ_NEW
654functions process a PKCS#10 certificate request using an
655.Vt X509_REQ
656structure.
657The
658.Sy X509_REQ
659write functions use CERTIFICATE REQUEST in the header whereas the
660.Sy X509_REQ_NEW
661functions use NEW CERTIFICATE REQUEST (as required by some CAs).
662The
663.Sy X509_REQ
664read functions will handle either form so there are no
665.Sy X509_REQ_NEW
666read functions.
667.Pp
668The
669.Sy X509_CRL
670functions process an X509 CRL using an
671.Vt X509_CRL
672structure.
673.Pp
674The
675.Sy PKCS7
676functions process a PKCS#7 ContentInfo using a
677.Vt PKCS7
678structure.
679.Pp
680The
681.Sy NETSCAPE_CERT_SEQUENCE
682functions process a Netscape Certificate Sequence using a
683.Vt NETSCAPE_CERT_SEQUENCE
684structure.
685.Pp
686The old
687.Sy PrivateKey
688write routines are retained for compatibility.
689New applications should write private keys using the
690.Fn PEM_write_bio_PKCS8PrivateKey
691or
692.Fn PEM_write_PKCS8PrivateKey
693routines because they are more secure (they use an iteration count of
6942048 whereas the traditional routines use a count of 1) unless
695compatibility with older versions of OpenSSL is important.
696.Pp
697The
698.Sy PrivateKey
699read routines can be used in all applications because they handle all
700formats transparently.
701.Ss PEM function arguments
702The PEM functions have many common arguments.
703.Pp
704The
705.Fa bp
706parameter specifies the
707.Vt BIO
708to read from or write to.
709.Pp
710The
711.Fa fp
712parameter specifies the
713.Vt FILE
714pointer to read from or write to.
715.Pp
716The PEM read functions all take a pointer to pointer argument
717.Fa x
718and return a pointer of the same type.
719If
720.Fa x
721is
722.Dv NULL ,
723then the parameter is ignored.
724If
725.Fa x
726is not
727.Dv NULL
728but
729.Pf * Fa x
730is
731.Dv NULL ,
732then the structure returned will be written to
733.Pf * Fa x .
734If neither
735.Fa x
736nor
737.Pf * Fa x
738are
739.Dv NULL ,
740then an attempt is made to reuse the structure at
741.Pf * Fa x ,
742but see the
743.Sx BUGS
744and
745.Sx EXAMPLES
746sections.
747Irrespective of the value of
748.Fa x ,
749a pointer to the structure is always returned, or
750.Dv NULL
751if an error occurred.
752.Pp
753The PEM functions which write private keys take an
754.Fa enc
755parameter which specifies the encryption algorithm to use.
756Encryption is done at the PEM level.
757If this parameter is set to
758.Dv NULL ,
759then the private key is written in unencrypted form.
760.Pp
761The
762.Fa cb
763argument is the callback to use when querying for the passphrase used
764for encrypted PEM structures (normally only private keys).
765.Pp
766For the PEM write routines, if the
767.Fa kstr
768parameter is not
769.Dv NULL ,
770then
771.Fa klen
772bytes at
773.Fa kstr
774are used as the passphrase and
775.Fa cb
776is ignored.
777.Pp
778If the
779.Fa cb
780parameters is set to
781.Dv NULL
782and the
783.Fa u
784parameter is not
785.Dv NULL ,
786then the
787.Fa u
788parameter is interpreted as a null terminated string to use as the
789passphrase.
790If both
791.Fa cb
792and
793.Fa u
794are
795.Dv NULL ,
796then the default callback routine is used which will typically
797prompt for the passphrase on the current terminal with echoing
798turned off.
799.Pp
800The default passphrase callback is sometimes inappropriate (for example
801in a GUI application) so an alternative can be supplied.
802The callback routine has the following form:
803.Bd -filled -offset inset
804.Ft int
805.Fo cb
806.Fa "char *buf"
807.Fa "int size"
808.Fa "int rwflag"
809.Fa "void *u"
810.Fc
811.Ed
812.Pp
813.Fa buf
814is the buffer to write the passphrase to.
815.Fa size
816is the maximum length of the passphrase, i.e. the size of
817.Fa buf .
818.Fa rwflag
819is a flag which is set to 0 when reading and 1 when writing.
820A typical routine will ask the user to verify the passphrase (for
821example by prompting for it twice) if
822.Fa rwflag
823is 1.
824The
825.Fa u
826parameter has the same value as the
827.Fa u
828parameter passed to the PEM routine.
829It allows arbitrary data to be passed to the callback by the application
830(for example a window handle in a GUI application).
831The callback must return the number of characters in the passphrase
832or 0 if an error occurred.
833.Ss PEM encryption format
834This old
835.Sy PrivateKey
836routines use a non standard technique for encryption.
837.Pp
838The private key (or other data) takes the following form:
839.Bd -literal -offset indent
840-----BEGIN RSA PRIVATE KEY-----
841Proc-Type: 4,ENCRYPTED
842DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
843
844\&...base64 encoded data...
845-----END RSA PRIVATE KEY-----
846.Ed
847.Pp
848The line beginning with
849.Dq DEK-Info
850contains two comma separated pieces of information:
851the encryption algorithm name as used by
852.Xr EVP_get_cipherbyname 3
853and an 8 byte salt encoded as a set of hexadecimal digits.
854.Pp
855After this is the base64 encoded encrypted data.
856.Pp
857The encryption key is determined using
858.Xr EVP_BytesToKey 3 ,
859using the salt and an iteration count of 1.
860The IV used is the value of the salt and *not* the IV returned by
861.Xr EVP_BytesToKey 3 .
862.Sh RETURN VALUES
863The read routines return either a pointer to the structure read or
864.Dv NULL
865if an error occurred.
866.Pp
867The write routines return 1 for success or 0 for failure.
868.Sh EXAMPLES
869Although the PEM routines take several arguments, in almost all
870applications most of them are set to 0 or
871.Dv NULL .
872.Pp
873Read a certificate in PEM format from a
874.Vt BIO :
875.Bd -literal
876X509 *x;
877x = PEM_read_bio_X509(bp, NULL, 0, NULL);
878if (x == NULL) {
879 /* Error */
880}
881.Ed
882.Pp
883Alternative method:
884.Bd -literal
885X509 *x = NULL;
886if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
887 /* Error */
888}
889.Ed
890.Pp
891Write a certificate to a
892.Vt BIO :
893.Bd -literal
894if (!PEM_write_bio_X509(bp, x)) {
895 /* Error */
896}
897.Ed
898.Pp
899Write an unencrypted private key to a
900.Vt FILE :
901.Bd -literal
902if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
903 /* Error */
904}
905.Ed
906.Pp
907Write a private key (using traditional format) to a
908.Vt BIO
909using triple DES encryption, the pass phrase is prompted for:
910.Bd -literal
911if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
912 NULL, 0, 0, NULL)) {
913 /* Error */
914}
915.Ed
916.Pp
917Write a private key (using PKCS#8 format) to a
918.Vt BIO
919using triple DES encryption, using the pass phrase "hello":
920.Bd -literal
921if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
922 NULL, 0, 0, "hello")) {
923 /* Error */
924}
925.Ed
926.Pp
927Read a private key from a
928.Vt BIO
929using the pass phrase "hello":
930.Bd -literal
931key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
932if (key == NULL) {
933 /* Error */
934}
935.Ed
936.Pp
937Read a private key from a
938.Vt BIO
939using a pass phrase callback:
940.Bd -literal
941key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
942if (key == NULL) {
943 /* Error */
944}
945.Ed
946.Pp
947Skeleton pass phrase callback:
948.Bd -literal
949int
950pass_cb(char *buf, int size, int rwflag, void *u)
951{
952 int len;
953 char *tmp;
954
955 /* We'd probably do something else if 'rwflag' is 1 */
956 printf("Enter pass phrase for \e"%s\e"\en", u);
957
958 /* get pass phrase, length 'len' into 'tmp' */
959 tmp = "hello";
960 len = strlen(tmp);
961
962 if (len == 0)
963 return 0;
964 /* if too long, truncate */
965 if (len > size)
966 len = size;
967 memcpy(buf, tmp, len);
968 return len;
969}
970.Ed
971.Sh CAVEATS
972A frequent cause of problems is attempting to use the PEM routines like
973this:
974.Bd -literal
975X509 *x;
976PEM_read_bio_X509(bp, &x, 0, NULL);
977.Ed
978.Pp
979This is a bug because an attempt will be made to reuse the data at
980.Fa x
981which is an uninitialised pointer.
982.Sh BUGS
983The PEM read routines in some versions of OpenSSL will not correctly
984reuse an existing structure.
985Therefore
986.Pp
987.Dl PEM_read_bio_X509(bp, &x, 0, NULL);
988.Pp
989where
990.Fa x
991already contains a valid certificate may not work, whereas
992.Bd -literal -offset indent
993X509_free(x);
994x = PEM_read_bio_X509(bp, NULL, 0, NULL);
995.Ed
996.Pp
997is guaranteed to work.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-09 11:09:03 +0000