1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
|
Content-type: text/html
<HTML><HEAD><TITLE>Manpage of IPSEC_TTODATA</TITLE>
</HEAD><BODY>
<H1>IPSEC_TTODATA</H1>
Section: C Library Functions (3)<BR>Updated: 16 August 2003<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
ipsec ttodata, datatot - convert binary data bytes from and to text formats
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
<P>
<B>const char *ttodata(const char *src, size_t srclen,</B>
<BR>
<B>int base, char *dst, size_t dstlen, size_t *lenp);</B>
<BR>
<B>const char *ttodatav(const char *src, size_t srclen,</B>
<BR>
<B>int base, char *dst, size_t dstlen, size_t *lenp,</B>
<BR>
<B>char *errp, size_t errlen, int flags);</B>
<BR>
<B>size_t datatot(const char *src, size_t srclen,</B>
<BR>
<B>int format, char *dst, size_t dstlen);</B>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
<I>Ttodata</I>,
<I>ttodatav</I>,
and
<I>datatot</I>
convert arbitrary binary data (e.g. encryption or authentication keys)
from and to more-or-less human-readable text formats.
<P>
Currently supported formats are hexadecimal, base64, and characters.
<P>
A hexadecimal text value begins with a
<B>0x</B>
(or
<B>0X</B>)
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
<B>_</B>
(underscore)
between consecutive groups is ignored, permitting punctuation to improve
readability; doing this every eight digits seems about right.
<P>
A base64 text value begins with a
<B>0s</B>
(or
<B>0S</B>)
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
<B>flags</B>
has the
<B>TTODATAV_IGNORESPACE</B>
bit on, blanks are ignore (after the prefix).
Note that the last one or two digits of a base64 group can be
<B>=</B>
to indicate that fewer than three binary bytes are encoded.
<P>
A character text value begins with a
<B>0t</B>
(or
<B>0T</B>)
prefix
and continues with text characters, each being the value of one binary byte.
<P>
All these functions basically copy data from
<I>src</I>
(whose size is specified by
<I>srclen</I>)
to
<I>dst</I>
(whose size is specified by
<I>dstlen</I>),
doing the conversion en route.
If the result will not fit in
<I>dst</I>,
it is truncated;
under no circumstances are more than
<I>dstlen</I>
bytes of result written to
<I>dst</I>.
<I>Dstlen</I>
can be zero, in which case
<I>dst</I>
need not be valid and no result bytes are written at all.
<P>
The
<I>base</I>
parameter of
<I>ttodata</I>
and
<I>ttodatav</I>
specifies what format the input is in;
normally it should be
<B>0</B>
to signify that this gets figured out from the prefix.
Values of
<B>16</B>,
<B>64</B>,
and
<B>256</B>
respectively signify hexadecimal, base64, and character-text formats
without prefixes.
<P>
The
<I>format</I>
parameter of
<I>datatot</I>,
a single character used as a type code,
specifies which text format is wanted.
The value
<B>0</B>
(not ASCII
<B>'0'</B>,
but a zero value) specifies a reasonable default.
Other currently-supported values are:
<DL COMPACT><DT><DD>
<DL COMPACT>
<DT><B>'x'</B>
<DD>
continuous lower-case hexadecimal with a
<B>0x</B>
prefix
<DT><B>'h'</B>
<DD>
lower-case hexadecimal with a
<B>0x</B>
prefix and a
<B>_</B>
every eight digits
<DT><B>':'</B>
<DD>
lower-case hexadecimal with no prefix and a
<B>:</B>
(colon) every two digits
<DT><B>16</B>
<DD>
lower-case hexadecimal with no prefix or
<B>_</B>
<DT><B>'s'</B>
<DD>
continuous base64 with a
<B>0s</B>
prefix
<DT><B>64</B>
<DD>
continuous base64 with no prefix
</DL>
</DL>
<P>
The default format is currently
<B>'h'</B>.
<P>
<I>Ttodata</I>
returns NULL for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
On success,
if and only if
<I>lenp</I>
is non-NULL,
<B>*lenp</B>
is set to the number of bytes required to contain the full untruncated result.
It is the caller's responsibility to check this against
<I>dstlen</I>
to determine whether he has obtained a complete result.
The
<B>*lenp</B>
value is correct even if
<I>dstlen</I>
is zero, which offers a way to determine how much space would be needed
before having to allocate any.
<P>
<I>Ttodatav</I>
is just like
<I>ttodata</I>
except that in certain cases,
if
<I>errp</I>
is non-NULL,
the buffer pointed to by
<I>errp</I>
(whose length is given by
<I>errlen</I>)
is used to hold a more detailed error message.
The return value is NULL for success,
and is either
<I>errp</I>
or a pointer to a string literal for failure.
If the size of the error-message buffer is
inadequate for the desired message,
<I>ttodatav</I>
will fall back on returning a pointer to a literal string instead.
The
<I>freeswan.h</I>
header file defines a constant
<B>TTODATAV_BUF</B>
which is the size of a buffer large enough for worst-case results.
<P>
The normal return value of
<I>datatot</I>
is the number of bytes required
to contain the full untruncated result.
It is the caller's responsibility to check this against
<I>dstlen</I>
to determine whether he has obtained a complete result.
The return value is correct even if
<I>dstlen</I>
is zero, which offers a way to determine how much space would be needed
before having to allocate any.
A return value of
<B>0</B>
signals a fatal error of some kind
(see DIAGNOSTICS).
<P>
A zero value for
<I>srclen</I>
in
<I>ttodata</I>
(but not
<I>datatot</I>!)
is synonymous with
<B>strlen(src)</B>.
A non-zero
<I>srclen</I>
in
<I>ttodata</I>
must not include the terminating NUL.
<P>
Unless
<I>dstlen</I>
is zero,
the result supplied by
<I>datatot</I>
is always NUL-terminated,
and its needed-size return value includes space for the terminating NUL.
<P>
Several obsolete variants of these functions
(<I>atodata</I>,
<I>datatoa</I>,
<I>atobytes</I>,
and
<I>bytestoa</I>)
are temporarily also supported.
<A NAME="lbAE"> </A>
<H2>SEE ALSO</H2>
<A HREF="sprintf.3.html">sprintf</A>(3), <A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A>(3)
<A NAME="lbAF"> </A>
<H2>DIAGNOSTICS</H2>
Fatal errors in
<I>ttodata</I>
and
<I>ttodatav</I>
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.
<P>
Fatal errors in
<I>datatot</I>
are:
unknown format code;
zero-length input.
<A NAME="lbAG"> </A>
<H2>HISTORY</H2>
Written for the FreeS/WAN project by Henry Spencer.
<A NAME="lbAH"> </A>
<H2>BUGS</H2>
<I>Datatot</I>
should have a format code to produce character-text output.
<P>
The
<B>0s</B>
and
<B>0t</B>
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
<B>0b</B>
for binary)
and possible confusion with unprefixed hexadecimal.
<P>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">SEE ALSO</A><DD>
<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
<DT><A HREF="#lbAG">HISTORY</A><DD>
<DT><A HREF="#lbAH">BUGS</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 21:40:17 GMT, November 11, 2003
</BODY>
</HTML>
|
