An interface between applications and keying systems

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 .

Purpose of this API.

There are two major kinds of objects that are defined by this document. These are the Protection Token (pToken) and the Identity Token (iToken). Both objects are abstracted into unique opaque tokens which may be manipulated only indirectly by applications. Each object has a series of attributes associated with it. The API provides a mechanism to query the value of attributes of the token. The attributes are where all of the content of the objects are. Each token has a scope - the place and time in which it can be considered valid. There are many conflicting qualities that one would wish for the token, and the result is a different compromise among these qualities for each token type. The tokens should be: small easy to allocate and deallocate automatically cleaned up when an application terminates (both properly and inproperly) easily compared easily passed back in a recvmsg(2) call as auxiliary data (for pToken)

The protection token has a per-process (i.e. per-address space) scope. The scope of the token is not related to the underlying protection provided by IPsec. The token is a handle.

The identity token has a per-system scope, although two applications running on the same system may not be able to compare it literally.

The pToken is valid only within the scope of a single process. The token may not be saved in any long term storage. It is permitted for one protection token to be replaced with another (equivalent) protection token due to a node moving, suspending and resuming, or due to extended network outages, however the underlying identity token would be guaranteed to be the same. This would most likely occur with unconnected sockets, where due to the outage/downtime, the keying system was unable to maintain a keying channel, and had to re-create the keys from scratch.

The iToken may be valid across the entire system, although it may need to be turned into an external representation. Some forms of identity token may be valid across systems, but in general an identity token is only valid in reference to a local set of trust anchors. (See ).

All functions and macros defined by this API are prefixed with "ipsec_" for functions and variables, and with "IPSEC_" if they are macros or enumerated types. (cf. to appropriate POSIX section?) Whenever sensible, the enumerated values defined in are used if appropriate.

An application that receives a connection using accept(2), or with recvmsg(2) needs to get a protection token that is associated with the socket. For connected sockets (such as TCP and some SCTP modes), the protection token should not change during the lifetime of the socket, so a simple process is appropriate. For unconnected sockets (such as UDP and some SCTP modes), each datagram received may be received may arrive from a different source, and therefore may have different protections applied. A protection token needs to be returned with each datagram, so it must be returned as ancilliary data with recvmsg(2). For connected sockets, the pToken will not change during the connection. (see notes about rekeying). A simple function is provided to return a pToken from a file descriptor. Many implementions are likely to implement this using getsockopt(2), but an interface in those terms is not specified in order to keep it somewhat abstract.

stuff