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

   1 .\" Automatically generated by Pod::Man 4.14 (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_BYTES_READ_BIO 3"
 136 .TH PEM_BYTES_READ_BIO 3 "2020-09-22" "1.1.1h" "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_bytes_read_bio, PEM_bytes_read_bio_secmem \- read a PEM\-encoded data structure from a BIO
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/pem.h>
 147 \&
 148 \& int PEM_bytes_read_bio(unsigned char **pdata, long *plen, char **pnm,
 149 \&                        const char *name, BIO *bp, pem_password_cb *cb,
 150 \&                        void *u);
 151 \& int PEM_bytes_read_bio_secmem(unsigned char **pdata, long *plen, char **pnm,
 152 \&                               const char *name, BIO *bp, pem_password_cb *cb,
 153 \&                               void *u);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 \&\fBPEM_bytes_read_bio()\fR reads PEM-formatted (\s-1IETF RFC 1421\s0 and \s-1IETF RFC 7468\s0)
 158 data from the \s-1BIO\s0
 159 \&\fIbp\fR for the data type given in \fIname\fR (\s-1RSA PRIVATE KEY, CERTIFICATE,\s0
 160 etc.).  If multiple PEM-encoded data structures are present in the same
 161 stream, \fBPEM_bytes_read_bio()\fR will skip non-matching data types and
 162 continue reading.  Non-PEM data present in the stream may cause an
 163 error.
 164 .PP
 165 The \s-1PEM\s0 header may indicate that the following data is encrypted; if so,
 166 the data will be decrypted, waiting on user input to supply a passphrase
 167 if needed.  The password callback \fIcb\fR and rock \fIu\fR are used to obtain
 168 the decryption passphrase, if applicable.
 169 .PP
 170 Some data types have compatibility aliases, such as a file containing
 171 X509 \s-1CERTIFICATE\s0 matching a request for the deprecated type \s-1CERTIFICATE.\s0
 172 The actual type indicated by the file is returned in \fI*pnm\fR if \fIpnm\fR is
 173 non-NULL.  The caller must free the storage pointed to by \fI*pnm\fR.
 174 .PP
 175 The returned data is the DER-encoded form of the requested type, in
 176 \&\fI*pdata\fR with length \fI*plen\fR.  The caller must free the storage pointed
 177 to by \fI*pdata\fR.
 178 .PP
 179 \&\fBPEM_bytes_read_bio_secmem()\fR is similar to \fBPEM_bytes_read_bio()\fR, but uses
 180 memory from the secure heap for its temporary buffers and the storage
 181 returned in \fI*pdata\fR and \fI*pnm\fR.  Accordingly, the caller must use
 182 \&\fBOPENSSL_secure_free()\fR to free that storage.
 183 .SH "NOTES"
 184 .IX Header "NOTES"
 185 \&\fBPEM_bytes_read_bio_secmem()\fR only enforces that the secure heap is used for
 186 storage allocated within the \s-1PEM\s0 processing stack.  The \s-1BIO\s0 stack from
 187 which input is read may also use temporary buffers, which are not necessarily
 188 allocated from the secure heap.  In cases where it is desirable to ensure
 189 that the contents of the \s-1PEM\s0 file only appears in memory from the secure heap,
 190 care is needed in generating the \s-1BIO\s0 passed as \fIbp\fR.  In particular, the
 191 use of \fBBIO_s_file()\fR indicates the use of the operating system stdio
 192 functionality, which includes buffering as a feature; \fBBIO_s_fd()\fR is likely
 193 to be more appropriate in such cases.
 194 .PP
 195 These functions make no assumption regarding the pass phrase received from the
 196 password callback.
 197 It will simply be treated as a byte sequence.
 198 .SH "RETURN VALUES"
 199 .IX Header "RETURN VALUES"
 200 \&\fBPEM_bytes_read_bio()\fR and \fBPEM_bytes_read_bio_secmem()\fR return 1 for success or
 201 0 for failure.
 202 .SH "SEE ALSO"
 203 .IX Header "SEE ALSO"
 204 \&\fBPEM_read_bio_ex\fR\|(3),
 205 \&\fBpassphrase\-encoding\fR\|(7)
 206 .SH "HISTORY"
 207 .IX Header "HISTORY"
 208 \&\fBPEM_bytes_read_bio_secmem()\fR was introduced in OpenSSL 1.1.1
 209 .SH "COPYRIGHT"
 210 .IX Header "COPYRIGHT"
 211 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
 212 .PP
 213 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 214 this file except in compliance with the License.  You can obtain a copy
 215 in the file \s-1LICENSE\s0 in the source distribution or at
 216 <https://www.openssl.org/source/license.html>.