--- name: "ipsec_ttodata" section: "3" platform: "linux" package: "openswan" version: "1:2.6.37-3+deb7u1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/ipsec_ttodata" --- # ipsec\_ttodata(3) convert binary data bytes from and to text formats ## NAME ipsec\_ttodata, ipsec\_datatot - convert binary data bytes from and to text formats ## SYNOPSIS ``` #include ``` **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 *freeswan.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. Several obsolete variants of these functions (*atodata*, *datatoa*, *atobytes*, and *bytestoa*) are temporarily also supported. ## SEE ALSO [**sprintf**(3)](/sprintf/3.md), [**ipsec\_atoaddr**(3)](/ipsec_atoaddr/3.md) ## 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.