secure/lib/libcrypto/man/PEM_read.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "PEM_READ 3"
 132 .TH PEM_READ 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 PEM_write, PEM_write_bio, PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO \&\- PEM encoding routines
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/pem.h>
 143 \&
 144 \& int PEM_write(FILE *fp, const char *name, const char *header,
 145 \&               const unsigned char *data, long len)
 146 \& int PEM_write_bio(BIO *bp, const char *name, const char *header,
 147 \&                   const unsigned char *data, long len)
 148 \&
 149 \& int PEM_read(FILE *fp, char **name, char **header,
 150 \&              unsigned char **data, long *len);
 151 \& int PEM_read_bio(BIO *bp, char **name, char **header,
 152 \&                  unsigned char **data, long *len);
 153 \&
 154 \& int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);
 155 \& int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
 156 \&                   pem_password_cb *cb, void *u);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 These functions read and write PEM-encoded objects, using the \s-1PEM\s0
 161 type \fBname\fR, any additional \fBheader\fR information, and the raw
 162 \&\fBdata\fR of length \fBlen\fR.
 163 .PP
 164 \&\s-1PEM\s0 is the term used for binary content encoding first defined in \s-1IETF
 165 RFC 1421.\s0  The content is a series of base64\-encoded lines, surrounded
 166 by begin/end markers each on their own line.  For example:
 167 .PP
 168 .Vb 4
 169 \& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\-
 170 \& MIICdg....
 171 \& ... bhTQ==
 172 \& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\-
 173 .Ve
 174 .PP
 175 Optional header line(s) may appear after the begin line, and their
 176 existence depends on the type of object being written or read.
 177 .PP
 178 \&\fIPEM_write()\fR writes to the file \fBfp\fR, while \fIPEM_write_bio()\fR writes to
 179 the \s-1BIO\s0 \fBbp\fR.  The \fBname\fR is the name to use in the marker, the
 180 \&\fBheader\fR is the header value or \s-1NULL,\s0 and \fBdata\fR and \fBlen\fR specify
 181 the data and its length.
 182 .PP
 183 The final \fBdata\fR buffer is typically an \s-1ASN.1\s0 object which can be decoded with
 184 the \fBd2i\fR function appropriate to the type \fBname\fR; see \fId2i_X509\fR\|(3)
 185 for examples.
 186 .PP
 187 \&\fIPEM_read()\fR reads from the file \fBfp\fR, while \fIPEM_read_bio()\fR reads
 188 from the \s-1BIO\s0 \fBbp\fR.
 189 Both skip any non-PEM data that precedes the start of the next \s-1PEM\s0 object.
 190 When an object is successfully retrieved, the type name from the \*(L"\-\-\-\-BEGIN
 191 <type>\-\-\-\-\-\*(R" is returned via the \fBname\fR argument, any encapsulation headers
 192 are returned in \fBheader\fR and the base64\-decoded content and its length are
 193 returned via \fBdata\fR and \fBlen\fR respectively.
 194 The \fBname\fR, \fBheader\fR and \fBdata\fR pointers are allocated via \fIOPENSSL_malloc()\fR
 195 and should be freed by the caller via \fIOPENSSL_free()\fR when no longer needed.
 196 .PP
 197 \&\fIPEM_get_EVP_CIPHER_INFO()\fR can be used to determine the \fBdata\fR returned by
 198 \&\fIPEM_read()\fR or \fIPEM_read_bio()\fR is encrypted and to retrieve the associated cipher
 199 and \s-1IV.\s0
 200 The caller passes a pointer to structure of type \fB\s-1EVP_CIPHER_INFO\s0\fR via the
 201 \&\fBcinfo\fR argument and the \fBheader\fR returned via \fIPEM_read()\fR or \fIPEM_read_bio()\fR.
 202 If the call is successful 1 is returned and the cipher and \s-1IV\s0 are stored at the
 203 address pointed to by \fBcinfo\fR.
 204 When the header is malformed, or not supported or when the cipher is unknown
 205 or some internal error happens 0 is returned.
 206 This function is deprecated, see \fB\s-1NOTES\s0\fR below.
 207 .PP
 208 \&\fIPEM_do_header()\fR can then be used to decrypt the data if the header
 209 indicates encryption.
 210 The \fBcinfo\fR argument is a pointer to the structure initialized by the previous
 211 call to \fIPEM_get_EVP_CIPHER_INFO()\fR.
 212 The \fBdata\fR and \fBlen\fR arguments are those returned by the previous call to
 213 \&\fIPEM_read()\fR or \fIPEM_read_bio()\fR.
 214 The \fBcb\fR and \fBu\fR arguments make it possible to override the default password
 215 prompt function as described in \fIPEM_read_PrivateKey\fR\|(3).
 216 On successful completion the \fBdata\fR is decrypted in place, and \fBlen\fR is
 217 updated to indicate the plaintext length.
 218 This function is deprecated, see \fB\s-1NOTES\s0\fR below.
 219 .PP
 220 If the data is a priori known to not be encrypted, then neither \fIPEM_do_header()\fR
 221 nor \fIPEM_get_EVP_CIPHER_INFO()\fR need be called.
 222 .SH "RETURN VALUES"
 223 .IX Header "RETURN VALUES"
 224 \&\fIPEM_read()\fR and \fIPEM_read_bio()\fR return 1 on success and 0 on failure, the latter
 225 includes the case when no more \s-1PEM\s0 objects remain in the input file.
 226 To distinguish end of file from more serious errors the caller must peek at the
 227 error stack and check for \fB\s-1PEM_R_NO_START_LINE\s0\fR, which indicates that no more
 228 \&\s-1PEM\s0 objects were found.  See \fIERR_peek_last_error\fR\|(3), \s-1\fIERR_GET_REASON\s0\fR\|(3).
 229 .PP
 230 \&\fIPEM_get_EVP_CIPHER_INFO()\fR and \fIPEM_do_header()\fR return 1 on success, and 0 on
 231 failure.
 232 The \fBdata\fR is likely meaningless if these functions fail.
 233 .SH "NOTES"
 234 .IX Header "NOTES"
 235 The \fIPEM_get_EVP_CIPHER_INFO()\fR and \fIPEM_do_header()\fR functions are deprecated.
 236 This is because the underlying \s-1PEM\s0 encryption format is obsolete, and should
 237 be avoided.
 238 It uses an encryption format with an OpenSSL-specific key-derivation function,
 239 which employs \s-1MD5\s0 with an iteration count of 1!
 240 Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5
 241 v2.0 \s-1PBE.\s0
 242 See \fIPEM_write_PrivateKey\fR\|(3) and \fId2i_PKCS8PrivateKey_bio\fR\|(3).
 243 .PP
 244 \&\fIPEM_do_header()\fR makes no assumption regarding the pass phrase received from the
 245 password callback.
 246 It will simply be treated as a byte sequence.
 247 .SH "SEE ALSO"
 248 .IX Header "SEE ALSO"
 249 \&\fIERR_peek_last_error\fR\|(3), \s-1\fIERR_GET_LIB\s0\fR\|(3),
 250 \&\fId2i_PKCS8PrivateKey_bio\fR\|(3),
 251 \&\fIpassphrase\-encoding\fR\|(7)
 252 .SH "COPYRIGHT"
 253 .IX Header "COPYRIGHT"
 254 Copyright 1998\-2018 The OpenSSL Project Authors. All Rights Reserved.
 255 .PP
 256 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 257 this file except in compliance with the License.  You can obtain a copy
 258 in the file \s-1LICENSE\s0 in the source distribution or at
 259 <https://www.openssl.org/source/license.html>.