nettle: ASCII encoding
1
1 6.9 ASCII encoding
1 ==================
1
1 Encryption will transform your data from text into binary format, and
1 that may be a problem if, for example, you want to send the data as if
1 it was plain text in an email, or store it along with descriptive text
1 in a file. You may then use an encoding from binary to text: each
1 binary byte is translated into a number of bytes of plain text.
1
1 A base-N encoding of data is one representation of data that only
1 uses N different symbols (instead of the 256 possible values of a byte).
1
1 The base64 encoding will always use alphanumeric (upper and lower
1 case) characters and the ’+’, ’/’ and ’=’ symbols to represent the data.
1 Four output characters are generated for each three bytes of input. In
1 case the length of the input is not a multiple of three, padding
1 characters are added at the end. There’s also a “URL safe” variant,
1 which is useful for encoding binary data into URLs and filenames. See
1 ‘RFC 4648’.
1
1 The base16 encoding, also known as “hexadecimal”, uses the decimal
1 digits and the letters from A to F. Two hexadecimal digits are generated
1 for each input byte.
1
1 Nettle supports both base64 and base16 encoding and decoding.
1
1 Encoding and decoding uses a context struct to maintain its state
1 (with the exception of base16 encoding, which doesn’t need any). To
1 encode or decode the data, first initialize the context, then call the
1 update function as many times as necessary, and complete the operation
1 by calling the final function.
1
1 The following functions can be used to perform base64 encoding and
1 decoding. They are defined in ‘<nettle/base64.h>’.
1
1 -- Context struct: struct base64_encode_ctx
1
1 -- Function: void base64_encode_init (struct base64_encode_ctx *CTX)
1 -- Function: void base64url_encode_init (struct base64_encode_ctx *CTX)
1 Initializes a base64 context. This is necessary before starting an
1 encoding session. ‘base64_encode_init’ selects the standard base64
1 alphabet, while ‘base64url_encode_init’ selects the URL safe
1 alphabet.
1
1 -- Function: size_t base64_encode_single (struct base64_encode_ctx
1 *CTX, uint8_t *DST, uint8_t SRC)
1 Encodes a single byte. Returns amount of output (always 1 or 2).
1
1 -- Macro: BASE64_ENCODE_LENGTH (LENGTH)
1 The maximum number of output bytes when passing LENGTH input bytes
1 to ‘base64_encode_update’.
1
1 -- Function: size_t base64_encode_update (struct base64_encode_ctx
1 *CTX, uint8_t *DST, size_t LENGTH, const uint8_t *SRC)
1 After CTX is initialized, this function may be called to encode
1 LENGTH bytes from SRC. The result will be placed in DST, and the
1 return value will be the number of bytes generated. Note that DST
1 must be at least of size BASE64_ENCODE_LENGTH(LENGTH).
1
1 -- Constant: BASE64_ENCODE_FINAL_LENGTH
1 The maximum amount of output from ‘base64_encode_final’.
1
1 -- Function: size_t base64_encode_final (struct base64_encode_ctx *CTX,
1 uint8_t *DST)
1 After calling base64_encode_update one or more times, this function
1 should be called to generate the final output bytes, including any
1 needed paddding. The return value is the number of output bytes
1 generated.
1
1 -- Context struct: struct base64_decode_ctx
1
1 -- Function: void base64_decode_init (struct base64_decode_ctx *CTX)
1 -- Function: void base64url_decode_init (struct base64_decode_ctx *CTX)
1 Initializes a base64 decoding context. This is necessary before
1 starting a decoding session. ‘base64_decode_init’ selects the
1 standard base64 alphabet, while ‘base64url_decode_init’ selects the
1 URL safe alphabet.
1
1 -- Function: int base64_decode_single (struct base64_decode_ctx *CTX,
1 uint8_t *DST, uint8_t SRC)
1 Decodes a single byte (SRC) and stores the result in DST. Returns
1 amount of output (0 or 1), or -1 on errors.
1
1 -- Macro: BASE64_DECODE_LENGTH (LENGTH)
1 The maximum number of output bytes when passing LENGTH input bytes
1 to ‘base64_decode_update’.
1
1 -- Function: void base64_decode_update (struct base64_decode_ctx *CTX,
1 size_t *DST_LENGTH, uint8_t *DST, size_t SRC_LENGTH, const
1 uint8_t *SRC)
1 After CTX is initialized, this function may be called to decode
1 SRC_LENGTH bytes from SRC. DST should point to an area of size at
1 least BASE64_DECODE_LENGTH(SRC_LENGTH). The amount of data
1 generated is returned in *DST_LENGTH. Returns 1 on success and 0
1 on error.
1
1 -- Function: int base64_decode_final (struct base64_decode_ctx *CTX)
1 Check that final padding is correct. Returns 1 on success, and 0
1 on error.
1
1 Similarly to the base64 functions, the following functions perform
1 base16 encoding, and are defined in ‘<nettle/base16.h>’. Note that
1 there is no encoding context necessary for doing base16 encoding.
1
1 -- Function: void base16_encode_single (uint8_t *DST, uint8_t SRC)
1 Encodes a single byte. Always stores two digits in DST[0] and
1 DST[1].
1
1 -- Macro: BASE16_ENCODE_LENGTH (LENGTH)
1 The number of output bytes when passing LENGTH input bytes to
1 ‘base16_encode_update’.
1
1 -- Function: void base16_encode_update (uint8_t *DST, size_t LENGTH,
1 const uint8_t *SRC)
1 Always stores BASE16_ENCODE_LENGTH(LENGTH) digits in DST.
1
1 -- Context struct: struct base16_decode_ctx
1
1 -- Function: void base16_decode_init (struct base16_decode_ctx *CTX)
1 Initializes a base16 decoding context. This is necessary before
1 starting a decoding session.
1
1 -- Function: int base16_decode_single (struct base16_decode_ctx *CTX,
1 uint8_t *DST, uint8_t SRC)
1 Decodes a single byte from SRC into DST. Returns amount of output
1 (0 or 1), or -1 on errors.
1
1 -- Macro: BASE16_DECODE_LENGTH (LENGTH)
1 The maximum number of output bytes when passing LENGTH input bytes
1 to ‘base16_decode_update’.
1
1 -- Function: int base16_decode_update (struct base16_decode_ctx *CTX,
1 size_t *DST_LENGTH, uint8_t *DST, size_t SRC_LENGTH, const
1 uint8_t *SRC)
1 After CTX is initialized, this function may be called to decode
1 SRC_LENGTH bytes from SRC. DST should point to an area of size at
1 least BASE16_DECODE_LENGTH(SRC_LENGTH). The amount of data
1 generated is returned in *DST_LENGTH. Returns 1 on success and 0
1 on error.
1
1 -- Function: int base16_decode_final (struct base16_decode_ctx *CTX)
1 Checks that the end of data is correct (i.e., an even number of
1 hexadecimal digits have been seen). Returns 1 on success, and 0 on
1 error.
1