Network Working Group D. L. McDonald Internet Draft Sun Microsystems draft-mcdonald-simple-ipsec-api-01.txt 20 March 1997 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 20 March 1997 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 20 March 1997 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. This level is primarily designed for IP server applications that wish to mirror their client's behavior. A server is usually a receiver in terms of key management [MSST96], so if a sender has initiated a negotiation, the server will use the association already in place. Key management MAY be invoked at this phase. Once an SA is established, the packets MAY use the SA that was established. Unlike the next level, traffic can flow independently from any key management. Use - If a security association does not exist for outbound traffic, acquire one and use it for outbound packets. Still accept any inbound packets. As the previous level is designed for IP server applications, this level SHOULD NOT be used by server applications. A malicious attacker can send several initial unsecure packets, and the server, being set to this level, will initiate key managment for clients that do not exist. The resources spent on such negotiations will slow the server down unacceptably. 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 McDonald, D. L. Expires in 6 months [Page 3] Internet Draft Simple IPsec API 20 March 1997 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. The Open Issues section discusses other possbilities for IP security policy. 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. 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 ... int s, error; int seclevel; s = socket(AF_INET{,6}, SOCK_{DGRAM,STREAM}, 0); McDonald, D. L. Expires in 6 months [Page 4] Internet Draft Simple IPsec API 20 March 1997 seclevel = ; error = setsockopt(s, IPPROTO_IP{,V6}, , seclevel, sizeof (int)); Values for 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 */ 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: McDonald, D. L. Expires in 6 months [Page 5] Internet Draft Simple IPsec API 20 March 1997 ... 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. ---------- 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: McDonald, D. L. Expires in 6 months [Page 6] Internet Draft Simple IPsec API 20 March 1997 ... 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. */ 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)); McDonald, D. L. Expires in 6 months [Page 7] Internet Draft Simple IPsec API 20 March 1997 /* 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. This section outlines these issues, and in some cases illustrates them. Many of the ideas discussed here will require implementation experience, and many may require extensive rework of existing codebases. Some intermidiate-level granularity may prove valuable in helping a system implement an IP security policy. Using the simple attributes described above, one such intermediate-level granularity is the per- route policy. Consider the following example: ESP Trans. AH ESP Network Global/Default None If avail None 10.21.12.0/24 None Require None 10.51.50.0/24 Require Require None 10.91.25.0/24 None None None If a datagram was heading out for 10.51.50.21, It would require both ESP Transport and AH. Likewise packets arriving from 10.51.50.21 will need to have both ESP transport and AH on each packet. The advantage to performing per-route policy is that it allows a finer granularity of security, and will increase performance on non- security-critical routes. The disadvantages include adding more data to routing entries, confusion with concepts such as the tunelling interfaces (e.g. 10.8.0.0/16 traffic being encrypted inside IP datagrams bound for a tunnel endpoint of 10.10.14.4), and the requirement of checking routes for source addresses on inbound datagrams. 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 8] Internet Draft Simple IPsec API 20 March 1997 Another useful property of certificates is to allow identification of an incoming TCP connection. This may allow programs like rlogin and rsh to provide certificate-based access control. Keeping this in mind, some new library calls might be added to a socket library. /* Include files and certificate_info_t need to be defined. */ int setmycert(int socket, certificate_info_t *cert); int getmycert(int socket, certificate_info_t *cert); int setpeercert(int socket, certificate_info_t *cert); int getpeercert(int socket, certificate_info_t *cert); These are hypothetical library routines that might be used by an application to set varying certificate properties. The first call, setmycert() would be made by either active or passive sockets to attach a local certificate (or certificate identity) to a socket. The second call, getmycert(), might be used if the socket is inherited from a parent process. The third call, setpeercert() might be made before calling connect() or sendto() to pass a hint to key management about which peer it needs to negotiate keys with. The last call, getpeercert() would obtain the peer certificate of the security assocation of the last datagram received. While note as useful with a connectionless datagram socket, it would be very useful for a connection-oriented socket, such as a TCP socket. This call would allow access control based on peer certificate identities. This would add strength to programs such as rsh or rlogin, allowing cryptographic assurances of a peer's identity. Sometimes, one security association pair is enough to protect several connections. (A web page with many tiny GIFs is one such example. This may say something for fixing HTTP, however.) In such a case, a call might be necessary to make sure that a socket is protected by the same IP Security Associations that another one is. Another advantage of this is where if (as above) the normal system policy is UNIQUE keying, this can bypass it with the knowledge of the application. An open question centers around an application's ability to select its IPsec algorithm(s) or transforms. 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. Still others argue that the system may have a policy that disallows user-selected algorithm strengths. If user selection is allowed, 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 McDonald, D. L. Expires in 6 months [Page 9] Internet Draft Simple IPsec API 20 March 1997 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. ISAKMP has a concept of a "proposed situation" and that may well be what a socket needs to specify in part or in whole. 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. Properties mentioned in this document SHOULD not cause weaknesses in a system's security. If anything does, it MUST be documented (like the denial of service bug). 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. Many of the advanced API topics and other refinements come from very fruitful discussions with Steve Bellovin. Jeremy McCooey of the University of New Hampshire pointed out the denial of service attack on server applications using the "Use" security level. Bill Sommerfeld introduced the "If available" level before the attack was pointed out to the author, and in fact may have been a pre-emptive defense against such an attack. 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", McDonald, D. L. Expires in 6 months [Page 10] Internet Draft Simple IPsec API 20 March 1997 Proceedings of the Sixth USENIX UNIX Security Symposium, San Jose, CA, June 1996, USENIX Association. [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. [MSST96] Douglas Maughan, Mark Schertler, Mark Schneider, and Jeff Turner, "Internet Security Association and Key Management Protocol (ISAKMP)", Internet Draft, November, 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 APPENDIX A: CHANGE LOG The following changes have occured since the draft-mcdonald-simple-ipsec-api-00.txt: * Detailed a semantic of the "Available" security level. This may cause another level to be added, depending on people's perception of the semantics. * Detailed denial-of-service attack if a server program sets its IPsec level to USE. * Added per-route policy discussion in Open Issues. McDonald, D. L. Expires in 6 months [Page 11] Internet Draft Simple IPsec API 20 March 1997 * Added proposal for certificate identities in Open Issues. * Added SA inheritance discussion in Open Issues. * Rewording about algorithm/transform selection. * Added acknowledgements where appropriate. McDonald, D. L. Expires in 6 months [Page 12]