1 /* gbase64.c - Base64 encoding/decoding
3 * Copyright (C) 2006 Alexander Larsson <alexl@redhat.com>
4 * Copyright (C) 2000-2003 Ximian Inc.
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * This is based on code in camel, written by:
20 * Michael Zucchi <notzed@ximian.com>
21 * Jeffrey Stedfast <fejj@ximian.com>
29 #include "gtestutils.h"
35 * @title: Base64 Encoding
36 * @short_description: encodes and decodes data in Base64 format
38 * Base64 is an encoding that allows a sequence of arbitrary bytes to be
39 * encoded as a sequence of printable ASCII characters. For the definition
41 * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
43 * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
44 * Base64 is most commonly used as a MIME transfer encoding
47 * GLib supports incremental encoding using g_base64_encode_step() and
48 * g_base64_encode_close(). Incremental decoding can be done with
49 * g_base64_decode_step(). To encode or decode data in one go, use
50 * g_base64_encode() or g_base64_decode(). To avoid memory allocation when
51 * decoding, you can use g_base64_decode_inplace().
53 * Support for Base64 encoding has been added in GLib 2.12.
56 static const char base64_alphabet[] =
57 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
60 * g_base64_encode_step:
61 * @in: (array length=len) (element-type guint8): the binary data to encode
62 * @len: the length of @in
63 * @break_lines: whether to break long lines
64 * @out: (out) (array) (element-type guint8): pointer to destination buffer
65 * @state: (inout): Saved state between steps, initialize to 0
66 * @save: (inout): Saved state between steps, initialize to 0
68 * Incrementally encode a sequence of binary data into its Base-64 stringified
69 * representation. By calling this function multiple times you can convert
70 * data in chunks to avoid having to have the full encoded data in memory.
72 * When all of the data has been converted you must call
73 * g_base64_encode_close() to flush the saved state.
75 * The output buffer must be large enough to fit all the data that will
76 * be written to it. Due to the way base64 encodes you will need
77 * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
78 * non-zero state). If you enable line-breaking you will need at least:
79 * ((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space.
81 * @break_lines is typically used when putting base64-encoded data in emails.
82 * It breaks the lines at 72 columns instead of putting all of the text on
83 * the same line. This avoids problems with long lines in the email system.
84 * Note however that it breaks the lines with `LF` characters, not
85 * `CR LF` sequences, so the result cannot be passed directly to SMTP
86 * or certain other protocols.
88 * Returns: The number of bytes of output that was written
93 g_base64_encode_step (const guchar *in,
103 g_return_val_if_fail (in != NULL || len == 0, 0);
104 g_return_val_if_fail (out != NULL, 0);
105 g_return_val_if_fail (state != NULL, 0);
106 g_return_val_if_fail (save != NULL, 0);
114 if (len + ((char *) save) [0] > 2)
116 const guchar *inend = in+len-2;
122 switch (((char *) save) [0])
125 c1 = ((unsigned char *) save) [1];
128 c1 = ((unsigned char *) save) [1];
129 c2 = ((unsigned char *) save) [2];
134 * yes, we jump into the loop, no i'm not going to change it,
137 while (inptr < inend)
144 *outptr++ = base64_alphabet [ c1 >> 2 ];
145 *outptr++ = base64_alphabet [ c2 >> 4 |
147 *outptr++ = base64_alphabet [ ((c2 &0x0f) << 2) |
149 *outptr++ = base64_alphabet [ c3 & 0x3f ];
150 /* this is a bit ugly ... */
151 if (break_lines && (++already) >= 19)
158 ((char *)save)[0] = 0;
159 len = 2 - (inptr - inend);
163 g_assert (len == 0 || len == 1 || len == 2);
168 /* points to the slot for the next char to save */
169 saveout = & (((char *)save)[1]) + ((char *)save)[0];
171 /* len can only be 0 1 or 2 */
175 *saveout++ = *inptr++;
178 *saveout++ = *inptr++;
180 ((char *)save)[0] += len;
187 * g_base64_encode_close:
188 * @break_lines: whether to break long lines
189 * @out: (out) (array) (element-type guint8): pointer to destination buffer
190 * @state: (inout): Saved state from g_base64_encode_step()
191 * @save: (inout): Saved state from g_base64_encode_step()
193 * Flush the status from a sequence of calls to g_base64_encode_step().
195 * The output buffer must be large enough to fit all the data that will
196 * be written to it. It will need up to 4 bytes, or up to 5 bytes if
197 * line-breaking is enabled.
199 * The @out array will not be automatically nul-terminated.
201 * Returns: The number of bytes of output that was written
206 g_base64_encode_close (gboolean break_lines,
214 g_return_val_if_fail (out != NULL, 0);
215 g_return_val_if_fail (state != NULL, 0);
216 g_return_val_if_fail (save != NULL, 0);
218 c1 = ((unsigned char *) save) [1];
219 c2 = ((unsigned char *) save) [2];
221 switch (((char *) save) [0])
224 outptr [2] = base64_alphabet[ ( (c2 &0x0f) << 2 ) ];
225 g_assert (outptr [2] != 0);
229 c2 = 0; /* saved state here is not relevant */
231 outptr [0] = base64_alphabet [ c1 >> 2 ];
232 outptr [1] = base64_alphabet [ c2 >> 4 | ( (c1&0x3) << 4 )];
248 * @data: (array length=len) (element-type guint8) (nullable): the binary data to encode
249 * @len: the length of @data
251 * Encode a sequence of binary data into its Base-64 stringified
254 * Returns: (transfer full): a newly allocated, zero-terminated Base-64
255 * encoded string representing @data. The returned string must
256 * be freed with g_free().
261 g_base64_encode (const guchar *data,
265 gint state = 0, outlen;
268 g_return_val_if_fail (data != NULL || len == 0, NULL);
270 /* We can use a smaller limit here, since we know the saved state is 0,
271 +1 is needed for trailing \0, also check for unlikely integer overflow */
272 g_return_val_if_fail (len < ((G_MAXSIZE - 1) / 4 - 1) * 3, NULL);
274 out = g_malloc ((len / 3 + 1) * 4 + 1);
276 outlen = g_base64_encode_step (data, len, FALSE, out, &state, &save);
277 outlen += g_base64_encode_close (FALSE, out + outlen, &state, &save);
280 return (gchar *) out;
283 static const unsigned char mime_base64_rank[256] = {
284 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
285 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
286 255,255,255,255,255,255,255,255,255,255,255, 62,255,255,255, 63,
287 52, 53, 54, 55, 56, 57, 58, 59, 60, 61,255,255,255, 0,255,255,
288 255, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
289 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,255,255,255,255,255,
290 255, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
291 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51,255,255,255,255,255,
292 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
293 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
294 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
295 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
296 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
297 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
298 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
299 255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
303 * g_base64_decode_step: (skip)
304 * @in: (array length=len) (element-type guint8): binary input data
305 * @len: max length of @in data to decode
306 * @out: (out caller-allocates) (array) (element-type guint8): output buffer
307 * @state: (inout): Saved state between steps, initialize to 0
308 * @save: (inout): Saved state between steps, initialize to 0
310 * Incrementally decode a sequence of binary data from its Base-64 stringified
311 * representation. By calling this function multiple times you can convert
312 * data in chunks to avoid having to have the full encoded data in memory.
314 * The output buffer must be large enough to fit all the data that will
315 * be written to it. Since base64 encodes 3 bytes in 4 chars you need
316 * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
319 * Returns: The number of bytes of output that was written
324 g_base64_decode_step (const gchar *in,
338 g_return_val_if_fail (in != NULL || len == 0, 0);
339 g_return_val_if_fail (out != NULL, 0);
340 g_return_val_if_fail (state != NULL, 0);
341 g_return_val_if_fail (save != NULL, 0);
346 inend = (const guchar *)in+len;
349 /* convert 4 base64 bytes to 3 normal bytes */
353 last[0] = last[1] = 0;
355 /* we use the sign in the state to determine if we got a padding character
356 in the previous sequence */
363 inptr = (const guchar *)in;
364 while (inptr < inend)
367 rank = mime_base64_rank [c];
387 *state = last[0] == '=' ? -i : i;
394 * @text: (not nullable): zero-terminated string with base64 text to decode
395 * @out_len: (out): The length of the decoded data is written here
397 * Decode a sequence of Base-64 encoded text into binary data. Note
398 * that the returned binary data is not necessarily zero-terminated,
399 * so it should not be used as a character string.
401 * Returns: (transfer full) (array length=out_len) (element-type guint8):
402 * newly allocated buffer containing the binary data
403 * that @text represents. The returned buffer must
404 * be freed with g_free().
409 g_base64_decode (const gchar *text,
417 g_return_val_if_fail (text != NULL, NULL);
418 g_return_val_if_fail (out_len != NULL, NULL);
420 input_length = strlen (text);
422 /* We can use a smaller limit here, since we know the saved state is 0,
423 +1 used to avoid calling g_malloc0(0), and hence returning NULL */
424 ret = g_malloc0 ((input_length / 4) * 3 + 1);
426 *out_len = g_base64_decode_step (text, input_length, ret, &state, &save);
432 * g_base64_decode_inplace:
433 * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated
434 * string with base64 text to decode
435 * @out_len: (inout): The length of the decoded data is written here
437 * Decode a sequence of Base-64 encoded text into binary data
438 * by overwriting the input data.
440 * Returns: (transfer none): The binary data that @text responds. This pointer
441 * is the same as the input @text.
446 g_base64_decode_inplace (gchar *text,
449 gint input_length, state = 0;
452 g_return_val_if_fail (text != NULL, NULL);
453 g_return_val_if_fail (out_len != NULL, NULL);
455 input_length = strlen (text);
457 g_return_val_if_fail (input_length > 1, NULL);
459 *out_len = g_base64_decode_step (text, input_length, (guchar *) text, &state, &save);
461 return (guchar *) text;