linux/lib/libfreeswan/ttosa.3

   1 .TH IPSEC_TTOSA 3 "26 Nov 2001"
   2 .\" RCSID $Id: ttosa.3,v 1.1 2004/03/15 20:35:26 as Exp $
   3 .SH NAME
   4 ipsec ttosa, satot \- convert IPsec Security Association IDs to and from text
   5 .br
   6 ipsec initsaid \- initialize an SA ID
   7 .SH SYNOPSIS
   8 .B "#include <freeswan.h>
   9 .sp
  10 .B "typedef struct {"
  11 .ti +1c
  12 .B "ip_address dst;"
  13 .ti +1c
  14 .B "ipsec_spi_t spi;"
  15 .ti +1c
  16 .B "int proto;"
  17 .br
  18 .B "} ip_said;"
  19 .sp
  20 .B "const char *ttosa(const char *src, size_t srclen,"
  21 .ti +1c
  22 .B "ip_said *sa);
  23 .br
  24 .B "size_t satot(const ip_said *sa, int format,"
  25 .ti +1c
  26 .B "char *dst, size_t dstlen);"
  27 .br
  28 .B "void initsaid(const ip_address *addr, ipsec_spi_t spi,"
  29 .ti +1c
  30 .B "int proto, ip_said *dst);"
  31 .SH DESCRIPTION
  32 .I Ttosa
  33 converts an ASCII Security Association (SA) specifier into an
  34 .B ip_said
  35 structure (containing
  36 a destination-host address
  37 in network byte order,
  38 an SPI number in network byte order, and
  39 a protocol code).
  40 .I Satot
  41 does the reverse conversion, back to a text SA specifier.
  42 .I Initsaid
  43 initializes an
  44 .B ip_said
  45 from separate items of information.
  46 .PP
  47 An SA is specified in text with a mail-like syntax, e.g.
  48 .BR esp.5a7@1.2.3.4 .
  49 An SA specifier contains
  50 a protocol prefix (currently
  51 .BR ah ,
  52 .BR esp ,
  53 .BR tun ,
  54 .BR comp ,
  55 or
  56 .BR int ),
  57 a single character indicating the address family
  58 .RB ( .
  59 for IPv4,
  60 .B :
  61 for IPv6),
  62 an unsigned integer SPI number in hexadecimal (with no
  63 .B 0x
  64 prefix),
  65 and an IP address.
  66 The IP address can be any form accepted by
  67 .IR ipsec_ttoaddr (3),
  68 e.g. dotted-decimal IPv4 address,
  69 colon-hex IPv6 address,
  70 or DNS name.
  71 .PP
  72 As a special case, the SA specifier
  73 .B %passthrough4
  74 or
  75 .B %passthrough6
  76 signifies the special SA used to indicate that packets should be
  77 passed through unaltered.
  78 (At present, these are synonyms for
  79 .B tun.0@0.0.0.0
  80 and
  81 .B tun:0@::
  82 respectively,
  83 but that is subject to change without notice.)
  84 .B %passthrough
  85 is a historical synonym for
  86 .BR %passthrough4 .
  87 These forms are known to both
  88 .I ttosa
  89 and
  90 .IR satot ,
  91 so the internal representation is never visible.
  92 .PP
  93 Similarly, the SA specifiers
  94 .BR %pass ,
  95 .BR %drop ,
  96 .BR %reject ,
  97 .BR %hold ,
  98 .BR %trap ,
  99 and
 100 .BR %trapsubnet
 101 signify special ``magic'' SAs used to indicate that packets should be
 102 passed, dropped, rejected (dropped with ICMP notification),
 103 held,
 104 and trapped (sent up to
 105 .IR ipsec_pluto (8),
 106 with either of two forms of
 107 .B %hold
 108 automatically installed)
 109 respectively.
 110 These forms too are known to both routines,
 111 so the internal representation of the magic SAs should never be visible.
 112 .PP
 113 The
 114 .B <freeswan.h>
 115 header file supplies the
 116 .B ip_said
 117 structure, as well as a data type
 118 .B ipsec_spi_t
 119 which is an unsigned 32-bit integer.
 120 (There is no consistency between kernel and user on what such a type
 121 is called, hence the header hides the differences.)
 122 .PP
 123 The protocol code uses the same numbers that IP does.
 124 For user convenience, given the difficulty in acquiring the exact set of
 125 protocol names used by the kernel,
 126 .B <freeswan.h>
 127 defines the names
 128 .BR SA_ESP ,
 129 .BR SA_AH ,
 130 .BR SA_IPIP ,
 131 and
 132 .BR SA_COMP
 133 to have the same values as the kernel names
 134 .BR IPPROTO_ESP ,
 135 .BR IPPROTO_AH ,
 136 .BR IPPROTO_IPIP ,
 137 and
 138 .BR IPPROTO_COMP .
 139 .PP
 140 .B <freeswan.h>
 141 also defines
 142 .BR SA_INT
 143 to have the value
 144 .BR 61
 145 (reserved by IANA for ``any host internal protocol'')
 146 and
 147 .BR SPI_PASS ,
 148 .BR SPI_DROP ,
 149 .BR SPI_REJECT ,
 150 .BR SPI_HOLD ,
 151 and
 152 .B SPI_TRAP
 153 to have the values 256-260 (in \fIhost\fR byte order) respectively.
 154 These are used in constructing the magic SAs
 155 (which always have address
 156 .BR 0.0.0.0 ).
 157 .PP
 158 If
 159 .I satot
 160 encounters an unknown protocol code, e.g. 77,
 161 it yields output using a prefix
 162 showing the code numerically, e.g. ``unk77''.
 163 This form is
 164 .I not
 165 recognized by
 166 .IR ttosa .
 167 .PP
 168 The
 169 .I srclen
 170 parameter of
 171 .I ttosa
 172 specifies the length of the string pointed to by
 173 .IR src ;
 174 it is an error for there to be anything else
 175 (e.g., a terminating NUL) within that length.
 176 As a convenience for cases where an entire NUL-terminated string is
 177 to be converted,
 178 a
 179 .I srclen
 180 value of
 181 .B 0
 182 is taken to mean
 183 .BR strlen(src) .
 184 .PP
 185 The
 186 .I dstlen
 187 parameter of
 188 .I satot
 189 specifies the size of the
 190 .I dst
 191 parameter;
 192 under no circumstances are more than
 193 .I dstlen
 194 bytes written to
 195 .IR dst .
 196 A result which will not fit is truncated.
 197 .I Dstlen
 198 can be zero, in which case
 199 .I dst
 200 need not be valid and no result is written,
 201 but the return value is unaffected;
 202 in all other cases, the (possibly truncated) result is NUL-terminated.
 203 The
 204 .B <freeswan.h>
 205 header file defines a constant,
 206 .BR SATOT_BUF ,
 207 which is the size of a buffer just large enough for worst-case results.
 208 .PP
 209 The
 210 .I format
 211 parameter of
 212 .I satot
 213 specifies what format is to be used for the conversion.
 214 The value
 215 .B 0
 216 (not the ASCII character
 217 .BR '0' ,
 218 but a zero value)
 219 specifies a reasonable default
 220 (currently
 221 lowercase protocol prefix, lowercase hexadecimal SPI,
 222 dotted-decimal or colon-hex address).
 223 The value
 224 .B 'f'
 225 is similar except that the SPI is padded with
 226 .BR 0 s
 227 to a fixed 32-bit width, to ease aligning displayed tables.
 228 .PP
 229 .I Ttosa
 230 returns
 231 .B NULL
 232 for success and
 233 a pointer to a string-literal error message for failure;
 234 see DIAGNOSTICS.
 235 .I Satot
 236 returns
 237 .B 0
 238 for a failure, and otherwise
 239 always returns the size of buffer which would
 240 be needed to
 241 accommodate the full conversion result, including terminating NUL;
 242 it is the caller's responsibility to check this against the size of
 243 the provided buffer to determine whether truncation has occurred.
 244 .PP
 245 There is also, temporarily, support for some obsolete
 246 forms of SA specifier which lack the address-family indicator.
 247 .SH SEE ALSO
 248 ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3)
 249 .SH DIAGNOSTICS
 250 Fatal errors in
 251 .I ttosa
 252 are:
 253 empty input;
 254 input too small to be a legal SA specifier;
 255 no
 256 .B @
 257 in input;
 258 unknown protocol prefix;
 259 conversion error in
 260 .I ttoul
 261 or
 262 .IR ttoaddr .
 263 .PP
 264 Fatal errors in
 265 .I satot
 266 are:
 267 unknown format.
 268 .SH HISTORY
 269 Written for the FreeS/WAN project by Henry Spencer.
 270 .SH BUGS
 271 The restriction of text-to-binary error reports to literal strings
 272 (so that callers don't need to worry about freeing them or copying them)
 273 does limit the precision of error reporting.
 274 .PP
 275 The text-to-binary error-reporting convention lends itself
 276 to slightly obscure code,
 277 because many readers will not think of NULL as signifying success.
 278 A good way to make it clearer is to write something like:
 279 .PP
 280 .RS
 281 .nf
 282 .B "const char *error;"
 283 .sp
 284 .B "error = ttosa( /* ... */ );"
 285 .B "if (error != NULL) {"
 286 .B "        /* something went wrong */"
 287 .fi
 288 .RE