1IPSEC_TTODATA(3) Library Functions Manual IPSEC_TTODATA(3)
2
6 ipsec ttodata, datatot - convert binary data bytes from and to text
7 formats
8
10 #include <freeswan.h>
11 const char *ttodata(const char *src, size_t srclen,
13 int base, char *dst, size_t dstlen, size_t *lenp);
14 const char *ttodatav(const char *src, size_t srclen,
15 int base, char *dst, size_t dstlen, size_t *lenp,
16 char *errp, size_t errlen, int flags);
17 size_t datatot(const char *src, size_t srclen,
18 int format, char *dst, size_t dstlen);
19
21 Ttodata, ttodatav, and datatot convert arbitrary binary data (e.g.
22 encryption or authentication keys) from and to more-or-less human-read‐
23 able text formats.
24 Currently supported formats are hexadecimal, base64, and characters.
26 A hexadecimal text value begins with a 0x (or 0X) prefix and continues
28 with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each
29 group encoding the value of one binary byte, high-order digit first. A
30 single _ (underscore) between consecutive groups is ignored, permitting
31 punctuation to improve readability; doing this every eight digits seems
32 about right.
33 A base64 text value begins with a 0s (or 0S) prefix and continues with
35 four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), each
36 group encoding the value of three binary bytes as described in section
37 6.8 of RFC 2045. If flags has the TTODATAV_IGNORESPACE bit on, blanks
38 are ignore (after the prefix). Note that the last one or two digits of
39 a base64 group can be = to indicate that fewer than three binary bytes
40 are encoded.
41 A character text value begins with a 0t (or 0T) prefix and continues
43 with text characters, each being the value of one binary byte.
44 All these functions basically copy data from src (whose size is speci‐
46 fied by srclen) to dst (whose size is specified by dstlen), doing the
47 conversion en route. If the result will not fit in dst, it is trun‐
48 cated; under no circumstances are more than dstlen bytes of result
49 written to dst. Dstlen can be zero, in which case dst need not be
50 valid and no result bytes are written at all.
51 The base parameter of ttodata and ttodatav specifies what format the
53 input is in; normally it should be 0 to signify that this gets figured
54 out from the prefix. Values of 16, 64, and 256 respectively signify
55 hexadecimal, base64, and character-text formats without prefixes.
56 The format parameter of datatot, a single character used as a type
58 code, specifies which text format is wanted. The value 0 (not ASCII
59 '0', but a zero value) specifies a reasonable default. Other cur‐
60 rently-supported values are:
61 'x' continuous lower-case hexadecimal with a 0x prefix
63 'h' lower-case hexadecimal with a 0x prefix and a _ every eight dig‐
65 its
66 ':' lower-case hexadecimal with no prefix and a : (colon) every two
68 digits
69 16 lower-case hexadecimal with no prefix or _
71 's' continuous base64 with a 0s prefix
73 64 continuous base64 with no prefix
75 The default format is currently 'h'.
77 Ttodata returns NULL for success and a pointer to a string-literal
79 error message for failure; see DIAGNOSTICS. On success, if and only if
80 lenp is non-NULL, *lenp is set to the number of bytes required to con‐
81 tain the full untruncated result. It is the caller's responsibility to
82 check this against dstlen to determine whether he has obtained a com‐
83 plete result. The *lenp value is correct even if dstlen is zero, which
84 offers a way to determine how much space would be needed before having
85 to allocate any.
86 Ttodatav is just like ttodata except that in certain cases, if errp is
88 non-NULL, the buffer pointed to by errp (whose length is given by
89 errlen) is used to hold a more detailed error message. The return
90 value is NULL for success, and is either errp or a pointer to a string
91 literal for failure. If the size of the error-message buffer is inade‐
92 quate for the desired message, ttodatav will fall back on returning a
93 pointer to a literal string instead. The freeswan.h header file
94 defines a constant TTODATAV_BUF which is the size of a buffer large
95 enough for worst-case results.
96 The normal return value of datatot is the number of bytes required to
98 contain the full untruncated result. It is the caller's responsibility
99 to check this against dstlen to determine whether he has obtained a
100 complete result. The return value is correct even if dstlen is zero,
101 which offers a way to determine how much space would be needed before
102 having to allocate any. A return value of 0 signals a fatal error of
103 some kind (see DIAGNOSTICS).
104 A zero value for srclen in ttodata (but not datatot!) is synonymous
106 with strlen(src). A non-zero srclen in ttodata must not include the
107 terminating NUL.
108 Unless dstlen is zero, the result supplied by datatot is always NUL-
110 terminated, and its needed-size return value includes space for the
111 terminating NUL.
112 Several obsolete variants of these functions (atodata, datatoa, ato‐
114 bytes, and bytestoa) are temporarily also supported.
115
117 sprintf(3), ipsec_atoaddr(3)
118
120 Fatal errors in ttodata and ttodatav are: unknown characters in the
121 input; unknown or missing prefix; unknown base; incomplete digit group;
122 non-zero padding in a base64 less-than-three-bytes digit group; zero-
123 length input.
124 Fatal errors in datatot are: unknown format code; zero-length input.
126
128 Written for the FreeS/WAN project by Henry Spencer.
129
131 Datatot should have a format code to produce character-text output.
132 The 0s and 0t prefixes are the author's inventions and are not a stan‐
134 dard of any kind. They have been chosen to avoid collisions with
135 existing practice (some C implementations use 0b for binary) and possi‐
136 ble confusion with unprefixed hexadecimal.
137 16 August 2003 IPSEC_TTODATA(3)