secure/lib/libcrypto/man/man3/PEM_read.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "PEM_READ 3"
 136 .TH PEM_READ 3 "2020-04-21" "1.1.1g" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 PEM_write, PEM_write_bio, PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO \&\- PEM encoding routines
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/pem.h>
 147 \&
 148 \& int PEM_write(FILE *fp, const char *name, const char *header,
 149 \&               const unsigned char *data, long len)
 150 \& int PEM_write_bio(BIO *bp, const char *name, const char *header,
 151 \&                   const unsigned char *data, long len)
 152 \&
 153 \& int PEM_read(FILE *fp, char **name, char **header,
 154 \&              unsigned char **data, long *len);
 155 \& int PEM_read_bio(BIO *bp, char **name, char **header,
 156 \&                  unsigned char **data, long *len);
 157 \&
 158 \& int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);
 159 \& int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
 160 \&                   pem_password_cb *cb, void *u);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 These functions read and write PEM-encoded objects, using the \s-1PEM\s0
 165 type \fBname\fR, any additional \fBheader\fR information, and the raw
 166 \&\fBdata\fR of length \fBlen\fR.
 167 .PP
 168 \&\s-1PEM\s0 is the term used for binary content encoding first defined in \s-1IETF
 169 RFC 1421.\s0  The content is a series of base64\-encoded lines, surrounded
 170 by begin/end markers each on their own line.  For example:
 171 .PP
 172 .Vb 4
 173 \& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\-
 174 \& MIICdg....
 175 \& ... bhTQ==
 176 \& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\-
 177 .Ve
 178 .PP
 179 Optional header line(s) may appear after the begin line, and their
 180 existence depends on the type of object being written or read.
 181 .PP
 182 \&\fBPEM_write()\fR writes to the file \fBfp\fR, while \fBPEM_write_bio()\fR writes to
 183 the \s-1BIO\s0 \fBbp\fR.  The \fBname\fR is the name to use in the marker, the
 184 \&\fBheader\fR is the header value or \s-1NULL,\s0 and \fBdata\fR and \fBlen\fR specify
 185 the data and its length.
 186 .PP
 187 The final \fBdata\fR buffer is typically an \s-1ASN.1\s0 object which can be decoded with
 188 the \fBd2i\fR function appropriate to the type \fBname\fR; see \fBd2i_X509\fR\|(3)
 189 for examples.
 190 .PP
 191 \&\fBPEM_read()\fR reads from the file \fBfp\fR, while \fBPEM_read_bio()\fR reads
 192 from the \s-1BIO\s0 \fBbp\fR.
 193 Both skip any non-PEM data that precedes the start of the next \s-1PEM\s0 object.
 194 When an object is successfully retrieved, the type name from the \*(L"\-\-\-\-BEGIN
 195 <type>\-\-\-\-\-\*(R" is returned via the \fBname\fR argument, any encapsulation headers
 196 are returned in \fBheader\fR and the base64\-decoded content and its length are
 197 returned via \fBdata\fR and \fBlen\fR respectively.
 198 The \fBname\fR, \fBheader\fR and \fBdata\fR pointers are allocated via \fBOPENSSL_malloc()\fR
 199 and should be freed by the caller via \fBOPENSSL_free()\fR when no longer needed.
 200 .PP
 201 \&\fBPEM_get_EVP_CIPHER_INFO()\fR can be used to determine the \fBdata\fR returned by
 202 \&\fBPEM_read()\fR or \fBPEM_read_bio()\fR is encrypted and to retrieve the associated cipher
 203 and \s-1IV.\s0
 204 The caller passes a pointer to structure of type \fB\s-1EVP_CIPHER_INFO\s0\fR via the
 205 \&\fBcinfo\fR argument and the \fBheader\fR returned via \fBPEM_read()\fR or \fBPEM_read_bio()\fR.
 206 If the call is successful 1 is returned and the cipher and \s-1IV\s0 are stored at the
 207 address pointed to by \fBcinfo\fR.
 208 When the header is malformed, or not supported or when the cipher is unknown
 209 or some internal error happens 0 is returned.
 210 This function is deprecated, see \fB\s-1NOTES\s0\fR below.
 211 .PP
 212 \&\fBPEM_do_header()\fR can then be used to decrypt the data if the header
 213 indicates encryption.
 214 The \fBcinfo\fR argument is a pointer to the structure initialized by the previous
 215 call to \fBPEM_get_EVP_CIPHER_INFO()\fR.
 216 The \fBdata\fR and \fBlen\fR arguments are those returned by the previous call to
 217 \&\fBPEM_read()\fR or \fBPEM_read_bio()\fR.
 218 The \fBcb\fR and \fBu\fR arguments make it possible to override the default password
 219 prompt function as described in \fBPEM_read_PrivateKey\fR\|(3).
 220 On successful completion the \fBdata\fR is decrypted in place, and \fBlen\fR is
 221 updated to indicate the plaintext length.
 222 This function is deprecated, see \fB\s-1NOTES\s0\fR below.
 223 .PP
 224 If the data is a priori known to not be encrypted, then neither \fBPEM_do_header()\fR
 225 nor \fBPEM_get_EVP_CIPHER_INFO()\fR need be called.
 226 .SH "RETURN VALUES"
 227 .IX Header "RETURN VALUES"
 228 \&\fBPEM_read()\fR and \fBPEM_read_bio()\fR return 1 on success and 0 on failure, the latter
 229 includes the case when no more \s-1PEM\s0 objects remain in the input file.
 230 To distinguish end of file from more serious errors the caller must peek at the
 231 error stack and check for \fB\s-1PEM_R_NO_START_LINE\s0\fR, which indicates that no more
 232 \&\s-1PEM\s0 objects were found.  See \fBERR_peek_last_error\fR\|(3), \s-1\fBERR_GET_REASON\s0\fR\|(3).
 233 .PP
 234 \&\fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR return 1 on success, and 0 on
 235 failure.
 236 The \fBdata\fR is likely meaningless if these functions fail.
 237 .SH "NOTES"
 238 .IX Header "NOTES"
 239 The \fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR functions are deprecated.
 240 This is because the underlying \s-1PEM\s0 encryption format is obsolete, and should
 241 be avoided.
 242 It uses an encryption format with an OpenSSL-specific key-derivation function,
 243 which employs \s-1MD5\s0 with an iteration count of 1!
 244 Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5
 245 v2.0 \s-1PBE.\s0
 246 See \fBPEM_write_PrivateKey\fR\|(3) and \fBd2i_PKCS8PrivateKey_bio\fR\|(3).
 247 .PP
 248 \&\fBPEM_do_header()\fR makes no assumption regarding the pass phrase received from the
 249 password callback.
 250 It will simply be treated as a byte sequence.
 251 .SH "SEE ALSO"
 252 .IX Header "SEE ALSO"
 253 \&\fBERR_peek_last_error\fR\|(3), \s-1\fBERR_GET_LIB\s0\fR\|(3),
 254 \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3),
 255 \&\fBpassphrase\-encoding\fR\|(7)
 256 .SH "COPYRIGHT"
 257 .IX Header "COPYRIGHT"
 258 Copyright 1998\-2018 The OpenSSL Project Authors. All Rights Reserved.
 259 .PP
 260 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 261 this file except in compliance with the License.  You can obtain a copy
 262 in the file \s-1LICENSE\s0 in the source distribution or at
 263 <https://www.openssl.org/source/license.html>.