include/nettle/base64.h

0001 /* base64.h
0002
0003    Base-64 encoding and decoding.
0004
0005    Copyright (C) 2002 Niels Möller, Dan Egnor
0006
0007    This file is part of GNU Nettle.
0008
0009    GNU Nettle is free software: you can redistribute it and/or
0010    modify it under the terms of either:
0011
0012      * the GNU Lesser General Public License as published by the Free
0013        Software Foundation; either version 3 of the License, or (at your
0014        option) any later version.
0015
0016    or
0017
0018      * the GNU General Public License as published by the Free
0019        Software Foundation; either version 2 of the License, or (at your
0020        option) any later version.
0021
0022    or both in parallel, as here.
0023
0024    GNU Nettle is distributed in the hope that it will be useful,
0025    but WITHOUT ANY WARRANTY; without even the implied warranty of
0026    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0027    General Public License for more details.
0028
0029    You should have received copies of the GNU General Public License and
0030    the GNU Lesser General Public License along with this program.  If
0031    not, see http://www.gnu.org/licenses/.
0032 */
0033
0034 #ifndef NETTLE_BASE64_H_INCLUDED
0035 #define NETTLE_BASE64_H_INCLUDED
0036
0037 #include "nettle-types.h"
0038
0039 #ifdef __cplusplus
0040 extern "C" {
0041 #endif
0042
0043 /* Name mangling */
0044 #define base64_encode_init nettle_base64_encode_init
0045 #define base64url_encode_init nettle_base64url_encode_init
0046 #define base64_encode_single nettle_base64_encode_single
0047 #define base64_encode_update nettle_base64_encode_update
0048 #define base64_encode_final nettle_base64_encode_final
0049 #define base64_encode_raw nettle_base64_encode_raw
0050 #define base64_encode_group nettle_base64_encode_group
0051 #define base64_decode_init nettle_base64_decode_init
0052 #define base64url_decode_init nettle_base64url_decode_init
0053 #define base64_decode_single nettle_base64_decode_single
0054 #define base64_decode_update nettle_base64_decode_update
0055 #define base64_decode_final nettle_base64_decode_final
0056
0057 #define BASE64_BINARY_BLOCK_SIZE 3
0058 #define BASE64_TEXT_BLOCK_SIZE 4
0059
0060 /* Base64 encoding */
0061
0062 /* Maximum length of output for base64_encode_update. NOTE: Doesn't
0063  * include any padding that base64_encode_final may add. */
0064 /* We have at most 4 buffered bits, and a total of (4 + length * 8) bits. */
0065 #define BASE64_ENCODE_LENGTH(length) (((length) * 8 + 4)/6)
0066
0067 /* Maximum length of output generated by base64_encode_final. */
0068 #define BASE64_ENCODE_FINAL_LENGTH 3
0069
0070 /* Exact length of output generated by base64_encode_raw, including
0071  * padding. */
0072 #define BASE64_ENCODE_RAW_LENGTH(length) ((((length) + 2)/3)*4)
0073
0074 struct base64_encode_ctx
0075 {
0076   const char *alphabet;    /* Alphabet to use for encoding */
0077   unsigned short word;     /* Leftover bits */
0078   unsigned char bits;      /* Number of bits, always 0, 2, or 4. */
0079 };
0080
0081 /* Initialize encoding context for base-64 */
0082 void
0083 base64_encode_init(struct base64_encode_ctx *ctx);
0084
0085 /* Initialize encoding context for URL safe alphabet, RFC 4648. */
0086 void
0087 base64url_encode_init(struct base64_encode_ctx *ctx);
0088
0089 /* Encodes a single byte. Returns amount of output (always 1 or 2). */
0090 size_t
0091 base64_encode_single(struct base64_encode_ctx *ctx,
0092              char *dst,
0093              uint8_t src);
0094
0095 /* Returns the number of output characters. DST should point to an
0096  * area of size at least BASE64_ENCODE_LENGTH(length). */
0097 size_t
0098 base64_encode_update(struct base64_encode_ctx *ctx,
0099              char *dst,
0100              size_t length,
0101              const uint8_t *src);
0102
0103 /* DST should point to an area of size at least
0104  * BASE64_ENCODE_FINAL_LENGTH */
0105 size_t
0106 base64_encode_final(struct base64_encode_ctx *ctx,
0107             char *dst);
0108
0109 /* Lower level functions */
0110
0111 /* Encodes a string in one go, including any padding at the end.
0112  * Generates exactly BASE64_ENCODE_RAW_LENGTH(length) bytes of output.
0113  * Supports overlapped operation, if src <= dst. FIXME: Use of overlap
0114  * is deprecated, if needed there should be a separate public fucntion
0115  * to do that.*/
0116 void
0117 base64_encode_raw(char *dst, size_t length, const uint8_t *src);
0118
0119 void
0120 base64_encode_group(char *dst, uint32_t group);
0121
0122
0123 /* Base64 decoding */
0124
0125 /* Maximum length of output for base64_decode_update. */
0126 /* We have at most 6 buffered bits, and a total of (length + 1) * 6 bits. */
0127 #define BASE64_DECODE_LENGTH(length) ((((length) + 1) * 6) / 8)
0128
0129 struct base64_decode_ctx
0130 {
0131   const signed char *table; /* Decoding table */
0132   unsigned short word;      /* Leftover bits */
0133   unsigned char bits;       /* Number buffered bits */
0134
0135   /* Number of padding characters encountered */
0136   unsigned char padding;
0137 };
0138
0139 /* Initialize decoding context for base-64 */
0140 void
0141 base64_decode_init(struct base64_decode_ctx *ctx);
0142
0143 /* Initialize encoding context for URL safe alphabet, RFC 4648. */
0144 void
0145 base64url_decode_init(struct base64_decode_ctx *ctx);
0146
0147 /* Decodes a single byte. Returns amount of output (0 or 1), or -1 on
0148  * errors. */
0149 int
0150 base64_decode_single(struct base64_decode_ctx *ctx,
0151              uint8_t *dst,
0152              char src);
0153
0154 /* Returns 1 on success, 0 on error. DST should point to an area of
0155  * size at least BASE64_DECODE_LENGTH(length). The amount of data
0156  * generated is returned in *DST_LENGTH. */
0157 int
0158 base64_decode_update(struct base64_decode_ctx *ctx,
0159              size_t *dst_length,
0160              uint8_t *dst,
0161              size_t src_length,
0162              const char *src);
0163
0164 /* Returns 1 on success. */
0165 int
0166 base64_decode_final(struct base64_decode_ctx *ctx);
0167
0168 #ifdef __cplusplus
0169 }
0170 #endif
0171
0172 #endif /* NETTLE_BASE64_H_INCLUDED */