One document matched: draft-mcdonald-simple-ipsec-api-00.txt
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]
| PAFTECH AB 2003-2026 | 2026-04-23 08:44:41 |