<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id='ttosa3'>
<refentryinfo>
  <author><firstname>Paul</firstname><surname>Wouters</surname><authorblurb><para>placeholder to suppress warning</para> </authorblurb></author>
</refentryinfo>
<refmeta>
<refentrytitle>IPSEC-TTOSA</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class='date'>26 Nov 2001</refmiscinfo>
<refmiscinfo class="source">libreswan</refmiscinfo>
<refmiscinfo class="manual">Library functions</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>ipsec-ttosa</refname>
<refname>ipsec-satot</refname>
<refname>ipsec-initsaid</refname>
<refpurpose>convert IPsec Security Association IDs to and from text, initialize an SA ID</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv id='synopsis'>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;libreswan.h&gt;

typedef struct { ip_address dst; ipsec_spi_t spi; int proto;
 } ip_said; </funcsynopsisinfo>
<funcprototype>
<funcdef>const char *<function>ttosa</function></funcdef>
    <paramdef>const char * <parameter>src</parameter></paramdef>
    <paramdef>size_t <parameter>srclen</parameter></paramdef>
    <paramdef>ip_said * <parameter>sa</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>size_t <function>satot</function></funcdef>
    <paramdef>const ip_said * <parameter>sa</parameter></paramdef>
    <paramdef>int <parameter>format</parameter></paramdef>
    <paramdef>char * <parameter>dst</parameter></paramdef>
    <paramdef>size_t <parameter>dstlen</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>void <function>initsaid</function></funcdef>
    <paramdef>const ip_address * <parameter>addr</parameter></paramdef>
    <paramdef>ipsec_spi_t <parameter>spi</parameter></paramdef>
    <paramdef>int <parameter>proto</parameter></paramdef>
    <paramdef>ip_said * <parameter>dst</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>


<refsect1 id='description'><title>DESCRIPTION</title>
<para><emphasis>Ttosa</emphasis>
converts an ASCII Security Association (SA) specifier into an
<emphasis>ip_said</emphasis>
structure (containing
a destination-host address
in network byte order,
an SPI number in network byte order, and
a protocol code).
<emphasis>Satot</emphasis>
does the reverse conversion, back to a text SA specifier.
<emphasis>Initsaid</emphasis>
initializes an
<emphasis>ip_said</emphasis>
from separate items of information.</para>

<para>An SA is specified in text with a mail-like syntax, e.g.
<emphasis>esp.5a7@1.2.3.4</emphasis>.
An SA specifier contains
a protocol prefix (currently
<emphasis>ah</emphasis>,
<emphasis>esp</emphasis>,
<emphasis>tun</emphasis>,
<emphasis>comp</emphasis>,
or
<emphasis>int</emphasis>),
a single character indicating the address family
(<literal>.</literal>
for IPv4,
<emphasis>:</emphasis>
for IPv6),
an unsigned integer SPI number in hexadecimal (with no
<emphasis>0x</emphasis>
prefix),
and an IP address.
The IP address can be any form accepted by
<citerefentry><refentrytitle>ipsec-ttoaddr</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e.g. dotted-decimal IPv4 address,
colon-hex IPv6 address,
or DNS name.</para>

<para>As a special case, the SA specifier
<emphasis>%passthrough4</emphasis>
or
<emphasis>%passthrough6</emphasis>
signifies the special SA used to indicate that packets should be
passed through unaltered.
(At present, these are synonyms for
<emphasis>tun.0@0.0.0.0</emphasis>
and
<emphasis>tun:0@::</emphasis>
respectively,
but that is subject to change without notice.)
<emphasis>%passthrough</emphasis>
is a historical synonym for
<emphasis>%passthrough4</emphasis>.
These forms are known to both
<function>ttosa</function>
and
<function>satot</function>,
so the internal representation is never visible.</para>

<para>Similarly, the SA specifiers
<emphasis>%pass</emphasis>,
<emphasis>%drop</emphasis>,
<emphasis>%reject</emphasis>,
<emphasis>%hold</emphasis>,
<emphasis>%trap</emphasis>,
and
<emphasis>%trapsubnet</emphasis>
signify special &ldquo;magic&rdquo; SAs used to indicate that packets should be
passed, dropped, rejected (dropped with ICMP notification),
held,
and trapped (sent up to
<citerefentry><refentrytitle>ipsec-pluto</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
with either of two forms of
<emphasis>%hold</emphasis>
automatically installed)
respectively.
These forms too are known to both routines,
so the internal representation of the magic SAs should never be visible.</para>

<para>The
<emphasis>&lt;libreswan.h&gt;</emphasis>
header file supplies the
<emphasis>ip_said</emphasis>
structure, as well as a data type
<type>ipsec_spi_t</type>
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.)</para>

<para>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,
<emphasis>&lt;libreswan.h&gt;</emphasis>
defines the names
<emphasis>SA_ESP</emphasis>,
<emphasis>SA_AH</emphasis>,
<emphasis>SA_IPIP</emphasis>,
and
<emphasis>SA_COMP</emphasis>
to have the same values as the kernel names
<emphasis>IPPROTO_ESP</emphasis>,
<emphasis>IPPROTO_AH</emphasis>,
<emphasis>IPPROTO_IPIP</emphasis>,
and
<emphasis>IPPROTO_COMP</emphasis>.</para>

<para><emphasis>&lt;libreswan.h&gt;</emphasis>
also defines
<emphasis>SA_INT</emphasis>
to have the value
<literal>61</literal>
(reserved by IANA for &ldquo;any host internal protocol&rdquo;)
and
<emphasis>SPI_PASS</emphasis>,
<emphasis>SPI_DROP</emphasis>,
<emphasis>SPI_REJECT</emphasis>,
<emphasis>SPI_HOLD</emphasis>,
and
<emphasis>SPI_TRAP</emphasis>
to have the values 256-260 (in <emphasis>host</emphasis> byte order) respectively.
These are used in constructing the magic SAs
(which always have address
<literal>0.0.0.0</literal>).</para>

<para>If
<function>satot</function>
encounters an unknown protocol code, e.g. 77,
it yields output using a prefix
showing the code numerically, e.g. &ldquo;unk77&rdquo;.
This form is
<emphasis>not</emphasis>
recognized by
<function>ttosa</function>.</para>

<para>The
<varname role='parameter'>srclen</varname>
parameter of
<function>ttosa</function>
specifies the length of the string pointed to by
<varname role='parameter'>src</varname>;
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
<varname role='parameter'>srclen</varname>
value of
<literal>0</literal>
is taken to mean
<emphasis>strlen(src)</emphasis>.</para>

<para>The
<varname role='parameter'>dstlen</varname>
parameter of
<function>satot</function>
specifies the size of the
<varname role='parameter'>dst</varname>
parameter;
under no circumstances are more than
<varname role='parameter'>dstlen</varname>
bytes written to
<varname role='parameter'>dst</varname>.
A result that will not fit is truncated.
<emphasis>Dstlen</emphasis>
can be zero, in which case
<varname role='parameter'>dst</varname>
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
<emphasis>&lt;libreswan.h&gt;</emphasis>
header file defines a constant,
<emphasis>SATOT_BUF</emphasis>,
which is the size of a buffer just large enough for worst-case results.</para>

<para>The
<varname role='parameter'>format</varname>
parameter of
<function>satot</function>
specifies what format is to be used for the conversion.
The value
<literal>0</literal>
(not the ASCII character
<emphasis>'0'</emphasis>,
but a zero value)
specifies a reasonable default
(currently
lowercase protocol prefix, lowercase hexadecimal SPI,
dotted-decimal or colon-hex address).
The value
<emphasis>'f'</emphasis>
is similar except that the SPI is padded with
<literal>0</literal>s
to a fixed 32-bit width, to ease aligning displayed tables.</para>

<para><emphasis>Ttosa</emphasis>
returns
<emphasis>NULL</emphasis>
for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
<emphasis>Satot</emphasis>
returns
<literal>0</literal>
for a failure, and otherwise
always returns the size of buffer that 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.</para>

<para>There is also, temporarily, support for some obsolete
forms of SA specifier that lack the address-family indicator.</para>
</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para><citerefentry><refentrytitle>ipsec-ttoul</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>ipsec-ttoaddr</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>ipsec-samesaid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>inet</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
</refsect1>

<refsect1 id='diagnostics'><title>DIAGNOSTICS</title>
<para>Fatal errors in
<function>ttosa</function>
are:
empty input;
input too small to be a legal SA specifier;
no
<emphasis>@</emphasis>
in input;
unknown protocol prefix;
conversion error in
<emphasis>ttoul</emphasis>
or
<emphasis>ttoaddr</emphasis>.</para>

<para>Fatal errors in
<function>satot</function>
are:
unknown format.</para>
</refsect1>

<refsect1 id='history'><title>HISTORY</title>
<para>Written for the FreeS/WAN project by Henry Spencer.</para>
</refsect1>

<refsect1 id='bugs'><title>BUGS</title>
<para>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.</para>

<para>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:</para>

<literallayout>
<emphasis>const char *error;</emphasis>

<emphasis>error = ttosa( /* ... */ );</emphasis>
<emphasis>if (error != NULL) {</emphasis>
<emphasis>        /* something went wrong */</emphasis>
</literallayout> <!-- .fi -->
</refsect1>
  <refsect1 id='author'>
    <title>AUTHOR</title>
    <para>
      <emphasis role='strong'>Paul Wouters</emphasis>
    </para>
  </refsect1>
</refentry>