1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOSA</TITLE>
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>
10 <A NAME="lbAB"> </A>
13 ipsec ttosa, satot - convert IPSEC Security Association IDs to and from text
16 ipsec initsaid - initialize an SA ID
17 <A NAME="lbAC"> </A>
20 <B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
23 <B>typedef struct {</B>
27 <B>ip_address dst;</B>
31 <B>ipsec_spi_t spi;</B>
42 <B>const char *ttosa(const char *src, size_t srclen,</B>
50 <B>size_t satot(const ip_said *sa, int format,</B>
54 <B>char *dst, size_t dstlen);</B>
58 <B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B>
62 <B>int proto, ip_said *dst);</B>
64 <A NAME="lbAD"> </A>
69 converts an ASCII Security Association (SA) specifier into an
73 a destination-host address
74 in network byte order,
75 an SPI number in network byte order, and
79 does the reverse conversion, back to a text SA specifier.
85 from separate items of information.
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>.
91 An SA specifier contains
92 a protocol prefix (currently
104 a single character indicating the address family
111 an unsigned integer SPI number in hexadecimal (with no
116 The IP address can be any form accepted by
117 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3),
119 e.g. dotted-decimal IPv4 address,
120 colon-hex IPv6 address,
124 As a special case, the SA specifier
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>
139 but that is subject to change without notice.)
142 is a historical synonym for
143 <B>%passthrough4</B>.
145 These forms are known to both
151 so the internal representation is never visible.
154 Similarly, the SA specifiers
166 signify special ``magic'' SAs used to indicate that packets should be
167 passed, dropped, rejected (dropped with ICMP notification),
169 and trapped (sent up to
170 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8))
173 These forms too are known to both routines,
174 so the internal representation of the magic SAs should never be visible.
178 <B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
180 header file supplies the
183 structure, as well as a data type
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.)
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><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
206 to have the same values as the kernel names
218 <B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
226 (reserved by IANA for ``any host internal protocol'')
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
249 encounters an unknown protocol code, e.g. 77,
250 it yields output using a prefix
251 showing the code numerically, e.g. ``unk77''.
266 specifies the length of the string pointed to by
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
290 specifies the size of the
294 under no circumstances are more than
300 A result which will not fit is truncated.
303 can be zero, in which case
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.
310 <B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
312 header file defines a constant,
315 which is the size of a buffer just large enough for worst-case results.
324 specifies what format is to be used for the conversion.
328 (not the ASCII character
332 specifies a reasonable default
334 lowercase protocol prefix, lowercase hexadecimal SPI,
335 dotted-decimal or colon-hex address).
339 is similar except that the SPI is padded with
342 to a fixed 32-bit width, to ease aligning displayed tables.
351 a pointer to a string-literal error message for failure;
358 for a failure, and otherwise
359 always returns the size of buffer which would
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.
366 There is also, temporarily, support for some obsolete
367 forms of SA specifier which lack the address-family indicator.
368 <A NAME="lbAE"> </A>
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"> </A>
380 input too small to be a legal SA specifier;
385 unknown protocol prefix;
399 <A NAME="lbAG"> </A>
402 Written for the FreeS/WAN project by Henry Spencer.
403 <A NAME="lbAH"> </A>
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.
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:
419 <B>const char *error;</B>
421 <B>error = ttosa( /* ... */ );</B>
422 <B>if (error != NULL) {</B>
423 <B> /* something went wrong */</B>
431 <A NAME="index"> </A><H2>Index</H2>
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>
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:34 GMT, June 19, 2001