]>
Commit | Line | Data |
---|---|---|
204afd81 BK |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | PEM_read_bio_ex, PEM_FLAG_SECURE, PEM_FLAG_EAY_COMPATIBLE, | |
6 | PEM_FLAG_ONLY_B64 - read PEM format files with custom processing | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/pem.h> | |
11 | ||
12 | #define PEM_FLAG_SECURE 0x1 | |
13 | #define PEM_FLAG_EAY_COMPATIBLE 0x2 | |
14 | #define PEM_FLAG_ONLY_B64 0x4 | |
15 | int PEM_read_bio_ex(BIO *in, char **name, char **header, | |
16 | unsigned char **data, long *len, unsigned int flags); | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | PEM_read_bio_ex() reads in PEM formatted data from an input BIO, outputting | |
21 | the name of the type of contained data, the header information regarding | |
22 | the possibly encrypted data, and the binary data payload (after base64 decoding). | |
23 | It should generally only be used to implement PEM_read_bio_-family functions | |
24 | for specific data types or other usage, but is exposed to allow greater flexibility | |
25 | over how processing is performed, if needed. | |
26 | ||
27 | If PEM_FLAG_SECURE is set, the intermediate buffers used to read in lines of | |
28 | input are allocated from the secure heap. | |
29 | ||
30 | If PEM_FLAG_EAY_COMPATIBLE is set, a simple algorithm is used to remove whitespace | |
31 | and control characters from the end of each line, so as to be compatible with | |
32 | the historical behavior of PEM_read_bio(). | |
33 | ||
34 | If PEM_FLAG_ONLY_B64 is set, all characters are required to be valid base64 | |
35 | characters (or newlines); non-base64 characters are treated as end of input. | |
36 | ||
37 | If neither PEM_FLAG_EAY_COMPATIBLE or PEM_FLAG_ONLY_B64 is set, control characters | |
38 | are ignored. | |
39 | ||
40 | If both PEM_FLAG_EAY_COMPATIBLE and PEM_FLAG_ONLY_B64 are set, an error is returned; | |
41 | these options are not compatible with each other. | |
42 | ||
43 | =head1 NOTES | |
44 | ||
45 | The caller must release the storage allocated for *name, *header, and *data. | |
46 | If PEM_FLAG_SECURE was set, use OPENSSL_secure_free(); otherwise, | |
47 | OPENSSL_free() is used. | |
48 | ||
49 | =head1 RETURN VALUES | |
50 | ||
51 | PEM_read_bio_ex() returns 1 for success or 0 for failure. | |
52 | ||
53 | =head1 SEE ALSO | |
54 | ||
55 | L<PEM(3)> | |
56 | ||
57 | =head1 HISTORY | |
58 | ||
fc5ecadd | 59 | The PEM_read_bio_ex() function was added in OpenSSL 1.1.1. |
204afd81 BK |
60 | |
61 | =head1 COPYRIGHT | |
62 | ||
63 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
64 | ||
4746f25a | 65 | Licensed under the Apache License 2.0 (the "License"). You may not use |
204afd81 BK |
66 | this file except in compliance with the License. You can obtain a copy |
67 | in the file LICENSE in the source distribution or at | |
68 | L<https://www.openssl.org/source/license.html>. | |
69 | ||
70 | =cut |