Network Working Group D. L. McDonald Internet Draft Sun Microsystems draft-mcdonald-simple-ipsec-api-00.txt 1 November 1996 A Simple IP Security API Extension to BSD Sockets STATUS OF THIS MEMO This document is an Internet Draft. Internet Drafts are working documents. Internet Drafts are draft documents valid for a maximum of 6 months. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as "work in progress". A future version of this draft will be submitted to the RFC Editor for publication as an Informational document. ABSTRACT In order to take advantage of the IP Security Architecture [Atk95], an application should be able to tell the system what IP-layer security services it needs to function with some degree of confidence. A simple API that also allows simple security association policy to be set is presented here. This document descends from earlier work performed in the U. S. Naval Research Laboratory's IPv6 and IP security implementation [AMPMC96]. 1. INTRODUCTION IP security is required for IPv6 [DH95], and is also being developed and deployed for IPv4. The IP Security Architecture was designed to be used in two primary ways. The first is to use secured IP tunnels to connect virtual private networks over the global Internet. The second, which this API primarily addresses, is securing a single end-to-end session. The reader is assumed to be familiar with BSD sockets, and with the workings of IP and IP security. All references to "IP" refer to IPv4 McDonald, D. L. Expires in 6 months [Page 1]
Internet Draft Simple IPsec API 1 November 1996 and IPv6, unless otherwise stated. 1.1 STANDARDS TERMINOLOGY Even though this document is not intended to be a standard, the words that are used to define the significance of particular features of this proposal are usually capitalized. These words are: - MUST This word or the adjective "REQUIRED" means that the item is an absolute requirement of this document. - SHOULD This word or the adjective "RECOMMENDED" means that there might exist valid reasons in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before taking a different course. - MAY This word or the adjective "OPTIONAL" means that this item is truly optional. One vendor might choose to include the item because a particular marketplace requires it or because it enhances the product, for example; another vendor may omit the same item. 1.2 CONCEPTS AND DEFINITIONS The simple API presented in this draft are a series of set of socket options, set with the setsockopt() function, and, if applicable, obtained with the getsockopt() function. Before the actual socket options are detailed, some higher-level concepts and definitions are presented. 1.2.1 IP SECURITY CATEGORIES The basic socket options set a "security level" for three different categories of IP security proposed here. The three categories are (in order of application to an outbound datagram): ESP - Use of the encapuslating security payload header on the the (transport) payload section of an IP datagram This includes possibly performing authentication of the encrypted data. [Hug96] AH - Use of the authentication header on outgoing packets. The AH will be inserted just before the transport level header, or the ESP transport mode header. McDonald, D. L. Expires in 6 months [Page 2]
Internet Draft Simple IPsec API 1 November 1996 ESP - Encapsulating the entire outbound datagram using ESP, then (network) prepending a minimal IP header that matches the encrypted packet's IP header. 1.2.2 IP SECURITY LEVELS Security levels are a simple enumeration which expresses a policy. Each of the above categories of IP security has its own level. This enumeration, in order of least secure to most secure, is as follows: None - Do not use any security on outbound packets, and (or Default) accept any inbound packets, secured or not. If no security levels are set, this is the default value. (Not including, of course, systemwide default values. See below.) If available - If a security association is available, use it for outbound packets. Otherwise, behave like the level was set to IPSEC_LEVEL_NONE. Use - If a security association does not exist for outbound traffic, acquire one and use it for outbound packets. Still accept any inbound packets. Require - Unlike IPSEC_LEVEL_USE, this level REQUIRES that inbound packets use security, same as outbound ones. Require unique - This level is the same as IPSEC_LEVEL_REQUIRE, but adds the restriction that the security association for outbound traffic is used only for this session. This addresses certain issues raised in [Bel96]. 1.2.3 GLOBAL SECURITY LEVELS AND PER-SOCKET SECURITY LEVELS The concepts presented above assume that the three categories of IP security have global, or systemwide, default levels. When setting a socket's security level, the operating system will use the most secure of what is globally set, or what is requested by the user, for the security level for the socket. The reason "Default" is the same level as "None" in the previous section is to imply that the socket will use whatever the systemwide default is. Some applications, most notably key management daemons, implement their own security, and need to bypass any IP security mechanisms. A separate security level, designed only for these privileged applications, is needed. McDonald, D. L. Expires in 6 months [Page 3]
Internet Draft Simple IPsec API 1 November 1996 Bypass - Bypass the security policy. This level MUST only be settable by privileged applications (such as key management). 2. SOCKET OPTIONS FOR IP SECURITY Applications can use socket options to set and retrieve various combinations of security categories and levels. The setting of systemwide security levels is left undefined as an operating-system specific detail. The IP security socket options SHOULD be set immediately after a successful socket() call. This allows the amount of security requested to take effect immediately, before any packets flow to or from the socket. The general form of the options follow, with globbing syntax used to denote the IPv4/IPv6 cases: #include <netinet/in.h> ... int s, error; int seclevel; s = socket(AF_INET{,6}, SOCK_{DGRAM,STREAM}, 0); seclevel = <security level>; error = setsockopt(s, IPPROTO_IP{,V6}, <category>, seclevel, sizeof (int)); Values for <category> are as follows: IP{,V6}_AUTH_LEVEL /* Authentication level */ IP{,V6}_ESP_TRANS_LEVEL /* ESP Transport level */ IP{,V6}_ESP_NETWORL_LEVEL /* ESP Network level */ Values to assign to the variable seclevel in the example include: IPSEC_LEVEL_BYPASS /* Bypass policy altogether */ IPSEC_LEVEL_NONE /* Send clear, accept any */ IPSEC_LEVEL_DEFAULT /* see above */ IPSEC_LEVEL_AVAIL /* Send secure if SA available */ IPSEC_LEVEL_USE /* Send secure, accept any */ IPSEC_LEVEL_REQUIRE /* Require secure on inbound, also use */ McDonald, D. L. Expires in 6 months [Page 4]
Internet Draft Simple IPsec API 1 November 1996 IPSEC_LEVEL_UNIQUE /* Use outbound SA that is unique to me */ Changing security levels in the middle of a session can have unpredictable effects. Nothing prevents a user from changing security levels in the middle of a session, but different implementations may have different side-effects from such changes. The same same potential side-effects may occur while changing systemwide default security levels while sessions are active. 3. EXAMPLES This section contains some brief examples, with sample code. It also will diagram the IP packets as they appear on the wire with various options set. 3.1 SERVER In order to prevent session hijacking, a server program may wish to have all of its sessions require IP-layer authentication. The following code fragment shows how this desire is implemented. Assume the systemwide default security levels are all "None". An IPv6 example: ... s = socket(AF_INET6, SOCK_STREAM, 0); /* IPv6 socket */ /* Now that I have the socket, set the security options. */ level = IPSEC_LEVEL_REQUIRE; error = setsockopt(s, IPPROTO_IPV6, IPV6_AUTH_LEVEL, (char *)&level, sizeof (int)); /* Now call bind(), listen(), etc. */ The server program will not see any inbound requests unless they are authenticated. The server will also send outbound datagrams with authentication. For example: ClientA Server Calls vanilla --- IPv6+TCP(syn) ----> Finds right port, but drop connect(). packet, not authenticated. ---------- McDonald, D. L. Expires in 6 months [Page 5]
Internet Draft Simple IPsec API 1 November 1996 ClientB Server Calls connect() -- IPv6+AH+TCP(syn) --> Passes policy, TCP handles after setting SYN, and sends back... up AH use. Handles SYN/ACK <-IPv6+AH+TCP(syn/ack)- ...this. and sends back -- IPv6+AH+TCP(ack) --> At this point, an accept() happens, and data now flows with AH in all packets. Sockets created by the accept() function will inherit the parent's security attributes. In this example, all sockets created by accept() will require (and use) authentication. 3.2 KEY MANAGEMENT DAEMON AND BYPASS On a system with systemwide security levels set to values other than, "None," a key management daemon, which needs to send its packets in the clear, will have to bypass systemwide security levels in all three categories. An IPv4 example: ... s = socket(AF_INET, SOCK_DGRAM, 0); /* IPv4 socket */ /* * Need to bypass system security policy, so I can send and * receive key management datagrams in the clear. */ level = IPSEC_LEVEL_BYPASS; /* Did I mention I'm privileged? */ error = setsockopt(s, IPPROTO_IP, IP_AUTH_LEVEL, (char *)&level, sizeof (int)); /* Check error */ error = setsockopt(s, IPPROTO_IP, IP_ESP_TRANS_LEVEL, (char *)&level, sizeof (int)); /* Check error */ error = setsockopt(s, IPPROTO_IP, IP_ESP_NETWORK_LEVEL, (char *)&level, sizeof (int)); /* Check error */ /* Now I'm ready to send exchanges in the clear. */ McDonald, D. L. Expires in 6 months [Page 6]
Internet Draft Simple IPsec API 1 November 1996 All packets will subsequently be sent without any IPsec extensions. Initiator Receiver Calls sendto() ---- IPv4+UDP -----> Gets packet. Calls sendto(). Packet will <---- IPv4+UDP ----- be accepted. 3.3 CLIENT Client code works pretty much the same as server code with respect to when the socket options should be set. Again, assume the systemwide security level is set to "None". ... s = socket(AF_INET6, SOCK_STREAM, 0); /* IPv6 socket */ /* Now that I have the socket, set the security options. */ level = IPSEC_LEVEL_REQUIRE; error = setsockopt(s, IPPROTO_IPV6, IPV6_AUTH_LEVEL, (char *)&level, sizeof (int)); /* Now call connect(). */ The packets sent out here are illustrated in the "ClientB" portion of the example in section 3.1. 4. OPEN ISSUES, FUTURE DIRECTIONS, AND TOPICS FOR AN ADVANCED IPSEC API There are still several outstanding issues with this simple API. Some of these issues will have to be addressed in future revisions of this document, others are beyond its scope. One issue is that of certificates, and endpoint identities. For a two-party unicast session, it is possible that both communicating parties wish to have key management exchange keying information using certificates of the parties' own choosing. This information somehow has to be associated with the communicating endpoints. Either a hint or an explicit certificate identity needs to be communicated with an endpoint, and may be needed for even a simple IP security API. The larger issues of multicast, or even unicast datagrams to multiple recipients from the same source complicate this issue. McDonald, D. L. Expires in 6 months [Page 7]
Internet Draft Simple IPsec API 1 November 1996 Other issues relate to applying advanced policy to endpoints. An open question centers around an application's ability to select its IPsec algorithm. Some argue that an application should be able to specify precisely what algorithm is used for its ESP or AH computations. Others would just like to have a metric that corresponds to algorithm strength, and use some value to specify algorithm strength. Also more sophisticated algorithm selection strategies (e.g. Use 3DES if you can, otherwise, use vanilla DES) need to be considered. Key strength (e.g. Don't accept incoming connections unless the SA's key is sufficiently strong) is another such advanced policy issue. Advances in what policies are in the domain of the endpoint will become clear from future research and development. There are probably other issues not mentioned here out of ignorance or oversight. Those issues should be brought to the author's attention. 5. SECURITY CONSIDERATIONS Security API's need a well-designed operating system underneath them. If the operating system does not enforce its own user policy properly, it is possible that IP security policy cannot be properly enforced. ACKNOWLEDGEMENTS The initial work on such an API was performed at the U. S. Naval Research Laboratory as part of their IPv6/IPsec implementation. Bao Phan, Ron Lee, and Craig Metz are the current members of the NRL team. Ran Atkinson provided many useful insights both as former NRL team member and current IPsec co-chair. REFERENCES [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite BSD", Proceedings of the 1996 USENIX Conference, San Diego, CA, January 1996, USENIX Association. [Atk95] Randall J. Atkinson, IP Security Architecture, RFC-1825, August 1995. [Bel96] Steven M. Bellovin, "Problem Areas for the IP Security Protocols", Proceedings of the Sixth USENIX UNIX Security Symposium, San Jose, CA, June 1996, USENIX Association. McDonald, D. L. Expires in 6 months [Page 8]
Internet Draft Simple IPsec API 1 November 1996 [DH95] S. Deering and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", RFC 1883. [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay Prevention Security Transform", Internet Draft, April 1996. DISCLAIMER The views and specification here are those of the author and are not necessarily those of his employer. The employer has not passed judgement on the merits, if any, of this work. The author and his employer specifically disclaim responsibility for any problems arising from correct or incorrect implementation or use of this specification. AUTHOR INFORMATION Daniel L. McDonald Sun Microsystems, Inc. 2550 Garcia Avenue, MS UMPK17-202 Mountain View, CA 94043-1100 E-mail: danmcd@eng.sun.com Voice: (415) 786-6815 Fax: (415) 786-5896 McDonald, D. L. Expires in 6 months [Page 9]