diff options
Diffstat (limited to 'src/libfreeswan/ttosa.3')
| -rw-r--r-- | src/libfreeswan/ttosa.3 | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/src/libfreeswan/ttosa.3 b/src/libfreeswan/ttosa.3 new file mode 100644 index 000000000..bf918e108 --- /dev/null +++ b/src/libfreeswan/ttosa.3 @@ -0,0 +1,288 @@ +.TH IPSEC_TTOSA 3 "26 Nov 2001" +.\" RCSID $Id: ttosa.3,v 1.1 2004/03/15 20:35:26 as Exp $ +.SH NAME +ipsec ttosa, satot \- convert IPsec Security Association IDs to and from text +.br +ipsec initsaid \- initialize an SA ID +.SH SYNOPSIS +.B "#include <freeswan.h> +.sp +.B "typedef struct {" +.ti +1c +.B "ip_address dst;" +.ti +1c +.B "ipsec_spi_t spi;" +.ti +1c +.B "int proto;" +.br +.B "} ip_said;" +.sp +.B "const char *ttosa(const char *src, size_t srclen," +.ti +1c +.B "ip_said *sa); +.br +.B "size_t satot(const ip_said *sa, int format," +.ti +1c +.B "char *dst, size_t dstlen);" +.br +.B "void initsaid(const ip_address *addr, ipsec_spi_t spi," +.ti +1c +.B "int proto, ip_said *dst);" +.SH DESCRIPTION +.I Ttosa +converts an ASCII Security Association (SA) specifier into an +.B ip_said +structure (containing +a destination-host address +in network byte order, +an SPI number in network byte order, and +a protocol code). +.I Satot +does the reverse conversion, back to a text SA specifier. +.I Initsaid +initializes an +.B ip_said +from separate items of information. +.PP +An SA is specified in text with a mail-like syntax, e.g. +.BR esp.5a7@1.2.3.4 . +An SA specifier contains +a protocol prefix (currently +.BR ah , +.BR esp , +.BR tun , +.BR comp , +or +.BR int ), +a single character indicating the address family +.RB ( . +for IPv4, +.B : +for IPv6), +an unsigned integer SPI number in hexadecimal (with no +.B 0x +prefix), +and an IP address. +The IP address can be any form accepted by +.IR ipsec_ttoaddr (3), +e.g. dotted-decimal IPv4 address, +colon-hex IPv6 address, +or DNS name. +.PP +As a special case, the SA specifier +.B %passthrough4 +or +.B %passthrough6 +signifies the special SA used to indicate that packets should be +passed through unaltered. +(At present, these are synonyms for +.B tun.0@0.0.0.0 +and +.B tun:0@:: +respectively, +but that is subject to change without notice.) +.B %passthrough +is a historical synonym for +.BR %passthrough4 . +These forms are known to both +.I ttosa +and +.IR satot , +so the internal representation is never visible. +.PP +Similarly, the SA specifiers +.BR %pass , +.BR %drop , +.BR %reject , +.BR %hold , +.BR %trap , +and +.BR %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 +.IR ipsec_pluto (8), +with either of two forms of +.B %hold +automatically installed) +respectively. +These forms too are known to both routines, +so the internal representation of the magic SAs should never be visible. +.PP +The +.B <freeswan.h> +header file supplies the +.B ip_said +structure, as well as a data type +.B 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.) +.PP +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, +.B <freeswan.h> +defines the names +.BR SA_ESP , +.BR SA_AH , +.BR SA_IPIP , +and +.BR SA_COMP +to have the same values as the kernel names +.BR IPPROTO_ESP , +.BR IPPROTO_AH , +.BR IPPROTO_IPIP , +and +.BR IPPROTO_COMP . +.PP +.B <freeswan.h> +also defines +.BR SA_INT +to have the value +.BR 61 +(reserved by IANA for ``any host internal protocol'') +and +.BR SPI_PASS , +.BR SPI_DROP , +.BR SPI_REJECT , +.BR SPI_HOLD , +and +.B SPI_TRAP +to have the values 256-260 (in \fIhost\fR byte order) respectively. +These are used in constructing the magic SAs +(which always have address +.BR 0.0.0.0 ). +.PP +If +.I 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 +.I not +recognized by +.IR ttosa . +.PP +The +.I srclen +parameter of +.I ttosa +specifies the length of the string pointed to by +.IR 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 +.I srclen +value of +.B 0 +is taken to mean +.BR strlen(src) . +.PP +The +.I dstlen +parameter of +.I satot +specifies the size of the +.I dst +parameter; +under no circumstances are more than +.I dstlen +bytes written to +.IR dst . +A result which will not fit is truncated. +.I Dstlen +can be zero, in which case +.I 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 +.B <freeswan.h> +header file defines a constant, +.BR SATOT_BUF , +which is the size of a buffer just large enough for worst-case results. +.PP +The +.I format +parameter of +.I satot +specifies what format is to be used for the conversion. +The value +.B 0 +(not the ASCII character +.BR '0' , +but a zero value) +specifies a reasonable default +(currently +lowercase protocol prefix, lowercase hexadecimal SPI, +dotted-decimal or colon-hex address). +The value +.B 'f' +is similar except that the SPI is padded with +.BR 0 s +to a fixed 32-bit width, to ease aligning displayed tables. +.PP +.I Ttosa +returns +.B NULL +for success and +a pointer to a string-literal error message for failure; +see DIAGNOSTICS. +.I Satot +returns +.B 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. +.PP +There is also, temporarily, support for some obsolete +forms of SA specifier which lack the address-family indicator. +.SH SEE ALSO +ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3) +.SH DIAGNOSTICS +Fatal errors in +.I ttosa +are: +empty input; +input too small to be a legal SA specifier; +no +.B @ +in input; +unknown protocol prefix; +conversion error in +.I ttoul +or +.IR ttoaddr . +.PP +Fatal errors in +.I satot +are: +unknown format. +.SH HISTORY +Written for the FreeS/WAN project by Henry Spencer. +.SH 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. +.PP +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: +.PP +.RS +.nf +.B "const char *error;" +.sp +.B "error = ttosa( /* ... */ );" +.B "if (error != NULL) {" +.B " /* something went wrong */" +.fi +.RE |