Better than Nothing Security M. Komu Internet-Draft Tarkoma Intended status: Standards Track Helsinki Institute for Information Expires: September 7, 2007 Technology March 6, 2007 IPsec Application Programming Interfaces draft-komu-btns-api-01 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 September 7, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract IPsec based security is usually transparent for applications and and they h have no common mechanism for gathering information about protected network connections and being aware of underlying security mechanisms. This document specifies an API that increases the Komu & Tarkoma Expires September 7, 2007 [Page 1] Internet-Draft IPsec APIs March 2007 visibility of IPsec to applications. The API allows applications to use the Stand-alone BTNS mode, control the channel bindigs, and control also other network security properties related to IPsec. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. IPsec APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. IPsec Policies . . . . . . . . . . . . . . . . . . . . . . 5 2.1.1. Policy Creation . . . . . . . . . . . . . . . . . . . 5 2.1.2. Policy Attributes . . . . . . . . . . . . . . . . . . 6 2.1.3. Connection Oriented Communications . . . . . . . . . . 7 2.1.4. Datagram Oriented Communications . . . . . . . . . . . 7 2.1.5. Other Policy Related Functions . . . . . . . . . . . . 8 2.2. Channel Bindings . . . . . . . . . . . . . . . . . . . . . 8 2.2.1. Channel Creation . . . . . . . . . . . . . . . . . . . 8 2.2.2. Channel Attributes . . . . . . . . . . . . . . . . . . 9 2.2.3. Connection Oriented Communications . . . . . . . . . . 10 2.2.4. Datagram Oriented Communications . . . . . . . . . . . 10 2.2.5. Other Channel Related Function . . . . . . . . . . . . 11 3. Security Considerations . . . . . . . . . . . . . . . . . . . 12 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 Appendix A. Appendix . . . . . . . . . . . . . . . . . . . . . . 12 Appendix A.1. Code Examples . . . . . . . . . . . . . . . . . . . 12 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 6.1. Normative References . . . . . . . . . . . . . . . . . . . 19 6.2. Informative References . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 Intellectual Property and Copyright Statements . . . . . . . . . . 21 Komu & Tarkoma Expires September 7, 2007 [Page 2] Internet-Draft IPsec APIs March 2007 1. Introduction The "better than nothing" (BTNS) extensions 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 BTNS related APIs. The network communications of applications are usually secured explicitly with TLS on transport layer [RFC4346], or using even higher layer interfaces such as GSS [RFC2744] or SASL [RFC4422] 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 "all or nothing" security measure, which can be problematic in early deployments when the number of IPsec enabled machines is small. An alternative approach could be to use IPsec in "use when peer supports" fashion. However, the application or the user may not have any knowledge that the communications was actually protected in this case. Finally, it is more efficient to remove redundant authentications when IPsec and TLS are being used for the same connection. In this document, we attempt to increase the visibility of the IPsec layer to the applications and to fulfil the BTNS requirements presented in [I-D.ietf-btns-ipsec-apireq]. The APIs defined in this document are based on the sockets API [POSIX] or similar APIs that provide socket descriptors for applications. 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 simultaneously. The security and performance related benefits of this are described in more detail in [I-D.ietf-btns-prob-and-applic]. Komu & Tarkoma Expires September 7, 2007 [Page 3] Internet-Draft IPsec APIs March 2007 +---------+---------+---------+---------+ | 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 Figure 1 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 policies and channel bindings. The definitions are based on C-language. An application creates first a policy and attaches some attributes Komu & Tarkoma Expires September 7, 2007 [Page 4] Internet-Draft IPsec APIs March 2007 for it. For example, the application can define in the attributes that it wants to use CBB mode for a certain socket. After this, the application can require certain channel bindings from the socket (to implement ACLs, for example) and try to communicate with a peer through the socket. Alternatively, the application can do a leap of faith with first time communication with the peer and store the channel bindings for later use. See Appendix A.1 for code examples on how to use the APIs in practise. 2.1. IPsec Policies This section defines functions that manage application policies. The policies are used to control the key management software or the IPsec module of a host. The two main policy attributes are the following: controlling BTNS standalone mode and requiring channel bindings. The former prevents IPSec authentication, and the latter allows channel creation and management. 2.1.1. Policy Creation The data structure that represents an application policy is contained in an opaque ipsec_policy 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_policy_t typedef as a short hand for the policy structure. The typedef is shown in Figure 2. typedef ipsec_policy_t struct ipsec_policy; Figure 2 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 3. ipsec_policy_t *ipsec_create_policy(uint32_t type); int ipsec_free_policy(ipsec_policy_t *policy); Figure 3 Function ipsec_create_policy allocates memory for a policy and initializes it. The function returns the created policy, or NULL upon failure. The function takes one input argument that initializes the default policy type. The different policy types are listed in Table 1. Komu & Tarkoma Expires September 7, 2007 [Page 5] Internet-Draft IPsec APIs March 2007 +----------------------+-----------------+ | Policy Type | Purpose | +----------------------+-----------------+ | IPSEC_DEFAULT_POLICY | System defaults | +----------------------+-----------------+ Table 1 Function ipsec_free_policy deinitializes and frees the memory allocated to a policy. It returns zero on success, and non-zero upon failure. 2.1.2. Policy Attributes Policies are opaque data structures that MUST NOT be manipulated directly. Instead, the application uses the accessor functions shown in Figure 4. int ipsec_get_policy_attr(const ipsec_policy_t *policy, uint32_t attr_type, uint32_t *attr_len, void **attr_val); int ipsec_set_policy_attr(ipsec_policy_t *policy, uint32_t attr_type, uint32_t attr_len, const void *attr_val); Figure 4 Function ipsec_get_policy_attr searches for the given attribute type (attr_type) from the policy. It allocates memory into attr_val and copies the attribute into the allocated memory. On successful operation, it sets the attribute length in attr_len. Function ipsec_set_policy_attr writes the attribute (attr_val) to the policy. The type and length of the attribute must be set in attr_type and attr_len. The attribute types and their lengths are shown in Table 2. +----------------------------+----------+---------------------------+ | Attribute Type | Length | Purpose | +----------------------------+----------+---------------------------+ | IPSEC_BTNS_STANDALONE | 4 octets | Allow BTNS standalone | | | | mode | | IPSEC_BTNS_CHANNEL_BINDING | 4 octets | Require channel bindings | +----------------------------+----------+---------------------------+ Komu & Tarkoma Expires September 7, 2007 [Page 6] Internet-Draft IPsec APIs March 2007 Table 2 Both of the functions return zero for success and non-zero for failure. XX FIX list error values here. 2.1.3. Connection Oriented Communications Declaring a policy does not affect the networking communications of an application. For connection oriented communications, the application must first attach the policy to socket before the policy is effective. It is also possible to query for the policy attached to a socket as shown in Figure 5. int ipsec_set_socket_policy(int fd, const ipsec_policy_t *policy); int ipsec_get_socket_policy(int fd, ipsec_policy_t **policy); Figure 5 Both functions input an socket descriptor as the first argument and a policy pointer as the second argument. Function ipsec_set_socket_policy attaches the given policy pointer to the socket descriptor fd. For ipsec_get_socket_policy, the policy is a double pointer because the function also allocates the memory for the queried policy. Both functions return zero upon success, and non-zero upon failure. XX FIX list error values here. 2.1.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 functions are shown in Figure 6. int ipsec_set_msg_policy(const struct msghdr *msg, const ipsec_policy_t *policy); int ipsec_get_msg_policy(const struct msghdr *msg, ipsec_policy_t **policy); Figure 6 Function ipsec_set_msg_policy applies the given policy to the msg data structure. The policy of a msg can be queried using ipsec_get_msg_policy. It allocates the memory required for the policy and returns it to the caller in policy double pointer. Komu & Tarkoma Expires September 7, 2007 [Page 7] Internet-Draft IPsec APIs March 2007 Both functions return zero on success and non-zero on failure. XX FIX list error values here. 2.1.5. Other Policy Related Functions An application is not allowed to read or write to policies directly. The same restriction applies also to comparison and byte-wise copying of policies. Theses operations have their own accessor functions that are shown in Figure 7. int ipsec_cmp_policy(ipsec_policy_t *p1, ipsec_policy_t *p2); int ipsec_dup_policy(ipsec_policy_t *p, ipsec_policy_t **p_dup); Figure 7 Function ipsec_cmp_policy inputs two policies, p1 and p2, and returns zero if they are equal. Otherwise it returns non-zero. Function ipsec_dup_policy duplicates given policy p and writes it to p_dup. The function allocates the memory for duplicated policy that the caller is responsible of freeing. Return value is zero on success and non-zero on failure. XX list error values here. 2.2. Channel Bindings Channel bindings are handled locally at the host, i.e., they are not communicated with a peer host. The channel bindings allow the application to replace network layer authentication with, e.g., TLS certificates. In addition, application can store the channel binding information and use it to verify that it is still talking to the same host in subsequent communications. 2.2.1. Channel Creation Similarly to policies, also channel related information is stored in an opaque structure. An application MUST not read or write directly channel information data structures, but rather use the accessor functions introduce in the following sections. Typedef for channel information is shown in Figure 8. typedef ipsec_channel_info_t struct ipsec_channel_info; Figure 8 Channel information data structures are created and initialized using ipsec_create_channel_info function. Deallocation is handled through Komu & Tarkoma Expires September 7, 2007 [Page 8] Internet-Draft IPsec APIs March 2007 ipsec_free_channel_info function. The functions are shown in Figure 9. ipsec_channel_info_t *ipsec_create_channel_info(); int ipsec_free_channel_info(*ipsec_channel_info_t *ci); Figure 9 Function ipsec_create_channel_info allocated memory for the channel information and returns it to the caller. Upon failure, it returns NULL. ipsec_free_channel_info deallocates the given channel information data structure ci. It returns zero on success and non-zero on failure. 2.2.2. Channel Attributes The details of the channel information can be queried and set using the functions shown in Figure 10. int ipsec_set_channel_attr(ipsec_channel_info_t *ci, uint32_t attr_type, uint32_t attr_len, const void *attr_val); int ipsec_get_channel_attr(const ipsec_channel_info_t *ci, uint32_t attr_type, uint32_t *attr_len, void **attr_val); Figure 10 Function ipsec_set_channel_attr writes the given channel attribute attr_val to the channel information ci. The length and type of the attribute are passed in attr_type and attr_len. Function ipsec_get_channel_attr reads the channel attribute from ci, allocates memory for the attribute and writes the queried attribute (attr_type) to attr_val. The function writes the length of the attribute to attr_len. Different attribute types along with lengths are shown in Table 3. Komu & Tarkoma Expires September 7, 2007 [Page 9] Internet-Draft IPsec APIs March 2007 +----+----+----+ | xx | xx | xx | +----+----+----+ | xx | xx | xx | +----+----+----+ Table 3 Both of the attribute functions return zero on success and non-zero on failure. The error values are listed in Table 4. +----+----+ | xx | xx | +----+----+ | xx | xx | +----+----+ Table 4 2.2.3. Connection Oriented Communications With connection oriented sockets, an application can attach channel information to a socket with ipsec_set_socket_channel_info function. The channel information can be e.g. a TLS certificate. In turn, ipsec_get_socket_channel_info function can be used to query the channel information attached to a socket. The application can use this information to e.g. verify that it is talking to the same host as before. Figure Figure 11 shows the get and set functions. int ipsec_set_socket_channel_info(int fd, const ipsec_channel_info_t *ci); int ipsec_get_socket_channel_info(int fd, ipsec_channel_info_t **ci); Figure 11 Both of the functions input a socket descriptor fd. Function ipsec_set_socket_channel_info inputs the channel information to be set in ci. Function ipsec_get_socket_channel_info allocates memory for channel information and outputs it to ci. The functions return zero on success and non-zero on failure. XX fix list error values here. 2.2.4. Datagram Oriented Communications When an application uses sendmsg or recvmsg calls for datagram oriented communications, it can use the functions shown in Figure 12. Komu & Tarkoma Expires September 7, 2007 [Page 10] Internet-Draft IPsec APIs March 2007 Functions recvfrom and sendto are not supported. int ipsec_set_msg_channel_info(const struct *msg_hdr, const ipsec_channel_info_t *ci); int ipsec_get_msg_channel_info(const struct *msg_hdr, ipsec_channel_info_t **ci); Figure 12 Function ipsec_set_msg_channel_info attaches the channel information ci into the msg_hdr. Function ipsec_get_msg_channel_info reads channel information from msg_hdr, allocates memory for it and returns it in ci. Both functions return zero on success and non-zero on failure. XX FIX list error values here. 2.2.5. Other Channel Related Function Channel information is opaque and must be operated through accessor functions. Channel information comparison, duplication and conversion functions are shown in Figure 13. int ipsec_cmp_channel_info(const ipsec_channel_info_t *ci1, const ipsec_channel_info_t *ci2); int ipsec_dup_channel_info(const ipsec_channel_info_t *ci, ipsec_channel_info_t **ci_dup); int ipsec_openssl_to_channel_info(const SSL *ssl, const ipsec_policy_t *policy, ipsec_channel_info_t **ci); Figure 13 Function ipsec_cmp_channel_info compares channel information ci1 and ci2. It returns zero when they are equal or non-zero when they are different. Channel information is duplicated using ipsec_dup_channel_info. It inputs channel information ci and outputs the duplicated ci_dup. The function reserves memory for the duplicated channel information. Return value is zero on success and non-zero on failure. XX FIX list error values here. Function ipsec_openssl_to_channel_info converts an OpenSSL data structure ssl to channel information ci according to the rules in the given policy. The function reserves memory for the created channel information. Komu & Tarkoma Expires September 7, 2007 [Page 11] Internet-Draft IPsec APIs March 2007 The function returns zero on success and non-zero on failure. XX FIX list error values here. 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 policy and 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 Michael Richardson, Love Hoernquist Aestrand, Nicolas Williams and Julien Laganier for feedback, ideas and discussion on the topic. Appendix A. Appendix Appendix A.1. Code Examples This section shows code examples that illustrate the use of the APIs. Error value handling is not very verbose to keep the code length smaller. In addition, the code snippets do not show e.g. address resolution at all. int hello_conn_client(int domain, int type, int family, Komu & Tarkoma Expires September 7, 2007 [Page 12] Internet-Draft IPsec APIs March 2007 const struct sockaddr *sockaddr, socklen_t sockaddr_len, ipsec_channel_info_t **old_channel) { int sockfd = 0, err = 0, hello_len; unint32_t on = 1; ipsec_channel_info_t *channel_info = NULL; ipsec_policy_t *policy = NULL; char *hello = "hello world"; ssize_t count; hello_len = strlen(hello); sockfd = socket(domain, type, family); if (sockfd < 0) { err = -1; goto out; } /* Set socket policy to allow btns in channel binding mode. This way, lower layer authentication can be omitted because we are using TLS with certificates for this connection */ policy = ipsec_new_policy(IPSEC_DEFAULT_POLICY); if (policy == 0) goto out_err; err = ipsec_set_policy_attr(policy, IPSEC_BTNS_STANDALONE, sizeof(on), &on); if (err) goto out; err = ipsec_set_socket_policy(sockfd, policy); if (err) goto out; /* If we have contacted the peer before, we can ensure that the host is still the same by reusing the old channel binding */ if (*old_channel) { err = ipsec_set_socket_channel_info(sockfd, *old_channel); if (err) goto out; } /* In the case of TCP, connect() triggers a TCP handshake that is protected by IPsec according to the policy */ Komu & Tarkoma Expires September 7, 2007 [Page 13] Internet-Draft IPsec APIs March 2007 err = connect(sockfd, sockaddr, sockaddr_len); if (err) goto out; /* Store new channel bindings for subsequent communications */ if (*old_channel == NULL) { /* Store channel information to the old_channel_info to check that the peer host is the still the same. */ err = ipsec_dup_channel_info(channel_info, old_channel) } /* Send data protected using IPsec according to the policy. */ count = send(sockfd, hello, hello_len, 0); if (count != hello_len) { err = -1; goto out; } out: if (channel_info) ipsec_free_channel_info(channel_info); if (sockfd) close(sockfd); if (policy) ipsec_free_policy(policy); return err; } Figure 14: Connection Oriented Client Example int hello_tls_conn_client(char *hostname, int domain, int type, int family, const struct sockaddr *sockaddr, socklen_t sockaddr_len, SSL_ctx *ctx, ipsec_channel_info_t **old_channel) { int sockfd = 0, err = 0, hello_len; unint32_t on = 1; ipsec_channel_info_t *channel_info = NULL; ipsec_policy_t *policy = NULL; Komu & Tarkoma Expires September 7, 2007 [Page 14] Internet-Draft IPsec APIs March 2007 char *hello = "hello world"; SSL *ssl = NULL; BIO *bio = NULL; ssize_t count; hello_len = strlen(hello); sockfd = socket(domain, type, family); if (sockfd < 0) { err = -1; goto out; } /* Set socket policy to allow btns in channel binding mode. This way, lower layer authentication can be omitted because we are using TLS with certificates for this connection */ policy = ipsec_new_policy(IPSEC_DEFAULT_POLICY); if (policy == 0) goto out_err; err = ipsec_set_policy_attr(policy, IPSEC_BTNS_CHANNEL_BINDING, sizeof(on), &on); if (err) goto out; err = ipsec_set_socket_policy(sockfd, policy); if (err) goto out; /* If we have contacted the peer before, we can ensure that the host is still the same by reusing the old channel binding */ if (*old_channel) { err = ipsec_set_socket_channel_info(sockfd, *old_channel); if (err) goto out; } /* Do TCP handshake that is protected using IPsec according to the application's policy */ err = connect(sockfd, sockaddr, sockaddr_len); if (err) goto out; /* Create ssl structure and associate sockfd to it. Do TLS handshake and verify server certificate. */ Komu & Tarkoma Expires September 7, 2007 [Page 15] Internet-Draft IPsec APIs March 2007 ssl = SSL_new(ctx); if (ssl == NULL) goto out; bio = BIO_new_socket(sockfd, BIO_NOCLOSE); if (bio == NULL) goto out; SSL_set_bio(ssl, bio, bio); if (SSL_connect(ssl) �= 0) goto out; if (verify_server_cert(ssl, hostname)) goto out; /* First connection attempt to the peer host. Get channel binding info from ssl according to the policy rules (the policy selects e.g. the certificate). Store it to verify subsequent communications */ if (*old_channel == NULL) { err = ipsec_openssl_to_channel_info(ssl, policy, &channel_info); if (err) goto out; err = ipsec_dup_channel_info(channel_info, old_channel) if (err) goto out; } /* Encrypt and send the data. For simplicity, a for loop is omitted here that would ensure all bytes were sent */ count = SSL_write(ssl, hello, hello_len); if (count != hello_len) { err = -1; goto out; } out: if (channel_info) ipsec_free_channel_info(channel_info); if (bio) BIO_free(bio) if (ssl) SSL_free(ssl); if (sockfd) close(sockfd); if (policy) ipsec_free_policy(policy); Komu & Tarkoma Expires September 7, 2007 [Page 16] Internet-Draft IPsec APIs March 2007 return err; } Figure 15: Connection Oriented TLS Client Example int hello_msg_client(int domain, int type, int family, const struct msg_hdr *hello_msg, ssize_t hello_len, socklen_t sockaddr_len, ipsec_channel_info_t **old_channel) { int sockfd = 0, err = 0, hello_len; unint32_t on = 1; ipsec_channel_info_t *channel_info = NULL; ipsec_policy_t *policy = NULL; ssize_t count; sockfd = socket(domain, type, family); if (sockfd < 0) { err = -1; goto out; } /* Set socket policy to allow btns in channel binding mode. This way, lower layer authentication can be omitted because we are using TLS with certificates for this connection */ policy = ipsec_new_policy(IPSEC_DEFAULT_POLICY); if (policy == 0) goto out_err; err = ipsec_set_policy_attr(policy, IPSEC_BTNS_STANDALONE, sizeof(on), &on); if (err) goto out; /* Send data to the peer. Data and peer are both defined in the msg header. If a previous channel binding is provided, use it to ensure that we are still talking to the same host */ if (*old_channel != NULL ) { err = ipsec_set_msg_policy(hello_msg, policy); if (err) goto out_err; Komu & Tarkoma Expires September 7, 2007 [Page 17] Internet-Draft IPsec APIs March 2007 err = ipsec_set_msg_channel_info(hello_msg, *old_channel); if (err) goto out_err; } count = sendmsg(sockfd, hello_msg, 0); if (count != hello_len) { err = -1; goto out; } /* If we just communicated with the peer for the first time, let's query and store the channel info for subsequent communications */ if (*old_channel == NULL) { err = ipsec_get_msg_channel_info(hello_msg, &channel_info); if (err) goto out_err; err = ipsec_dup_channel_info(channel_info, old_channel); } /* Let's receive a message from the peer. Apply IPsec policy and reuse the previous channel binding to ensure that we are still talking to the same host. */ err = ipsec_set_msg_policy(hello_msg, policy); if (err) goto out_err; err = ipsec_set_msg_channel_info(hello_msg, channel_info); if (err) goto out_err; count = recvmsg(sockfd, hello_msg, 0); if (count != hello_len) { err = -1; goto out; } out: if (channel_info) ipsec_free_channel_info(channel_info); if (sockfd) close(sockfd); if (policy) ipsec_free_policy(policy); return err; Komu & Tarkoma Expires September 7, 2007 [Page 18] Internet-Draft IPsec APIs March 2007 } Figure 16: Datagram Oriented Client Example 6. References 6.1. Normative References [I-D.ietf-btns-ipsec-apireq] Richardson, M. and B. Sommerfeld, "Requirements for an IPsec API", draft-ietf-btns-ipsec-apireq-00 (work in progress), April 2006. [I-D.ietf-btns-prob-and-applic] Touch, J., "Problem and Applicability Statement for Better Than Nothing Security (BTNS)", draft-ietf-btns-prob-and-applic-05 (work in progress), February 2007. [POSIX] Institute of Electrical and Electronics Engineers, "IEEE Std. 1003.1-2001 Standard for Information Technology - Portable Operating System Interface (POSIX)", Dec 2001. 6.2. Informative References [RFC2744] Wray, J., "Generic Security Service API Version 2 : C-bindings", RFC 2744, January 2000. [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. Komu & Tarkoma Expires September 7, 2007 [Page 19] Internet-Draft IPsec APIs March 2007 Authors' Addresses Miika Komu Helsinki Institute for Information Technology Tammasaarenkatu 3 Helsinki Finland Phone: +358503841531 Fax: +35896949768 Email: miika@iki.fi URI: http://www.iki.fi/miika/ Sasu Tarkoma Helsinki Institute for Information Technology Tammasaarenkatu 3 Helsinki Finland Phone: +358503841517 Fax: +35896949768 Email: sasu.tarkoma@hiit.fi URI: http://www.cs.helsinki.fi/u/starkoma/ Komu & Tarkoma Expires September 7, 2007 [Page 20] Internet-Draft IPsec APIs March 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). 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. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Komu & Tarkoma Expires September 7, 2007 [Page 21]