diff options
Diffstat (limited to 'doc/manpage.d/ipsec_ttosa.3.html')
| -rw-r--r-- | doc/manpage.d/ipsec_ttosa.3.html | 453 |
1 files changed, 0 insertions, 453 deletions
diff --git a/doc/manpage.d/ipsec_ttosa.3.html b/doc/manpage.d/ipsec_ttosa.3.html deleted file mode 100644 index 1e457fc24..000000000 --- a/doc/manpage.d/ipsec_ttosa.3.html +++ /dev/null @@ -1,453 +0,0 @@ -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> |