doc/manpage.d/ipsec_satot.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOSA</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_TTOSA</H1>
   6 Section: C Library Functions (3)<BR>Updated: 26 Nov 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 ttosa, satot - convert IPsec Security Association IDs to and from text
  14 <BR>
  15
  16 ipsec initsaid - initialize an SA ID
  17 <A NAME="lbAC">&nbsp;</A>
  18 <H2>SYNOPSIS</H2>
  19
  20 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  21
  22 <P>
  23 <B>typedef struct {</B>
  24
  25 <BR>
  26 &nbsp;
  27 <B>ip_address dst;</B>
  28
  29 <BR>
  30 &nbsp;
  31 <B>ipsec_spi_t spi;</B>
  32
  33 <BR>
  34 &nbsp;
  35 <B>int proto;</B>
  36
  37 <BR>
  38
  39 <B>} ip_said;</B>
  40
  41 <P>
  42 <B>const char *ttosa(const char *src, size_t srclen,</B>
  43
  44 <BR>
  45 &nbsp;
  46 <B>ip_said *sa);</B>
  47
  48 <BR>
  49
  50 <B>size_t satot(const ip_said *sa, int format,</B>
  51
  52 <BR>
  53 &nbsp;
  54 <B>char *dst, size_t dstlen);</B>
  55
  56 <BR>
  57
  58 <B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B>
  59
  60 <BR>
  61 &nbsp;
  62 <B>int proto, ip_said *dst);</B>
  63
  64 <A NAME="lbAD">&nbsp;</A>
  65 <H2>DESCRIPTION</H2>
  66
  67 <I>Ttosa</I>
  68
  69 converts an ASCII Security Association (SA) specifier into an
  70 <B>ip_said</B>
  71
  72 structure (containing
  73 a destination-host address
  74 in network byte order,
  75 an SPI number in network byte order, and
  76 a protocol code).
  77 <I>Satot</I>
  78
  79 does the reverse conversion, back to a text SA specifier.
  80 <I>Initsaid</I>
  81
  82 initializes an
  83 <B>ip_said</B>
  84
  85 from separate items of information.
  86 <P>
  87
  88 An SA is specified in text with a mail-like syntax, e.g.
  89 <B><A HREF="mailto:esp.5a7@1.2.3.4">esp.5a7@1.2.3.4</A></B>.
  90
  91 An SA specifier contains
  92 a protocol prefix (currently
  93 <B>ah</B>,
  94
  95 <B>esp</B>,
  96
  97 <B>tun</B>,
  98
  99 <B>comp</B>,
 100
 101 or
 102 <B>int</B>),
 103
 104 a single character indicating the address family
 105 (<B>.</B>
 106
 107 for IPv4,
 108 <B>:</B>
 109
 110 for IPv6),
 111 an unsigned integer SPI number in hexadecimal (with no
 112 <B>0x</B>
 113
 114 prefix),
 115 and an IP address.
 116 The IP address can be any form accepted by
 117 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3),
 118
 119 e.g. dotted-decimal IPv4 address,
 120 colon-hex IPv6 address,
 121 or DNS name.
 122 <P>
 123
 124 As a special case, the SA specifier
 125 <B>%passthrough4</B>
 126
 127 or
 128 <B>%passthrough6</B>
 129
 130 signifies the special SA used to indicate that packets should be
 131 passed through unaltered.
 132 (At present, these are synonyms for
 133 <B><A HREF="mailto:tun.0@0.0.0.0">tun.0@0.0.0.0</A></B>
 134
 135 and
 136 <B>tun:0@::</B>
 137
 138 respectively,
 139 but that is subject to change without notice.)
 140 <B>%passthrough</B>
 141
 142 is a historical synonym for
 143 <B>%passthrough4</B>.
 144
 145 These forms are known to both
 146 <I>ttosa</I>
 147
 148 and
 149 <I>satot</I>,
 150
 151 so the internal representation is never visible.
 152 <P>
 153
 154 Similarly, the SA specifiers
 155 <B>%pass</B>,
 156
 157 <B>%drop</B>,
 158
 159 <B>%reject</B>,
 160
 161 <B>%hold</B>,
 162
 163 <B>%trap</B>,
 164
 165 and
 166 <B>%trapsubnet</B>
 167
 168 signify special ``magic'' SAs used to indicate that packets should be
 169 passed, dropped, rejected (dropped with ICMP notification),
 170 held,
 171 and trapped (sent up to
 172 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
 173
 174 with either of two forms of
 175 <B>%hold</B>
 176
 177 automatically installed)
 178 respectively.
 179 These forms too are known to both routines,
 180 so the internal representation of the magic SAs should never be visible.
 181 <P>
 182
 183 The
 184 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 185
 186 header file supplies the
 187 <B>ip_said</B>
 188
 189 structure, as well as a data type
 190 <B>ipsec_spi_t</B>
 191
 192 which is an unsigned 32-bit integer.
 193 (There is no consistency between kernel and user on what such a type
 194 is called, hence the header hides the differences.)
 195 <P>
 196
 197 The protocol code uses the same numbers that IP does.
 198 For user convenience, given the difficulty in acquiring the exact set of
 199 protocol names used by the kernel,
 200 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 201
 202 defines the names
 203 <B>SA_ESP</B>,
 204
 205 <B>SA_AH</B>,
 206
 207 <B>SA_IPIP</B>,
 208
 209 and
 210 <B>SA_COMP</B>
 211
 212 to have the same values as the kernel names
 213 <B>IPPROTO_ESP</B>,
 214
 215 <B>IPPROTO_AH</B>,
 216
 217 <B>IPPROTO_IPIP</B>,
 218
 219 and
 220 <B>IPPROTO_COMP</B>.
 221
 222 <P>
 223
 224 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 225
 226 also defines
 227 <B>SA_INT</B>
 228
 229 to have the value
 230 <B>61</B>
 231
 232 (reserved by IANA for ``any host internal protocol'')
 233 and
 234 <B>SPI_PASS</B>,
 235
 236 <B>SPI_DROP</B>,
 237
 238 <B>SPI_REJECT</B>,
 239
 240 <B>SPI_HOLD</B>,
 241
 242 and
 243 <B>SPI_TRAP</B>
 244
 245 to have the values 256-260 (in <I>host</I> byte order) respectively.
 246 These are used in constructing the magic SAs
 247 (which always have address
 248 <B>0.0.0.0</B>).
 249
 250 <P>
 251
 252 If
 253 <I>satot</I>
 254
 255 encounters an unknown protocol code, e.g. 77,
 256 it yields output using a prefix
 257 showing the code numerically, e.g. ``unk77''.
 258 This form is
 259 <I>not</I>
 260
 261 recognized by
 262 <I>ttosa</I>.
 263
 264 <P>
 265
 266 The
 267 <I>srclen</I>
 268
 269 parameter of
 270 <I>ttosa</I>
 271
 272 specifies the length of the string pointed to by
 273 <I>src</I>;
 274
 275 it is an error for there to be anything else
 276 (e.g., a terminating NUL) within that length.
 277 As a convenience for cases where an entire NUL-terminated string is
 278 to be converted,
 279 a
 280 <I>srclen</I>
 281
 282 value of
 283 <B>0</B>
 284
 285 is taken to mean
 286 <B>strlen(src)</B>.
 287
 288 <P>
 289
 290 The
 291 <I>dstlen</I>
 292
 293 parameter of
 294 <I>satot</I>
 295
 296 specifies the size of the
 297 <I>dst</I>
 298
 299 parameter;
 300 under no circumstances are more than
 301 <I>dstlen</I>
 302
 303 bytes written to
 304 <I>dst</I>.
 305
 306 A result which will not fit is truncated.
 307 <I>Dstlen</I>
 308
 309 can be zero, in which case
 310 <I>dst</I>
 311
 312 need not be valid and no result is written,
 313 but the return value is unaffected;
 314 in all other cases, the (possibly truncated) result is NUL-terminated.
 315 The
 316 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 317
 318 header file defines a constant,
 319 <B>SATOT_BUF</B>,
 320
 321 which is the size of a buffer just large enough for worst-case results.
 322 <P>
 323
 324 The
 325 <I>format</I>
 326
 327 parameter of
 328 <I>satot</I>
 329
 330 specifies what format is to be used for the conversion.
 331 The value
 332 <B>0</B>
 333
 334 (not the ASCII character
 335 <B>'0'</B>,
 336
 337 but a zero value)
 338 specifies a reasonable default
 339 (currently
 340 lowercase protocol prefix, lowercase hexadecimal SPI,
 341 dotted-decimal or colon-hex address).
 342 The value
 343 <B>'f'</B>
 344
 345 is similar except that the SPI is padded with
 346 <B>0</B>s
 347
 348 to a fixed 32-bit width, to ease aligning displayed tables.
 349 <P>
 350
 351 <I>Ttosa</I>
 352
 353 returns
 354 <B>NULL</B>
 355
 356 for success and
 357 a pointer to a string-literal error message for failure;
 358 see DIAGNOSTICS.
 359 <I>Satot</I>
 360
 361 returns
 362 <B>0</B>
 363
 364 for a failure, and otherwise
 365 always returns the size of buffer which would
 366 be needed to
 367 accommodate the full conversion result, including terminating NUL;
 368 it is the caller's responsibility to check this against the size of
 369 the provided buffer to determine whether truncation has occurred.
 370 <P>
 371
 372 There is also, temporarily, support for some obsolete
 373 forms of SA specifier which lack the address-family indicator.
 374 <A NAME="lbAE">&nbsp;</A>
 375 <H2>SEE ALSO</H2>
 376
 377 <A HREF="ipsec_ttoul.3.html">ipsec_ttoul</A>(3), <A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A>(3), <A HREF="ipsec_samesaid.3.html">ipsec_samesaid</A>(3), <A HREF="inet.3.html">inet</A>(3)
 378 <A NAME="lbAF">&nbsp;</A>
 379 <H2>DIAGNOSTICS</H2>
 380
 381 Fatal errors in
 382 <I>ttosa</I>
 383
 384 are:
 385 empty input;
 386 input too small to be a legal SA specifier;
 387 no
 388 <B>@</B>
 389
 390 in input;
 391 unknown protocol prefix;
 392 conversion error in
 393 <I>ttoul</I>
 394
 395 or
 396 <I>ttoaddr</I>.
 397
 398 <P>
 399
 400 Fatal errors in
 401 <I>satot</I>
 402
 403 are:
 404 unknown format.
 405 <A NAME="lbAG">&nbsp;</A>
 406 <H2>HISTORY</H2>
 407
 408 Written for the FreeS/WAN project by Henry Spencer.
 409 <A NAME="lbAH">&nbsp;</A>
 410 <H2>BUGS</H2>
 411
 412 The restriction of text-to-binary error reports to literal strings
 413 (so that callers don't need to worry about freeing them or copying them)
 414 does limit the precision of error reporting.
 415 <P>
 416
 417 The text-to-binary error-reporting convention lends itself
 418 to slightly obscure code,
 419 because many readers will not think of NULL as signifying success.
 420 A good way to make it clearer is to write something like:
 421 <P>
 422
 423 <DL COMPACT><DT><DD>
 424 <PRE>
 425 <B>const char *error;</B>
 426
 427 <B>error = ttosa( /* ... */ );</B>
 428 <B>if (error != NULL) {</B>
 429 <B>        /* something went wrong */</B>
 430 </PRE>
 431
 432 </DL>
 433
 434 <P>
 435
 436 <HR>
 437 <A NAME="index">&nbsp;</A><H2>Index</H2>
 438 <DL>
 439 <DT><A HREF="#lbAB">NAME</A><DD>
 440 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 441 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 442 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 443 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 444 <DT><A HREF="#lbAG">HISTORY</A><DD>
 445 <DT><A HREF="#lbAH">BUGS</A><DD>
 446 </DL>
 447 <HR>
 448 This document was created by
 449 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 450 using the manual pages.<BR>
 451 Time: 21:40:18 GMT, November 11, 2003
 452 </BODY>
 453 </HTML>