| blob | 7d8b20deec67707b926139aa3156f43f13c3e18e |
1 /* gbase64.c - Base64 encoding/decoding
2 *
3 * Copyright (C) 2006 Alexander Larsson <alexl@redhat.com>
4 * Copyright (C) 2000-2003 Ximian Inc.
5 *
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.
10 *
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.
15 *
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/>.
18 *
19 * This is based on code in camel, written by:
20 * Michael Zucchi <notzed@ximian.com>
21 * Jeffrey Stedfast <fejj@ximian.com>
22 */
26 #include <string.h>
33 /**
34 * SECTION:base64
35 * @title: Base64 Encoding
36 * @short_description: encodes and decodes data in Base64 format
37 *
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
40 * of Base64, see
41 * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
42 * or
43 * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
44 * Base64 is most commonly used as a MIME transfer encoding
45 * for email.
46 *
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().
52 *
53 * Support for Base64 encoding has been added in GLib 2.12.
54 */
59 /**
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
67 *
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.
71 *
72 * When all of the data has been converted you must call
73 * g_base64_encode_close() to flush the saved state.
74 *
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.
80 *
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.
87 *
88 * Returns: The number of bytes of output that was written
89 *
90 * Since: 2.12
91 */
92 gsize
94 gsize len,
95 gboolean break_lines,
99 {
115 {
123 {
131 }
133 /*
134 * yes, we jump into the loop, no i'm not going to change it,
135 * it's beautiful!
136 */
138 {
140 skip1:
142 skip2:
150 /* this is a bit ugly ... */
152 {
155 }
156 }
161 }
164 {
167 /* points to the slot for the next char to save */
170 /* len can only be 0 1 or 2 */
172 {
175 }
177 }
180 }
182 /**
183 * g_base64_encode_close:
184 * @break_lines: whether to break long lines
185 * @out: (out) (array) (element-type guint8): pointer to destination buffer
186 * @state: (inout): Saved state from g_base64_encode_step()
187 * @save: (inout): Saved state from g_base64_encode_step()
188 *
189 * Flush the status from a sequence of calls to g_base64_encode_step().
190 *
191 * The output buffer must be large enough to fit all the data that will
192 * be written to it. It will need up to 4 bytes, or up to 5 bytes if
193 * line-breaking is enabled.
194 *
195 * The @out array will not be automatically nul-terminated.
196 *
197 * Returns: The number of bytes of output that was written
198 *
199 * Since: 2.12
200 */
201 gsize
206 {
218 {
226 skip:
232 }
240 }
242 /**
243 * g_base64_encode:
244 * @data: (array length=len) (element-type guint8): the binary data to encode
245 * @len: the length of @data
246 *
247 * Encode a sequence of binary data into its Base-64 stringified
248 * representation.
249 *
250 * Returns: (transfer full): a newly allocated, zero-terminated Base-64
251 * encoded string representing @data. The returned string must
252 * be freed with g_free().
253 *
254 * Since: 2.12
255 */
256 gchar *
258 gsize len)
259 {
266 /* We can use a smaller limit here, since we know the saved state is 0,
267 +1 is needed for trailing \0, also check for unlikely integer overflow */
279 }
298 };
300 /**
301 * g_base64_decode_step: (skip)
302 * @in: (array length=len) (element-type guint8): binary input data
303 * @len: max length of @in data to decode
304 * @out: (out caller-allocates) (array) (element-type guint8): output buffer
305 * @state: (inout): Saved state between steps, initialize to 0
306 * @save: (inout): Saved state between steps, initialize to 0
307 *
308 * Incrementally decode a sequence of binary data from its Base-64 stringified
309 * representation. By calling this function multiple times you can convert
310 * data in chunks to avoid having to have the full encoded data in memory.
311 *
312 * The output buffer must be large enough to fit all the data that will
313 * be written to it. Since base64 encodes 3 bytes in 4 chars you need
314 * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
315 * state).
316 *
317 * Returns: The number of bytes of output that was written
318 *
319 * Since: 2.12
320 **/
321 gsize
323 gsize len,
327 {
347 /* convert 4 base64 bytes to 3 normal bytes */
353 /* we use the sign in the state to determine if we got a padding character
354 in the previous sequence */
356 {
359 }
363 {
367 {
371 i++;
373 {
380 }
381 }
382 }
388 }
390 /**
391 * g_base64_decode:
392 * @text: zero-terminated string with base64 text to decode
393 * @out_len: (out): The length of the decoded data is written here
394 *
395 * Decode a sequence of Base-64 encoded text into binary data. Note
396 * that the returned binary data is not necessarily zero-terminated,
397 * so it should not be used as a character string.
398 *
399 * Returns: (transfer full) (array length=out_len) (element-type guint8):
400 * newly allocated buffer containing the binary data
401 * that @text represents. The returned buffer must
402 * be freed with g_free().
403 *
404 * Since: 2.12
405 */
406 guchar *
409 {
411 gsize input_length;
420 /* We can use a smaller limit here, since we know the saved state is 0,
421 +1 used to avoid calling g_malloc0(0), and hence returning NULL */
427 }
429 /**
430 * g_base64_decode_inplace:
431 * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated
432 * string with base64 text to decode
433 * @out_len: (inout): The length of the decoded data is written here
434 *
435 * Decode a sequence of Base-64 encoded text into binary data
436 * by overwriting the input data.
437 *
438 * Returns: (transfer none): The binary data that @text responds. This pointer
439 * is the same as the input @text.
440 *
441 * Since: 2.20
442 */
443 guchar *
446 {
460 }