What is b64?

Version 1.3.4

Introduction | License | b64 C-API | b64 C++-API

Installing b64 | Building b64 | Linking to b64 | Contact & Feedback

Introduction

b64 is a very small and simple library that provides Base-64 encoding and decoding, according to RFC-1113, in C and C++.

License

b64 is released under the BSD license, which basically means its free for any use, but you can't claim it's yours.

b64 C-API

The library is implemented in C, and provides a simple b64 C-API, consisting of the functions b64_encode() and b64_decode() and, as of version 1.1, the functions b64_encode2() and b64_decode2().

b64_encode() encodes a binary block into a block of printable characters, as follows:

  int     ints[]  =   { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
  size_t  cch     =   b64_encode(&ints[0], sizeof(ints), NULL, 0);  /* Ask for length required */
  char    *enc    =   (char*)malloc(cch);                           /* No error checking here ... real code must do so */

  b64_encode(&ints[0], sizeof(ints), enc, cch);

  printf("Converted: [%.*s]\n", cch, enc);

this prints:

Converted: [AQAAAAIAAAADAAAABAAAAAUAAAAGAAAABwAAAAgAAAAJAAAACgAAAA==]

b64_encode2() provides a superset of the functionality of b64_encode(). It is able to split the output in multiples of 4-characters, which supports the requirement to split any lines longer than 64-characters with carriage-return/new-line pairs of RFC-1113. Specifying B64_F_LINE_LEN_64 in the flags parameter splits on 64 bytes, or you can specify B64_F_LINE_LEN_USE_PARAM and a number divisible by 4 as the lineLength parameter. Specifying B64_F_LINE_LEN_USE_PARAM with a lineLength of 0 never splits, which is equivalent to the behaviour of b64_encode(). The following example illustrates how to split on 16-characters at a time:

  int     ints[]  =   { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
  size_t  cch     =   b64_encode2(&ints[0], sizeof(ints), NULL, 0, B64_F_LINE_LEN_USE_PARAM, 16, NULL); /* Ask for length required */
  char    *enc    =   (char*)malloc(cch);                                                               /* No error checking here ... real code must do so */

  b64_encode(&ints[0], sizeof(ints), enc, cch, B64_F_LINE_LEN_USE_PARAM, 16, NULL);

  printf("Converted: [%.*s]\n", cch, enc);

this prints:

Converted: [AQAAAAIAAAADAAAA
BAAAAAUAAAAGAAAA
BwAAAAgAAAAJAAAA
CgAAAA==]

b64_decode() decodes a block of printable characters into a binary block, as follows:

  size_t  cb      =   b64_decode(enc, cch, NULL, 0);                /* Ask for size required */
  int     *dec    =   (int*)alloca(cb);                             /* No error checking here ... real code must do so */

  b64_decode(enc, cch, dec, cb);

  assert(0 == memcmp(&ints[0], &dec[0], sizeof(ints)));

b64 C++-API

The b64 C++-API is a thin wrapper over the b64 C-API, providing for simplified client-code via manipulation of instances of the b64::string_t and b64::blob_t types.

The b64::encode() and b64::decode() functions correspond to the b64::b64_encode() and b64::b64_decode() ones from the b64 C-API. They are used as follows:

  int             ints[]  =   { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
  b64::string_t   enc     =   b64::encode(&ints[0], sizeof(ints));

  std::cout << enc << std::endl;

  b64::blob_t    dec =   b64::decode(enc);

  assert(0 == ::memcmp(&ints[0], &dec[0], sizeof(ints)));

There are three overloads of the b64::encode() and b64::decode() functions, to provide for encoding from:

a pointer (void const*) and a length
an array; note that this is only supported for compilers that support discrimination between arrays and pointers
a blob_t instance

and for decoding from:

a C-string (char const*) and a length
a string_t instance
any type for which string Access Shims c_str_ptr() and c_str_len() have been defined; this includes many types within the STLSoft libraries