1IPSEC_TTOSA(3) Library Functions Manual IPSEC_TTOSA(3)
2
6 ipsec ttosa, satot - convert IPsec Security Association IDs to and from
7 text
8 ipsec initsaid - initialize an SA ID
9
11 #include <freeswan.h>
12 typedef struct {
14 ip_address dst;
15 ipsec_spi_t spi;
16 int proto;
17 } ip_said;
18 const char *ttosa(const char *src, size_t srclen,
20 ip_said *sa);
21 size_t satot(const ip_said *sa, int format,
22 char *dst, size_t dstlen);
23 void initsaid(const ip_address *addr, ipsec_spi_t spi,
24 int proto, ip_said *dst);
25
27 Ttosa converts an ASCII Security Association (SA) specifier into an
28 ip_said structure (containing a destination-host address in network
29 byte order, an SPI number in network byte order, and a protocol code).
30 Satot does the reverse conversion, back to a text SA specifier. Init‐
31 said initializes an ip_said from separate items of information.
32 An SA is specified in text with a mail-like syntax, e.g.
34 esp.5a7@1.2.3.4. An SA specifier contains a protocol prefix (currently
35 ah, esp, tun, comp, or int), a single character indicating the address
36 family (. for IPv4, : for IPv6), an unsigned integer SPI number in
37 hexadecimal (with no 0x prefix), and an IP address. The IP address can
38 be any form accepted by ipsec_ttoaddr(3), e.g. dotted-decimal IPv4
39 address, colon-hex IPv6 address, or DNS name.
40 As a special case, the SA specifier %passthrough4 or %passthrough6 sig‐
42 nifies the special SA used to indicate that packets should be passed
43 through unaltered. (At present, these are synonyms for tun.0@0.0.0.0
44 and tun:0@:: respectively, but that is subject to change without
45 notice.) %passthrough is a historical synonym for %passthrough4.
46 These forms are known to both ttosa and satot, so the internal repre‐
47 sentation is never visible.
48 Similarly, the SA specifiers %pass, %drop, %reject, %hold, %trap, and
50 %trapsubnet signify special ``magic'' SAs used to indicate that packets
51 should be passed, dropped, rejected (dropped with ICMP notification),
52 held, and trapped (sent up to ipsec_pluto(8), with either of two forms
53 of %hold automatically installed) respectively. These forms too are
54 known to both routines, so the internal representation of the magic SAs
55 should never be visible.
56 The <freeswan.h> header file supplies the ip_said structure, as well as
58 a data type ipsec_spi_t which is an unsigned 32-bit integer. (There is
59 no consistency between kernel and user on what such a type is called,
60 hence the header hides the differences.)
61 The protocol code uses the same numbers that IP does. For user conve‐
63 nience, given the difficulty in acquiring the exact set of protocol
64 names used by the kernel, <freeswan.h> defines the names SA_ESP, SA_AH,
65 SA_IPIP, and SA_COMP to have the same values as the kernel names
66 IPPROTO_ESP, IPPROTO_AH, IPPROTO_IPIP, and IPPROTO_COMP.
67 <freeswan.h> also defines SA_INT to have the value 61 (reserved by IANA
69 for ``any host internal protocol'') and SPI_PASS, SPI_DROP, SPI_REJECT,
70 SPI_HOLD, and SPI_TRAP to have the values 256-260 (in host byte order)
71 respectively. These are used in constructing the magic SAs (which
72 always have address 0.0.0.0).
73 If satot encounters an unknown protocol code, e.g. 77, it yields output
75 using a prefix showing the code numerically, e.g. ``unk77''. This form
76 is not recognized by ttosa.
77 The srclen parameter of ttosa specifies the length of the string
79 pointed to by src; it is an error for there to be anything else (e.g.,
80 a terminating NUL) within that length. As a convenience for cases
81 where an entire NUL-terminated string is to be converted, a srclen
82 value of 0 is taken to mean strlen(src).
83 The dstlen parameter of satot specifies the size of the dst parameter;
85 under no circumstances are more than dstlen bytes written to dst. A
86 result which will not fit is truncated. Dstlen can be zero, in which
87 case dst need not be valid and no result is written, but the return
88 value is unaffected; in all other cases, the (possibly truncated)
89 result is NUL-terminated. The <freeswan.h> header file defines a con‐
90 stant, SATOT_BUF, which is the size of a buffer just large enough for
91 worst-case results.
92 The format parameter of satot specifies what format is to be used for
94 the conversion. The value 0 (not the ASCII character '0', but a zero
95 value) specifies a reasonable default (currently lowercase protocol
96 prefix, lowercase hexadecimal SPI, dotted-decimal or colon-hex
97 address). The value 'f' is similar except that the SPI is padded with
98 0s to a fixed 32-bit width, to ease aligning displayed tables.
99 Ttosa returns NULL for success and a pointer to a string-literal error
101 message for failure; see DIAGNOSTICS. Satot returns 0 for a failure,
102 and otherwise always returns the size of buffer which would be needed
103 to accommodate the full conversion result, including terminating NUL;
104 it is the caller's responsibility to check this against the size of the
105 provided buffer to determine whether truncation has occurred.
106 There is also, temporarily, support for some obsolete forms of SA spec‐
108 ifier which lack the address-family indicator.
109
111 ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3)
112
114 Fatal errors in ttosa are: empty input; input too small to be a legal
115 SA specifier; no @ in input; unknown protocol prefix; conversion error
116 in ttoul or ttoaddr.
117 Fatal errors in satot are: unknown format.
119
121 Written for the FreeS/WAN project by Henry Spencer.
122
124 The restriction of text-to-binary error reports to literal strings (so
125 that callers don't need to worry about freeing them or copying them)
126 does limit the precision of error reporting.
127 The text-to-binary error-reporting convention lends itself to slightly
129 obscure code, because many readers will not think of NULL as signifying
130 success. A good way to make it clearer is to write something like:
131 const char *error;
133 error = ttosa( /* ... */ );
135 if (error != NULL) {
136 /* something went wrong */
137 26 Nov 2001 IPSEC_TTOSA(3)