Man Linux: Main Page and Category List

NAME

       ipsec ttosa, satot - convert IPsec Security Association IDs to and from
       text
       ipsec initsaid - initialize an SA ID

SYNOPSIS

       #include <freeswan.h>

       typedef struct {
           ip_address dst;
           ipsec_spi_t spi;
           int proto;
       } ip_said;

       const char *ttosa(const char *src, size_t srclen,
           ip_said *sa);
       size_t satot(const ip_said *sa, int format,
           char *dst, size_t dstlen);
       void initsaid(const ip_address *addr, ipsec_spi_t spi,
           int proto, ip_said *dst);

DESCRIPTION

       Ttosa converts an ASCII Security Association  (SA)  specifier  into  an
       ip_said  structure  (containing  a  destination-host address in network
       byte order, an SPI number in network byte order, and a protocol  code).
       Satot  does  the  reverse  conversion,  back  to  a  text SA specifier.
       Initsaid initializes an ip_said from separate items of information.

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

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

       Similarly, the SA specifiers %pass, %drop, %reject, %hold,  %trap,  and
       %trapsubnet signify special ‘‘magic’’ SAs used to indicate that packets
       should be passed, dropped, rejected (dropped with  ICMP  notification),
       held,  and trapped (sent up to ipsec_pluto(8), with either of two forms
       of %hold automatically installed) respectively.  These  forms  too  are
       known to both routines, so the internal representation of the magic SAs
       should never be visible.

       The <freeswan.h> header file supplies the ip_said structure, as well as
       a data type ipsec_spi_t 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.)

       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,  <freeswan.h> defines the names
       SA_ESP, SA_AH, SA_IPIP, and SA_COMP to have  the  same  values  as  the
       kernel names IPPROTO_ESP, IPPROTO_AH, IPPROTO_IPIP, and IPPROTO_COMP.

       <freeswan.h> also defines SA_INT to have the value 61 (reserved by IANA
       for ‘‘any host internal protocol’’) and SPI_PASS, SPI_DROP, SPI_REJECT,
       SPI_HOLD,  and SPI_TRAP to have the values 256-260 (in host byte order)
       respectively.  These are used in  constructing  the  magic  SAs  (which
       always have address 0.0.0.0).

       If satot encounters an unknown protocol code, e.g. 77, it yields output
       using a prefix showing the code numerically, e.g. ‘‘unk77’’.  This form
       is not recognized by ttosa.

       The  srclen  parameter  of  ttosa  specifies  the  length of the string
       pointed to by src; 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  srclen
       value of 0 is taken to mean strlen(src).

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

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

       Ttosa  returns NULL for success and a pointer to a string-literal error
       message for failure; see DIAGNOSTICS.  Satot returns 0 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.

       There is also, temporarily, support  for  some  obsolete  forms  of  SA
       specifier which lack the address-family indicator.

SEE ALSO

       ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3)

DIAGNOSTICS

       Fatal  errors  in ttosa are: empty input; input too small to be a legal
       SA specifier; no @ in input; unknown protocol prefix; conversion  error
       in ttoul or ttoaddr.

       Fatal errors in satot are: unknown format.

HISTORY

       Written for the FreeS/WAN project by Henry Spencer.

BUGS

       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.

       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:

              const char *error;

              error = ttosa( /* ... */ );
              if (error != NULL) {
                      /* something went wrong */

                                  26 Nov 2001                   IPSEC_TTOSA(3)