freeswan/lib/ttodata.3

   1 .TH IPSEC_TTODATA 3 "12 March 2002"
   2 .\" RCSID $Id: ttodata.3,v 1.4 2002/03/12 17:04:58 henry Exp $
   3 .SH NAME
   4 ipsec ttodata, datatot \- convert binary data bytes from and to text formats
   5 .SH SYNOPSIS
   6 .B "#include <freeswan.h>"
   7 .sp
   8 .B "const char *ttodata(const char *src, size_t srclen,"
   9 .ti +1c
  10 .B "int base, char *dst, size_t dstlen, size_t *lenp);"
  11 .br
  12 .B "const char *ttodatav(const char *src, size_t srclen,"
  13 .ti +1c
  14 .B "int base, char *dst, size_t dstlen, size_t *lenp,"
  15 .ti +1c
  16 .B "char *errp, size_t errlen);"
  17 .br
  18 .B "size_t datatot(const char *src, size_t srclen,"
  19 .ti +1c
  20 .B "int format, char *dst, size_t dstlen);"
  21 .SH DESCRIPTION
  22 .IR Ttodata ,
  23 .IR ttodatav ,
  24 and
  25 .I datatot
  26 convert arbitrary binary data (e.g. encryption or authentication keys)
  27 from and to more-or-less human-readable text formats.
  28 .PP
  29 Currently supported formats are hexadecimal, base64, and characters.
  30 .PP
  31 A hexadecimal text value begins with a
  32 .B 0x
  33 (or
  34 .BR 0X )
  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.
  38 A single
  39 .B _
  40 (underscore)
  41 between consecutive groups is ignored, permitting punctuation to improve
  42 readability; doing this every eight digits seems about right.
  43 .PP
  44 A base64 text value begins with a
  45 .B 0s
  46 (or
  47 .BR 0S )
  48 prefix
  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.
  52 Note that the last one or two digits of a base64 group can be
  53 .B =
  54 to indicate that fewer than three binary bytes are encoded.
  55 .PP
  56 A character text value begins with a
  57 .B 0t
  58 (or
  59 .BR 0T )
  60 prefix
  61 and continues with text characters, each being the value of one binary byte.
  62 .PP
  63 All these functions basically copy data from
  64 .I src
  65 (whose size is specified by
  66 .IR srclen )
  67 to
  68 .I dst
  69 (whose size is specified by
  70 .IR dstlen ),
  71 doing the conversion en route.
  72 If the result will not fit in
  73 .IR dst ,
  74 it is truncated;
  75 under no circumstances are more than
  76 .I dstlen
  77 bytes of result written to
  78 .IR dst .
  79 .I Dstlen
  80 can be zero, in which case
  81 .I dst
  82 need not be valid and no result bytes are written at all.
  83 .PP
  84 The
  85 .I base
  86 parameter of
  87 .I ttodata
  88 and
  89 .I ttodatav
  90 specifies what format the input is in;
  91 normally it should be
  92 .B 0
  93 to signify that this gets figured out from the prefix.
  94 Values of
  95 .BR 16 ,
  96 .BR 64 ,
  97 and
  98 .BR 256
  99 respectively signify hexadecimal, base64, and character-text formats
 100 without prefixes.
 101 .PP
 102 The
 103 .I format
 104 parameter of
 105 .IR datatot ,
 106 a single character used as a type code,
 107 specifies which text format is wanted.
 108 The value
 109 .B 0
 110 (not ASCII
 111 .BR '0' ,
 112 but a zero value) specifies a reasonable default.
 113 Other currently-supported values are:
 114 .RS 2
 115 .TP 4
 116 .B 'x'
 117 continuous lower-case hexadecimal with a
 118 .B 0x
 119 prefix
 120 .TP
 121 .B 'h'
 122 lower-case hexadecimal with a
 123 .B 0x
 124 prefix and a
 125 .B _
 126 every eight digits
 127 .TP
 128 .B 16
 129 lower-case hexadecimal with no prefix or
 130 .B _
 131 .TP
 132 .B 's'
 133 continuous base64 with a
 134 .B 0s
 135 prefix
 136 .TP
 137 .B 64
 138 continuous base64 with no prefix
 139 .RE
 140 .PP
 141 The default format is currently
 142 .BR 'h' .
 143 .PP
 144 .I Ttodata
 145 returns NULL for success and
 146 a pointer to a string-literal error message for failure;
 147 see DIAGNOSTICS.
 148 On success,
 149 if and only if
 150 .I lenp
 151 is non-NULL,
 152 .B *lenp
 153 is set to the number of bytes required to contain the full untruncated result.
 154 It is the caller's responsibility to check this against
 155 .I dstlen
 156 to determine whether he has obtained a complete result.
 157 The
 158 .B *lenp
 159 value is correct even if
 160 .I dstlen
 161 is zero, which offers a way to determine how much space would be needed
 162 before having to allocate any.
 163 .PP
 164 .I Ttodatav
 165 is just like
 166 .I ttodata
 167 except that in certain cases,
 168 if
 169 .I errp
 170 is non-NULL,
 171 the buffer pointed to by
 172 .I errp
 173 (whose length is given by
 174 .IR errlen )
 175 is used to hold a more detailed error message.
 176 The return value is NULL for success,
 177 and is either
 178 .I errp
 179 or a pointer to a string literal for failure.
 180 If the size of the error-message buffer is
 181 inadequate for the desired message,
 182 .I ttodatav
 183 will fall back on returning a pointer to a literal string instead.
 184 The
 185 .I freeswan.h
 186 header file defines a constant
 187 .B TTODATAV_BUF
 188 which is the size of a buffer large enough for worst-case results.
 189 .PP
 190 The normal return value of
 191 .IR datatot
 192 is the number of bytes required
 193 to contain the full untruncated result.
 194 It is the caller's responsibility to check this against
 195 .I dstlen
 196 to determine whether he has obtained a complete result.
 197 The return value is correct even if
 198 .I dstlen
 199 is zero, which offers a way to determine how much space would be needed
 200 before having to allocate any.
 201 A return value of
 202 .B 0
 203 signals a fatal error of some kind
 204 (see DIAGNOSTICS).
 205 .PP
 206 A zero value for
 207 .I srclen
 208 in
 209 .I ttodata
 210 (but not
 211 .IR datatot !)
 212 is synonymous with
 213 .BR strlen(src) .
 214 A non-zero
 215 .I srclen
 216 in
 217 .I ttodata
 218 must not include the terminating NUL.
 219 .PP
 220 Unless
 221 .I dstlen
 222 is zero,
 223 the result supplied by
 224 .I datatot
 225 is always NUL-terminated,
 226 and its needed-size return value includes space for the terminating NUL.
 227 .PP
 228 Several obsolete variants of these functions
 229 .RI ( atodata ,
 230 .IR datatoa ,
 231 .IR atobytes ,
 232 and
 233 .IR bytestoa )
 234 are temporarily also supported.
 235 .SH SEE ALSO
 236 sprintf(3), ipsec_atoaddr(3)
 237 .SH DIAGNOSTICS
 238 Fatal errors in
 239 .I ttodata
 240 and
 241 .I ttodatav
 242 are:
 243 unknown characters in the input;
 244 unknown or missing prefix;
 245 unknown base;
 246 incomplete digit group;
 247 non-zero padding in a base64 less-than-three-bytes digit group;
 248 zero-length input.
 249 .PP
 250 Fatal errors in
 251 .I datatot
 252 are:
 253 unknown format code;
 254 zero-length input.
 255 .SH HISTORY
 256 Written for the FreeS/WAN project by Henry Spencer.
 257 .SH BUGS
 258 .I Datatot
 259 should have a format code to produce character-text output.
 260 .PP
 261 The
 262 .B 0s
 263 and
 264 .B 0t
 265 prefixes are the author's inventions and are not a standard
 266 of any kind.
 267 They have been chosen to avoid collisions with existing practice
 268 (some C implementations use
 269 .B 0b
 270 for binary)
 271 and possible confusion with unprefixed hexadecimal.