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