Unix/Linux Go Back    


CentOS 7.0 - man page for ipsec_initsaid (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


IPSEC_TTOSA(3)									   IPSEC_TTOSA(3)

NAME
       ipsec_ttosa,  ipsec_satot,  ipsec_initsaid - convert IPsec Security Association IDs to and
       from text, initialize an SA ID

SYNOPSIS
       #include <libreswan.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 speci-
       fier 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  <libreswan.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,  <libreswan.h>
       defines	the names SA_ESP, SA_AH, SA_IPIP, and SA_COMP to have the same values as the ker-
       nel names IPPROTO_ESP, IPPROTO_AH, IPPROTO_IPIP, and IPPROTO_COMP.

       <libreswan.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 circum-
       stances are more than dstlen bytes written to dst.  A result which will not fit	is  trun-
       cated.	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 <libreswan.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  fail-
       ure;  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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:11 PM.