summaryrefslogtreecommitdiffstats
path: root/src/lib/base64.h
blob: ec6ac17ae189b8bdcc41a15c7e9eaeefca97b643 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
#ifndef BASE64_H
#define BASE64_H

/*
 * Common Base64
 */

/* max. buffer size required for base64_encode() */
#define MAX_BASE64_ENCODED_SIZE(size) \
	((((size) + 2) / 3) * 4)
/* max. buffer size required for base64_decode() */
#define MAX_BASE64_DECODED_SIZE(size) \
	(((size) + 3) / 4 * 3)

struct base64_scheme {
	const char encmap[64];
	const unsigned char decmap[256];
};

/*
 * Low-level Base64 encoder
 */

enum base64_encode_flags {
	/* Use CRLF instead of the default LF as line ending. */
	BASE64_ENCODE_FLAG_CRLF                 = BIT(0),
	/* Encode no padding at the end of the data. */
	BASE64_ENCODE_FLAG_NO_PADDING           = BIT(1),
};

struct base64_encoder {
	const struct base64_scheme *b64;
	enum base64_encode_flags flags;
	size_t max_line_len;

	/* state */
	unsigned int sub_pos;
	unsigned char buf;
	size_t cur_line_len;

	unsigned char w_buf[10];
	unsigned int w_buf_len;

	bool pending_lf:1;
	bool finishing:1;
	bool finished:1;
};

/* Returns TRUE when base64_encode_finish() was called on this encoder. */
static inline bool
base64_encode_is_finished(struct base64_encoder *enc)
{
	return enc->finished;
}

/* Initialize the Base64 encoder. The b64 parameter is the definition of the
   particular Base64 encoding scheme that is used.
 */
static inline void
base64_encode_init(struct base64_encoder *enc,
		   const struct base64_scheme *b64,
		   enum base64_encode_flags flags,
		   size_t max_line_len)
{
	i_zero(enc);
	enc->b64 = b64;
	enc->flags = flags;
	enc->max_line_len = (max_line_len == 0 ? SIZE_MAX : max_line_len);
}

/* Reset the Base64 encoder to its initial state. */
static inline void
base64_encode_reset(struct base64_encoder *enc)
{
	const struct base64_scheme *b64 = enc->b64;
	enum base64_encode_flags flags = enc->flags;
	size_t max_line_len = enc->max_line_len;

	base64_encode_init(enc, b64, flags, max_line_len);
}

/* Translate the size of the full encoder input to the size of the encoder
   output.
 */
uoff_t base64_get_full_encoded_size(struct base64_encoder *enc,
				    uoff_t src_size);
/* Translate the size of the next input to the size of the output once encoded.
   This yields the amount of data appended to the dest buffer by
   base64_encode_more() with the indicated src_size. */
size_t base64_encode_get_size(struct base64_encoder *enc, size_t src_size);

/* Translate the space in the destination buffer to the number of bytes that can
   be encoded at most to complete the full base64 encoding, including padding
   and newlines if configured. */
size_t base64_encode_get_full_space(struct base64_encoder *enc,
				    size_t dst_space);

/* Translates binary data into some form of Base64. The src must not point to
   dest buffer. Returns TRUE when all the provided data is encoded. Returns
   FALSE when the space in the provided buffer is insufficient. The return value
   may be ignored. If src_pos_r is non-NULL, it's updated to first
   non-translated character in src.
 */
bool ATTR_NOWARN_UNUSED_RESULT
base64_encode_more(struct base64_encoder *enc, const void *src, size_t src_size,
		   size_t *src_pos_r, buffer_t *dest) ATTR_NULL(4);

/* Finishes Base64 encoding. Returns TRUE when all the provided data is encoded.
   Returns FALSE when the space in the provided buffer is insufficient. The
   return value may be ignored.
 */
bool ATTR_NOWARN_UNUSED_RESULT
base64_encode_finish(struct base64_encoder *enc, buffer_t *dest) ATTR_NULL(2);

/*
 * Low-level Base64 decoder
 */

enum base64_decode_flags {
	/* Decode input until a boundary is reached. This boundary is a
	   non-Base64 input sequence that would normally trigger a decode error;
	   e.g., Base64 data followed by a ':'. With this flag, it is possible
	   to decode such a Base64 prefix. The base64_decode_finish() function
	   will still check that the Base64 data ends properly (padding). */
	BASE64_DECODE_FLAG_EXPECT_BOUNDARY = BIT(0),
	/* Prohibit whitespace in the input. */
	BASE64_DECODE_FLAG_NO_WHITESPACE   = BIT(1),
	/* Require absence of padding at the end of the input. */
	BASE64_DECODE_FLAG_NO_PADDING      = BIT(2),
	/* Ignore padding at the end of the input. This flag is ignored when
	   BASE64_DECODE_FLAG_NO_PADDING is also set. If both of these flags are
	   absent, padding is required (the default). */
	BASE64_DECODE_FLAG_IGNORE_PADDING  = BIT(3),
};

struct base64_decoder {
	const struct base64_scheme *b64;
	enum base64_decode_flags flags;

	/* state */
	unsigned int sub_pos;
	unsigned char buf;

	bool seen_padding:1;
	bool seen_end:1;
	bool seen_boundary:1;
	bool finished:1;
	bool failed:1;
};

/* Returns TRUE when base64_decode_finish() was called on this decoder. */
static inline bool
base64_decode_is_finished(struct base64_decoder *dec)
{
	return dec->finished;
}

/* Initialize the Base64 decoder. The b64 parameter is the definition of the
   particular Base64 encoding scheme that is expected.
 */
static inline void
base64_decode_init(struct base64_decoder *dec,
		   const struct base64_scheme *b64,
		   enum base64_decode_flags flags)
{
	i_zero(dec);
	dec->b64 = b64;
	dec->flags = flags;
}

/* Reset the Base64 decoder to its initial state. */
static inline void
base64_decode_reset(struct base64_decoder *dec)
{
	const struct base64_scheme *b64 = dec->b64;
	enum base64_decode_flags flags = dec->flags;

	base64_decode_init(dec, b64, flags);
}

/* Translates some form of Base64 data into binary and appends it to dest
   buffer. dest may point to same buffer as src. Returns 1 if all ok, 0 if end
   of base64 data found, -1 if data is invalid.

   By default, any CR, LF characters are ignored, as well as any whitespace.
   This can be overridden using the BASE64_DECODE_FLAG_NO_WHITESPACE flag.

   If src_pos is non-NULL, it's updated to first non-translated character in
   src.
 */
int base64_decode_more(struct base64_decoder *dec,
		       const void *src, size_t src_size, size_t *src_pos_r,
		       buffer_t *dest) ATTR_NULL(4);
/* Finishes Base64 decoding. This function checks whether the encoded data ends
   in the proper padding. Returns 0 if all ok, and -1 if data is invalid.
 */
int base64_decode_finish(struct base64_decoder *dec);

/*
 * Generic Base64 API
 */

/* Translates binary data into some variant of Base64. The src must not point to
   dest buffer.

   The b64 parameter is the definition of the particular Base 64 encoding scheme
   that is used. See below for specific functions.
 */
static inline void
base64_scheme_encode(const struct base64_scheme *b64,
		     enum base64_encode_flags flags, size_t max_line_len,
		     const void *src, size_t src_size, buffer_t *dest)
{
	struct base64_encoder enc;

	base64_encode_init(&enc, b64, flags, max_line_len);
	base64_encode_more(&enc, src, src_size, NULL, dest);
	base64_encode_finish(&enc, dest);
}

buffer_t *t_base64_scheme_encode(const struct base64_scheme *b64,
				 enum base64_encode_flags flags,
				 size_t max_line_len,
				 const void *src, size_t src_size);

static inline buffer_t *
t_base64_scheme_encode_str(const struct base64_scheme *b64,
			   enum base64_encode_flags flags, size_t max_line_len,
			   const char *src)
{
        return t_base64_scheme_encode(b64, flags, max_line_len,
				      src, strlen(src));
}

/* Translates some variant of Base64 data into binary and appends it to dest
   buffer. dest may point to same buffer as src. Returns 1 if all ok, 0 if end
   of Base64 data found, -1 if data is invalid.

   The b64 parameter is the definition of the particular Base 64 encoding scheme
   that is expected. See below for specific functions.

   Any CR, LF characters are ignored, as well as whitespace at beginning or
   end of line.
 */
int base64_scheme_decode(const struct base64_scheme *b64,
			 enum base64_decode_flags flags,
			 const void *src, size_t src_size, buffer_t *dest);

/* Decode given data to a buffer allocated from data stack.

   The b64 parameter is the definition of the particular Base 64 encoding scheme
   that is expected. See below for specific functions.
 */
buffer_t *t_base64_scheme_decode(const struct base64_scheme *b64,
				 enum base64_decode_flags flags,
				 const void *src, size_t src_size);
/* Decode given string to a buffer allocated from data stack.

   The b64 parameter is the definition of the particular Base 64 encoding scheme
   that is expected. See below for specific functions.
 */
static inline buffer_t *
t_base64_scheme_decode_str(const struct base64_scheme *b64,
			   enum base64_decode_flags flags, const char *str)
{
	return t_base64_scheme_decode(b64, flags, str, strlen(str));
}

/* Returns TRUE if c is a valid encoding character (excluding '=') for the
   provided base64 mapping table */
static inline bool
base64_scheme_is_valid_char(const struct base64_scheme *b64, char c)
{
	return b64->decmap[(uint8_t)c] != 0xff;
}

/*
 * "base64" encoding scheme (RFC 4648, Section 4)
 */

extern struct base64_scheme base64_scheme;

/* Translates binary data into base64. See base64_scheme_encode(). */
static inline void
base64_encode(const void *src, size_t src_size, buffer_t *dest)
{
	base64_scheme_encode(&base64_scheme, 0, 0, src, src_size, dest);
}

static inline buffer_t *
t_base64_encode(enum base64_encode_flags flags, size_t max_line_len,
		const void *src, size_t src_size)
{
	return t_base64_scheme_encode(&base64_scheme, flags, max_line_len,
				      src, src_size);
}

static inline buffer_t *
t_base64_encode_str(enum base64_encode_flags flags, size_t max_line_len,
		    const char *src)
{
        return t_base64_scheme_encode(&base64_scheme, flags, max_line_len,
				      src, strlen(src));
}

/* Translates base64 data into binary and appends it to dest buffer. See
   base64_scheme_decode().

   The src_pos_r parameter is deprecated and MUST be NULL.
 */
static inline int
base64_decode(const void *src, size_t src_size, size_t *src_pos_r ATTR_UNUSED,
	      buffer_t *dest) ATTR_NULL(3)
{
	// NOTE: src_pos_r is deprecated here; to be removed in v2.4 */
	i_assert(src_pos_r == NULL);

	return base64_scheme_decode(&base64_scheme, 0, src, src_size, dest);
}

/* Decode given data to a buffer allocated from data stack. */
static inline buffer_t *
t_base64_decode(enum base64_decode_flags flags,
		const void *src, size_t src_size)
{
	return t_base64_scheme_decode(&base64_scheme, flags, src, src_size);
}

/* Decode given string to a buffer allocated from data stack. */
static inline buffer_t *t_base64_decode_str(const char *str)
{
	return t_base64_scheme_decode_str(&base64_scheme, 0, str);
}

/* Returns TRUE if c is a valid base64 encoding character (excluding '=') */
static inline bool base64_is_valid_char(char c)
{
	return base64_scheme_is_valid_char(&base64_scheme, c);
}

/*
 * "base64url" encoding scheme (RFC 4648, Section 5)
 */

extern struct base64_scheme base64url_scheme;

/* Translates binary data into base64url. See base64_scheme_encode(). */
static inline void
base64url_encode(enum base64_encode_flags flags, size_t max_line_len,
		 const void *src, size_t src_size, buffer_t *dest)
{
	base64_scheme_encode(&base64url_scheme, flags, max_line_len,
			     src, src_size, dest);
}

static inline buffer_t *
t_base64url_encode(enum base64_encode_flags flags, size_t max_line_len,
		const void *src, size_t src_size)
{
	return t_base64_scheme_encode(&base64url_scheme, flags, max_line_len,
				      src, src_size);
}

static inline buffer_t *
t_base64url_encode_str(enum base64_encode_flags flags, size_t max_line_len,
		       const char *src)
{
        return t_base64_scheme_encode(&base64url_scheme, flags, max_line_len,
				      src, strlen(src));
}

/* Translates base64url data into binary and appends it to dest buffer. See
   base64_scheme_decode(). */
static inline int
base64url_decode(enum base64_decode_flags flags,
		 const void *src, size_t src_size, buffer_t *dest)
{
	return base64_scheme_decode(&base64url_scheme, flags,
				    src, src_size, dest);
}

/* Decode given data to a buffer allocated from data stack. */
static inline buffer_t *
t_base64url_decode(enum base64_decode_flags flags,
		   const void *src, size_t src_size)
{
	return t_base64_scheme_decode(&base64url_scheme, flags, src, src_size);
}

/* Decode given string to a buffer allocated from data stack. */
static inline buffer_t *
t_base64url_decode_str(enum base64_decode_flags flags, const char *str)
{
	return t_base64_scheme_decode_str(&base64url_scheme, flags, str);
}

/* Returns TRUE if c is a valid base64url encoding character (excluding '=') */
static inline bool base64url_is_valid_char(char c)
{
	return base64_scheme_is_valid_char(&base64url_scheme, c);
}

#endif