Debian Codegraph @

upstream/debian-unstable/man3/PEM_read.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 "PEM_READ 3SSL"
58 .TH PEM_READ 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 PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO, PEM_write,
65 PEM_write_bio, PEM_ASN1_write, PEM_ASN1_write_bio, PEM_ASN1_write_bio_ctx
66 \&\- PEM encoding routines
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/pem.h>
71 \&
72 \& int PEM_read(FILE *fp, char **name, char **header,
73 \& unsigned char **data, long *len);
74 \& int PEM_read_bio(BIO *bp, char **name, char **header,
75 \& unsigned char **data, long *len);
76 \&
77 \& int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);
78 \& int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
79 \& pem_password_cb *cb, void *u);
80 \&
81 \& int PEM_write(FILE *fp, const char *name, const char *header,
82 \& const unsigned char *data, long len);
83 \& int PEM_write_bio(BIO *bp, const char *name, const char *header,
84 \& const unsigned char *data, long len);
85 \& int PEM_ASN1_write(i2d_of_void *i2d, const char *name, FILE *fp,
86 \& const void *x, const EVP_CIPHER *enc,
87 \& const unsigned char *kstr, int klen,
88 \& pem_password_cb *callback, void *u);
89 \& int PEM_ASN1_write_bio(i2d_of_void *i2d, const char *name, BIO *bp,
90 \& const void *x, const EVP_CIPHER *enc,
91 \& const unsigned char *kstr, int klen,
92 \& pem_password_cb *callback, void *u);
93 \& int PEM_ASN1_write_bio_ctx(OSSL_i2d_of_void_ctx *i2d, void *vctx,
94 \& const char *name, BIO *bp, const void *x,
95 \& const EVP_CIPHER *enc, const unsigned char *kstr,
96 \& int klen, pem_password_cb *callback, void *u);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 These functions read and write PEM-encoded objects, using the PEM
101 type \fBname\fR, any additional \fBheader\fR information, and the raw
102 \&\fBdata\fR of length \fBlen\fR.
103 .PP
104 PEM is the term used for binary content encoding first defined in IETF
105 RFC 1421. The content is a series of base64\-encoded lines, surrounded
106 by begin/end markers each on their own line. For example:
107 .PP
108 .Vb 4
109 \& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\-
110 \& MIICdg....
111 \& ... bhTQ==
112 \& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\-
113 .Ve
114 .PP
115 Optional header line(s) may appear after the begin line, and their
116 existence depends on the type of object being written or read.
117 .PP
118 \&\fBPEM_write()\fR writes to the file \fBfp\fR, while \fBPEM_write_bio()\fR writes to
119 the BIO \fBbp\fR. The \fBname\fR is the name to use in the marker, the
120 \&\fBheader\fR is the header value or NULL, and \fBdata\fR and \fBlen\fR specify
121 the data and its length.
122 .PP
123 The final \fBdata\fR buffer is typically an ASN.1 object which can be decoded with
124 the \fBd2i\fR function appropriate to the type \fBname\fR; see \fBd2i_X509\fR\|(3)
125 for examples.
126 .PP
127 \&\fBPEM_read()\fR reads from the file \fBfp\fR, while \fBPEM_read_bio()\fR reads
128 from the BIO \fBbp\fR.
129 Both skip any non-PEM data that precedes the start of the next PEM object.
130 When an object is successfully retrieved, the type name from the "\-\-\-\-BEGIN
131 <type>\-\-\-\-\-" is returned via the \fBname\fR argument, any encapsulation headers
132 are returned in \fBheader\fR and the base64\-decoded content and its length are
133 returned via \fBdata\fR and \fBlen\fR respectively.
134 The \fBname\fR, \fBheader\fR and \fBdata\fR pointers are allocated via \fBOPENSSL_malloc()\fR
135 and should be freed by the caller via \fBOPENSSL_free()\fR when no longer needed.
136 .PP
137 \&\fBPEM_get_EVP_CIPHER_INFO()\fR can be used to determine the \fBdata\fR returned by
138 \&\fBPEM_read()\fR or \fBPEM_read_bio()\fR is encrypted and to retrieve the associated cipher
139 and IV.
140 The caller passes a pointer to structure of type \fBEVP_CIPHER_INFO\fR via the
141 \&\fBcinfo\fR argument and the \fBheader\fR returned via \fBPEM_read()\fR or \fBPEM_read_bio()\fR.
142 If the call is successful 1 is returned and the cipher and IV are stored at the
143 address pointed to by \fBcinfo\fR.
144 When the header is malformed, or not supported or when the cipher is unknown
145 or some internal error happens 0 is returned.
146 This function is deprecated, see \fBNOTES\fR below.
147 .PP
148 \&\fBPEM_do_header()\fR can then be used to decrypt the data if the header
149 indicates encryption.
150 The \fBcinfo\fR argument is a pointer to the structure initialized by the previous
151 call to \fBPEM_get_EVP_CIPHER_INFO()\fR.
152 The \fBdata\fR and \fBlen\fR arguments are those returned by the previous call to
153 \&\fBPEM_read()\fR or \fBPEM_read_bio()\fR.
154 The \fBcb\fR and \fBu\fR arguments make it possible to override the default password
155 prompt function as described in \fBPEM_read_PrivateKey\fR\|(3).
156 On successful completion the \fBdata\fR is decrypted in place, and \fBlen\fR is
157 updated to indicate the plaintext length.
158 This function is deprecated, see \fBNOTES\fR below.
159 .PP
160 If the data is a priori known to not be encrypted, then neither \fBPEM_do_header()\fR
161 nor \fBPEM_get_EVP_CIPHER_INFO()\fR need be called.
162 .SH "RETURN VALUES"
163 .IX Header "RETURN VALUES"
164 \&\fBPEM_read()\fR, and \fBPEM_read_bio()\fR return 1 on success and 0 on failure, the latter
165 includes the case when no more PEM objects remain in the input file. To
166 distinguish end of file from more serious errors the caller must peek at the
167 error stack and check for \fBPEM_R_NO_START_LINE\fR, which indicates that no more
168 PEM objects were found. See \fBERR_peek_last_error\fR\|(3), \fBERR_GET_REASON\fR\|(3).
169 .PP
170 \&\fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR return 1 on success, and 0 on
171 failure.
172 The \fBdata\fR is likely meaningless if these functions fail.
173 .SH NOTES
174 .IX Header "NOTES"
175 The \fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR functions are deprecated.
176 This is because the underlying PEM encryption format is obsolete, and should
177 be avoided.
178 It uses an encryption format with an OpenSSL-specific key-derivation function,
179 which employs MD5 with an iteration count of 1!
180 Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5
181 v2.0 PBE.
182 See \fBPEM_write_PrivateKey\fR\|(3) and \fBd2i_PKCS8PrivateKey_bio\fR\|(3).
183 .PP
184 \&\fBPEM_do_header()\fR makes no assumption regarding the pass phrase received from the
185 password callback.
186 It will simply be treated as a byte sequence.
187 .PP
188 \&\fBPEM_write()\fR and \fBPEM_write_bio()\fR return the number of encoded bytes (not
189 counting the PEM header and end marker) written on success or 0 on failure.
190 .PP
191 \&\fBPEM_ASN1_write_bio()\fR, and \fBPEM_ASN1_write_bio_ctx()\fR return 1 on success and 0 on
192 failure. The latter function passes an additional application-provided context
193 value to the \fBi2d\fR function that serialises the input ASN.1 object.
194 .SH "SEE ALSO"
195 .IX Header "SEE ALSO"
196 \&\fBERR_peek_last_error\fR\|(3), \fBERR_GET_LIB\fR\|(3),
197 \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3),
198 \&\fBpassphrase\-encoding\fR\|(7)
199 .SH HISTORY
200 .IX Header "HISTORY"
201 The \fBPEM_ASN1_write_bio_ctx()\fR function was added in OpenSSL 3.5.
202 .SH COPYRIGHT
203 .IX Header "COPYRIGHT"
204 Copyright 1998\-2025 The OpenSSL Project Authors. All Rights Reserved.
205 .PP
206 Licensed under the Apache License 2.0 (the "License"). You may not use
207 this file except in compliance with the License. You can obtain a copy
208 in the file LICENSE in the source distribution or at
209 <https://www.openssl.org/source/license.html>.