getipsecalgbyname(3NSL) 			       Networking Services Library Functions				   getipsecalgbyname(3NSL)

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(1M). 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  algo-
       rithm.

       a_proto_num is the protocol identifer of this algorithm. a_alg_num is the algorithm number. a_mech_name contains the mechanism name associ-
       ated 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

       See attributes(5)  for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl (32 bit)		   |
       |			     |SUNWcslx (64 bit) 	   |
       +-----------------------------+-----------------------------+
       |MT Level		     |MT Safe			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       cryptoadm(1M), ipsecalgs(1M), getipsecprotobyname(3NSL), getipsecprotobyname(3NSL), attributes(5)

       Piper, D. RFC 2407, The Internet IP Security Domain of Interpretation for ISAKMP. Network Working Group. November, 1998.

SunOS 5.11							    20 Aug 2003 					   getipsecalgbyname(3NSL)