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 <netinet/in.h>
...
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 = <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 */
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:
<Route> 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]