C-Bindings for IPsec Application Programming Interfaces

The "better than nothing" (BTNS) extensions for IKE are intended to protect network traffic on their own (Stand Alone BTNS, or SAB), and may be useful in providing network layer security that can be authenticated by higher layers in the protocol stack, called Channel Bound BTNS (CBB). The motivation for SAB is to remove the need to deploy authentication information altogether. The motivation for CBB is to remove the need for redundant authentication at multiple layers. This document defines APIs for these purposes. The APIs can also be used by other protocols such as the Host Identity Protocol (HIP) and Session Initiation Protocol (SIP) . For example, a SIP user agent can use the presented APIs for determining whether or not required integrity and confidentiality protection is already in use. For certain networks and configuration this is expected to reduce overhead associated with the security mechanisms. The network communications of applications are usually secured explicitly with TLS on transport layer , or using even higher layer interfaces such as GSS or SASL APIs. However, such interfaces do not exist for IPsec because it operates on lower layers and is mostly transparent to applications. Using IPsec to protect existing applications is therefore easier than with, for example, TLS because IPsec does not require changes in the application. However, it is difficult for an application to detect when network connections are secured using IPsec. IPsec can be used as an "all or nothing" security measure, which can be problematic especially in deployments where the number of IPsec enabled machines is small. An alternative approach is to use IPsec when peer supports it. However, the application or the user may not have any knowledge that the communications was actually protected by IPsec in this case. In addition, it is more efficient to remove redundant authentications when IPsec and TLS are being used for the same connection. In this document, we define APIs that increase the visibility of the IPsec layer to the applications. This document fulfills the BTNS requirements presented in and present C-bindings to the abstract APIs . The APIs defined in this document are based on the sockets API . For related API work, please refer to , and . The documents defines an explicit way of enabling IPsec in applications. This API allows the dual use of both IPsec and higher layer security mechanisms (TLS, GSS or SASL) simultaneously. The security and performance related benefits of this are described in more detail in .

+---------+---------+---------+---------+ | App # 1 | App # 2 | App # 3 | App #4 | +-----+---+-----+---+---+-----+----+----+ | | | | | +---v-------v--+ | | | TLS/GSS/SASL | | +-----v-----+-------+------+ | Appl. Layer | IPsec APIs | | | +-----+---------+---+ | | | | | | +-----v---------v-------v-----------v---+ Sockets Layer | IPv4 and IPv6 APIs | +-----------+--------------+------------+ Transport Layer | SCTP | TCP | UDP | +-----------+--------------+------------+ IPsec Layer | IPsec | +--------------------+------------------+ Network Layer | IPv4 | IPv6 | +--------------------+------------------+ Link Layer | Ethernet | Etc | +--------------------+------------------+ illustrates four different applications. The first application is using only the IPsec APIs based on either IKE based authentication or Stand-alone BTNS. The second application is using both TLS (or other similar APIs) and IPsec APIs. In this case, the application can skip IKE authentication because of it is already provided by TLS. On the other hand, the application can avoid the use of TLS altogether when IKE authentication is available. The third application is using only TLS and the fourth one is using neither IPsec or TLS APIs. In the first three cases, the application is explicitly modified to use either TLS or IPsec. In contrast, the fourth application is not using either TLS or IPsec explicitly, but it may be using IPsec implicitly. This document covers the use of applications one and two.

The IPSec APIs are accessed by using tokens. The pToken has a per-process scope and is used to access the IPSec API. This token can be obtained, for example, from a connected socket, a received datagram, or a file descriptor. This token cannot be serialized. The iToken is a serializable token and represents the identity of a remote system. This section defines constants, data structures and functions for manipulating IPsec related data structures. The definitions are based on C-language. The integer values are always in host byte order.

Application can use identity tokes for querying the peer identity and for requiring certain channel bindings for a socket to implement ACLs or for logging purposes. Then, the application can communicate with a peer through the socket and the communication succeeds only when channel bindings are acceptable to the application. The application can also communicate with an peer of unknown identity, and to store and require the same peer identity in subsequent communications.

Identity tokens, iTokens, are machine-readable, opaque data structures. They can present either the local or remote identity, such as a public key. The iToken has a typedef which is illustrated .

typedef struct ipsec_iToken * ipsec_iToken_t; Operating environments that support the IPSec API will provide appropriate constructor and destructor for the iToken objects. Because applications will often not be aware of the byte-representation of the iToken object, nor will they know which attributes to initialize upon construction, applications MUST only use the provided constructor to create an iToken object. When an iToken object is no longer needed, applications MUST use the provided destructor to destroy it. illustrates this API.

ipsec_iToken_t ipsec_create_iToken(); int ipsec_free_iToken(ipsec_iToken_t p); Function ipsec_create_iToken() allocates memory for a iToken and initializes it. The function returns the created iToken, or NULL upon failure. Function ipsec_free_iToken() deinitializes and frees the memory allocated to an iToken. It returns zero on success, and non-zero upon failure.

This section describes the c-language bindings to section 8 in . Identity token attributes are shown in . They are accessed using the functions defined in .

enum { IPSEC_API_ATTR_auditString, IPSEC_API_ATTR_authenticationMethod, IPSEC_API_ATTR_certificateAuthorityDN, IPSEC_API_ATTR_certificateDN, IPSEC_API_ATTR_pubKeyID, IPSEC_API_ATTR_channelBinding } iToken_attribute; enum { IPSEC_API_ATTR_authMeth_NONE, IPSEC_API_ATTR_authMeth_BTNS, IPSEC_API_ATTR_authMeth_LEAPOFFAITH, IPSEC_API_ATTR_authMeth_PRESHAREDKEY, IPSEC_API_ATTR_authMeth_GROUPKEY, IPSEC_API_ATTR_authMeth_XAUTH, IPSEC_API_ATTR_authMeth_EAP, IPSEC_API_ATTR_authMeth_PKIX_TRUSTED, IPSEC_API_ATTR_authMeth_PKIX_INLINE, IPSEC_API_ATTR_authMeth_PKIX_OFFLINE } iToken_auth_meth; The group of attributes defined in iToken_attribute enumeration cannot be modified. The auditString attribute is a character array ending with a zero byte. It contains a human-readable description of the peer identity. The authenticationMethod attribute defines the key manager authentication method in an unsigned integer of two octets. The certificateAuthorityDN attribute is a character array ending with a zero byte and contains a human-readable description of the peer certificate authority. The pubKeyID attribute contains a binary presentation of the peer public key. The channelBinding attribute is a character array ending with a zero byte. It contains a human-readable description of the channel binding. Two channel bindings can be compared with the memcmp() function. The group of attributes in iToken_auth_meth enumeration contains a list of authentication methods. These attributes are both writable before network communications and readable after network communications. Here the use of the attributes is described only from the point of view of writing. The attributes in this group are 2-octet unsigned integer values, with values IPSEC_API_ATTR_ENABLE, IPSEC_API_ATTR_DISABLE and IPSEC_API_ATTR_ANY. The first two of the values enable or disable the attribute, and third one refers that the application relies on the system defaults. The attributes of the iToken_auth_meth are defined in . The first NONE attribute describes that no authentication should be used. The BTNS attribute enables or disables the extensions defined in The LEAPOFFAITH attribute declares that the peer was authenticated using a key which was previously cached, but was previously received inline, and was not verified in anyway. The PRESHAREDKEY attribute denotes that a unique preshared key should be used and GROUPKEY correspondingly refers to a non-unique group key. The XAUTH, EAP, and PKIX attributes refer to the respective authentication methods.

IPsec properties are handled indirectly using objects called tokens. They are are opaque data structures that must not be manipulated directly. Instead, the application uses accessor functions shown in .

int ipsec_get_token_attr(const void *token, uint32_t attr_type, uint32_t *attr_len, void *attr_val); int ipsec_set_token_attr(const void *token, uint32_t attr_type, uint32_t attr_len, const void *attr_val); Both of the functions can be applied both to policy and identity tokens to retrieve or change the low-level attributes. Function ipsec_token_attr_get() searches for the given attribute type (attr_type) from the token and writes it to attr_val. Parameter attr_len defines the size of attr_val structure in bytes. Function ipsec_set_token_attr() writes the attribute (attr_val) to the token. The type and length of the attribute must be set in attr_type and attr_len. The attr_val must not be NULL and attr_len must have the size of the allocated object. Both of the functions return zero on success. They return -1 on error and set errno accordingly.

An application creates a "protection token" and attaches some attributes for it. For example, the application can define in the attributes of protection token that it accepts BTNS extensions for a certain socket.

Application uses protection tokens, or pTokens, as "handles" to the key management or the IPsec module of the host. The application uses pToken attributes to e.g. enabled the BTNS extensions and to control iTokens. The former allows the use of IPSec without authentication, and the latter allows e.g. querying of channel bindings. The data structure that represents a pToken is contained in an opaque ipsec_pToken structure. The application must not alter the data structure contents directly, but rather use the accessor functions introduced in the following sections. The application can use ipsec_pToken_t typedef as a short hand for the policy structure. The typedef is shown in .

typedef struct ipsec_pToken * ipsec_pToken_t; The size of a policy is variable and applications MUST NOT declare them directly. Instead, the application uses the constructor and destructor functions shown in .

ipsec_pToken_t ipsec_create_pToken(void); int ipsec_free_pToken(ipsec_pToken_t p); Function ipsec_create_pToken() allocates memory for a pToken and initializes it. The function returns the created pToken, or NULL upon failure. Function ipsec_free_pToken() deinitializes and frees the memory allocated to a pToken. It returns zero on success, and non-zero upon failure.

This section defines c-bindings for section 7 in . Protection token attributes are shown in . They are get or set using the functions defined in .

enum { IPSEC_API_ATTR_privacyProtected, IPSEC_API_ATTR_integrityProtected, IPSEC_API_ATTR_compressionAvailable, IPSEC_API_ATTR_policyName, IPSEC_API_ATTR_iToken, IPSEC_API_ATTR_remote_iToken, IPSEC_API_ATTR_tunnelMode, IPSEC_API_ATTR_ipoptionsProtected, IPSEC_API_ATTR_auditString, IPSEC_API_ATTR_informationString } pToken_attribute; The attributes of the pToken_attribute structure are defined in . Here the use of the attributes is described only from writing point of view. Attribute value IPSEC_API_ATTR_DISABLE defines that the attribute should not be used. Value IPSEC_API_ATTR_ENABLE describes that the corresponding attribute should be used. It is possible to enable an attribute by declaring the "level" of the attribute with IPSEC_API_ATTR_LEVEL_LOW, IPSEC_API_ATTR_LEVEL_MEDIUM or IPSEC_API_ATTR_LEVEL_HIGH. The privacy, integrity and compression attributes are 2-octet unsigned integer values. These attributes are writable before network communication and readable after network communications. They can be used to enforce and negotiate required attribute values. privacyProtection - unsigned integer. Set to IPSEC_API_ATTR_DISABLE if the connection has either no privacy configured (AH, ESP-null), or if the privacy configured is known to be untrustworthy by the administrator. integrityProtection - unsigned integer. Set to IPSEC_API_ATTR_DISABLE if there is no data integrity protection other than the UDP/TCP checksum. compressionAvailable - unsigned integer. Set to IPSEC_API_ATTR_DISABLE if data count sent/ received from socket maps directly to data sent/received on wire. policyName - string. A handle which describes the system policy which was used (or is desired), to establish the connection. iToken - object. Set to iToken object which represents identity of remote system. remote_iToken - object. Set to iToken object which was used to represent our identity to the remote system. tunnelMode - unsigned integer. Set if tunnel mode was used, or if it is desired. ipoptionsProtected - unsigned integer. Set if ip options (and IPv6 header extensions), are protected. auditString - string. The auditString is a character array ending in zero byte and contains a human readable description of the protection token. informationString - string. Readonly. Not part of a template. Valid only after connection establishment. Contains a string which can be displayed to a user, informing them of what kind of security association was established for this connection. This string may be localized. No session keys are disclosed by this string.

Declaring a pToken does not affect the networking communications of an application. For connection oriented communications, the application must first attach the pToken to the socket before the pToken is effective. It is also possible to query for the pToken attached to a socket as shown in .

int ipsec_set_socket_pToken(int fd, const ipsec_pToken_t pToken); int ipsec_get_socket_pToken(int fd, ipsec_pToken_t pToken); Both functions input an socket descriptor as the first argument and a pToken as the second argument. Function ipsec_set_socket_pToken() attaches the given pToken to the socket descriptor fd. Function ipsec_get_socket_pToken() assumes that the application has allocated the policy token beforehand with ipsec_create_pToken(). Both functions return zero upon success, and non-zero upon failure.

The previous section covered the use of connected sockets. Datagram oriented communications based on sendmsg() and recvmsg() functions are supported in the API. Datagram related functions are applicable both to incoming and outgoing packets. The IPsec API functions related sendmsg() and recvmsg() are shown in .

int ipsec_set_msg_pToken(struct msghdr *msg, const ipsec_pToken_t pToken); int ipsec_get_msg_pToken(const struct msghdr *msg, ipsec_pToken_t pToken); Function ipsec_set_msg_pToken() attaches the given pToken to the ancillary data of msg. The pToken of a msg can be queried using ipsec_get_msg_pToken() that assumes the application has allocated the policy token beforehand with ipsec_create_pToken. Both functions return zero on success. The functions return -1 on error and set errno accordingly. It should be noticed that these functions can be applied only to sendto() and recvmsg() as they support per packet anchillary data. Applications using sendto() and recvfrom() can apply the "stream-based" functions described in the other sections of the document with certain restrictions. TBD: discuss.

An application is not allowed to read or write to pTokens directly. The same restriction applies also to comparison of pTokens. The function for comparing two pTokens is shown in .

int ipsec_cmp_pToken(ipsec_pToken_t p1, ipsec_pToken_t p2); Function ipsec_cmp_pToken() inputs two policies, p1 and p2, and returns zero if they represent two SAs that cover identical SPD ranges, and have equivalent cryptographic security properties. The function returns a nonzero value if p1 is not equal to p2. The two SAs need not represent SAs that identical --- they might vary in many different ways, including, but not limited to: Time: One SA may have been created later, but both are valid. Jitter/performance properties: One SA may be on hardware and the other on software, and have different properties about what kind of latency or jitter a packet might experience Algorithm: one SA might use AES128-CBC while the other uses AES128-CTR (DISCUSS) for performance reasons. IPsec SA endpoints. The two SAs may cover the same inner IP packets, but might connect using differing outer IP addresses, and be used in some kind of multipath IPsec (such as MOBIKE).

Byte-wise copying of pTokens is not allowed e.g. with memcpy(). Function ipsec_dup_pToken() duplicates given pToken p and writes it to p_dup. The function allocates the memory for duplicated pToken that the caller is responsible of freeing. Return value is zero on success and non-zero on failure.

int ipsec_dup_pToken(const ipsec_pToken_t p, ipsec_pToken_t *p_dup);