diff options
Diffstat (limited to 'doc/manpage.d/ipsec_atosa.3.html')
| -rw-r--r-- | doc/manpage.d/ipsec_atosa.3.html | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/doc/manpage.d/ipsec_atosa.3.html b/doc/manpage.d/ipsec_atosa.3.html new file mode 100644 index 000000000..9e2dc2f61 --- /dev/null +++ b/doc/manpage.d/ipsec_atosa.3.html @@ -0,0 +1,347 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of IPSEC_ATOSA</TITLE> +</HEAD><BODY> +<H1>IPSEC_ATOSA</H1> +Section: C Library Functions (3)<BR>Updated: 11 June 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 atosa, satoa - convert IPsec Security Association IDs to and from ASCII +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +<P> +<B>const char *atosa(const char *src, size_t srclen,</B> + +<BR> + +<B>struct sa_id *sa);</B> + +<BR> + +<B>size_t satoa(struct sa_id sa, int format,</B> + +<BR> + +<B>char *dst, size_t dstlen);</B> + +<P> +<B>struct sa_id {</B> + +<BR> + +<B>struct in_addr dst;</B> + +<BR> + +<B>ipsec_spi_t spi;</B> + +<BR> + +<B>int proto;</B> + +<BR> + +<B>};</B> + +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +These functions are obsolete; see +<I><A HREF="ipsec_ttosa.3.html">ipsec_ttosa</A></I>(3) + +for their replacements. +<P> + +<I>Atosa</I> + +converts an ASCII Security Association (SA) specifier into an +<B>sa_id</B> + +structure (containing +a destination-host address +in network byte order, +an SPI number in network byte order, and +a protocol code). +<I>Satoa</I> + +does the reverse conversion, back to an ASCII SA specifier. +<P> + +An SA is specified in ASCII with a mail-like syntax, e.g. +<B><A HREF="mailto:esp507@1.2.3.4">esp507@1.2.3.4</A></B>. + +An SA specifier contains +a protocol prefix (currently +<B>ah</B>, + +<B>esp</B>, + +or +<B>tun</B>), + +an unsigned integer SPI number, +and an IP address. +The SPI number can be decimal or hexadecimal +(with +<B>0x</B> + +prefix), as accepted by +<I><A HREF="ipsec_atoul.3.html">ipsec_atoul</A></I>(3). + +The IP address can be any form accepted by +<I><A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A></I>(3), + +e.g. dotted-decimal address or DNS name. +<P> + +As a special case, the SA specifier +<B>%passthrough</B> + +signifies the special SA used to indicate that packets should be +passed through unaltered. +(At present, this is a synonym for +<B><A HREF="mailto:tun0x0@0.0.0.0">tun0x0@0.0.0.0</A></B>, + +but that is subject to change without notice.) +This form is known to both +<I>atosa</I> + +and +<I>satoa</I>, + +so the internal form of +<B>%passthrough</B> + +is never visible. +<P> + +The +<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> + +header file supplies the +<B>sa_id</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>, + +and +<B>SA_IPIP</B> + +to have the same values as the kernel names +<B>IPPROTO_ESP</B>, + +<B>IPPROTO_AH</B>, + +and +<B>IPPROTO_IPIP</B>. + +<P> + +The +<I>srclen</I> + +parameter of +<I>atosa</I> + +specifies the length of the ASCII 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>satoa</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 +<I>freeswan.h</I> + +header file defines a constant, +<B>SATOA_BUF</B>, + +which is the size of a buffer just large enough for worst-case results. +<P> + +The +<I>format</I> + +parameter of +<I>satoa</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 address). +The value +<B>d</B> + +causes the SPI to be generated in decimal instead. +<P> + +<I>Atosa</I> + +returns +<B>NULL</B> + +for success and +a pointer to a string-literal error message for failure; +see DIAGNOSTICS. +<I>Satoa</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. +<A NAME="lbAE"> </A> +<H2>SEE ALSO</H2> + +<A HREF="ipsec_atoul.3.html">ipsec_atoul</A>(3), <A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A>(3), <A HREF="inet.3.html">inet</A>(3) +<A NAME="lbAF"> </A> +<H2>DIAGNOSTICS</H2> + +Fatal errors in +<I>atosa</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>atoul</I> + +or +<I>atoaddr</I>. + +<P> + +Fatal errors in +<I>satoa</I> + +are: +unknown format; unknown protocol code. +<A NAME="lbAG"> </A> +<H2>HISTORY</H2> + +Written for the FreeS/WAN project by Henry Spencer. +<A NAME="lbAH"> </A> +<H2>BUGS</H2> + +The +<B>tun</B> + +protocol code is a FreeS/WANism which may eventually disappear. +<P> + +The restriction of ASCII-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 ASCII-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 = atoaddr( /* ... */ );</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:17 GMT, November 11, 2003 +</BODY> +</HTML> |