IPsec Application Programming Interfaces
draft-ietf-btns-c-api-03

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. This document may not be modified, and derivative works of it may not be created, except to publish it as an RFC and to translate it into languages other than English.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on August 22, 2008.

Abstract

IPsec based security is usually transparent for applications and and they have no standard APIs for gathering information about protected network connections and for detecting the underlying security mechanisms. This document specifies an API that increases the visibility of IPsec to applications. The API allows applications to allow BTNS extensions, control the channel bindigs, and control also other security properties related to IPsec.

Table of Contents

1.  Introduction
2.  IPsec APIs
    2.1.  Token Attributes
    2.2.  Identity Tokens
        2.2.1.  Creation of Identity Tokens
        2.2.2.  Attributes of Identity Tokens
    2.3.  Protection Tokens
        2.3.1.  Creation of Protection Tokens
        2.3.2.  Attributes of Protection Tokens
        2.3.3.  Connection Oriented Communications
        2.3.4.  Datagram Oriented Communications
        2.3.5.  Equivalency of Protection Tokens
        2.3.6.  Duplication of Protection Tokens
3.  Security Considerations
4.  IANA Considerations
5.  Acknowledgements
6.  References
    6.1.  Normative References
    6.2.  Informative References
§  Authors' Addresses
§  Intellectual Property and Copyright Statements

1.  Introduction

The "better than nothing" (BTNS) extensions for IKE [I‑D.ietf‑btns‑core] (Williams, N. and M. Richardson, “Better-Than-Nothing-Security: An Unauthenticated Mode of IPsec,” August 2008.) 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 HIP.

The network communications of applications are usually secured explicitly with TLS on transport layer [RFC4346] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.1,” April 2006.), or using even higher layer interfaces such as GSS [RFC2744] (Wray, J., “Generic Security Service API Version 2 : C-bindings,” January 2000.) or SASL [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.) 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 defined APIs that increase the visibility of the IPsec layer to the applications. This document fulfisl the BTNS requirements presented in [I‑D.ietf‑btns‑ipsec‑apireq] (Richardson, M. and B. Sommerfeld, “Requirements for an IPsec API,” April 2006.) and present C-bindings to the abstract APIs [I‑D.ietf‑btns‑abstract‑api] (Richardson, M., “An abstract interface between applications and IPsec,” November 2008.). The APIs defined in this document are based on the sockets API [POSIX] (Institute of Electrical and Electronics Engineers, “IEEE Std. 1003.1-2001 Standard for Information Technology - Portable Operating System Interface (POSIX),” Dec 2001.) or similar APIs that provide socket descriptors for applications. For related API work, please refer to [I‑D.ietf‑hip‑native‑api] (Komu, M. and T. Henderson, “Basic Socket Interface Extensions for Host Identity Protocol (HIP),” January 2010.), [mcdonald] (Internet Engineering Task Force, “A Simple IP Security API Extension to BSD Sockets,” Mar 1997.) and [atkinson] (USENIX 1996 Annual Technical Conference, “Implementation of IPv6 in 4.4 BSD,” Jan 1996.).

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 [I‑D.ietf‑btns‑prob‑and‑applic] (Touch, J., Black, D., and Y. Wang, “Problem and Applicability Statement for Better Than Nothing Security (BTNS),” July 2008.).

                +---------+---------+---------+---------+
                | 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       |
                +--------------------+------------------+

Figure 1 (API Layering) 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.

2.  IPsec APIs

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.

2.1.  Token Attributes

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 the accessor functions shown in Figure 2.

  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);

Function ipsec_token_attr_get() searches for the given attribute type (attr_type) from the token. The attr_val pointer may have memory allocated for it already. If so, it will be non-NULL, and the attr_len must have the size of the allocated memory set. When attr_val pointer is NULL, the function allocates memory into attr_val (using malloc) and copies the attribute into the allocated memory. On successful operation, the function sets the attribute length in attr_len. When attr_val is NULL, then no object will be returned, but attr_len will still be set to the size of the attr_val.

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.

2.2.  Identity Tokens

This section describes the use of IPsec identity tokens. The identity tokes can be used 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 unkown identity, and to store and require the same peer identity in subsequent communications.

2.2.1.  Creation of Identity Tokens

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 in Figure 3.

  typedef struct ipsec_iToken * ipsec_iToken_t;

The size of a iToken is variable and applications MUST NOT declare it directly. Instead, the application uses the constructor and destructor functions shown in Figure 4.

  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.

2.2.2.  Attributes of Identity Tokens

Identity token attributes are shown in Figure 5. They are accessed using the functions defined in Section 2.1 (Token Attributes).

  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_LEAFOFFAITH,
       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 first 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. Possible values are XX TBD. 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 s 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 second 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 writing point of view.

The attibutes for the second 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. NONE describes that no authentication should be used.

In the second group, BTNS enables or disables the extensions in [I‑D.ietf‑btns‑core] (Williams, N. and M. Richardson, “Better-Than-Nothing-Security: An Unauthenticated Mode of IPsec,” August 2008.) . The LEAFOFFAITH attribute declares that the application does not have to know the peer identity beforehand. The PRESHAREDKEY attribute denotes that a preshared key should be used (XX REF) and GROUPKEY correspondingly refers to a group key (XX REF). The XAUTH and EAP attributes refer to the authentication methods defined in (XX REFS). The PKIX methods refer to the authentication methods in (XX REF).

2.3.  Protection Tokens

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.

2.3.1.  Creation of Protection Tokens

Protection tokens, or pTokens, are used as handles to the key management or the IPsec module of the host. The two main pToken attributes are enabling the BTNS extensions and controlling of iTokens. The former allows the use of IPSec without authentication, and the latter allows e.g. quering 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 Figure 6.

  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 Figure 7.

  ipsec_pToken_t ipsec_create_pToken();
  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.

2.3.2.  Attributes of Protection Tokens

Protection token attributes are shown in Figure 8. They are get or set using the functions defined in Section 2.1 (Token Attributes).

  enum {
       IPSEC_API_ATTR_privacyProtection,
       IPSEC_API_ATTR_integrityProtection,
       IPSEC_API_ATTR_compression,
       IPSEC_API_ATTR_iToken,
       IPSEC_API_ATTR_auditString
  } pToken_attribute;

The privacy, intergrity and compression attributes are 2-octet unsigned integer values. These attributes are writable before network communication and readable after network communications. Here the use of the attributes is described only from writing point of view. 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 the 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 attribute iToken is the peer identity in an iToken data structure. The auditString is a character array ending in zero byte and contains a human readable description of the protection token.

2.3.3.  Connection Oriented Communications

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 Figure 9.

  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. For ipsec_get_socket_pToken(), the pToken is actually a double pointer because the function also allocates the memory for the queried pToken.

Both functions return zero upon success, and non-zero upon failure.

2.3.4.  Datagram Oriented Communications

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

  int ipsec_set_msg_pToken(const 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(). The function allocates the memory required for the pToken and returns it to the caller in pToken, which is effectively a double pointer.

Both functions return zero on success and non-zero on failure.

2.3.5.  Equivalency of Protection Tokens

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 Figure 11.

  int ipsec_cmp_pToken(ipsec_pToken_t p1, ipsec_pToken_t p2);

Function ipsec_cmp_policy() 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 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).

2.3.6.  Duplication of Protection Tokens

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(ipsec_pToken_t *p, ipsec_pToken_t *p_dup);

3.  Security Considerations

The BTNS Stand Alone mode allows applications to omit network layer authentication. In this case, an application is using a higher level security mechanism, such as TLS, and thus the required level of security is maintained. The application has the control and duplicate security techniques are not applied.

The channel bindings allow applications to create and manage security channels. Given that applications omit higher layer security techniques based on information in an existing pToken and the corresping channel binding, there is a possibility for a security channel downgrade attack. In this attack, another application modifies the current application's channel binding in such a way that the application believes that an authenticated IPsec security channel to be active eventhough there is no such channel. If the application omits TLS or other higher level security mechanism, then there will not be a secured channel and transmitted data is exposed.

4.  IANA Considerations

TBD

5.  Acknowledgements

Thanks for Love Hörnquist Åstrand, Julien Laganier for feedback, ideas and discussion on the topic. The authors wish to thank also Simon Josefsson and Daniel McDonald for comments on the draft.

6.  References

6.1. Normative References

6.2. Informative References

Authors' Addresses

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.