doc/manpage.d/ipsec_ttodata.3.html

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