- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -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 [email protected] .
|
||||
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 [email protected] ,
|
||||
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
|
||||
Reference in New Issue
Block a user