[Search] [txt|pdfized|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00                                                            
IP Security Policy                                         W. Sommerfeld
Internet-Draft                                          Sun Microsystems
Expires: December 16, 2003                                 June 17, 2003

                     Requirements for an IPsec API

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   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-

   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://

   The list of Internet-Draft Shadow Directories can be accessed at

   This Internet-Draft will expire on December 16, 2003.

Copyright Notice

   Copyright (C) The Internet Society (2003).  All Rights Reserved.


   Given the open nature of the Internet today, application protocols
   require strong security.  IPsec's wire protocols appear to meet the
   requirements of many protocols.  The lack of a common model for
   application-layer interfaces has complicated use of IPsec by upper-
   layer protocols.  This document provides an overview of facilities
   which a host IPsec implementation should provide to applications to
   allow them to both observe and influence how IPsec protects their

1. Motivation for this work

   Many protocols under development are considering the use of IPsec for

Sommerfeld             Expires December 16, 2003                [Page 1]

Internet-Draft           IPsec API requirements                June 2003

   security.  Unfortunately, most existing IPsec implementations do not
   give applications any visibility into what, if anything, they are
   doing on behalf of an application.  This limitation only allows IPsec
   to do all-or-nothing access control, and requires two levels of
   authentication, with one within the application, and a second level
   within an IPsec key management protocol (most typically IKE

2. Terminology

   The term "socket" will be used here to identify an application-layer
   communications endpoint; it does imply any specific API is to be
   used.  For the purposes of this discussion, a socket may include:

      A communications endpoint for a connectionless protocol

      One end of an established connection for a connection-oriented

      A listening endpoint for a connection-oriented protocol

   For the purposes of this document, the term "application" refers to
   programs implementing any client protocol using either IP or a
   transport protocol such as TCP or UDP running over IP.  Note that
   this is in many ways somewhat broader than the traditional use of
   "application" within the IETF, as it may also include
   "infrastructure" protocols built on top of IP and IPsec, including
   routing, ICMP, etc.

3. Goals

   Separate policy and mechanism

4. Requirements

   Here are some basic requirements for an IPsec application API:

      An application should be able to determine HOW a communication was
      protected (or not).

      An application should be able to determine WHO it is talking to.

      If a communication is nominally authorized but fails, an
      application should be able to get an indication of WHY it failed,
      to help identify the configuration error causing the spurious

      An application should be able to influence HOW a communication is

Sommerfeld             Expires December 16, 2003                [Page 2]

Internet-Draft           IPsec API requirements                June 2003

      protected, subject to override or modification by system policy.

      An application should be able to indicate WHO it wishes to talk
      to, again subject to override or modification by system policy.

      These interfaces should be as independant as possible of the key
      management protocol being used; it should be possible to implement
      this with IKEv1, IKEv2, KINK, etc.,

5. System policy

   Interactions with system policy:

      System-level policy trumps all

      By default, applications should be able to ask for *more*

      Applications wishing *less* protection may need appropriate local
      privileges.  (example: ike bypass of UDP port 500; DHCP lease

6. HOW

   An application may have requirements for confidentiality and/or
   integrity; it should be able to determine if an inbound communication
   was protected and whether an outbound communication will be
   protected.  In addition, there may well be a desire to express
   preferences for relative strength of algorithms, or specify the
   specific algorithm to be used.  Hard-coding algorithm names into
   applications should be actively discouraged; perhaps there should be
   generic "weak" or "strong" indications instead of specific algorithm

7. WHO

   This is perhaps the most tricky part of the problem.  Existing IPsec
   key management protocols provide a wide variety of authentication
   methods -- preshared secrets, public key, Kerberos, X.509
   certificates, etc.,

   There are several potential uses for names provided by IPsec:


   It should be possible to determine that two IPsec-protected

Sommerfeld             Expires December 16, 2003                [Page 3]

Internet-Draft           IPsec API requirements                June 2003

   communications conducted within a short to medium time frame were
   with the same authenticated peer; it should be possible to use a
   received identity to initiate a communication back to that identity.

   Example cases: connectionless replies; linking ftp control and data

   The application need only be able to determine if two identities are


   It should be possible for an application to construct a log entry
   naming the peer.


   While policy rules may allow traffic to be blocked entirely, it's
   often necessary for a program to provide services to mutually
   suspicious clients.  It should be possible for a service to make
   appropriate access control decisions based on the identity of the
   peer; in addition, the peer's certificate may contain interesting
   SubjectAltName or other attributes which may have relevance for the
   application; it may also be possible for the system to derive other
   attributes from the peer's identity.


   [Mission Creep Alert] In many cases, an application is not so much
   interested in the peer's name, but rather in some other attribute of
   the peer.  Exactly where and how to map from long-term keys to these
   attributes needs to be nailed down; it may well be that this is best
   left as a local issue.

   Some of this is probably out of scope for the working group; however,
   we should not preclude others from building on this.

8. Error reporting

   There are a number of reasons why a communication may fail because of
   IPsec configuration mismatches..

   These include, but are not limited to:

      Blocked by local or peer SPD.

      Local or peer key management protocols cannot establish an SA.

Sommerfeld             Expires December 16, 2003                [Page 4]

Internet-Draft           IPsec API requirements                June 2003

      Local or peer key management protocols cannot authenticate  to
      each other.

   It MAY be appropriate to map IPsec failures into existing error codes
   (e.g., "connection refused", "connection timed out"), so that
   existing applications use appropriate error recovery strategies;
   however, this does result in a loss of information.  It SHOULD be
   possible for an IPsec-aware application to get additional information
   about the reasons that a communications failed.

9. Security Guarantees

   Connection-oriented and connectionless communication often require
   different application structure.  In many case, it will often be most
   convenient to do security checks once per connection, while for
   connectionless communications, per-message operations will be needed.

9.1 Connection-oriented communication

   Packet boundaries are not, in general, visible to clients of stream
   protocols such as TCP, while IPsec protection is provided (or not) on
   a packet-by-packet basis,

   In addition, it would be an unreasonable burden on applications to
   force them to continuously inquire about each individual packet.

   It should be possible for an application to ensure that all traffic
   to a particular socket is protected appropriately; it should also be
   possible for an application to ensure that all traffic to a socket
   originates from the same authenticated identity.

   A pair of communicating applications should be able to determine that
   the ipsec protection on a connection between them is end-to-end.

   Note that it is common for datagram socket API's to allow a "connect"
   operation which sets a default destination and filters inbound
   packets based on source address; it should similarly be possible for
   the connection-oriented security guarantees to be applied to datagram
   sockets being used for 1:1 communications.

9.2 Connectionless communication

   It is also common to use datagram sockets for many-to-many
   communication; it should be possible to get and set identity
   information on a packet-by-packet basis.

   It may well be the case that a datagram-oriented client application
   will use the connection-oriented part of this API (because it is

Sommerfeld             Expires December 16, 2003                [Page 5]

Internet-Draft           IPsec API requirements                June 2003

   using a given datagram socket to talk to a specific server) while the
   server it is talking to use the connectionless API because it is
   using a single socket to receive requests from and send replies to a
   large number of clients.

10. Non-goals And Bad Ideas

   Here are a few ideas which have popped up every so often which really
   seem to be bad ideas..  in other words, things which should not be
   exposed to applications because they can't be used reliably or which
   cause active harm.

10.1 Exposure of keys

   There is absolutely no reason for applications to see the underlying
   encryption keys.

10.2 Exposure of IPsec SPI values

   In general, there is no need for applications to see SPI values or
   keys; it's also the case that in many cases the exact algorithm used
   may not be of interest as long as it is appropriately strong.

   Since both IKE and IPsec SA's may be short-lived, it is plausible

      an application connection or association will outlive any given
      IPsec SA.

      an application connection or association will outlive any given
      IKE SA.

      an application connection may be idle for extended periods, during
      which time there is no IKE or IPsec SA state between the peers.

   It should be the case that any properties provided to applications
   regarding peer identity, protection, etc., should be able to survive

   It may be appropriate to use SPI values as temporary handles, but
   applications may last much longer than SA's, and SPI values may be
   recycled over time; it would be better for there to be a separate,
   local-use-only, space for (identity, params) pairs.

11. Other issues

      Interface-specific vs.  application-specific policy; deal with
      this as separate layers of filtering/intersections/etc?

Sommerfeld             Expires December 16, 2003                [Page 6]

Internet-Draft           IPsec API requirements                June 2003

      Real-time notifications of both ends that rekey, etc., is having
      trouble (highly desirable for VoIP-type applications).

      Balancing keeping full certificate handling out of applications
      while still providing full access to certificate attributes.

12. Security Considerations

13. Document TODO

      Flesh out Other Issues section.

      Flesh out Informative References with references to existing
      IPsec-related API's

      Improve security considerations section.

Normative References

   [1]  Kent, S. and R. Atkinson, "Security Architecture for the
        Internet Protocol", RFC 2401, November 1998.

   [2]  Piper, D., "The Internet IP Security Domain of Interpretation
        for ISAKMP", RFC 2407, November 1998.

   [3]  Maughan, D., Schneider, M. and M. Schertler, "Internet Security
        Association and Key Management Protocol (ISAKMP)", RFC 2408,
        November 1998.

   [4]  Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)",
        RFC 2409, November 1998.

Informative References

Author's Address

   Bill Sommerfeld
   Sun Microsystems
   1 Network Drive
   Burlington, MA  01803

   Phone: +1 781 442 3458
   EMail: sommerfeld@sun.com

Sommerfeld             Expires December 16, 2003                [Page 7]

Internet-Draft           IPsec API requirements                June 2003

Full Copyright Statement

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an


   Funding for the RFC Editor function is currently provided by the
   Internet Society.

Sommerfeld             Expires December 16, 2003                [Page 8]