Coverage Report

Created: 2024-11-21 06:38

/src/BearSSL/inc/bearssl_pem.h
Line
Count
Source (jump to first uncovered line)
1
/*
2
 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3
 *
4
 * Permission is hereby granted, free of charge, to any person obtaining 
5
 * a copy of this software and associated documentation files (the
6
 * "Software"), to deal in the Software without restriction, including
7
 * without limitation the rights to use, copy, modify, merge, publish,
8
 * distribute, sublicense, and/or sell copies of the Software, and to
9
 * permit persons to whom the Software is furnished to do so, subject to
10
 * the following conditions:
11
 *
12
 * The above copyright notice and this permission notice shall be 
13
 * included in all copies or substantial portions of the Software.
14
 *
15
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
16
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
18
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
 * SOFTWARE.
23
 */
24
25
#ifndef BR_BEARSSL_PEM_H__
26
#define BR_BEARSSL_PEM_H__
27
28
#include <stddef.h>
29
#include <stdint.h>
30
31
#ifdef __cplusplus
32
extern "C" {
33
#endif
34
35
/** \file bearssl_pem.h
36
 *
37
 * # PEM Support
38
 *
39
 * PEM is a traditional encoding layer use to store binary objects (in
40
 * particular X.509 certificates, and private keys) in text files. While
41
 * the acronym comes from an old, defunct standard ("Privacy Enhanced
42
 * Mail"), the format has been reused, with some variations, by many
43
 * systems, and is a _de facto_ standard, even though it is not, actually,
44
 * specified in all clarity anywhere.
45
 *
46
 * ## Format Details
47
 *
48
 * BearSSL contains a generic, streamed PEM decoder, which handles the
49
 * following format:
50
 *
51
 *   - The input source (a sequence of bytes) is assumed to be the
52
 *     encoding of a text file in an ASCII-compatible charset. This
53
 *     includes ISO-8859-1, Windows-1252, and UTF-8 encodings. Each
54
 *     line ends on a newline character (U+000A LINE FEED). The
55
 *     U+000D CARRIAGE RETURN characters are ignored, so the code
56
 *     accepts both Windows-style and Unix-style line endings.
57
 *
58
 *   - Each object begins with a banner that occurs at the start of
59
 *     a line; the first banner characters are "`-----BEGIN `" (five
60
 *     dashes, the word "BEGIN", and a space). The banner matching is
61
 *     not case-sensitive.
62
 *
63
 *   - The _object name_ consists in the characters that follow the
64
 *     banner start sequence, up to the end of the line, but without
65
 *     trailing dashes (in "normal" PEM, there are five trailing
66
 *     dashes, but this implementation is not picky about these dashes).
67
 *     The BearSSL decoder normalises the name characters to uppercase
68
 *     (for ASCII letters only) and accepts names up to 127 characters.
69
 *
70
 *   - The object ends with a banner that again occurs at the start of
71
 *     a line, and starts with "`-----END `" (again case-insensitive).
72
 *
73
 *   - Between that start and end banner, only Base64 data shall occur.
74
 *     Base64 converts each sequence of three bytes into four
75
 *     characters; the four characters are ASCII letters, digits, "`+`"
76
 *     or "`-`" signs, and one or two "`=`" signs may occur in the last
77
 *     quartet. Whitespace is ignored (whitespace is any ASCII character
78
 *     of code 32 or less, so control characters are whitespace) and
79
 *     lines may have arbitrary length; the only restriction is that the
80
 *     four characters of a quartet must appear on the same line (no
81
 *     line break inside a quartet).
82
 *
83
 *   - A single file may contain more than one PEM object. Bytes that
84
 *     occur between objects are ignored.
85
 *
86
 *
87
 * ## PEM Decoder API
88
 *
89
 * The PEM decoder offers a state-machine API. The caller allocates a
90
 * decoder context, then injects source bytes. Source bytes are pushed
91
 * with `br_pem_decoder_push()`. The decoder stops accepting bytes when
92
 * it reaches an "event", which is either the start of an object, the
93
 * end of an object, or a decoding error within an object.
94
 *
95
 * The `br_pem_decoder_event()` function is used to obtain the current
96
 * event; it also clears it, thus allowing the decoder to accept more
97
 * bytes. When a object start event is raised, the decoder context
98
 * offers the found object name (normalised to ASCII uppercase).
99
 *
100
 * When an object is reached, the caller must set an appropriate callback
101
 * function, which will receive (by chunks) the decoded object data.
102
 *
103
 * Since the decoder context makes no dynamic allocation, it requires
104
 * no explicit deallocation.
105
 */
106
107
/**
108
 * \brief PEM decoder context.
109
 *
110
 * Contents are opaque (they should not be accessed directly).
111
 */
112
typedef struct {
113
#ifndef BR_DOXYGEN_IGNORE
114
  /* CPU for the T0 virtual machine. */
115
  struct {
116
    uint32_t *dp;
117
    uint32_t *rp;
118
    const unsigned char *ip;
119
  } cpu;
120
  uint32_t dp_stack[32];
121
  uint32_t rp_stack[32];
122
  int err;
123
124
  const unsigned char *hbuf;
125
  size_t hlen;
126
127
  void (*dest)(void *dest_ctx, const void *src, size_t len);
128
  void *dest_ctx;
129
130
  unsigned char event;
131
  char name[128];
132
  unsigned char buf[255];
133
  size_t ptr;
134
#endif
135
} br_pem_decoder_context;
136
137
/**
138
 * \brief Initialise a PEM decoder structure.
139
 *
140
 * \param ctx   decoder context to initialise.
141
 */
142
void br_pem_decoder_init(br_pem_decoder_context *ctx);
143
144
/**
145
 * \brief Push some bytes into the decoder.
146
 *
147
 * Returned value is the number of bytes actually consumed; this may be
148
 * less than the number of provided bytes if an event is raised. When an
149
 * event is raised, it must be read (with `br_pem_decoder_event()`);
150
 * until the event is read, this function will return 0.
151
 *
152
 * \param ctx    decoder context.
153
 * \param data   new data bytes.
154
 * \param len    number of new data bytes.
155
 * \return  the number of bytes actually received (may be less than `len`).
156
 */
157
size_t br_pem_decoder_push(br_pem_decoder_context *ctx,
158
  const void *data, size_t len);
159
160
/**
161
 * \brief Set the receiver for decoded data.
162
 *
163
 * When an object is entered, the provided function (with opaque context
164
 * pointer) will be called repeatedly with successive chunks of decoded
165
 * data for that object. If `dest` is set to 0, then decoded data is
166
 * simply ignored. The receiver can be set at any time, but, in practice,
167
 * it should be called immediately after receiving a "start of object"
168
 * event.
169
 *
170
 * \param ctx        decoder context.
171
 * \param dest       callback for receiving decoded data.
172
 * \param dest_ctx   opaque context pointer for the `dest` callback.
173
 */
174
static inline void
175
br_pem_decoder_setdest(br_pem_decoder_context *ctx,
176
  void (*dest)(void *dest_ctx, const void *src, size_t len),
177
  void *dest_ctx)
178
0
{
179
0
  ctx->dest = dest;
180
0
  ctx->dest_ctx = dest_ctx;
181
0
}
Unexecuted instantiation: module.cpp:br_pem_decoder_setdest(br_pem_decoder_context*, void (*)(void*, void const*, unsigned long), void*)
Unexecuted instantiation: poly1305_ctmul.c:br_pem_decoder_setdest
Unexecuted instantiation: chacha20_sse2.c:br_pem_decoder_setdest
Unexecuted instantiation: chacha20_ct.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_x86ni_ctrcbc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_x86ni.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_small_ctrcbc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct_ctrcbc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct_ctr.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct64_ctrcbc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct64.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_common.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_big_ctrcbc.c:br_pem_decoder_setdest
Unexecuted instantiation: prf_md5sha1.c:br_pem_decoder_setdest
Unexecuted instantiation: prf.c:br_pem_decoder_setdest
Unexecuted instantiation: sysrng.c:br_pem_decoder_setdest
Unexecuted instantiation: hmac_drbg.c:br_pem_decoder_setdest
Unexecuted instantiation: hmac.c:br_pem_decoder_setdest
Unexecuted instantiation: shake.c:br_pem_decoder_setdest
Unexecuted instantiation: hkdf.c:br_pem_decoder_setdest
Unexecuted instantiation: sha2small.c:br_pem_decoder_setdest
Unexecuted instantiation: sha2big.c:br_pem_decoder_setdest
Unexecuted instantiation: sha1.c:br_pem_decoder_setdest
Unexecuted instantiation: md5sha1.c:br_pem_decoder_setdest
Unexecuted instantiation: md5.c:br_pem_decoder_setdest
Unexecuted instantiation: ghash_ctmul32.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i31_vrfy_raw.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i31_sign_raw.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i31_bits.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i15_vrfy_raw.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i15_sign_raw.c:br_pem_decoder_setdest
Unexecuted instantiation: ecdsa_i15_bits.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_secp521r1.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_secp384r1.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_secp256r1.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_pubkey.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_prime_i31.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_prime_i15.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_p256_m64.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_p256_m62.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_p256_m31.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_p256_m15.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_keygen.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_default.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_m64.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_m62.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_m31.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_m15.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_i31.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_c25519_i15.c:br_pem_decoder_setdest
Unexecuted instantiation: ec_all_m31.c:br_pem_decoder_setdest
Unexecuted instantiation: enc64be.c:br_pem_decoder_setdest
Unexecuted instantiation: enc32le.c:br_pem_decoder_setdest
Unexecuted instantiation: enc32be.c:br_pem_decoder_setdest
Unexecuted instantiation: dec64be.c:br_pem_decoder_setdest
Unexecuted instantiation: dec32le.c:br_pem_decoder_setdest
Unexecuted instantiation: dec32be.c:br_pem_decoder_setdest
Unexecuted instantiation: ccopy.c:br_pem_decoder_setdest
Unexecuted instantiation: gcm.c:br_pem_decoder_setdest
Unexecuted instantiation: ccm.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_small_enc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct_enc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_ct64_enc.c:br_pem_decoder_setdest
Unexecuted instantiation: aes_big_enc.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_sub.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_rshift.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_ninv31.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_montmul.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_modpow.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_iszero.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_fmont.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_encode.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_decode.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_decmod.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_bitlen.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_add.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_sub.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_rshift.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_ninv15.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_montmul.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_modpow.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_iszero.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_fmont.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_encode.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_decode.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_decmod.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_bitlen.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_add.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_tmont.c:br_pem_decoder_setdest
Unexecuted instantiation: i31_muladd.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_tmont.c:br_pem_decoder_setdest
Unexecuted instantiation: i15_muladd.c:br_pem_decoder_setdest
Unexecuted instantiation: i32_div32.c:br_pem_decoder_setdest
182
183
/**
184
 * \brief Get the last event.
185
 *
186
 * If an event was raised, then this function returns the event value, and
187
 * also clears it, thereby allowing the decoder to proceed. If no event
188
 * was raised since the last call to `br_pem_decoder_event()`, then this
189
 * function returns 0.
190
 *
191
 * \param ctx   decoder context.
192
 * \return  the raised event, or 0.
193
 */
194
int br_pem_decoder_event(br_pem_decoder_context *ctx);
195
196
/**
197
 * \brief Event: start of object.
198
 *
199
 * This event is raised when the start of a new object has been detected.
200
 * The object name (normalised to uppercase) can be accessed with
201
 * `br_pem_decoder_name()`.
202
 */
203
#define BR_PEM_BEGIN_OBJ   1
204
205
/**
206
 * \brief Event: end of object.
207
 *
208
 * This event is raised when the end of the current object is reached
209
 * (normally, i.e. with no decoding error).
210
 */
211
#define BR_PEM_END_OBJ     2
212
213
/**
214
 * \brief Event: decoding error.
215
 *
216
 * This event is raised when decoding fails within an object.
217
 * This formally closes the current object and brings the decoder back
218
 * to the "out of any object" state. The offending line in the source
219
 * is consumed.
220
 */
221
#define BR_PEM_ERROR       3
222
223
/**
224
 * \brief Get the name of the encountered object.
225
 *
226
 * The encountered object name is defined only when the "start of object"
227
 * event is raised. That name is normalised to uppercase (for ASCII letters
228
 * only) and does not include trailing dashes.
229
 *
230
 * \param ctx   decoder context.
231
 * \return  the current object name.
232
 */
233
static inline const char *
234
br_pem_decoder_name(br_pem_decoder_context *ctx)
235
0
{
236
0
  return ctx->name;
237
0
}
Unexecuted instantiation: module.cpp:br_pem_decoder_name(br_pem_decoder_context*)
Unexecuted instantiation: poly1305_ctmul.c:br_pem_decoder_name
Unexecuted instantiation: chacha20_sse2.c:br_pem_decoder_name
Unexecuted instantiation: chacha20_ct.c:br_pem_decoder_name
Unexecuted instantiation: aes_x86ni_ctrcbc.c:br_pem_decoder_name
Unexecuted instantiation: aes_x86ni.c:br_pem_decoder_name
Unexecuted instantiation: aes_small_ctrcbc.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct_ctrcbc.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct_ctr.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct64_ctrcbc.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct64.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct.c:br_pem_decoder_name
Unexecuted instantiation: aes_common.c:br_pem_decoder_name
Unexecuted instantiation: aes_big_ctrcbc.c:br_pem_decoder_name
Unexecuted instantiation: prf_md5sha1.c:br_pem_decoder_name
Unexecuted instantiation: prf.c:br_pem_decoder_name
Unexecuted instantiation: sysrng.c:br_pem_decoder_name
Unexecuted instantiation: hmac_drbg.c:br_pem_decoder_name
Unexecuted instantiation: hmac.c:br_pem_decoder_name
Unexecuted instantiation: shake.c:br_pem_decoder_name
Unexecuted instantiation: hkdf.c:br_pem_decoder_name
Unexecuted instantiation: sha2small.c:br_pem_decoder_name
Unexecuted instantiation: sha2big.c:br_pem_decoder_name
Unexecuted instantiation: sha1.c:br_pem_decoder_name
Unexecuted instantiation: md5sha1.c:br_pem_decoder_name
Unexecuted instantiation: md5.c:br_pem_decoder_name
Unexecuted instantiation: ghash_ctmul32.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i31_vrfy_raw.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i31_sign_raw.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i31_bits.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i15_vrfy_raw.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i15_sign_raw.c:br_pem_decoder_name
Unexecuted instantiation: ecdsa_i15_bits.c:br_pem_decoder_name
Unexecuted instantiation: ec_secp521r1.c:br_pem_decoder_name
Unexecuted instantiation: ec_secp384r1.c:br_pem_decoder_name
Unexecuted instantiation: ec_secp256r1.c:br_pem_decoder_name
Unexecuted instantiation: ec_pubkey.c:br_pem_decoder_name
Unexecuted instantiation: ec_prime_i31.c:br_pem_decoder_name
Unexecuted instantiation: ec_prime_i15.c:br_pem_decoder_name
Unexecuted instantiation: ec_p256_m64.c:br_pem_decoder_name
Unexecuted instantiation: ec_p256_m62.c:br_pem_decoder_name
Unexecuted instantiation: ec_p256_m31.c:br_pem_decoder_name
Unexecuted instantiation: ec_p256_m15.c:br_pem_decoder_name
Unexecuted instantiation: ec_keygen.c:br_pem_decoder_name
Unexecuted instantiation: ec_default.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_m64.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_m62.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_m31.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_m15.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_i31.c:br_pem_decoder_name
Unexecuted instantiation: ec_c25519_i15.c:br_pem_decoder_name
Unexecuted instantiation: ec_all_m31.c:br_pem_decoder_name
Unexecuted instantiation: enc64be.c:br_pem_decoder_name
Unexecuted instantiation: enc32le.c:br_pem_decoder_name
Unexecuted instantiation: enc32be.c:br_pem_decoder_name
Unexecuted instantiation: dec64be.c:br_pem_decoder_name
Unexecuted instantiation: dec32le.c:br_pem_decoder_name
Unexecuted instantiation: dec32be.c:br_pem_decoder_name
Unexecuted instantiation: ccopy.c:br_pem_decoder_name
Unexecuted instantiation: gcm.c:br_pem_decoder_name
Unexecuted instantiation: ccm.c:br_pem_decoder_name
Unexecuted instantiation: aes_small_enc.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct_enc.c:br_pem_decoder_name
Unexecuted instantiation: aes_ct64_enc.c:br_pem_decoder_name
Unexecuted instantiation: aes_big_enc.c:br_pem_decoder_name
Unexecuted instantiation: i31_sub.c:br_pem_decoder_name
Unexecuted instantiation: i31_rshift.c:br_pem_decoder_name
Unexecuted instantiation: i31_ninv31.c:br_pem_decoder_name
Unexecuted instantiation: i31_montmul.c:br_pem_decoder_name
Unexecuted instantiation: i31_modpow.c:br_pem_decoder_name
Unexecuted instantiation: i31_iszero.c:br_pem_decoder_name
Unexecuted instantiation: i31_fmont.c:br_pem_decoder_name
Unexecuted instantiation: i31_encode.c:br_pem_decoder_name
Unexecuted instantiation: i31_decode.c:br_pem_decoder_name
Unexecuted instantiation: i31_decmod.c:br_pem_decoder_name
Unexecuted instantiation: i31_bitlen.c:br_pem_decoder_name
Unexecuted instantiation: i31_add.c:br_pem_decoder_name
Unexecuted instantiation: i15_sub.c:br_pem_decoder_name
Unexecuted instantiation: i15_rshift.c:br_pem_decoder_name
Unexecuted instantiation: i15_ninv15.c:br_pem_decoder_name
Unexecuted instantiation: i15_montmul.c:br_pem_decoder_name
Unexecuted instantiation: i15_modpow.c:br_pem_decoder_name
Unexecuted instantiation: i15_iszero.c:br_pem_decoder_name
Unexecuted instantiation: i15_fmont.c:br_pem_decoder_name
Unexecuted instantiation: i15_encode.c:br_pem_decoder_name
Unexecuted instantiation: i15_decode.c:br_pem_decoder_name
Unexecuted instantiation: i15_decmod.c:br_pem_decoder_name
Unexecuted instantiation: i15_bitlen.c:br_pem_decoder_name
Unexecuted instantiation: i15_add.c:br_pem_decoder_name
Unexecuted instantiation: i31_tmont.c:br_pem_decoder_name
Unexecuted instantiation: i31_muladd.c:br_pem_decoder_name
Unexecuted instantiation: i15_tmont.c:br_pem_decoder_name
Unexecuted instantiation: i15_muladd.c:br_pem_decoder_name
Unexecuted instantiation: i32_div32.c:br_pem_decoder_name
238
239
/**
240
 * \brief Encode an object in PEM.
241
 *
242
 * This function encodes the provided binary object (`data`, of length `len`
243
 * bytes) into PEM. The `banner` text will be included in the header and
244
 * footer (e.g. use `"CERTIFICATE"` to get a `"BEGIN CERTIFICATE"` header).
245
 *
246
 * The length (in characters) of the PEM output is returned; that length
247
 * does NOT include the terminating zero, that this function nevertheless
248
 * adds. If using the returned value for allocation purposes, the allocated
249
 * buffer size MUST be at least one byte larger than the returned size.
250
 *
251
 * If `dest` is `NULL`, then the encoding does not happen; however, the
252
 * length of the encoded object is still computed and returned.
253
 *
254
 * The `data` pointer may be `NULL` only if `len` is zero (when encoding
255
 * an object of length zero, which is not very useful), or when `dest`
256
 * is `NULL` (in that case, source data bytes are ignored).
257
 *
258
 * Some `flags` can be specified to alter the encoding behaviour:
259
 *
260
 *   - If `BR_PEM_LINE64` is set, then line-breaking will occur after
261
 *     every 64 characters of output, instead of the default of 76.
262
 *
263
 *   - If `BR_PEM_CRLF` is set, then end-of-line sequence will use
264
 *     CR+LF instead of a single LF.
265
 *
266
 * The `data` and `dest` buffers may overlap, in which case the source
267
 * binary data is destroyed in the process. Note that the PEM-encoded output
268
 * is always larger than the source binary.
269
 *
270
 * \param dest     the destination buffer (or `NULL`).
271
 * \param data     the source buffer (can be `NULL` in some cases).
272
 * \param len      the source length (in bytes).
273
 * \param banner   the PEM banner expression.
274
 * \param flags    the behavioural flags.
275
 * \return  the PEM object length (in characters), EXCLUDING the final zero.
276
 */
277
size_t br_pem_encode(void *dest, const void *data, size_t len,
278
  const char *banner, unsigned flags);
279
280
/**
281
 * \brief PEM encoding flag: split lines at 64 characters.
282
 */
283
#define BR_PEM_LINE64   0x0001
284
285
/**
286
 * \brief PEM encoding flag: use CR+LF line endings.
287
 */
288
#define BR_PEM_CRLF     0x0002
289
290
#ifdef __cplusplus
291
}
292
#endif
293
294
#endif