| 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_BIO_PRIVATEKEY 3SSL" |
| 58 |
.TH PEM_READ_BIO_PRIVATEKEY 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_password_cb, |
| 65 |
PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey, |
| 66 |
PEM_read_PrivateKey_ex, PEM_read_PrivateKey, |
| 67 |
PEM_write_bio_PrivateKey_ex, PEM_write_bio_PrivateKey, |
| 68 |
PEM_write_bio_PrivateKey_traditional, |
| 69 |
PEM_write_PrivateKey_ex, PEM_write_PrivateKey, |
| 70 |
PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, |
| 71 |
PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, |
| 72 |
PEM_read_bio_PUBKEY_ex, PEM_read_bio_PUBKEY, |
| 73 |
PEM_read_PUBKEY_ex, PEM_read_PUBKEY, |
| 74 |
PEM_write_bio_PUBKEY_ex, PEM_write_bio_PUBKEY, |
| 75 |
PEM_write_PUBKEY_ex, PEM_write_PUBKEY, |
| 76 |
PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, |
| 77 |
PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, |
| 78 |
PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, |
| 79 |
PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, |
| 80 |
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, |
| 81 |
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, |
| 82 |
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, |
| 83 |
PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters_ex, PEM_read_bio_Parameters, |
| 84 |
PEM_write_bio_Parameters, PEM_read_bio_DSAparams, PEM_read_DSAparams, |
| 85 |
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, |
| 86 |
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, |
| 87 |
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, |
| 88 |
PEM_read_bio_X509_ACERT, PEM_read_X509_ACERT, |
| 89 |
PEM_write_bio_X509_ACERT, PEM_write_X509_ACERT, |
| 90 |
PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, |
| 91 |
PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, |
| 92 |
PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, |
| 93 |
PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, |
| 94 |
PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, |
| 95 |
PEM_write_bio_PKCS7, PEM_write_PKCS7 \- PEM routines |
| 96 |
.SH SYNOPSIS |
| 97 |
.IX Header "SYNOPSIS" |
| 98 |
.Vb 1 |
| 99 |
\& #include <openssl/pem.h> |
| 100 |
\& |
| 101 |
\& typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); |
| 102 |
\& |
| 103 |
\& EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x, |
| 104 |
\& pem_password_cb *cb, void *u, |
| 105 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 106 |
\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, |
| 107 |
\& pem_password_cb *cb, void *u); |
| 108 |
\& EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, |
| 109 |
\& void *u, OSSL_LIB_CTX *libctx, |
| 110 |
\& const char *propq); |
| 111 |
\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, |
| 112 |
\& pem_password_cb *cb, void *u); |
| 113 |
\& int PEM_write_bio_PrivateKey_ex(BIO *bp, const EVP_PKEY *x, |
| 114 |
\& const EVP_CIPHER *enc, |
| 115 |
\& unsigned char *kstr, int klen, |
| 116 |
\& pem_password_cb *cb, void *u, |
| 117 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 118 |
\& int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, |
| 119 |
\& unsigned char *kstr, int klen, |
| 120 |
\& pem_password_cb *cb, void *u); |
| 121 |
\& int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, |
| 122 |
\& const EVP_CIPHER *enc, |
| 123 |
\& unsigned char *kstr, int klen, |
| 124 |
\& pem_password_cb *cb, void *u); |
| 125 |
\& int PEM_write_PrivateKey_ex(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
| 126 |
\& unsigned char *kstr, int klen, |
| 127 |
\& pem_password_cb *cb, void *u, |
| 128 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 129 |
\& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
| 130 |
\& unsigned char *kstr, int klen, |
| 131 |
\& pem_password_cb *cb, void *u); |
| 132 |
\& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, |
| 133 |
\& char *kstr, int klen, |
| 134 |
\& pem_password_cb *cb, void *u); |
| 135 |
\& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, |
| 136 |
\& char *kstr, int klen, |
| 137 |
\& pem_password_cb *cb, void *u); |
| 138 |
\& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid, |
| 139 |
\& char *kstr, int klen, |
| 140 |
\& pem_password_cb *cb, void *u); |
| 141 |
\& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid, |
| 142 |
\& char *kstr, int klen, |
| 143 |
\& pem_password_cb *cb, void *u); |
| 144 |
\& |
| 145 |
\& EVP_PKEY *PEM_read_bio_PUBKEY_ex(BIO *bp, EVP_PKEY **x, |
| 146 |
\& pem_password_cb *cb, void *u, |
| 147 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 148 |
\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, |
| 149 |
\& pem_password_cb *cb, void *u); |
| 150 |
\& EVP_PKEY *PEM_read_PUBKEY_ex(FILE *fp, EVP_PKEY **x, |
| 151 |
\& pem_password_cb *cb, void *u, |
| 152 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 153 |
\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, |
| 154 |
\& pem_password_cb *cb, void *u); |
| 155 |
\& int PEM_write_bio_PUBKEY_ex(BIO *bp, EVP_PKEY *x, |
| 156 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 157 |
\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); |
| 158 |
\& int PEM_write_PUBKEY_ex(FILE *fp, EVP_PKEY *x, |
| 159 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 160 |
\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); |
| 161 |
\& |
| 162 |
\& EVP_PKEY *PEM_read_bio_Parameters_ex(BIO *bp, EVP_PKEY **x, |
| 163 |
\& OSSL_LIB_CTX *libctx, const char *propq); |
| 164 |
\& EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x); |
| 165 |
\& int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x); |
| 166 |
\& |
| 167 |
\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); |
| 168 |
\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); |
| 169 |
\& int PEM_write_bio_X509(BIO *bp, X509 *x); |
| 170 |
\& int PEM_write_X509(FILE *fp, X509 *x); |
| 171 |
\& |
| 172 |
\& X509_ACERT *PEM_read_bio_X509_ACERT(BIO *bp, X509_ACERT **x, |
| 173 |
\& pem_password_cb *cb, void *u); |
| 174 |
\& X509_ACERT *PEM_read_X509_ACERT(FILE *fp, X509_ACERT **x, |
| 175 |
\& pem_password_cb *cb, void *u); |
| 176 |
\& int PEM_write_bio_X509_ACERT(BIO *bp, X509_ACERT *x); |
| 177 |
\& int PEM_write_X509_ACERT(FILE *fp, X509_ACERT *x); |
| 178 |
\& |
| 179 |
\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); |
| 180 |
\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); |
| 181 |
\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); |
| 182 |
\& int PEM_write_X509_AUX(FILE *fp, X509 *x); |
| 183 |
\& |
| 184 |
\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, |
| 185 |
\& pem_password_cb *cb, void *u); |
| 186 |
\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, |
| 187 |
\& pem_password_cb *cb, void *u); |
| 188 |
\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); |
| 189 |
\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); |
| 190 |
\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); |
| 191 |
\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); |
| 192 |
\& |
| 193 |
\& X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, |
| 194 |
\& pem_password_cb *cb, void *u); |
| 195 |
\& X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, |
| 196 |
\& pem_password_cb *cb, void *u); |
| 197 |
\& int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); |
| 198 |
\& int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); |
| 199 |
\& |
| 200 |
\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); |
| 201 |
\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); |
| 202 |
\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); |
| 203 |
\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x); |
| 204 |
.Ve |
| 205 |
.PP |
| 206 |
The following functions have been deprecated since OpenSSL 3.0, and can be |
| 207 |
hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, |
| 208 |
see \fBopenssl_user_macros\fR\|(7): |
| 209 |
.PP |
| 210 |
.Vb 10 |
| 211 |
\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, |
| 212 |
\& pem_password_cb *cb, void *u); |
| 213 |
\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, |
| 214 |
\& pem_password_cb *cb, void *u); |
| 215 |
\& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, |
| 216 |
\& unsigned char *kstr, int klen, |
| 217 |
\& pem_password_cb *cb, void *u); |
| 218 |
\& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, |
| 219 |
\& unsigned char *kstr, int klen, |
| 220 |
\& pem_password_cb *cb, void *u); |
| 221 |
\& |
| 222 |
\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, |
| 223 |
\& pem_password_cb *cb, void *u); |
| 224 |
\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, |
| 225 |
\& pem_password_cb *cb, void *u); |
| 226 |
\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); |
| 227 |
\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x); |
| 228 |
\& |
| 229 |
\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, |
| 230 |
\& pem_password_cb *cb, void *u); |
| 231 |
\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, |
| 232 |
\& pem_password_cb *cb, void *u); |
| 233 |
\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); |
| 234 |
\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); |
| 235 |
\& |
| 236 |
\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, |
| 237 |
\& pem_password_cb *cb, void *u); |
| 238 |
\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, |
| 239 |
\& pem_password_cb *cb, void *u); |
| 240 |
\& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, |
| 241 |
\& unsigned char *kstr, int klen, |
| 242 |
\& pem_password_cb *cb, void *u); |
| 243 |
\& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, |
| 244 |
\& unsigned char *kstr, int klen, |
| 245 |
\& pem_password_cb *cb, void *u); |
| 246 |
\& |
| 247 |
\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, |
| 248 |
\& pem_password_cb *cb, void *u); |
| 249 |
\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, |
| 250 |
\& pem_password_cb *cb, void *u); |
| 251 |
\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); |
| 252 |
\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); |
| 253 |
\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); |
| 254 |
\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); |
| 255 |
\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x); |
| 256 |
\& int PEM_write_DSAparams(FILE *fp, DSA *x); |
| 257 |
\& |
| 258 |
\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); |
| 259 |
\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); |
| 260 |
\& int PEM_write_bio_DHparams(BIO *bp, DH *x); |
| 261 |
\& int PEM_write_DHparams(FILE *fp, DH *x); |
| 262 |
.Ve |
| 263 |
.SH DESCRIPTION |
| 264 |
.IX Header "DESCRIPTION" |
| 265 |
All of the functions described on this page that have a \fITYPE\fR of \fBDH\fR, \fBDSA\fR |
| 266 |
and \fBRSA\fR are deprecated. Applications should use \fBOSSL_ENCODER_to_bio\fR\|(3) and |
| 267 |
\&\fBOSSL_DECODER_from_bio\fR\|(3) instead. |
| 268 |
.PP |
| 269 |
The PEM functions read or write structures in PEM format. In |
| 270 |
this sense PEM format is simply base64 encoded data surrounded |
| 271 |
by header lines. |
| 272 |
.PP |
| 273 |
For more details about the meaning of arguments see the |
| 274 |
\&\fBPEM FUNCTION ARGUMENTS\fR section. |
| 275 |
.PP |
| 276 |
Each operation has four functions associated with it. For |
| 277 |
brevity the term "\fR\f(BITYPE\fR\fB\fR functions" will be used below to collectively |
| 278 |
refer to the \fBPEM_read_bio_\fR\f(BITYPE\fR\fB\fR(), \fBPEM_read_\fR\f(BITYPE\fR\fB\fR(), |
| 279 |
\&\fBPEM_write_bio_\fR\f(BITYPE\fR\fB\fR(), and \fBPEM_write_\fR\f(BITYPE\fR\fB\fR() functions. |
| 280 |
.PP |
| 281 |
Some operations have additional variants that take a library context \fIlibctx\fR |
| 282 |
and a property query string \fIpropq\fR. The \fBX509\fR, \fBX509_REQ\fR and \fBX509_CRL\fR |
| 283 |
objects may have an associated library context or property query string but |
| 284 |
there are no variants of these functions that take a library context or property |
| 285 |
query string parameter. In this case it is possible to set the appropriate |
| 286 |
library context or property query string by creating an empty \fBX509\fR, |
| 287 |
\&\fBX509_REQ\fR or \fBX509_CRL\fR object using \fBX509_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) |
| 288 |
or \fBX509_CRL_new_ex\fR\|(3) respectively. Then pass the empty object as a parameter |
| 289 |
to the relevant PEM function. See the "EXAMPLES" section below. |
| 290 |
.PP |
| 291 |
The \fBPrivateKey\fR functions read or write a private key in PEM format using |
| 292 |
an EVP_PKEY structure. The write routines use PKCS#8 private key format and are |
| 293 |
equivalent to \fBPEM_write_bio_PKCS8PrivateKey()\fR. The read functions transparently |
| 294 |
handle traditional and PKCS#8 format encrypted and unencrypted keys. |
| 295 |
.PP |
| 296 |
\&\fBPEM_write_bio_PrivateKey_traditional()\fR writes out a private key in the |
| 297 |
"traditional" format with a simple private key marker and should only |
| 298 |
be used for compatibility with legacy programs. |
| 299 |
.PP |
| 300 |
\&\fBPEM_write_bio_PKCS8PrivateKey()\fR and \fBPEM_write_PKCS8PrivateKey()\fR write a private |
| 301 |
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using |
| 302 |
PKCS#5 v2.0 password based encryption algorithms. The \fIcipher\fR argument |
| 303 |
specifies the encryption algorithm to use: unlike some other PEM routines the |
| 304 |
encryption is applied at the PKCS#8 level and not in the PEM headers. If |
| 305 |
\&\fIcipher\fR is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo |
| 306 |
structure is used instead. |
| 307 |
.PP |
| 308 |
\&\fBPEM_write_bio_PKCS8PrivateKey_nid()\fR and \fBPEM_write_PKCS8PrivateKey_nid()\fR |
| 309 |
also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however |
| 310 |
it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm |
| 311 |
to use is specified in the \fInid\fR parameter and should be the NID of the |
| 312 |
corresponding OBJECT IDENTIFIER (see NOTES section). |
| 313 |
.PP |
| 314 |
The \fBPUBKEY\fR functions process a public key using an EVP_PKEY |
| 315 |
structure. The public key is encoded as a SubjectPublicKeyInfo |
| 316 |
structure. |
| 317 |
.PP |
| 318 |
The \fBRSAPrivateKey\fR functions process an RSA private key using an |
| 319 |
RSA structure. The write routines uses traditional format. The read |
| 320 |
routines handles the same formats as the \fBPrivateKey\fR |
| 321 |
functions but an error occurs if the private key is not RSA. |
| 322 |
.PP |
| 323 |
The \fBRSAPublicKey\fR functions process an RSA public key using an |
| 324 |
RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey |
| 325 |
structure. |
| 326 |
.PP |
| 327 |
The \fBRSA_PUBKEY\fR functions also process an RSA public key using |
| 328 |
an RSA structure. However, the public key is encoded using a |
| 329 |
SubjectPublicKeyInfo structure and an error occurs if the public |
| 330 |
key is not RSA. |
| 331 |
.PP |
| 332 |
The \fBDSAPrivateKey\fR functions process a DSA private key using a |
| 333 |
DSA structure. The write routines uses traditional format. The read |
| 334 |
routines handles the same formats as the \fBPrivateKey\fR |
| 335 |
functions but an error occurs if the private key is not DSA. |
| 336 |
.PP |
| 337 |
The \fBDSA_PUBKEY\fR functions process a DSA public key using |
| 338 |
a DSA structure. The public key is encoded using a |
| 339 |
SubjectPublicKeyInfo structure and an error occurs if the public |
| 340 |
key is not DSA. |
| 341 |
.PP |
| 342 |
The \fBParameters\fR functions read or write key parameters in PEM format using |
| 343 |
an EVP_PKEY structure. The encoding depends on the type of key; for DSA key |
| 344 |
parameters, it will be a Dss-Parms structure as defined in RFC 3370, and for DH |
| 345 |
key parameters, it will be a PKCS#3 DHparameter structure. \fIThese functions |
| 346 |
only exist for the \fR\f(BIBIO\fR\fI type\fR. |
| 347 |
.PP |
| 348 |
The \fBDSAparams\fR functions process DSA parameters using a DSA |
| 349 |
structure. The parameters are encoded using a Dss-Parms structure |
| 350 |
as defined in RFC 3370. |
| 351 |
.PP |
| 352 |
The \fBDHparams\fR functions process DH parameters using a DH |
| 353 |
structure. The parameters are encoded using a PKCS#3 DHparameter |
| 354 |
structure. |
| 355 |
.PP |
| 356 |
The \fBX509\fR functions process an X509 certificate using an X509 |
| 357 |
structure. They will also process a trusted X509 certificate but |
| 358 |
any trust settings are discarded. |
| 359 |
.PP |
| 360 |
The \fBX509_ACERT\fR functions process an X509 attribute certificate using |
| 361 |
an X509_ACERT structure. |
| 362 |
.PP |
| 363 |
The \fBX509_AUX\fR functions process a trusted X509 certificate using |
| 364 |
an X509 structure. |
| 365 |
.PP |
| 366 |
The \fBX509_REQ\fR and \fBX509_REQ_NEW\fR functions process a PKCS#10 |
| 367 |
certificate request using an X509_REQ structure. The \fBX509_REQ\fR |
| 368 |
write functions use \fBCERTIFICATE REQUEST\fR in the header whereas |
| 369 |
the \fBX509_REQ_NEW\fR functions use \fBNEW CERTIFICATE REQUEST\fR |
| 370 |
(as required by some CAs). The \fBX509_REQ\fR read functions will |
| 371 |
handle either form so there are no \fBX509_REQ_NEW\fR read functions. |
| 372 |
.PP |
| 373 |
The \fBX509_CRL\fR functions process an X509 CRL using an X509_CRL |
| 374 |
structure. |
| 375 |
.PP |
| 376 |
The \fBPKCS7\fR functions process a PKCS#7 ContentInfo using a PKCS7 |
| 377 |
structure. |
| 378 |
.SH "PEM FUNCTION ARGUMENTS" |
| 379 |
.IX Header "PEM FUNCTION ARGUMENTS" |
| 380 |
The PEM functions have many common arguments. |
| 381 |
.PP |
| 382 |
The \fIbp\fR BIO parameter (if present) specifies the BIO to read from |
| 383 |
or write to. The \fIbp\fR BIO parameter \fBMUST NOT\fR be NULL. |
| 384 |
.PP |
| 385 |
The \fIfp\fR FILE parameter (if present) specifies the FILE pointer to |
| 386 |
read from or write to. |
| 387 |
.PP |
| 388 |
The PEM read functions all take an argument \fR\f(BITYPE\fR\fI **x\fR and return |
| 389 |
a \fI\fR\f(BITYPE\fR\fI *\fR pointer. Where \fI\fR\f(BITYPE\fR\fI\fR is whatever structure the function |
| 390 |
uses. If \fIx\fR is NULL then the parameter is ignored. If \fIx\fR is not |
| 391 |
NULL but \fI*x\fR is NULL then the structure returned will be written |
| 392 |
to \fI*x\fR. If neither \fIx\fR nor \fI*x\fR is NULL then an attempt is made |
| 393 |
to reuse the structure at \fI*x\fR (but see BUGS and EXAMPLES sections). |
| 394 |
Irrespective of the value of \fIx\fR a pointer to the structure is always |
| 395 |
returned (or NULL if an error occurred). The caller retains ownership of the |
| 396 |
returned object and needs to free it when it is no longer needed, e.g. |
| 397 |
using \fBX509_free()\fR for X509 objects or \fBEVP_PKEY_free()\fR for EVP_PKEY objects. |
| 398 |
.PP |
| 399 |
The PEM functions which write private keys take an \fIenc\fR parameter |
| 400 |
which specifies the encryption algorithm to use, encryption is done |
| 401 |
at the PEM level. If this parameter is set to NULL then the private |
| 402 |
key is written in unencrypted form. |
| 403 |
.PP |
| 404 |
The \fIcb\fR argument is the callback to use when querying for the pass |
| 405 |
phrase used for encrypted PEM structures (normally only private keys). |
| 406 |
.PP |
| 407 |
For the PEM write routines if the \fIkstr\fR parameter is not NULL then |
| 408 |
\&\fIklen\fR bytes at \fIkstr\fR are used as the passphrase and \fIcb\fR is |
| 409 |
ignored. |
| 410 |
.PP |
| 411 |
If the \fIcb\fR parameters is set to NULL and the \fIu\fR parameter is not |
| 412 |
NULL then the \fIu\fR parameter is interpreted as a NUL terminated string |
| 413 |
to use as the passphrase. If both \fIcb\fR and \fIu\fR are NULL then the |
| 414 |
default callback routine is used which will typically prompt for the |
| 415 |
passphrase on the current terminal with echoing turned off. |
| 416 |
.PP |
| 417 |
The default passphrase callback is sometimes inappropriate (for example |
| 418 |
in a GUI application) so an alternative can be supplied. The callback |
| 419 |
routine has the following form: |
| 420 |
.PP |
| 421 |
.Vb 1 |
| 422 |
\& int cb(char *buf, int size, int rwflag, void *u); |
| 423 |
.Ve |
| 424 |
.PP |
| 425 |
\&\fIbuf\fR is the buffer to write the passphrase to. \fIsize\fR is the maximum |
| 426 |
length of the passphrase (i.e. the size of buf). \fIrwflag\fR is a flag |
| 427 |
which is set to 0 when reading and 1 when writing. A typical routine |
| 428 |
will ask the user to verify the passphrase (for example by prompting |
| 429 |
for it twice) if \fIrwflag\fR is 1. The \fIu\fR parameter has the same |
| 430 |
value as the \fIu\fR parameter passed to the PEM routine. It allows |
| 431 |
arbitrary data to be passed to the callback by the application |
| 432 |
(for example a window handle in a GUI application). The callback |
| 433 |
\&\fImust\fR return the number of characters in the passphrase or \-1 if |
| 434 |
an error occurred. The passphrase can be arbitrary data; in the case where it |
| 435 |
is a string, it is not NUL terminated. See the "EXAMPLES" section below. |
| 436 |
.PP |
| 437 |
Some implementations may need to use cryptographic algorithms during their |
| 438 |
operation. If this is the case and \fIlibctx\fR and \fIpropq\fR parameters have been |
| 439 |
passed then any algorithm fetches will use that library context and property |
| 440 |
query string. Otherwise the default library context and property query string |
| 441 |
will be used. |
| 442 |
.SH NOTES |
| 443 |
.IX Header "NOTES" |
| 444 |
The PEM reading functions will skip any extraneous content or PEM data of |
| 445 |
a different type than they expect. This allows for example having a certificate |
| 446 |
(or multiple certificates) and a key in the PEM format in a single file. |
| 447 |
.PP |
| 448 |
The old \fBPrivateKey\fR write routines are retained for compatibility. |
| 449 |
New applications should write private keys using the |
| 450 |
\&\fBPEM_write_bio_PKCS8PrivateKey()\fR or \fBPEM_write_PKCS8PrivateKey()\fR routines |
| 451 |
because they are more secure (they use an iteration count of 2048 whereas |
| 452 |
the traditional routines use a count of 1) unless compatibility with older |
| 453 |
versions of OpenSSL is important. |
| 454 |
.PP |
| 455 |
The \fBPrivateKey\fR read routines can be used in all applications because |
| 456 |
they handle all formats transparently. |
| 457 |
.PP |
| 458 |
A frequent cause of problems is attempting to use the PEM routines like |
| 459 |
this: |
| 460 |
.PP |
| 461 |
.Vb 1 |
| 462 |
\& X509 *x; |
| 463 |
\& |
| 464 |
\& PEM_read_bio_X509(bp, &x, 0, NULL); |
| 465 |
.Ve |
| 466 |
.PP |
| 467 |
this is a bug because an attempt will be made to reuse the data at \fIx\fR |
| 468 |
which is an uninitialised pointer. |
| 469 |
.PP |
| 470 |
These functions make no assumption regarding the pass phrase received from the |
| 471 |
password callback. |
| 472 |
It will simply be treated as a byte sequence. |
| 473 |
.SH "PEM ENCRYPTION FORMAT" |
| 474 |
.IX Header "PEM ENCRYPTION FORMAT" |
| 475 |
These old \fBPrivateKey\fR routines use a non standard technique for encryption. |
| 476 |
.PP |
| 477 |
The private key (or other data) takes the following form: |
| 478 |
.PP |
| 479 |
.Vb 3 |
| 480 |
\& \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\- |
| 481 |
\& Proc\-Type: 4,ENCRYPTED |
| 482 |
\& DEK\-Info: DES\-EDE3\-CBC,3F17F5316E2BAC89 |
| 483 |
\& |
| 484 |
\& ...base64 encoded data... |
| 485 |
\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\- |
| 486 |
.Ve |
| 487 |
.PP |
| 488 |
The line beginning with \fIProc-Type\fR contains the version and the |
| 489 |
protection on the encapsulated data. The line beginning \fIDEK-Info\fR |
| 490 |
contains two comma separated values: the encryption algorithm name as |
| 491 |
used by \fBEVP_get_cipherbyname()\fR and an initialization vector used by the |
| 492 |
cipher encoded as a set of hexadecimal digits. After those two lines is |
| 493 |
the base64\-encoded encrypted data. |
| 494 |
.PP |
| 495 |
The encryption key is derived using \fBEVP_BytesToKey()\fR. The cipher's |
| 496 |
initialization vector is passed to \fBEVP_BytesToKey()\fR as the \fIsalt\fR |
| 497 |
parameter. Internally, \fBPKCS5_SALT_LEN\fR bytes of the salt are used |
| 498 |
(regardless of the size of the initialization vector). The user's |
| 499 |
password is passed to \fBEVP_BytesToKey()\fR using the \fIdata\fR and \fIdatal\fR |
| 500 |
parameters. Finally, the library uses an iteration count of 1 for |
| 501 |
\&\fBEVP_BytesToKey()\fR. |
| 502 |
.PP |
| 503 |
The \fIkey\fR derived by \fBEVP_BytesToKey()\fR along with the original initialization |
| 504 |
vector is then used to decrypt the encrypted data. The \fIiv\fR produced by |
| 505 |
\&\fBEVP_BytesToKey()\fR is not utilized or needed, and NULL should be passed to |
| 506 |
the function. |
| 507 |
.PP |
| 508 |
The pseudo code to derive the key would look similar to: |
| 509 |
.PP |
| 510 |
.Vb 2 |
| 511 |
\& EVP_CIPHER* cipher = EVP_des_ede3_cbc(); |
| 512 |
\& EVP_MD* md = EVP_md5(); |
| 513 |
\& |
| 514 |
\& unsigned int nkey = EVP_CIPHER_get_key_length(cipher); |
| 515 |
\& unsigned int niv = EVP_CIPHER_get_iv_length(cipher); |
| 516 |
\& unsigned char key[nkey]; |
| 517 |
\& unsigned char iv[niv]; |
| 518 |
\& |
| 519 |
\& memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); |
| 520 |
\& rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); |
| 521 |
\& if (rc != nkey) |
| 522 |
\& /* Error */ |
| 523 |
\& |
| 524 |
\& /* On success, use key and iv to initialize the cipher */ |
| 525 |
.Ve |
| 526 |
.SH BUGS |
| 527 |
.IX Header "BUGS" |
| 528 |
The PEM read routines in some versions of OpenSSL will not correctly reuse |
| 529 |
an existing structure. Therefore, the following: |
| 530 |
.PP |
| 531 |
.Vb 1 |
| 532 |
\& PEM_read_bio_X509(bp, &x, 0, NULL); |
| 533 |
.Ve |
| 534 |
.PP |
| 535 |
where \fIx\fR already contains a valid certificate, may not work, whereas: |
| 536 |
.PP |
| 537 |
.Vb 2 |
| 538 |
\& X509_free(x); |
| 539 |
\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); |
| 540 |
.Ve |
| 541 |
.PP |
| 542 |
is guaranteed to work. It is always acceptable for \fIx\fR to contain a newly |
| 543 |
allocated, empty \fBX509\fR object (for example allocated via \fBX509_new_ex\fR\|(3)). |
| 544 |
.SH "RETURN VALUES" |
| 545 |
.IX Header "RETURN VALUES" |
| 546 |
The read routines return either a pointer to the structure read or NULL |
| 547 |
if an error occurred. |
| 548 |
.PP |
| 549 |
The write routines return 1 for success or 0 for failure. |
| 550 |
.SH EXAMPLES |
| 551 |
.IX Header "EXAMPLES" |
| 552 |
Although the PEM routines take several arguments in almost all applications |
| 553 |
most of them are set to 0 or NULL. |
| 554 |
.PP |
| 555 |
To read a certificate with a library context in PEM format from a BIO: |
| 556 |
.PP |
| 557 |
.Vb 1 |
| 558 |
\& X509 *x = X509_new_ex(libctx, NULL); |
| 559 |
\& |
| 560 |
\& if (x == NULL) |
| 561 |
\& /* Error */ |
| 562 |
\& |
| 563 |
\& if (PEM_read_bio_X509(bp, &x, 0, NULL) == NULL) |
| 564 |
\& /* Error */ |
| 565 |
.Ve |
| 566 |
.PP |
| 567 |
Read a certificate in PEM format from a BIO: |
| 568 |
.PP |
| 569 |
.Vb 1 |
| 570 |
\& X509 *x; |
| 571 |
\& |
| 572 |
\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); |
| 573 |
\& if (x == NULL) |
| 574 |
\& /* Error */ |
| 575 |
.Ve |
| 576 |
.PP |
| 577 |
Alternative method: |
| 578 |
.PP |
| 579 |
.Vb 1 |
| 580 |
\& X509 *x = NULL; |
| 581 |
\& |
| 582 |
\& if (!PEM_read_bio_X509(bp, &x, 0, NULL)) |
| 583 |
\& /* Error */ |
| 584 |
.Ve |
| 585 |
.PP |
| 586 |
Write a certificate to a BIO: |
| 587 |
.PP |
| 588 |
.Vb 2 |
| 589 |
\& if (!PEM_write_bio_X509(bp, x)) |
| 590 |
\& /* Error */ |
| 591 |
.Ve |
| 592 |
.PP |
| 593 |
Write a private key (using traditional format) to a BIO using |
| 594 |
triple DES encryption, the pass phrase is prompted for: |
| 595 |
.PP |
| 596 |
.Vb 2 |
| 597 |
\& if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) |
| 598 |
\& /* Error */ |
| 599 |
.Ve |
| 600 |
.PP |
| 601 |
Write a private key (using PKCS#8 format) to a BIO using triple |
| 602 |
DES encryption, using the pass phrase "hello": |
| 603 |
.PP |
| 604 |
.Vb 3 |
| 605 |
\& if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), |
| 606 |
\& NULL, 0, 0, "hello")) |
| 607 |
\& /* Error */ |
| 608 |
.Ve |
| 609 |
.PP |
| 610 |
Read a private key from a BIO using a pass phrase callback: |
| 611 |
.PP |
| 612 |
.Vb 3 |
| 613 |
\& key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); |
| 614 |
\& if (key == NULL) |
| 615 |
\& /* Error */ |
| 616 |
.Ve |
| 617 |
.PP |
| 618 |
Skeleton pass phrase callback: |
| 619 |
.PP |
| 620 |
.Vb 2 |
| 621 |
\& int pass_cb(char *buf, int size, int rwflag, void *u) |
| 622 |
\& { |
| 623 |
\& |
| 624 |
\& /* We\*(Aqd probably do something else if \*(Aqrwflag\*(Aq is 1 */ |
| 625 |
\& printf("Enter pass phrase for \e"%s\e"\en", (char *)u); |
| 626 |
\& |
| 627 |
\& /* get pass phrase, length \*(Aqlen\*(Aq into \*(Aqtmp\*(Aq */ |
| 628 |
\& char *tmp = "hello"; |
| 629 |
\& if (tmp == NULL) /* An error occurred */ |
| 630 |
\& return \-1; |
| 631 |
\& |
| 632 |
\& size_t len = strlen(tmp); |
| 633 |
\& |
| 634 |
\& if (len > size) |
| 635 |
\& len = size; |
| 636 |
\& memcpy(buf, tmp, len); |
| 637 |
\& return len; |
| 638 |
\& } |
| 639 |
.Ve |
| 640 |
.SH "SEE ALSO" |
| 641 |
.IX Header "SEE ALSO" |
| 642 |
\&\fBEVP_EncryptInit\fR\|(3), \fBEVP_BytesToKey\fR\|(3), |
| 643 |
\&\fBpassphrase\-encoding\fR\|(7) |
| 644 |
.SH HISTORY |
| 645 |
.IX Header "HISTORY" |
| 646 |
The old Netscape certificate sequences were no longer documented |
| 647 |
in OpenSSL 1.1.0; applications should use the PKCS7 standard instead |
| 648 |
as they will be formally deprecated in a future releases. |
| 649 |
.PP |
| 650 |
\&\fBPEM_read_bio_PrivateKey_ex()\fR, \fBPEM_read_PrivateKey_ex()\fR, |
| 651 |
\&\fBPEM_read_bio_PUBKEY_ex()\fR, \fBPEM_read_PUBKEY_ex()\fR and |
| 652 |
\&\fBPEM_read_bio_Parameters_ex()\fR were introduced in OpenSSL 3.0. |
| 653 |
.PP |
| 654 |
The functions \fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_RSAPrivateKey()\fR, |
| 655 |
\&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_RSAPrivateKey()\fR, |
| 656 |
\&\fBPEM_read_bio_RSAPublicKey()\fR, \fBPEM_read_RSAPublicKey()\fR, |
| 657 |
\&\fBPEM_write_bio_RSAPublicKey()\fR, \fBPEM_write_RSAPublicKey()\fR, |
| 658 |
\&\fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_RSA_PUBKEY()\fR, |
| 659 |
\&\fBPEM_write_bio_RSA_PUBKEY()\fR, \fBPEM_write_RSA_PUBKEY()\fR, |
| 660 |
\&\fBPEM_read_bio_DSAPrivateKey()\fR, \fBPEM_read_DSAPrivateKey()\fR, |
| 661 |
\&\fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_DSAPrivateKey()\fR, |
| 662 |
\&\fBPEM_read_bio_DSA_PUBKEY()\fR, \fBPEM_read_DSA_PUBKEY()\fR, |
| 663 |
\&\fBPEM_write_bio_DSA_PUBKEY()\fR, \fBPEM_write_DSA_PUBKEY()\fR; |
| 664 |
\&\fBPEM_read_bio_DSAparams()\fR, \fBPEM_read_DSAparams()\fR, |
| 665 |
\&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_DSAparams()\fR, |
| 666 |
\&\fBPEM_read_bio_DHparams()\fR, \fBPEM_read_DHparams()\fR, |
| 667 |
\&\fBPEM_write_bio_DHparams()\fR and \fBPEM_write_DHparams()\fR were deprecated in 3.0. |
| 668 |
.PP |
| 669 |
\&\fBPEM_read_bio_X509_ACERT()\fR, \fBPEM_read_X509_ACERT()\fR, |
| 670 |
\&\fBPEM_write_bio_X509_ACERT()\fR, \fBPEM_write_X509_ACERT()\fR |
| 671 |
were added in OpenSSL 3.4. |
| 672 |
.SH COPYRIGHT |
| 673 |
.IX Header "COPYRIGHT" |
| 674 |
Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved. |
| 675 |
.PP |
| 676 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 677 |
this file except in compliance with the License. You can obtain a copy |
| 678 |
in the file LICENSE in the source distribution or at |
| 679 |
<https://www.openssl.org/source/license.html>. |