diff options
Diffstat (limited to 'doc/manpage.d/ipsec_satot.3.html')
| -rw-r--r-- | doc/manpage.d/ipsec_satot.3.html | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/doc/manpage.d/ipsec_satot.3.html b/doc/manpage.d/ipsec_satot.3.html new file mode 100644 index 000000000..1e457fc24 --- /dev/null +++ b/doc/manpage.d/ipsec_satot.3.html @@ -0,0 +1,453 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of IPSEC_TTOSA</TITLE> +</HEAD><BODY> +<H1>IPSEC_TTOSA</H1> +Section: C Library Functions (3)<BR>Updated: 26 Nov 2001<BR><A HREF="#index">Index</A> +<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> + + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +ipsec ttosa, satot - convert IPsec Security Association IDs to and from text +<BR> + +ipsec initsaid - initialize an SA ID +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +<P> +<B>typedef struct {</B> + +<BR> + +<B>ip_address dst;</B> + +<BR> + +<B>ipsec_spi_t spi;</B> + +<BR> + +<B>int proto;</B> + +<BR> + +<B>} ip_said;</B> + +<P> +<B>const char *ttosa(const char *src, size_t srclen,</B> + +<BR> + +<B>ip_said *sa);</B> + +<BR> + +<B>size_t satot(const ip_said *sa, int format,</B> + +<BR> + +<B>char *dst, size_t dstlen);</B> + +<BR> + +<B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B> + +<BR> + +<B>int proto, ip_said *dst);</B> + +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<I>Ttosa</I> + +converts an ASCII Security Association (SA) specifier into an +<B>ip_said</B> + +structure (containing +a destination-host address +in network byte order, +an SPI number in network byte order, and +a protocol code). +<I>Satot</I> + +does the reverse conversion, back to a text SA specifier. +<I>Initsaid</I> + +initializes an +<B>ip_said</B> + +from separate items of information. +<P> + +An SA is specified in text with a mail-like syntax, e.g. +<B><A HREF="mailto:esp.5a7@1.2.3.4">esp.5a7@1.2.3.4</A></B>. + +An SA specifier contains +a protocol prefix (currently +<B>ah</B>, + +<B>esp</B>, + +<B>tun</B>, + +<B>comp</B>, + +or +<B>int</B>), + +a single character indicating the address family +(<B>.</B> + +for IPv4, +<B>:</B> + +for IPv6), +an unsigned integer SPI number in hexadecimal (with no +<B>0x</B> + +prefix), +and an IP address. +The IP address can be any form accepted by +<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3), + +e.g. dotted-decimal IPv4 address, +colon-hex IPv6 address, +or DNS name. +<P> + +As a special case, the SA specifier +<B>%passthrough4</B> + +or +<B>%passthrough6</B> + +signifies the special SA used to indicate that packets should be +passed through unaltered. +(At present, these are synonyms for +<B><A HREF="mailto:tun.0@0.0.0.0">tun.0@0.0.0.0</A></B> + +and +<B>tun:0@::</B> + +respectively, +but that is subject to change without notice.) +<B>%passthrough</B> + +is a historical synonym for +<B>%passthrough4</B>. + +These forms are known to both +<I>ttosa</I> + +and +<I>satot</I>, + +so the internal representation is never visible. +<P> + +Similarly, the SA specifiers +<B>%pass</B>, + +<B>%drop</B>, + +<B>%reject</B>, + +<B>%hold</B>, + +<B>%trap</B>, + +and +<B>%trapsubnet</B> + +signify special ``magic'' SAs used to indicate that packets should be +passed, dropped, rejected (dropped with ICMP notification), +held, +and trapped (sent up to +<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8), + +with either of two forms of +<B>%hold</B> + +automatically installed) +respectively. +These forms too are known to both routines, +so the internal representation of the magic SAs should never be visible. +<P> + +The +<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +header file supplies the +<B>ip_said</B> + +structure, as well as a data type +<B>ipsec_spi_t</B> + +which is an unsigned 32-bit integer. +(There is no consistency between kernel and user on what such a type +is called, hence the header hides the differences.) +<P> + +The protocol code uses the same numbers that IP does. +For user convenience, given the difficulty in acquiring the exact set of +protocol names used by the kernel, +<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +defines the names +<B>SA_ESP</B>, + +<B>SA_AH</B>, + +<B>SA_IPIP</B>, + +and +<B>SA_COMP</B> + +to have the same values as the kernel names +<B>IPPROTO_ESP</B>, + +<B>IPPROTO_AH</B>, + +<B>IPPROTO_IPIP</B>, + +and +<B>IPPROTO_COMP</B>. + +<P> + +<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +also defines +<B>SA_INT</B> + +to have the value +<B>61</B> + +(reserved by IANA for ``any host internal protocol'') +and +<B>SPI_PASS</B>, + +<B>SPI_DROP</B>, + +<B>SPI_REJECT</B>, + +<B>SPI_HOLD</B>, + +and +<B>SPI_TRAP</B> + +to have the values 256-260 (in <I>host</I> byte order) respectively. +These are used in constructing the magic SAs +(which always have address +<B>0.0.0.0</B>). + +<P> + +If +<I>satot</I> + +encounters an unknown protocol code, e.g. 77, +it yields output using a prefix +showing the code numerically, e.g. ``unk77''. +This form is +<I>not</I> + +recognized by +<I>ttosa</I>. + +<P> + +The +<I>srclen</I> + +parameter of +<I>ttosa</I> + +specifies the length of the string pointed to by +<I>src</I>; + +it is an error for there to be anything else +(e.g., a terminating NUL) within that length. +As a convenience for cases where an entire NUL-terminated string is +to be converted, +a +<I>srclen</I> + +value of +<B>0</B> + +is taken to mean +<B>strlen(src)</B>. + +<P> + +The +<I>dstlen</I> + +parameter of +<I>satot</I> + +specifies the size of the +<I>dst</I> + +parameter; +under no circumstances are more than +<I>dstlen</I> + +bytes written to +<I>dst</I>. + +A result which will not fit is truncated. +<I>Dstlen</I> + +can be zero, in which case +<I>dst</I> + +need not be valid and no result is written, +but the return value is unaffected; +in all other cases, the (possibly truncated) result is NUL-terminated. +The +<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +header file defines a constant, +<B>SATOT_BUF</B>, + +which is the size of a buffer just large enough for worst-case results. +<P> + +The +<I>format</I> + +parameter of +<I>satot</I> + +specifies what format is to be used for the conversion. +The value +<B>0</B> + +(not the ASCII character +<B>'0'</B>, + +but a zero value) +specifies a reasonable default +(currently +lowercase protocol prefix, lowercase hexadecimal SPI, +dotted-decimal or colon-hex address). +The value +<B>'f'</B> + +is similar except that the SPI is padded with +<B>0</B>s + +to a fixed 32-bit width, to ease aligning displayed tables. +<P> + +<I>Ttosa</I> + +returns +<B>NULL</B> + +for success and +a pointer to a string-literal error message for failure; +see DIAGNOSTICS. +<I>Satot</I> + +returns +<B>0</B> + +for a failure, and otherwise +always returns the size of buffer which would +be needed to +accommodate the full conversion result, including terminating NUL; +it is the caller's responsibility to check this against the size of +the provided buffer to determine whether truncation has occurred. +<P> + +There is also, temporarily, support for some obsolete +forms of SA specifier which lack the address-family indicator. +<A NAME="lbAE"> </A> +<H2>SEE ALSO</H2> + +<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) +<A NAME="lbAF"> </A> +<H2>DIAGNOSTICS</H2> + +Fatal errors in +<I>ttosa</I> + +are: +empty input; +input too small to be a legal SA specifier; +no +<B>@</B> + +in input; +unknown protocol prefix; +conversion error in +<I>ttoul</I> + +or +<I>ttoaddr</I>. + +<P> + +Fatal errors in +<I>satot</I> + +are: +unknown format. +<A NAME="lbAG"> </A> +<H2>HISTORY</H2> + +Written for the FreeS/WAN project by Henry Spencer. +<A NAME="lbAH"> </A> +<H2>BUGS</H2> + +The restriction of text-to-binary error reports to literal strings +(so that callers don't need to worry about freeing them or copying them) +does limit the precision of error reporting. +<P> + +The text-to-binary error-reporting convention lends itself +to slightly obscure code, +because many readers will not think of NULL as signifying success. +A good way to make it clearer is to write something like: +<P> + +<DL COMPACT><DT><DD> +<PRE> +<B>const char *error;</B> + +<B>error = ttosa( /* ... */ );</B> +<B>if (error != NULL) {</B> +<B> /* something went wrong */</B> +</PRE> + +</DL> + +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">SEE ALSO</A><DD> +<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD> +<DT><A HREF="#lbAG">HISTORY</A><DD> +<DT><A HREF="#lbAH">BUGS</A><DD> +</DL> +<HR> +This document was created by +<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 21:40:18 GMT, November 11, 2003 +</BODY> +</HTML> |