Tribblix: manual page: getipsecalgbyname.3nsl

GETIPSECALGBYNAME(3NSL) Networking Services Library Functions

NAME

getipsecalgbyname, getipsecalgbynum, freeipsecalgent - query
algorithm mapping entries

SYNOPSIS

cc -flag ... file ...-lnsl [ -library ... ]
#include <netdb.h>

struct ipsecalgent *getipsecalgbyname
(const char *alg_name, int protocol_num, int *errnop

struct ipsecalgent *getipsecalgbynum(int alg_num, int protocol_num,
int *errnop

void freeipsecalgent(struct ipsecalgent *ptr

DESCRIPTION

Use the getipsecalgbyname(), getipsecalgbynum(), freeipsecalgent()
functions to obtain the IPsec algorithm mappings that are defined by
ipsecalgs(8). The IPsec algorithms and associated protocol name
spaces are defined by RFC 2407.

getipsecalgbyname() and getipsecalgbynum() return a structure that
describes the algorithm entry found. This structure is described in
the RETURN VALUES section below.

freeipsecalgent() must be used by the caller to free the structures
returned by getipsecalgbyname() and getipsecalgbynum() when they are
no longer needed.

Both getipsecalgbyname() and getipsecalgbynum() take as parameter the
protocol identifier in which the algorithm is defined. See
getipsecprotobyname(3NSL) and getipsecprotobyname(3NSL).

The following protocol numbers are pre-defined:

IPSEC_PROTO_ESP
Defines the encryption algorithms (transforms)
that can be used by IPsec to provide data
confidentiality.

IPSEC_PROTO_AH
Defines the authentication algorithms (transforms)
that can be used by IPsec to provide
authentication.

getipsecalgbyname() looks up the algorithm by its name, while
getipsecalgbynum() looks up the algorithm by its assigned number.

PARAMETERS

errnop
A pointer to an integer used to return an error status
value on certain error conditions. See ERRORS.

RETURN VALUES

The getipsecalgbyname() and getipsecalgbynum() functions return a
pointer to the structure ipsecalgent_t, defined in <netdb.h>. If
the requested algorithm cannot be found, these functions return NULL.

The structure ipsecalgent_t is defined as follows:

typedef struct ipsecalgent {
char **a_names; /* algorithm names */
int a_proto_num; /* protocol number */
int a_alg_num; /* algorithm number */
char *a_mech_name; /* mechanism name */
int *a_block_sizes; /* supported block sizes */
int *a_key_sizes; /* supported key sizes */
int a_key_increment; /* key size increment */
} ipsecalgent_t;

If a_key_increment is non-zero, a_key_sizes[0] contains the default
key size for the algorithm. a_key_sizes[1] and a_key_sizes[2] specify
the smallest and biggest key sizes support by the algorithm, and
a_key_increment specifies the valid key size increments in that
range.

If a_key_increment is zero, the array a_key_sizes contains the set
of key sizes, in bits, supported by the algorithm. The last key
length in the array is followed by an element of value 0. The first
element of this array is used as the default key size for the
algorithm.

a_name is an array of algorithm names, terminated by an element
containing a NULL pointer. a_name[0] is the primary name for the
algorithm.

a_proto_num is the protocol identifier of this algorithm. a_alg_num
is the algorithm number. a_mech_name contains the mechanism name
associated with the algorithm.

a_block_sizes is an array containing the supported block lengths or
MAC lengths, in bytes, supported by the algorithm. The last valid
value in the array is followed by an element containing the value 0.

ERRORS

When the specified algorithm cannot be returned to the caller,
getipsecalgbynam() and getipsecalgbynum() return a value of NULL and
set the integer pointed to by the errnop parameter to one of the
following values:

ENOMEM
Not enough memory

ENOENT
Specified algorithm not found

EINVAL
Specified protocol number not found

ATTRIBUTES