freeswan/doc/manpage.d/ipsec_initsaid.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: 27 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 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 and
 164 <B>%trap</B>
 165
 166 signify special ``magic'' SAs used to indicate that packets should be
 167 passed, dropped, rejected (dropped with ICMP notification),
 168 held,
 169 and trapped (sent up to
 170 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8))
 171
 172 respectively.
 173 These forms too are known to both routines,
 174 so the internal representation of the magic SAs should never be visible.
 175 <P>
 176
 177 The
 178 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 179
 180 header file supplies the
 181 <B>ip_said</B>
 182
 183 structure, as well as a data type
 184 <B>ipsec_spi_t</B>
 185
 186 which is an unsigned 32-bit integer.
 187 (There is no consistency between kernel and user on what such a type
 188 is called, hence the header hides the differences.)
 189 <P>
 190
 191 The protocol code uses the same numbers that IP does.
 192 For user convenience, given the difficulty in acquiring the exact set of
 193 protocol names used by the kernel,
 194 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 195
 196 defines the names
 197 <B>SA_ESP</B>,
 198
 199 <B>SA_AH</B>,
 200
 201 <B>SA_IPIP</B>,
 202
 203 and
 204 <B>SA_COMP</B>
 205
 206 to have the same values as the kernel names
 207 <B>IPPROTO_ESP</B>,
 208
 209 <B>IPPROTO_AH</B>,
 210
 211 <B>IPPROTO_IPIP</B>,
 212
 213 and
 214 <B>IPPROTO_COMP</B>.
 215
 216 <P>
 217
 218 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 219
 220 also defines
 221 <B>SA_INT</B>
 222
 223 to have the value
 224 <B>61</B>
 225
 226 (reserved by IANA for ``any host internal protocol'')
 227 and
 228 <B>SPI_PASS</B>,
 229
 230 <B>SPI_DROP</B>,
 231
 232 <B>SPI_REJECT</B>,
 233
 234 <B>SPI_HOLD</B>,
 235
 236 and
 237 <B>SPI_TRAP</B>
 238
 239 to have the values 256-260 (in <I>host</I> byte order) respectively.
 240 These are used in constructing the magic SAs
 241 (which always have address
 242 <B>0.0.0.0</B>).
 243
 244 <P>
 245
 246 If
 247 <I>satot</I>
 248
 249 encounters an unknown protocol code, e.g. 77,
 250 it yields output using a prefix
 251 showing the code numerically, e.g. ``unk77''.
 252 This form is
 253 <I>not</I>
 254
 255 recognized by
 256 <I>ttosa</I>.
 257
 258 <P>
 259
 260 The
 261 <I>srclen</I>
 262
 263 parameter of
 264 <I>ttosa</I>
 265
 266 specifies the length of the string pointed to by
 267 <I>src</I>;
 268
 269 it is an error for there to be anything else
 270 (e.g., a terminating NUL) within that length.
 271 As a convenience for cases where an entire NUL-terminated string is
 272 to be converted,
 273 a
 274 <I>srclen</I>
 275
 276 value of
 277 <B>0</B>
 278
 279 is taken to mean
 280 <B>strlen(src)</B>.
 281
 282 <P>
 283
 284 The
 285 <I>dstlen</I>
 286
 287 parameter of
 288 <I>satot</I>
 289
 290 specifies the size of the
 291 <I>dst</I>
 292
 293 parameter;
 294 under no circumstances are more than
 295 <I>dstlen</I>
 296
 297 bytes written to
 298 <I>dst</I>.
 299
 300 A result which will not fit is truncated.
 301 <I>Dstlen</I>
 302
 303 can be zero, in which case
 304 <I>dst</I>
 305
 306 need not be valid and no result is written,
 307 but the return value is unaffected;
 308 in all other cases, the (possibly truncated) result is NUL-terminated.
 309 The
 310 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 311
 312 header file defines a constant,
 313 <B>SATOT_BUF</B>,
 314
 315 which is the size of a buffer just large enough for worst-case results.
 316 <P>
 317
 318 The
 319 <I>format</I>
 320
 321 parameter of
 322 <I>satot</I>
 323
 324 specifies what format is to be used for the conversion.
 325 The value
 326 <B>0</B>
 327
 328 (not the ASCII character
 329 <B>'0'</B>,
 330
 331 but a zero value)
 332 specifies a reasonable default
 333 (currently
 334 lowercase protocol prefix, lowercase hexadecimal SPI,
 335 dotted-decimal or colon-hex address).
 336 The value
 337 <B>'f'</B>
 338
 339 is similar except that the SPI is padded with
 340 <B>0</B>s
 341
 342 to a fixed 32-bit width, to ease aligning displayed tables.
 343 <P>
 344
 345 <I>Ttosa</I>
 346
 347 returns
 348 <B>NULL</B>
 349
 350 for success and
 351 a pointer to a string-literal error message for failure;
 352 see DIAGNOSTICS.
 353 <I>Satot</I>
 354
 355 returns
 356 <B>0</B>
 357
 358 for a failure, and otherwise
 359 always returns the size of buffer which would
 360 be needed to
 361 accommodate the full conversion result, including terminating NUL;
 362 it is the caller's responsibility to check this against the size of
 363 the provided buffer to determine whether truncation has occurred.
 364 <P>
 365
 366 There is also, temporarily, support for some obsolete
 367 forms of SA specifier which lack the address-family indicator.
 368 <A NAME="lbAE">&nbsp;</A>
 369 <H2>SEE ALSO</H2>
 370
 371 <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)
 372 <A NAME="lbAF">&nbsp;</A>
 373 <H2>DIAGNOSTICS</H2>
 374
 375 Fatal errors in
 376 <I>ttosa</I>
 377
 378 are:
 379 empty input;
 380 input too small to be a legal SA specifier;
 381 no
 382 <B>@</B>
 383
 384 in input;
 385 unknown protocol prefix;
 386 conversion error in
 387 <I>ttoul</I>
 388
 389 or
 390 <I>ttoaddr</I>.
 391
 392 <P>
 393
 394 Fatal errors in
 395 <I>satot</I>
 396
 397 are:
 398 unknown format.
 399 <A NAME="lbAG">&nbsp;</A>
 400 <H2>HISTORY</H2>
 401
 402 Written for the FreeS/WAN project by Henry Spencer.
 403 <A NAME="lbAH">&nbsp;</A>
 404 <H2>BUGS</H2>
 405
 406 The restriction of text-to-binary error reports to literal strings
 407 (so that callers don't need to worry about freeing them or copying them)
 408 does limit the precision of error reporting.
 409 <P>
 410
 411 The text-to-binary error-reporting convention lends itself
 412 to slightly obscure code,
 413 because many readers will not think of NULL as signifying success.
 414 A good way to make it clearer is to write something like:
 415 <P>
 416
 417 <DL COMPACT><DT><DD>
 418 <PRE>
 419 <B>const char *error;</B>
 420
 421 <B>error = ttosa( /* ... */ );</B>
 422 <B>if (error != NULL) {</B>
 423 <B>        /* something went wrong */</B>
 424 </PRE>
 425
 426 </DL>
 427
 428 <P>
 429
 430 <HR>
 431 <A NAME="index">&nbsp;</A><H2>Index</H2>
 432 <DL>
 433 <DT><A HREF="#lbAB">NAME</A><DD>
 434 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 435 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 436 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 437 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 438 <DT><A HREF="#lbAG">HISTORY</A><DD>
 439 <DT><A HREF="#lbAH">BUGS</A><DD>
 440 </DL>
 441 <HR>
 442 This document was created by
 443 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 444 using the manual pages.<BR>
 445 Time: 05:09:31 GMT, June 19, 2001
 446 </BODY>
 447 </HTML>