1 /* Licensed under BSD-MIT - see LICENSE file for details */
10 * base64_maps_t - structure to hold maps for encode/decode
14 signed char decode_map[256];
18 * base64_encoded_length - Calculate encode buffer length
19 * @param srclen the size of the data to be encoded
20 * @note add 1 to this to get null-termination
21 * @return Buffer length required for encode
23 size_t base64_encoded_length(size_t srclen);
26 * base64_decoded_length - Calculate decode buffer length
27 * @param srclen Length of the data to be decoded
28 * @note This does not return the size of the decoded data! see base64_decode
29 * @return Minimum buffer length for safe decode
31 size_t base64_decoded_length(size_t srclen);
34 * base64_init_maps - populate a base64_maps_t based on a supplied alphabet
35 * @param dest A base64 maps object
36 * @param src Alphabet to populate the maps from (e.g. base64_alphabet_rfc4648)
38 void base64_init_maps(base64_maps_t *dest, const char src[64]);
42 * base64_encode_triplet_using_maps - encode 3 bytes into base64 using a specific alphabet
43 * @param maps Maps to use for encoding (see base64_init_maps)
44 * @param dest Buffer containing 3 bytes
45 * @param src Buffer containing 4 characters
47 void base64_encode_triplet_using_maps(const base64_maps_t *maps,
48 char dest[4], const char src[3]);
51 * base64_encode_tail_using_maps - encode the final bytes of a source using a specific alphabet
52 * @param maps Maps to use for encoding (see base64_init_maps)
53 * @param dest Buffer containing 4 bytes
54 * @param src Buffer containing srclen bytes
55 * @param srclen Number of bytes (<= 3) to encode in src
57 void base64_encode_tail_using_maps(const base64_maps_t *maps, char dest[4],
58 const char *src, size_t srclen);
61 * base64_encode_using_maps - encode a buffer into base64 using a specific alphabet
62 * @param maps Maps to use for encoding (see base64_init_maps)
63 * @param dest Buffer to encode into
64 * @param destlen Length of dest
65 * @param src Buffer to encode
66 * @param srclen Length of the data to encode
67 * @return Number of encoded bytes set in dest. -1 on error (and errno set)
68 * @note dest will be nul-padded to destlen (past any required padding)
69 * @note sets errno = EOVERFLOW if destlen is too small
71 ssize_t base64_encode_using_maps(const base64_maps_t *maps,
72 char *dest, size_t destlen,
73 const char *src, size_t srclen);
76 * base64_char_in_alphabet - returns true if character can be part of an encoded string
77 * @param maps A base64 maps object (see base64_init_maps)
78 * @param b64char Character to check
80 bool base64_char_in_alphabet(const base64_maps_t *maps, char b64char);
83 * base64_decode_using_maps - decode a base64-encoded string using a specific alphabet
84 * @param maps A base64 maps object (see base64_init_maps)
85 * @param dest Buffer to decode into
86 * @param destlen length of dest
87 * @param src the buffer to decode
88 * @param srclen the length of the data to decode
89 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
90 * @note dest will be nul-padded to destlen
91 * @note sets errno = EOVERFLOW if destlen is too small
92 * @note sets errno = EDOM if src contains invalid characters
94 ssize_t base64_decode_using_maps(const base64_maps_t *maps,
95 char *dest, size_t destlen,
96 const char *src, size_t srclen);
99 * base64_decode_quartet_using_maps - decode 4 bytes from base64 using a specific alphabet
100 * @param maps A base64 maps object (see base64_init_maps)
101 * @param dest Buffer containing 3 bytes
102 * @param src Buffer containing 4 bytes
103 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
104 * @note sets errno = EDOM if src contains invalid characters
106 ssize_t base64_decode_quartet_using_maps(const base64_maps_t *maps,
107 char dest[3], const char src[4]);
110 * base64_decode_tail_using_maps - decode the final bytes of a base64 string using a specific alphabet
111 * @param maps A base64 maps object (see base64_init_maps)
112 * @param dest Buffer containing 3 bytes
113 * @param src Buffer containing 4 bytes - padded with '=' as required
114 * @param srclen Number of bytes to decode in src
115 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
116 * @note sets errno = EDOM if src contains invalid characters
117 * @note sets errno = EINVAL if src is an invalid base64 tail
119 ssize_t base64_decode_tail_using_maps(const base64_maps_t *maps, char dest[3],
120 const char *src, size_t srclen);
123 /* the rfc4648 functions: */
125 extern const base64_maps_t base64_maps_rfc4648;
128 * base64_encode - Encode a buffer into base64 according to rfc4648
129 * @param dest Buffer to encode into
130 * @param destlen Length of the destination buffer
131 * @param src Buffer to encode
132 * @param srclen Length of the data to encode
133 * @return Number of encoded bytes set in dest. -1 on error (and errno set)
134 * @note dest will be nul-padded to destlen (past any required padding)
135 * @note sets errno = EOVERFLOW if destlen is too small
137 * This function encodes src according to http://tools.ietf.org/html/rfc4648
140 * size_t encoded_length;
142 * const char *src = "This string gets encoded";
143 * encoded_length = base64_encode(dest, sizeof(dest), src, strlen(src));
144 * printf("Returned data of length %zd @%p\n", encoded_length, &dest);
147 ssize_t base64_encode(char *dest, size_t destlen,
148 const char *src, size_t srclen)
150 return base64_encode_using_maps(&base64_maps_rfc4648,
151 dest, destlen, src, srclen);
155 * base64_encode_triplet - encode 3 bytes into base64 according to rfc4648
156 * @param dest Buffer containing 4 bytes
157 * @param src Buffer containing 3 bytes
160 void base64_encode_triplet(char dest[4], const char src[3])
162 base64_encode_triplet_using_maps(&base64_maps_rfc4648, dest, src);
166 * base64_encode_tail - encode the final bytes of a source according to rfc4648
167 * @param dest Buffer containing 4 bytes
168 * @param src Buffer containing srclen bytes
169 * @param srclen Number of bytes (<= 3) to encode in src
172 void base64_encode_tail(char dest[4], const char *src, size_t srclen)
174 base64_encode_tail_using_maps(&base64_maps_rfc4648, dest, src, srclen);
179 * base64_decode - decode An rfc4648 base64-encoded string
180 * @param dest Buffer to decode into
181 * @param destlen Length of the destination buffer
182 * @param src Buffer to decode
183 * @param srclen Length of the data to decode
184 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
185 * @note dest will be nul-padded to destlen
186 * @note sets errno = EOVERFLOW if destlen is too small
187 * @note sets errno = EDOM if src contains invalid characters
189 * This function decodes the buffer according to
190 * http://tools.ietf.org/html/rfc4648
193 * size_t decoded_length;
195 * const char *src = "Zm9vYmFyYmF6";
196 * decoded_length = base64_decode(ret, sizeof(ret), src, strlen(src));
197 * printf("Returned data of length %zd @%p\n", decoded_length, &ret);
200 ssize_t base64_decode(char *dest, size_t destlen,
201 const char *src, size_t srclen)
203 return base64_decode_using_maps(&base64_maps_rfc4648,
204 dest, destlen, src, srclen);
208 * base64_decode_quartet - decode the first 4 characters in src into dest
209 * @param dest Buffer containing 3 bytes
210 * @param src Buffer containing 4 characters
211 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
212 * @note sets errno = EDOM if src contains invalid characters
215 ssize_t base64_decode_quartet(char dest[3], const char src[4])
217 return base64_decode_quartet_using_maps(&base64_maps_rfc4648,
222 * @brief decode the final bytes of a base64 string from src into dest
223 * @param dest Buffer containing 3 bytes
224 * @param src Buffer containing 4 bytes - padded with '=' as required
225 * @param srclen Number of bytes to decode in src
226 * @return Number of decoded bytes set in dest. -1 on error (and errno set)
227 * @note sets errno = EDOM if src contains invalid characters
228 * @note sets errno = EINVAL if src is an invalid base64 tail
231 ssize_t base64_decode_tail(char dest[3], const char *src, size_t srclen)
233 return base64_decode_tail_using_maps(&base64_maps_rfc4648,
237 /* end rfc4648 functions */
241 #endif /* CCAN_BASE64_H */