diff options
Diffstat (limited to 'src/libfreeswan/atosa.3')
| -rw-r--r-- | src/libfreeswan/atosa.3 | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/src/libfreeswan/atosa.3 b/src/libfreeswan/atosa.3 new file mode 100644 index 000000000..116483a73 --- /dev/null +++ b/src/libfreeswan/atosa.3 @@ -0,0 +1,218 @@ +.TH IPSEC_ATOSA 3 "11 June 2001" +.\" RCSID $Id: atosa.3,v 1.1 2004/03/15 20:35:26 as Exp $ +.SH NAME +ipsec atosa, satoa \- convert IPsec Security Association IDs to and from ASCII +.SH SYNOPSIS +.B "#include <freeswan.h> +.sp +.B "const char *atosa(const char *src, size_t srclen," +.ti +1c +.B "struct sa_id *sa); +.br +.B "size_t satoa(struct sa_id sa, int format," +.ti +1c +.B "char *dst, size_t dstlen);" +.sp +.B "struct sa_id {" +.ti +1c +.B "struct in_addr dst;" +.ti +1c +.B "ipsec_spi_t spi;" +.ti +1c +.B "int proto;" +.br +.B "};" +.SH DESCRIPTION +These functions are obsolete; see +.IR ipsec_ttosa (3) +for their replacements. +.PP +.I Atosa +converts an ASCII Security Association (SA) specifier into an +.B sa_id +structure (containing +a destination-host address +in network byte order, +an SPI number in network byte order, and +a protocol code). +.I Satoa +does the reverse conversion, back to an ASCII SA specifier. +.PP +An SA is specified in ASCII with a mail-like syntax, e.g. +.BR esp507@1.2.3.4 . +An SA specifier contains +a protocol prefix (currently +.BR ah , +.BR esp , +or +.BR tun ), +an unsigned integer SPI number, +and an IP address. +The SPI number can be decimal or hexadecimal +(with +.B 0x +prefix), as accepted by +.IR ipsec_atoul (3). +The IP address can be any form accepted by +.IR ipsec_atoaddr (3), +e.g. dotted-decimal address or DNS name. +.PP +As a special case, the SA specifier +.B %passthrough +signifies the special SA used to indicate that packets should be +passed through unaltered. +(At present, this is a synonym for +.BR tun0x0@0.0.0.0 , +but that is subject to change without notice.) +This form is known to both +.I atosa +and +.IR satoa , +so the internal form of +.B %passthrough +is never visible. +.PP +The +.B <freeswan.h> +header file supplies the +.B sa_id +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 , +and +.B SA_IPIP +to have the same values as the kernel names +.BR IPPROTO_ESP , +.BR IPPROTO_AH , +and +.BR IPPROTO_IPIP . +.PP +The +.I srclen +parameter of +.I atosa +specifies the length of the ASCII 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 satoa +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 +.I freeswan.h +header file defines a constant, +.BR SATOA_BUF , +which is the size of a buffer just large enough for worst-case results. +.PP +The +.I format +parameter of +.I satoa +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 address). +The value +.B d +causes the SPI to be generated in decimal instead. +.PP +.I Atosa +returns +.B NULL +for success and +a pointer to a string-literal error message for failure; +see DIAGNOSTICS. +.I Satoa +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. +.SH SEE ALSO +ipsec_atoul(3), ipsec_atoaddr(3), inet(3) +.SH DIAGNOSTICS +Fatal errors in +.I atosa +are: +empty input; +input too small to be a legal SA specifier; +no +.B @ +in input; +unknown protocol prefix; +conversion error in +.I atoul +or +.IR atoaddr . +.PP +Fatal errors in +.I satoa +are: +unknown format; unknown protocol code. +.SH HISTORY +Written for the FreeS/WAN project by Henry Spencer. +.SH BUGS +The +.B tun +protocol code is a FreeS/WANism which may eventually disappear. +.PP +The restriction of ASCII-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 ASCII-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 = atoaddr( /* ... */ );" +.B "if (error != NULL) {" +.B " /* something went wrong */" +.fi +.RE |