# Base64 Library

Base64 is an encoding for representing arbitrary data as a printable ASCII string. 4 Bytes in base64 encoding represent 3 Bytes of the data.

## File information

File | common/ilib/base64.h
Public functions | encode_base64 decode_base64 decode_base64_bin encode_base64_buffer_len encode_base64url decode_base64url decode_base64url_bin
Examples | encode_base64 decode_base64 decode_base64_bin encode_base64_buffer_len

Two decode variants exist for each alphabet: *_bin takes an explicit output-buffer size and returns the byte-count actually written. The plain version (decode_base64, decode_base64url) assumes the buffer is large enough and returns the decoded length as dword.

The helper function encode_base64_buffer_len(len) isn’t a conversion routine; it just tells you how large the destination buffer must be when you call encode_base64.

From \ To | Binary | Base64 | Base64URL
--- | --- | --- | ---
Binary |  | encode_base64 | encode_base64url
Base64 | decode_base64 decode_base64_bin |  | missing
Base64URL | decode_base64url decode_base64url_bin | missing |

# Public functions

encode_base64
  Encodes arbitrary data into a null-terminated base64 string. This increases the needed space by 4/3 plus one byte for the null-termination.

  #### Parameters

  const byte * in | The data that shall be encoded.
  char * out | The function writes the null-terminated base64 string to this buffer. The buffer has to be large enough to contain 4/3 * len + 1 bytes.
  int len | The number of bytes that shall be encoded.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

decode_base64
  Decodes a base64 string into a null-terminated plain string.

  #### Parameters

  const char * in | The base64 string to be decoded.
  byte * out | The function writes the decoded data to this buffer and places an additional null byte at the end.
  int n | The number of bytes in the in buffer to be decoded.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

decode_base64_bin
  Decodes a null-terminated base64 string.

  #### Parameters

  const char * in | The null-terminated base64 string to be decoded.
  byte * out | The function writes the decoded data to this buffer.
  unsigned size_of_out | The size of the out buffer.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

encode_base64_buffer_len
  Calculates the required buffer size for the `encode_base64` function.

  #### Parameters

  dword len | The number of bytes of the original data.

  #### Return value

  dword | The required size for the output buffer, including space for the null-terminator.

encode_base64url
  Encodes arbitrary data into a null-terminated base64url string using the URL and filename safe alphabet (RFC 4648, section 5).

  #### Parameters

  const byte * in | The data that shall be encoded.
  char * out | The function writes the null-terminated base64url string to this buffer.
  int len | The number of bytes that shall be encoded.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

decode_base64url
  Decodes a base64url string into a null-terminated plain string. It uses the URL and filename safe alphabet.

  #### Parameters

  const char * in | The base64url string to be decoded.
  byte * out | The function writes the decoded data to this buffer and places an additional null byte at the end.
  int n | The number of bytes in the in buffer to be decoded.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

decode_base64url_bin
  Decodes a null-terminated base64url string using the URL and filename safe alphabet.

  #### Parameters

  const char * in | The null-terminated base64url string to be decoded.
  byte * out | The function writes the decoded data to this buffer.
  unsigned size_of_out | The size of the out buffer.

  #### Return value

  dword | The number of bytes that have been written to the out buffer.

# Code Example

## encode_base64

    const char * in = "This is an example text";
    char out[64];
    dword out_len = encode_base64(in, out, strlen(in));

## decode_base64

    const char * in = "VGhpcyBpcyBhbiBleGFtcGxlIHRleHQ=";
    char out[64];
    dword out_len = decode_base64(in, out, strlen(in));

## decode_base64_bin

    const char * in = "VGhpcyBpcyBhbiBleGFtcGxlIHRleHQ=";
    char out[64];
    dword out_len = decode_base64_bin(in, out, sizeof(out));

## encode_base64_buffer_len

    const byte * data = (const byte *)"This is an example text";
    dword data_len = strlen((const char *)data);
    char * out = (char *)alloca(encode_base64_buffer_len(data_len));
    encode_base64(data, out, data_len);