1 .TH IPSEC_TTODATA 3 "16 August 2003"
2 .\" RCSID $Id: ttodata.3,v 1.2 2005/07/18 20:13:42 as Exp $
4 ipsec ttodata, datatot \- convert binary data bytes from and to text formats
6 .B "#include <freeswan.h>"
8 .B "const char *ttodata(const char *src, size_t srclen,"
10 .B "int base, char *dst, size_t dstlen, size_t *lenp);"
12 .B "const char *ttodatav(const char *src, size_t srclen,"
14 .B "int base, char *dst, size_t dstlen, size_t *lenp,"
16 .B "char *errp, size_t errlen, int flags);"
18 .B "size_t datatot(const char *src, size_t srclen,"
20 .B "int format, char *dst, size_t dstlen);"
26 convert arbitrary binary data (e.g. encryption or authentication keys)
27 from and to more-or-less human-readable text formats.
29 Currently supported formats are hexadecimal, base64, and characters.
31 A hexadecimal text value begins with a
35 prefix and continues with two-digit groups
36 of hexadecimal digits (0-9, and a-f or A-F),
37 each group encoding the value of one binary byte, high-order digit first.
41 between consecutive groups is ignored, permitting punctuation to improve
42 readability; doing this every eight digits seems about right.
44 A base64 text value begins with a
49 and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /),
50 each group encoding the value of three binary bytes as described in
51 section 6.8 of RFC 2045.
55 .B TTODATAV_IGNORESPACE
56 bit on, blanks are ignore (after the prefix).
57 Note that the last one or two digits of a base64 group can be
59 to indicate that fewer than three binary bytes are encoded.
61 A character text value begins with a
66 and continues with text characters, each being the value of one binary byte.
68 All these functions basically copy data from
70 (whose size is specified by
74 (whose size is specified by
76 doing the conversion en route.
77 If the result will not fit in
80 under no circumstances are more than
82 bytes of result written to
85 can be zero, in which case
87 need not be valid and no result bytes are written at all.
95 specifies what format the input is in;
98 to signify that this gets figured out from the prefix.
104 respectively signify hexadecimal, base64, and character-text formats
111 a single character used as a type code,
112 specifies which text format is wanted.
117 but a zero value) specifies a reasonable default.
118 Other currently-supported values are:
122 continuous lower-case hexadecimal with a
127 lower-case hexadecimal with a
134 lower-case hexadecimal with no prefix and a
136 (colon) every two digits
139 lower-case hexadecimal with no prefix or
143 continuous base64 with a
148 continuous base64 with no prefix
151 The default format is currently
155 returns NULL for success and
156 a pointer to a string-literal error message for failure;
163 is set to the number of bytes required to contain the full untruncated result.
164 It is the caller's responsibility to check this against
166 to determine whether he has obtained a complete result.
169 value is correct even if
171 is zero, which offers a way to determine how much space would be needed
172 before having to allocate any.
177 except that in certain cases,
181 the buffer pointed to by
183 (whose length is given by
185 is used to hold a more detailed error message.
186 The return value is NULL for success,
189 or a pointer to a string literal for failure.
190 If the size of the error-message buffer is
191 inadequate for the desired message,
193 will fall back on returning a pointer to a literal string instead.
196 header file defines a constant
198 which is the size of a buffer large enough for worst-case results.
200 The normal return value of
202 is the number of bytes required
203 to contain the full untruncated result.
204 It is the caller's responsibility to check this against
206 to determine whether he has obtained a complete result.
207 The return value is correct even if
209 is zero, which offers a way to determine how much space would be needed
210 before having to allocate any.
213 signals a fatal error of some kind
228 must not include the terminating NUL.
233 the result supplied by
235 is always NUL-terminated,
236 and its needed-size return value includes space for the terminating NUL.
238 Several obsolete variants of these functions
244 are temporarily also supported.
246 sprintf(3), ipsec_atoaddr(3)
253 unknown characters in the input;
254 unknown or missing prefix;
256 incomplete digit group;
257 non-zero padding in a base64 less-than-three-bytes digit group;
266 Written for the FreeS/WAN project by Henry Spencer.
269 should have a format code to produce character-text output.
275 prefixes are the author's inventions and are not a standard
277 They have been chosen to avoid collisions with existing practice
278 (some C implementations use
281 and possible confusion with unprefixed hexadecimal.