]>
Commit | Line | Data |
---|---|---|
7671342e BK |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | PEM_bytes_read_bio, PEM_bytes_read_bio_secmem - read a PEM-encoded data structure from a BIO | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/pem.h> | |
10 | ||
11 | int PEM_bytes_read_bio(unsigned char **pdata, long *plen, char **pnm, | |
12 | const char *name, BIO *bp, pem_password_cb *cb, | |
13 | void *u); | |
14 | int PEM_bytes_read_bio_secmem(unsigned char **pdata, long *plen, char **pnm, | |
15 | const char *name, BIO *bp, pem_password_cb *cb, | |
16 | void *u); | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | PEM_bytes_read_bio() reads PEM-formatted (RFC 1421) data from the BIO | |
21 | I<bp> for the data type given in I<name> (RSA PRIVATE KEY, CERTIFICATE, | |
22 | etc.). If multiple PEM-encoded data structures are present in the same | |
23 | stream, PEM_bytes_read_bio() will skip non-matching data types and | |
24 | continue reading. Non-PEM data present in the stream may cause an | |
25 | error. | |
26 | ||
27 | The PEM header may indicate that the following data is encrypted; if so, | |
28 | the data will be decrypted, waiting on user input to supply a passphrase | |
29 | if needed. The password callback I<cb> and rock I<u> are used to obtain | |
30 | the decryption passphrase, if applicable. | |
31 | ||
32 | Some data types have compatibility aliases, such as a file containing | |
33 | X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE. | |
34 | The actual type indicated by the file is returned in I<*pnm> if I<pnm> is | |
35 | non-NULL. The caller must free the storage pointed to by I<*pnm>. | |
36 | ||
37 | The returned data is the DER-encoded form of the requested type, in | |
38 | I<*pdata> with length I<*plen>. The caller must free the storage pointed | |
39 | to by I<*pdata>. | |
40 | ||
41 | PEM_bytes_read_bio_secmem() is similar to PEM_bytes_read_bio(), but uses | |
42 | memory from the secure heap for its temporary buffers and the storage | |
43 | returned in I<*pdata> and I<*pnm>. Accordingly, the caller must use | |
44 | OPENSSL_secure_free() to free that storage. | |
45 | ||
46 | =head1 NOTES | |
47 | ||
48 | PEM_bytes_read_bio_secmem() only enforces that the secure heap is used for | |
49 | storage allocated within the PEM processing stack. The BIO stack from | |
50 | which input is read may also use temporary buffers, which are not necessarily | |
51 | allocated from the secure heap. In cases where it is desirable to ensure | |
52 | that the contents of the PEM file only appears in memory from the secure heap, | |
53 | care is needed in generating the BIO passed as I<bp>. In particular, the | |
54 | use of BIO_s_file() indicates the use of the operating system stdio | |
55 | functionality, which includes buffering as a feature; BIO_s_fd() is likely | |
56 | to be more appropriate in such cases. | |
57 | ||
84814344 RL |
58 | These functions make no assumption regarding the pass phrase received from the |
59 | password callback. | |
60 | It will simply be treated as a byte sequence. | |
61 | ||
7671342e BK |
62 | =head1 RETURN VALUES |
63 | ||
64 | PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or | |
65 | 0 for failure. | |
66 | ||
67 | =head1 SEE ALSO | |
68 | ||
69 | L<PEM(3)>, | |
84814344 RL |
70 | L<PEM_read_bio_ex(3)>, |
71 | L<passphrase-encoding(7)> | |
7671342e BK |
72 | |
73 | =head1 HISTORY | |
74 | ||
75 | PEM_bytes_read_bio_secmem() was introduced in OpenSSL 1.1.1 | |
76 | ||
77 | =head1 COPYRIGHT | |
78 | ||
83cf7abf | 79 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. |
7671342e | 80 | |
4746f25a | 81 | Licensed under the Apache License 2.0 (the "License"). You may not use |
7671342e BK |
82 | this file except in compliance with the License. You can obtain a copy |
83 | in the file LICENSE in the source distribution or at | |
84 | L<https://www.openssl.org/source/license.html>. | |
85 | ||
86 | =cut |