1 .TH IPSEC_TTOSA 3 "26 Nov 2001"
2 .\" RCSID $Id: ttosa.3,v 1.1 2004/03/15 20:35:26 as Exp $
4 ipsec ttosa, satot \- convert IPsec Security Association IDs to and from text
6 ipsec initsaid \- initialize an SA ID
8 .B "#include <freeswan.h>
20 .B "const char *ttosa(const char *src, size_t srclen,"
24 .B "size_t satot(const ip_said *sa, int format,"
26 .B "char *dst, size_t dstlen);"
28 .B "void initsaid(const ip_address *addr, ipsec_spi_t spi,"
30 .B "int proto, ip_said *dst);"
33 converts an ASCII Security Association (SA) specifier into an
36 a destination-host address
37 in network byte order,
38 an SPI number in network byte order, and
41 does the reverse conversion, back to a text SA specifier.
45 from separate items of information.
47 An SA is specified in text with a mail-like syntax, e.g.
49 An SA specifier contains
50 a protocol prefix (currently
57 a single character indicating the address family
62 an unsigned integer SPI number in hexadecimal (with no
66 The IP address can be any form accepted by
67 .IR ipsec_ttoaddr (3),
68 e.g. dotted-decimal IPv4 address,
69 colon-hex IPv6 address,
72 As a special case, the SA specifier
76 signifies the special SA used to indicate that packets should be
77 passed through unaltered.
78 (At present, these are synonyms for
83 but that is subject to change without notice.)
85 is a historical synonym for
87 These forms are known to both
91 so the internal representation is never visible.
93 Similarly, the SA specifiers
101 signify special ``magic'' SAs used to indicate that packets should be
102 passed, dropped, rejected (dropped with ICMP notification),
104 and trapped (sent up to
106 with either of two forms of
108 automatically installed)
110 These forms too are known to both routines,
111 so the internal representation of the magic SAs should never be visible.
115 header file supplies the
117 structure, as well as a data type
119 which is an unsigned 32-bit integer.
120 (There is no consistency between kernel and user on what such a type
121 is called, hence the header hides the differences.)
123 The protocol code uses the same numbers that IP does.
124 For user convenience, given the difficulty in acquiring the exact set of
125 protocol names used by the kernel,
133 to have the same values as the kernel names
145 (reserved by IANA for ``any host internal protocol'')
153 to have the values 256-260 (in \fIhost\fR byte order) respectively.
154 These are used in constructing the magic SAs
155 (which always have address
160 encounters an unknown protocol code, e.g. 77,
161 it yields output using a prefix
162 showing the code numerically, e.g. ``unk77''.
172 specifies the length of the string pointed to by
174 it is an error for there to be anything else
175 (e.g., a terminating NUL) within that length.
176 As a convenience for cases where an entire NUL-terminated string is
189 specifies the size of the
192 under no circumstances are more than
196 A result which will not fit is truncated.
198 can be zero, in which case
200 need not be valid and no result is written,
201 but the return value is unaffected;
202 in all other cases, the (possibly truncated) result is NUL-terminated.
205 header file defines a constant,
207 which is the size of a buffer just large enough for worst-case results.
213 specifies what format is to be used for the conversion.
216 (not the ASCII character
219 specifies a reasonable default
221 lowercase protocol prefix, lowercase hexadecimal SPI,
222 dotted-decimal or colon-hex address).
225 is similar except that the SPI is padded with
227 to a fixed 32-bit width, to ease aligning displayed tables.
233 a pointer to a string-literal error message for failure;
238 for a failure, and otherwise
239 always returns the size of buffer which would
241 accommodate the full conversion result, including terminating NUL;
242 it is the caller's responsibility to check this against the size of
243 the provided buffer to determine whether truncation has occurred.
245 There is also, temporarily, support for some obsolete
246 forms of SA specifier which lack the address-family indicator.
248 ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3)
254 input too small to be a legal SA specifier;
258 unknown protocol prefix;
269 Written for the FreeS/WAN project by Henry Spencer.
271 The restriction of text-to-binary error reports to literal strings
272 (so that callers don't need to worry about freeing them or copying them)
273 does limit the precision of error reporting.
275 The text-to-binary error-reporting convention lends itself
276 to slightly obscure code,
277 because many readers will not think of NULL as signifying success.
278 A good way to make it clearer is to write something like:
282 .B "const char *error;"
284 .B "error = ttosa( /* ... */ );"
285 .B "if (error != NULL) {"
286 .B " /* something went wrong */"