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