- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -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:[email protected]">[email protected]</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:[email protected]">[email protected]</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:17 GMT, November 11, 2003
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in New Issue
Block a user