base64.h

   1 /* base64.h
   2  *
   3  * "ASCII armor" codecs.
   4  */
   5
   6 /* nettle, low-level cryptographics library
   7  *
   8  * Copyright (C) 2002 Niels Möller, Dan Egnor
   9  *
  10  * The nettle library is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or (at your
  13  * option) any later version.
  14  *
  15  * The nettle library is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  17  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  18  * License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with the nettle library; see the file COPYING.LIB.  If not, write to
  22  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  23  * MA 02111-1301, USA.
  24  */
  25
  26 #ifndef NETTLE_BASE64_H_INCLUDED
  27 #define NETTLE_BASE64_H_INCLUDED
  28
  29 #include "nettle-types.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /* Name mangling */
  36 #define base64_encode_init nettle_base64_encode_init
  37 #define base64_encode_single nettle_base64_encode_single
  38 #define base64_encode_update nettle_base64_encode_update
  39 #define base64_encode_final nettle_base64_encode_final
  40 #define base64_encode_raw nettle_base64_encode_raw
  41 #define base64_encode_group nettle_base64_encode_group
  42 #define base64_decode_init nettle_base64_decode_init
  43 #define base64_decode_single nettle_base64_decode_single
  44 #define base64_decode_update nettle_base64_decode_update
  45 #define base64_decode_final nettle_base64_decode_final
  46
  47 #define BASE64_BINARY_BLOCK_SIZE 3
  48 #define BASE64_TEXT_BLOCK_SIZE 4
  49
  50 /* Base64 encoding */
  51
  52 /* Maximum length of output for base64_encode_update. NOTE: Doesn't
  53  * include any padding that base64_encode_final may add. */
  54 /* We have at most 4 buffered bits, and a total of (4 + length * 8) bits. */
  55 #define BASE64_ENCODE_LENGTH(length) (((length) * 8 + 4)/6)
  56
  57 /* Maximum length of output generated by base64_encode_final. */
  58 #define BASE64_ENCODE_FINAL_LENGTH 3
  59
  60 /* Exact length of output generated by base64_encode_raw, including
  61  * padding. */
  62 #define BASE64_ENCODE_RAW_LENGTH(length) ((((length) + 2)/3)*4)
  63
  64 struct base64_encode_ctx
  65 {
  66   unsigned word;   /* Leftover bits */
  67   unsigned bits;  /* Number of bits, always 0, 2, or 4. */
  68 };
  69
  70 void
  71 base64_encode_init(struct base64_encode_ctx *ctx);
  72
  73 /* Encodes a single byte. Returns amount of output (always 1 or 2). */
  74 unsigned
  75 base64_encode_single(struct base64_encode_ctx *ctx,
  76                      uint8_t *dst,
  77                      uint8_t src);
  78
  79 /* Returns the number of output characters. DST should point to an
  80  * area of size at least BASE64_ENCODE_LENGTH(length). */
  81 unsigned
  82 base64_encode_update(struct base64_encode_ctx *ctx,
  83                      uint8_t *dst,
  84                      unsigned length,
  85                      const uint8_t *src);
  86
  87 /* DST should point to an area of size at least
  88  * BASE64_ENCODE_FINAL_LENGTH */
  89 unsigned
  90 base64_encode_final(struct base64_encode_ctx *ctx,
  91                     uint8_t *dst);
  92
  93 /* Lower level functions */
  94
  95 /* Encodes a string in one go, including any padding at the end.
  96  * Generates exactly BASE64_ENCODE_RAW_LENGTH(length) bytes of output.
  97  * Supports overlapped operation, if src <= dst. */
  98 void
  99 base64_encode_raw(uint8_t *dst, unsigned length, const uint8_t *src);
 100
 101 void
 102 base64_encode_group(uint8_t *dst, uint32_t group);
 103
 104
 105 /* Base64 decoding */
 106
 107 /* Maximum length of output for base64_decode_update. */
 108 /* We have at most 6 buffered bits, and a total of (length + 1) * 6 bits. */
 109 #define BASE64_DECODE_LENGTH(length) ((((length) + 1) * 6) / 8)
 110
 111 struct base64_decode_ctx
 112 {
 113   unsigned word;   /* Leftover bits */
 114   unsigned bits;   /* Number buffered bits */
 115
 116   /* Number of padding characters encountered */
 117   unsigned padding;
 118 };
 119
 120 void
 121 base64_decode_init(struct base64_decode_ctx *ctx);
 122
 123 /* Decodes a single byte. Returns amount of output (0 or 1), or -1 on
 124  * errors. */
 125 int
 126 base64_decode_single(struct base64_decode_ctx *ctx,
 127                      uint8_t *dst,
 128                      uint8_t src);
 129
 130 /* Returns 1 on success, 0 on error. DST should point to an area of
 131  * size at least BASE64_DECODE_LENGTH(length), and for sanity
 132  * checking, *DST_LENGTH should be initialized to the size of that
 133  * area before the call. *DST_LENGTH is updated to the amount of
 134  * decoded output. */
 135
 136 /* Currently results in an assertion failure if *DST_LENGTH is
 137  * too small. FIXME: Return some error instead? */
 138 int
 139 base64_decode_update(struct base64_decode_ctx *ctx,
 140                      unsigned *dst_length,
 141                      uint8_t *dst,
 142                      unsigned src_length,
 143                      const uint8_t *src);
 144
 145 /* Returns 1 on success. */
 146 int
 147 base64_decode_final(struct base64_decode_ctx *ctx);
 148
 149 #ifdef __cplusplus
 150 }
 151 #endif
 152
 153 #endif /* NETTLE_BASE64_H_INCLUDED */