ipsec_atosa(3)

NAME

ipsec atosa, satoa - convert IPsec Security Association

IDs to and from ASCII

SYNOPSIS

#include <freeswan.h>
const char *atosa(const char *src, size_t srclen,
    struct sa_id *sa);
size_t satoa(struct sa_id sa, int format,
    char *dst, size_t dstlen);
struct sa_id {
    struct in_addr dst;
    ipsec_spi_t spi;
    int proto;
};

DESCRIPTION

These functions are obsolete; see ipsec_ttosa(3) for their

replacements.

Atosa converts an ASCII Security Association (SA) specifi

er into an sa_id structure (containing a destination-host address

in network byte order, an SPI number in network byte order, and a

protocol code). Satoa does the reverse conversion, back to an

ASCII SA specifier.

An SA is specified in ASCII with a mail-like syntax, e.g.

esp507@1.2.3.4. An SA specifier contains a protocol prefix (cur

rently ah, esp, or tun), an unsigned integer SPI number, and an

IP address. The SPI number can be decimal or hexadecimal (with

0x prefix), as accepted by ipsec_atoul(3). The IP address can be

any form accepted by ipsec_atoaddr(3), e.g. dotted-decimal ad

dress or DNS name.

As a special case, the SA specifier %passthrough signifies

the special SA used to indicate that packets should be passed

through unaltered. (At present, this is a synonym for

tun0x0@0.0.0.0, but that is subject to change without notice.)

This form is known to both atosa and satoa, so the internal form

of %passthrough is never visible.

The <freeswan.h> header file supplies the sa_id structure,

as well as a data type 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 differ

ences.)

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, <freeswan.h> defines the

names SA_ESP, SA_AH, and SA_IPIP to have the same values as the

kernel names IPPROTO_ESP, IPPROTO_AH, and IPPROTO_IPIP.

The srclen parameter of atosa specifies the length of the

ASCII string pointed to by 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 srclen value of 0 is taken to mean strlen(src).

The dstlen parameter of satoa specifies the size of the

dst parameter; under no circumstances are more than dstlen bytes

written to dst. A result which will not fit is truncated.

Dstlen can be zero, in which case 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 freeswan.h header file defines a constant, SATOA_BUF, which

is the size of a buffer just large enough for worst-case results.

The format parameter of satoa specifies what format is to

be used for the conversion. The value 0 (not the ASCII character

'0', but a zero value) specifies a reasonable default (currently

lowercase protocol prefix, lowercase hexadecimal SPI, dotted-dec

imal address). The value d causes the SPI to be generated in

decimal instead.

Atosa returns NULL for success and a pointer to a string

literal error message for failure; see DIAGNOSTICS. Satoa re

turns 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 responsi

bility to check this against the size of the provided buffer to

determine whether truncation has occurred.

SEE ALSO

ipsec_atoul(3), ipsec_atoaddr(3), inet(3)

DIAGNOSTICS

Fatal errors in atosa are: empty input; input too small to

be a legal SA specifier; no @ in input; unknown protocol prefix;

conversion error in atoul or atoaddr.

Fatal errors in satoa are: unknown format; unknown proto

col code.

HISTORY

Written for the FreeS/WAN project by Henry Spencer.

BUGS

The tun protocol code is a FreeS/WANism which may eventu

ally disappear.

The restriction of ASCII-to-binary error reports to liter

al strings (so that callers don't need to worry about freeing

them or copying them) does limit the precision of error report

ing.

The ASCII-to-binary error-reporting convention lends it

self 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:

const char *error;

error = atoaddr( /* ... */ );
if (error != NULL) {

/* something went wrong */

11 June 2001

IPSEC_ATOSA(3)