Paul Wouters

placeholder to suppress warning

IPSEC_TTODATA 3 16 August 2003 libreswan Library functions
ipsec ttodata ipsec datatot convert binary data bytes from and to text formats

    #include <libreswan.h>

const char *`ttodata` const char * src size_t srclen int base char * dst size_t dstlen size_t * lenp

const char *`ttodatav` const char * src size_t srclen int base char * dst size_t dstlen size_t * lenp char * errp size_t errlen int flags

size_t `datatot` const char * src size_t srclen int format char * dst size_t dstlen

## DESCRIPTION

Ttodata, `ttodatav`, and `datatot` convert arbitrary binary data (e.g. encryption or authentication keys) from and to more-or-less human-readable text formats.

Currently supported formats are hexadecimal, base64, and characters.

A hexadecimal text value begins with a 0x (or 0X) prefix and continues with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each group encoding the value of one binary byte, high-order digit first. A single _ (underscore) between consecutive groups is ignored, permitting punctuation to improve readability; doing this every eight digits seems about right.

A base64 text value begins with a 0s (or 0S) prefix and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each group encoding the value of three binary bytes as described in section 6.8 of RFC 2045. If `flags` has the TTODATAV_IGNORESPACE bit on, blanks are ignore (after the prefix). Note that the last one or two digits of a base64 group can be = to indicate that fewer than three binary bytes are encoded.

A character text value begins with a 0t (or 0T) prefix and continues with text characters, each being the value of one binary byte.

All these functions basically copy data from `src` (whose size is specified by `srclen`) to `dst` (whose size is specified by `dstlen`), doing the conversion en route. If the result will not fit in `dst`, it is truncated; under no circumstances are more than `dstlen` bytes of result written to `dst`. Dstlen can be zero, in which case `dst` need not be valid and no result bytes are written at all.

The `base` parameter of `ttodata` and `ttodatav` specifies what format the input is in; normally it should be `0` to signify that this gets figured out from the prefix. Values of `16`, `64`, and `256` respectively signify hexadecimal, base64, and character-text formats without prefixes.

The `format` parameter of `datatot`, a single character used as a type code, specifies which text format is wanted. The value `0` (not ASCII '0', but a zero value) specifies a reasonable default. Other currently-supported values are:

'x'

  continuous lower-case hexadecimal with a 0x prefix

'h'

  lower-case hexadecimal with a 0x prefix and a _ every eight digits

':'

  lower-case hexadecimal with no prefix and a : (colon) every two digits

`16`

  lower-case hexadecimal with no prefix or _

's'

  continuous base64 with a 0s prefix

`64`

  continuous base64 with no prefix

The default format is currently 'h'.

Ttodata returns NULL for success and a pointer to a string-literal error message for failure; see DIAGNOSTICS. On success, if and only if `lenp` is non-NULL, *lenp is set to the number of bytes required to contain the full untruncated result. It is the caller's responsibility to check this against `dstlen` to determine whether he has obtained a complete result. The *lenp value is correct even if `dstlen` is zero, which offers a way to determine how much space would be needed before having to allocate any.

Ttodatav is just like `ttodata` except that in certain cases, if `errp` is non-NULL, the buffer pointed to by `errp` (whose length is given by `errlen`) is used to hold a more detailed error message. The return value is NULL for success, and is either `errp` or a pointer to a string literal for failure. If the size of the error-message buffer is inadequate for the desired message, `ttodatav` will fall back on returning a pointer to a literal string instead. The libreswan.h header file defines a constant TTODATAV_BUF which is the size of a buffer large enough for worst-case results.

The normal return value of `datatot` is the number of bytes required to contain the full untruncated result. It is the caller's responsibility to check this against `dstlen` to determine whether he has obtained a complete result. The return value is correct even if `dstlen` is zero, which offers a way to determine how much space would be needed before having to allocate any. A return value of `0` signals a fatal error of some kind (see DIAGNOSTICS).

A zero value for `srclen` in `ttodata` (but not `datatot`!) is synonymous with strlen(src). A non-zero `srclen` in `ttodata` must not include the terminating NUL.

Unless `dstlen` is zero, the result supplied by `datatot` is always NUL-terminated, and its needed-size return value includes space for the terminating NUL.

## SEE ALSO

sprintf 3, ipsec_atoaddr 3

## DIAGNOSTICS

Fatal errors in `ttodata` and `ttodatav` are: unknown characters in the input; unknown or missing prefix; unknown base; incomplete digit group; non-zero padding in a base64 less-than-three-bytes digit group; zero-length input.

Fatal errors in `datatot` are: unknown format code; zero-length input.

## HISTORY

Written for the FreeS/WAN project by Henry Spencer.

## BUGS

Datatot should have a format code to produce character-text output.

The 0s and 0t prefixes are the author's inventions and are not a standard of any kind. They have been chosen to avoid collisions with existing practice (some C implementations use 0b for binary) and possible confusion with unprefixed hexadecimal.