288 lines
6.3 KiB
Plaintext
288 lines
6.3 KiB
Plaintext
.TH IPSEC_TTOSA 3 "26 Nov 2001"
|
|
.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
|