348 lines
6.5 KiB
HTML
348 lines
6.5 KiB
HTML
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:18 GMT, November 11, 2003
|
|
</BODY>
|
|
</HTML>
|