linux/lib/libfreeswan/ttodata.3

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