[Search] [txt|pdfized|bibtex] [Tracker] [Email] [Nits]
Versions: 00                                                            
BTNS Working Group                                            D. Migault
Internet-Draft                                           Orange Labs R&D
Intended status: Standards Track                           March 2, 2009
Expires: September 3, 2009


                         IPSEC_API requirements
             draft-mglt-btns-ipsec-api-requirements-00.txt

Status of this Memo

   This Internet-Draft is submitted to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.

   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-
   Drafts.

   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://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on September 3, 2009.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Abstract

   IPsec suite has been designed to secure communication between two
   nodes.  Security is performed at the network layer, and there are
   almost no interactions between applications and the IPsec layer.  The



Migault                 Expires September 3, 2009               [Page 1]


Internet-Draft           IPSEC_API requirements               March 2009


   main motivation of this API is to enable any applications to interact
   with the IPsec layer and to take advantage of the security deployed
   in IPsec suite.  This draft lists applications requirements with
   regard to the IPsec suite, and we tried not to limit the requirements
   to today's application requirements, but also to consider future
   applications' requirements.  Applications are associated to different
   privileges, and IPsec layer MUST be protected from nasty IPsec
   manipulations.  This draft is not considering applications privileges
   management.  This draft lists any possible requirements on the IPsec
   layer an application might require.


Table of Contents

   1.  Requirements notation  . . . . . . . . . . . . . . . . . . . .  3
   2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   3.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   4.  Goals  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     4.1.  Application goals  . . . . . . . . . . . . . . . . . . . .  4
     4.2.  Architecture description . . . . . . . . . . . . . . . . .  5
     4.3.  Impacts with IPsec . . . . . . . . . . . . . . . . . . . .  7
   5.  Requirements . . . . . . . . . . . . . . . . . . . . . . . . .  8
     5.1.  Application requirements with IPSEC_API  . . . . . . . . .  9
     5.2.  IPSEC_API requirements with IPsec layer  . . . . . . . . .  9
     5.3.  IPSEC_API requirements with IPSEC_API  . . . . . . . . . . 10
     5.4.  Next step to this draft  . . . . . . . . . . . . . . . . . 10
   6.  HOW  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     6.1.  Dynamic interaction between the IPSEC_API and an
           applications.  . . . . . . . . . . . . . . . . . . . . . . 11
       6.1.1.  non ESTABLISHED connections parameters . . . . . . . . 12
       6.1.2.  ESTABLISHED connection parameters  . . . . . . . . . . 12
       6.1.3.  Action performed by applications . . . . . . . . . . . 12
     6.2.  Simple Security Request Method . . . . . . . . . . . . . . 13
   7.  WHO  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     7.1.  The dynamic interaction between the IPSEC_API and an
           applications.  . . . . . . . . . . . . . . . . . . . . . . 15
       7.1.1.  NON ESTABLISHED parameters . . . . . . . . . . . . . . 16
       7.1.2.  ESTABLISHED connection parameters  . . . . . . . . . . 18
       7.1.3.  Actions performed by the application . . . . . . . . . 18
     7.2.  Simple Security Request Method . . . . . . . . . . . . . . 19
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 20
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 21
   10. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 21
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 21
     11.2. Informative References . . . . . . . . . . . . . . . . . . 22
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22




Migault                 Expires September 3, 2009               [Page 2]


Internet-Draft           IPSEC_API requirements               March 2009


1.  Requirements notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].


2.  Introduction

   This draft is based [I-D.ietf-btns-ipsec-apireq] and adopts a similar
   structure to ease merge of the two drafts.  This draft has been re-
   written since the former [I-D.ietf-btns-ipsec-apireq] was not any
   more active, and requirements did not match those of the IPSEC_API we
   are developing in our labs.

   IPsec suite [RFC4301] [RFC4302] [RFC4306] [RFC4307] has been designed
   to secure communication between two nodes.  Security is performed at
   the network layer, and there are almost no interactions between
   applications and the IPsec layer.  The main motivation of this API is
   to enable any applications to interact with the IPsec layer and to
   take advantage of the security deployed in IPsec suite.  This draft
   lists applications requirements with regard to the IPsec suite, and
   we tried not to limit the requirements to today's application
   requirements, but also to consider future applications requirements.
   Applications are associated to different privileges, and IPsec layer
   MUST be protected from nasty IPsec manipulations.  This draft is not
   considering applications privileges management which is described in
   [I-D.mglt-ipsec-appdb].  This draft lists any possible requirements
   on the IPsec layer an application might require.

   BTNS WG has designed solutions that enable IPsec communication
   without authentication [RFC5386].
   [I-D.ietf-btns-connection-latching] enables ULP protocols to specify
   IPsec parameters for the connection.  IPsec parameters are associated
   with a socket either in a listening mode or initiating a connection.
   This configures IKE for the key negotiation and update of the SAD.

   This is a first step for interrelations between ULP and the IPsec
   layer.  This draft is considering more interactions between
   applications and the IPsec stack.  Interactions will be provided
   through an API: IPSEC_API.  This draft is defining application
   requirements with the IPsec stack.  Today's Interfaces of IPSEC_API
   are defined in [I-D.ietf-btns-abstract-api], and C implementation is
   defined in [I-D.ietf-btns-c-api].  Those documents partly implement
   the requirements of this paper and need to be completed or to be re-
   written.





Migault                 Expires September 3, 2009               [Page 3]


Internet-Draft           IPSEC_API requirements               March 2009


3.  Terminology

   - IPSEC_API :   designates the layer (interfaces / daemons) that is
         between the IPsec layer and the application layer.  This
         IPSEC_API is composed of three interfaces one with the
         application layer, one with the IPsec layer and one with remote
         IPSEC_API.
   - APPDB :   stands for APplication Privilege DataBase.  This database
         contains all attributes to determine which action on the IPsec
         Database can be performed by a specific application, a specific
         user, ... this database is described in [I-D.mglt-ipsec-appdb].
   - APP :   stands for application
   - API :   stands for APplication Interface
   - SPD* or logical SPD :   is the SPD used by the kernel.  This SPD
         can results from the correlated SPD, and ULP-driven SPD as
         defined in [I-D.ietf-btns-connection-latching]
   - IKE* :   IKE Database is the aggregation of IKE_CONF and IKE_CTX.
   - IKE_CONF :   are the parameters required by IKE for negotiation.
         Typically that the parameters one set before launching the IKE
         daemon.
   - IKE_CTX :   are the IKE parameters for a given association between
         two peers.


4.  Goals

   This section lists the goals of this API.  Such goals have an impact
   on the IPsec stack.  This section provides architecture of our API
   and its interactions with the IPsec and application layer.  Then for
   all listed goals, and analysis on impacts with the IPsec layer is
   provided.

4.1.  Application goals

   An application can be either located on the same device as the one
   with the considered IPsec layer, or on a remote device.  On the
   application point of view this draft is considering the following
   main types of actions :

   o  An application wants to get IPsec information for a specific
      ESTABLISHED connection.  This type of information includes WHO is
      on the other side, HOW the peer has been authenticated, and HOW
      the communication is protected.  That information is stored into
      specific database, memory, contexts...
   o  An application wants to check the security policy or different
      IPsec parameters before connection is ESTABLISHED with a peer.





Migault                 Expires September 3, 2009               [Page 4]


Internet-Draft           IPSEC_API requirements               March 2009


   o  An application wants to interact with the IPsec layer and provide
      requirements on security parameters on a connection before it is
      established.  For example an application should be able to specify
      how authentication should be proceeded, how the communication
      should be protected.  By default application security requirements
      are accepted when security requirements are higher than IPsec
      security.  Nevertheless an application might also require lower
      security in very specific situation when security is balanced by
      CPU consumption for small device.  Such application MUST be
      configured to have such properties.
   o  An application wants also to interact with the IPsec and perform
      the authentication of the peer on the behave of the IPsec stack.
   o  An application DOES NOT want to have a complete knowledge of the
      IPsec stack.  Security MUST be set up with very simple key words
      and easy-to-understand operations.

4.2.  Architecture description

   This API should be placed between the application and the transport
   layer.  This IPSEC_API is interfacing the applications with the IPsec
   layer.  Network security mainly relies on IPsec and so IPsec
   configuration must be changed by authorized applications and in a
   controlled way.  This IPSEC_API is not a replacement for existing
   IPsec management protocol and must reuse those protocols (IPsec /IKE
   [RFC4301] [RFC4306] as well as associated management APIs such as
   PF_KEYv2 [RFC2367].

   The figure below represents the Interaction applications and the
   IPsec stack through the API.






















Migault                 Expires September 3, 2009               [Page 5]


Internet-Draft           IPSEC_API requirements               March 2009


      +-----------------------------------+
      |+----+ +------+      +-----+------+|
      ||SPD | | IKE  |      | App1| App2 ||
      |+----+ +------+      +-----+------+|
      ||PAD |  |  |                ^      |
      |+----+  |  |    APP / API   |      |
      +--^-----|--|----------------|------+
         |     |  |     +---=======|===---+
         +-----|--|-----|IPSEC_API v      ||  API / API
               |  |     |     ^           ||
       +-------+  +---+ +---==|========---+    User land
      _|______________|_______|________________________
      +|--------------|-------|-----------+    Kernel
      ||      PF_KEY  |   +---+API / IPsec|
      ||  +--------+  |   |               |
      ||  | SPD*   |<-----+               |
      ||  +--------+  |   |    +--------+ |
      ||  | SAD    |<-+---+--->|Latch DB| |
      ||  +--------+      |    +--------+ |
      |+->| IKE*   |<-----+--->| ...    | |
      |   +--------+           +--------+ |
      +-----------------------------------+


                          IPSEC_API Architecture

   Concerned IPsec databases are :

   o  SPD* is a logical SPD as mentioned in
      [I-D.ietf-btns-connection-latching].  This includes the SPD-
      decorrelated DB as well as ULP-driven SPD.  In this draft one must
      also consider application driven SPD.
   o  SAD is the security Association Database.
   o  IKE* is the database containing IKE parameters about SAs, SPs, and
      their negotiation status in IKE_CTX.  IKE_CONF contains the IKE
      parameters used for negotiation.
   o  Latch DB is the list of latched objects
      [I-D.ietf-btns-connection-latching]
   o  ... stands for other IPsec related Databases.

   The IPSEC_API is composed of three interfaces :

   o  API / API : is an interface between APIs on local and remote host.
      The interface can be used by the two communicating nodes or but
      also by a third party that manages IPsec parameters of the two
      communicating nodes.





Migault                 Expires September 3, 2009               [Page 6]


Internet-Draft           IPSEC_API requirements               March 2009


   o  APP / API : is an interface between APPlications and the
      IPSEC_API.  This interface enables APPlications to send requests
      and get information on IPsec layer.  This API MUST check that
      requested modification from applications are authorized before
      applying the modification to the kernel.
   o  API / IPsec : is an interface between the API and the IPsec layer.
      The interface enables the API to modify the IPsec databases.  SAD
      can be modified by using PF_KEY [RFC2367]

4.3.  Impacts with IPsec

   If an application wants to know IPsec information on and established
   connection, its needs to be able to read the various IPsec databases
   like PAD, SPD*, SAD, LD, IKE*.  SPD is used to get information on
   used policies, SAD on how security is performed between two
   endpoints, PAD what kind of ID were used for the IKE authentication
   phase.  IKE* although NOT so standardized, can provides the different
   proposed parameters proposed during the IKE negotiation.  (We said
   NOT so standardized since no IKE context have been defined, and IKE
   parameters are usually implementation dependant).  For a given
   established communication, IKE* could provide a picture of the
   negotiation status between the two peers, used keys, information on
   how authentication has been performed.  LD and SAD might be useful
   for ULP to latch connection [I-D.ietf-btns-connection-latching].
   Some information might not be stored in such database and so must be
   stored in the IPSEC_API local database.  Interface with SAD is
   provided with PFKEYv2 [RFC2367], but there are no standardized
   interface with SPD and IKE*.  Since it is hard to consider what are
   the IPsec parameters each application need to access now and in the
   future, all IPsec parameters should be accessed by applications.
   Restriction policies on read / write privileges MUST be clearly
   specified for any application.  IPsec parameters MUST also include
   implementation dependent IPsec parameters.  Such privileges are
   stored in the APplication Privilege Database (APPDB)
   [I-D.mglt-ipsec-appdb].  This would for example enable context
   transfer for one given application (raccon2, ...).  Applications do
   not need necessarily understand all IPsec parameters, application
   should also be able to request security status of a given established
   IPsec connection in the form of "encryption", "authentication",
   "strong-security"....

   One application might request information in prevision of a future
   IPsec connection.  This is especially the case when an application
   wants to initiate a secure connection with one specific host.  It
   might check what the security at the IPsec layer is.  This includes
   what mode is used, what types of algorithms are used what
   authentication method is used...  The application could then proceed
   to requirements on the IPsec layer, or decide it will proceed to the



Migault                 Expires September 3, 2009               [Page 7]


Internet-Draft           IPSEC_API requirements               March 2009


   authentication.  Authorized application must be able to access all
   those information, but application are not required to know precisely
   all IPsec parameters.  Applications could also expect response with
   basic words like "encryption", "authentication", "strong security"...
   The involved IPsec databases are mainly SPD and IKE_CONF since the
   connection is not in an established mode.  SAD / LD / IKE_CTX might
   also be useful since a connection might be in a dormant state.
   Application should be able to check all IPsec parameters but
   privileges of each application MUST be clearly specified in an
   Application Privilege Database (APPDB).  Of course the requirements
   above will in most of the cases generate closer interaction and
   modification of IPsec parameters by the application.

   One application MUST be able to specify IPsec parameters.  This means
   that an application can change its security policies.  According to
   its privileges the application will be able force a weaker or
   stronger security.  By default application will be only able to
   request stronger security.  The API MUST be able to send
   ACKknowledgemnt of the request or an ERROR message.  Applications
   privilege on the different IPsec parameters MUST be clearly specified
   in the APPD.  Application MUST be able to set every single IPsec
   parameters as well as setting IPsec parameters with generic key
   words.  For a non initiated IPsec connection, such requirements will
   mainly involve the SPD, and eventually IKE_CONF and PAD, or at least
   there application-driven equivalent.  When the application specifies
   it will perform the authentication on behalf of IKE, the application
   MUST send Acknowledgment or ERROR message to the API.  Such
   interaction will be done during the IKE authentication phase.  Once a
   connection has been initiated, an application MUST be able to change
   the IPsec parameters, by renegotiating or re-keying IPsec material.
   An application MUST also be able to proceed authentication either by
   using IKE or on the behalf of IKE.  A typical situation would be an
   application requesting to proceed to authentication of an
   unauthenticated IPsec connection [RFC5386].  This would require
   binding the unauthenticated channel to the authentication.
   Authentication would be proceeded with selected information (or hash
   of them) of the IPsec connection.  This is called channel binding
   [RFC5056].  This requirements means that applications can change
   IPsec parameters but can also trigger actions such as re-keying, re-
   authenticating, on IKE.


5.  Requirements

   This sections aims at defining the requirements on an IPsec point of
   view.  A first subsection lists the application requirements on the
   IPsec layer.  Those requirements are treated through the IPSEC_API.
   Other subsection lists requirements of the IPSEC_API and the its



Migault                 Expires September 3, 2009               [Page 8]


Internet-Draft           IPSEC_API requirements               March 2009


   interface with applications, with the IPsec layer and with other
   IPSEC_API.

5.1.  Application requirements with IPSEC_API

   o  Application MUST be able to establish connection with the
      IPSEC_API.  This can be done by local applications, or remote
      applications.
   o  Application MUST be able to read / write / create / delete any
      data in the IPsec databases, as well as other parameters within
      the local IPSEC_API database.  Such parameters can concern already
      established IPsec connection, non already established IPsec
      connection.  Such action MUST only be performed by authorized
      applications defined in APPDB [I-D.mglt-ipsec-appdb].
   o  Application requests MUST be controlled by the IPSEC_API.
      Unauthorized requests MUST be responded with an ERROR message.
   o  Application MUST be able to trigger action with IPsec daemon such
      as IKE.
   o  Application MUST be able to interact with IPsec by using generic
      key words.  Such Key words MUST be defined according to use cases.
   o  Applications MUST be able to perform authentication on behalf of
      the IPsec layer, and provides the results to the IPSEC_API.

5.2.  IPSEC_API requirements with IPsec layer

   o  IPSEC API MUST be aware of any change in IPsec Databases.
      IPSEC_API could eventually build its own local copies of IPsec
      databases.
   o  IPSEC_API SHOULD maintain local databases dealing with
      authentication status, of IP address function, so to be aware of
      the "Quality of Security", and to be able to adapt IPsec
      connections to very common network operations such as Multihoming
      and Mobility operations.
   o  IPSEC_API has root / admin privilege so it can change IPsec
      parameters.  The IPSEC_API MUST check privileges of any
      application before proceeding to any changes.  By default an
      application could not change IPsec parameters that do not concern
      its own connection.  By default, the set of parameters for each
      operation should also be reduced.  API like PF_KEYv2 [RFC2367]
      provides interface with SAD and the IPSEC_API.  Other interface
      with other IPsec databases MUST be either standardized or
      considered implementation dependent.
   o  IPSEC_API MUST understand high level application requests.  Such
      requests consider pre-configured operations that will be performed
      by IPSEC_API, which in turn guarantee operation will be performed
      in a secure manner.  Changing an SA for example will not be
      performed by simply changing the SAD, but rather by using IKE.
      Other operation (like those involved in Mobility or Multi-Homing)



Migault                 Expires September 3, 2009               [Page 9]


Internet-Draft           IPSEC_API requirements               March 2009


      might involve communication between the two involved IPSEC_API
      (which can probably be done through a future IKE-extension).
   o  IPSEC_API MUST compare security and eventually overwrite the
      network security.  A flag could specify whether SP is allowed to
      be weakened, strengthen or not.  The IPSEC_API MUST balanced the
      application authorization, the SP upgrade flag, and the requested
      / configured security policy.  The new SP MUST NOT survive to
      crash, and so MUST only impact the logical SPD.
   o  IPSEC_API MUST be able to ask for application authentication.
      Necessary information for channel binding MUST be provided to the
      application.  Such information MUST NOT appear in a clear mode by
      default, so not to communicate IPsec parameters.  On the other
      hand such parameters MUST be clearly specified so that for a given
      ESTABLISHED connection both sides can have a similar Nonce value
      use to bind the channel to the authentication.

5.3.  IPSEC_API requirements with IPSEC_API

   o  IPSEC_API MUST be able to communicate between each other.
      Communication between IPSEC_API can be done by using IKE channel.
   o  IPSEC_API channel MUST be secured.  IPsec can be used but should
      NOT rely on IP addresses. -- IPsec BEET mode, or HIP can be used.
   o  All commands on the IPSEC_API / IPsec layer could be sent through
      the IPSEC_API / IPSEC_API interface.

5.4.  Next step to this draft

   This draft does not consider the way Applications and IPSEC_API are
   establishing a channel to communicate.  In particularly it does not
   treat the authentication problematic which enables the IPSEC_API to
   authenticate the application it is communicating with.

   IPsec parameter protection is described in [I-D.mglt-ipsec-appdb].
   It shows privileges of any application on any IPsec parameters.
   Before performing an action, IPSEC_API MUST check the application has
   the required privileges.

   For a given REQUESTER and a given IPsec PARAMETER the possible
   ACTIONS are :

   o  CREATE: A VALUE MUST be specified.
   o  DELETE: No VALUE needs to be specified.
   o  UPDATE: A VALUE needs to be specified.
   o  READ: No VALUE needs to be specified.

   Other function can be created like SEARCH.  A complete description of
   the abstract interface should be defined in future version of
   [I-D.ietf-btns-abstract-api].



Migault                 Expires September 3, 2009              [Page 10]


Internet-Draft           IPSEC_API requirements               March 2009


   PARAMETER are designed by a TYPE and a SELECTOR which enables to
   distinct it from others in specific DATABASEs (SAD, LD, SPD, PAD,
   IKE_CONF, IKE_CTX).  Complete list of TYPEs, SELECTORs, and DATABASEs
   is defined in [I-D.ietf-btns-abstract-api].

   Such functions are the basic functions that handle the IPsec
   PARAMETERS.  Those functions are the same on the IPSEC_API /
   APPlication and on the IPSEC_API / IPsec layer interface.  On the
   IPSEC_API / IPsec layer those functions are the only interface.

   IPsec is composed of two distinct parts :

   o  Authentication of peers: the WHO part
   o  Protection of datagrams: the HOW part

   For each of those two parts, this draft will focus on the different
   requirements between the application.  For each of those parts, we
   will define:

   o  The dynamic interaction between the IPSEC_API and an application.
   o  Simple Security Request Method (SSRM).

   This draft also mentions what are the different modifications on
   IKEv1, IKEv2 and other IPsec related protocols.


6.  HOW

6.1.  Dynamic interaction between the IPSEC_API and an applications.

   The HOW part is considering three type of actions :

   o  An application can REQUEST security parameters of an ESTABLISHED
      connection.
   o  An application can REQUEST security parameters for a future
      connection.
   o  An application can PERFORM some action :
   o
      *  DELETE a connection.
      *  REKEY a SA.
      *  Manage IPsec connection in Multihoming environment.
      *  Manage IPsec connection in Mobility environment.

   There are two cases to consider the connection is in an ESTABLISHED
   state and the connection is not in an established state.  An
   application MUST be able to check whether a connection is ESTABLISHED
   or not.




Migault                 Expires September 3, 2009              [Page 11]


Internet-Draft           IPSEC_API requirements               March 2009


6.1.1.  non ESTABLISHED connections parameters

   When the connection is not in an established state, the application
   requirements might be on the following security parameters :

   o  NATURE_PROP: List of proposition of the NATURE of the connection.
      The list is ordered from the most preferred NATURE to the least
      preferred NATURE.  NATURE of the connection is a combination of
      COMPRESSION, CONFIDENTIALITY and INTEGRITY.
   o  ALGorithm_PROP: List of proposed ALG associated to one NATURE
      value.  The list is ordered.

   Those parameters values could be either REQUESTed by the application
   to know how the connection will be negotiated.  It can also be
   REQUIRED by the application.  Such requirements will update the
   decorrelated SPD (confidentiality, Integrity) and the IKE_CONF
   database.  NATURE_PROP and ALG_PROP are list of possibilities for the
   non established connection.  The ESTABLISHED connection MUST have a
   NATURE and ALG mentioned in the List.  Propositions MUST be kept in a
   context in case of re-negotiation of parameters.

6.1.2.  ESTABLISHED connection parameters

   When the connection is in an ESTABLISHED state, changing the security
   policy would require to renegotiate the IKE exchange.  On the other
   hand an application might only want to get some information about how
   the connection is protected.  Such parameters can be read from the
   SA.  The application requirements might be the following :

   o  NATURE_STATUS: indicates the NATURE of the connection it MUST be
      one of the value mentioned in the NATURE_PROP parameters.
   o  ALGorithm_STATUS: indicates which algorithm is used.
   o  Protection CTX: All protection parameters, it might be useful for
      an application .
   o  STATUS: Status of the connection ESTABLISHED, LARVAL, ...
   o  NATURE_PROP: List of proposition of the NATURE of the connection.
      The list is ordered from the most preferred NATURE to the least
      preferred NATURE.  NATURE of the connection is a combination of
      COMPRESSION, CONFIDENTIALITY and INTEGRITY.
   o  ALGorithm_PROP: List of proposed ALG associated to one NATURE
      value.  The list is ordered.

6.1.3.  Action performed by applications

   To avoid multiple IKE negotiations, an application wants an IPsec
   channel to be inherited from an already existing IPsec connection.
   This is especially the case in multihoming scenario.  IPSEC_API MUST
   check the SA matches the SPD, build the new SA from the already



Migault                 Expires September 3, 2009              [Page 12]


Internet-Draft           IPSEC_API requirements               March 2009


   existing SA, communicate such change to the other IPSEC_API and
   update the SAD.

   An application MUST be able to close an IPsec connection and put the
   IPsec status to close, so that it could not be used unless the
   application is latching this connection.

   An application wants to ask for mobility and transfer IPsec
   parameters to another endpoint.  This case can be seen as a
   combination of the two previous cases.  One need to add the other
   connection, wait it works and delete the currently used address.
   MOBIKE is considering this operation, for tunnel mode.  The IPSEC_API
   is extending this functionality to transport mode.

   An application wants to initiate an IKE negotiation before sending
   any packet.  This is mainly to avoid network latency.  Considering
   the previous cases, this will create a new SA, and there is no
   inheritance properties.

   An application wants to REKEY the IPsec connection when KEYs are
   consider short, or when an authentication has just been performed.

6.2.  Simple Security Request Method

   As mentioned previously, the main purpose of SSRM is to enable a safe
   interaction between application and IPsec layer.  With considered
   previous scenario, one can consider the REQUIRE method which attempt
   to send requirements, and the REQUEST method for IPsec parameters of
   established connection.  By default such SSRM are only applied for
   connection the application is involved in.

   Example of requests can be :

   REQUIRE [APP_ID] CONNECTION_ID PARAM

        REQUEST message to IPSEC_API for a non establish connection

   where :

   o  APP_ID is the application identifier.  It can be an option if the
      connection between the application and the IPSEC_API identifies
      the application.  We do not specify here how applications are
      identified by the IPSEC_API.  It could be by the port, or another
      ID.  We need to consider APP_ID if we consider security at the
      application layer.  Deriving security at the network layer is only
      a means to use IPsec for securing communication between
      applications.  APP_ID can also be seen as a higher granularity of
      SA descriptors than CONNECTION_ID.



Migault                 Expires September 3, 2009              [Page 13]


Internet-Draft           IPSEC_API requirements               March 2009


   o  CONNECTION_ID identifies the connection (@IP_src, @IP_dst,
      port_src, port_dst).  Value "ANY" could also be used as a
      wildcard.
   o  PARAM is required.  It can be CONFIDENTIALTY_PROP, INTEGRITY_PROP,
      and COMPRESSION_PROP with associated values MUST, MAY, NONE.  EALG
      with its related value, IALG with its related value.  The
      different value for EALG and IALG can be of keywords like
      STRONGEST, FASTEST - ([I-D.ietf-btns-abstract-api] suggests the
      following terms for policies : "secure", "ospf", "iSCSI", "very-
      secure", "do-not-tell-mom-secure", "minimum-security", "was-
      posted-on-usenet-security").  Values are specified only for the
      REQUIRE request.

   REQUEST [APP_ID] CONNECTION_ID PARAM

        REQUEST message to IPSEC_API for an established connection

   where :

   o  APP_ID is the application identifier.  It can be option if the
      connection between the application and the IPSEC_API identifies
      the application.  We do not specify here how applications are
      identified by the IPSEC_API.  It could be by the port, or another
      ID.  Deriving security at the network layer is only a means to use
      IPsec for securing communication between applications.  APP_ID can
      also be seen as a higher granularity of SA descriptors than
      CONNECTION_ID.
   o  CONNECTION_ID identifies the connection (@IP_src, @IP_dst,
      port_src, port_dst).  Value "ANY" could also be used.
   o  PARAM is required.  It can be CONFIDENTIALTY_STATUS,
      INTEGRITY_STATUS, and COMPRESSION_STATUS, EALG, IALG.  The
      different value for EALG and IALG can be of keywords like
      STRONGEST, FASTEST.  Values are specified only for the REQUIRE
      request.  STATUS defines the connection status.  This status can
      be ESTABLISHED, LARVAL, DORMANT, NULL...  PROTECT_CTX.

   MULTIHOME [APP_ID] NEW_CONNECTION_ID INHERIT_MTHD

                     MULTIHOMING message to IPSEC_API

   where :

   o  NEW_CONNECTION_ID is the new connection to establish.
   o  INHERIT_MTHD is the method used to derive the NEW_CONNECTION

   MOBILITY [APP_ID] CONNECTION_ID INHERIT_MTHD

                       MOBILITY message to IPSEC_API



Migault                 Expires September 3, 2009              [Page 14]


Internet-Draft           IPSEC_API requirements               March 2009


   where :

   o  CONNECTION_ID is the new connection SHOULD inherit from.
   o  INHERIT_MTHD is how the transition from the new and old address
      should be done.  This mainly includes how the previous connection
      SHOULD be deleted, and usually includes a Time stamp that
      indicates when the deletion occurs.

   DELETE [APP_ID] CONNECTION_ID DELETE_MODE

                        DELETE message to IPSEC_API

   where :

   o  CONNECTION_ID is the new connection to delete.
   o  DELETE_MODE defines how the SA SHOULD be deleted.

   The IPSEC_API MUST answer to such requests with a message of type :

   ACK RESPONSE_DATA

                        DELETE message to IPSEC_API

   or

   ERROR ERROR_MSG

                        DELETE message to IPSEC_API

   o  ACK is a positive answer with the expected response in
      RESPONSE_DATA.
   o  ERROR is an ERROR message with the ERROR_MSG value.


7.  WHO

7.1.  The dynamic interaction between the IPSEC_API and an applications.

   As in the HOW part, there are different things to consider :

   o  An application can REQUEST authentication information of an
      ESTABLISHED connection.
   o  An application can REQUIRE authentication method and mode for a
      NON already ESTABLISHED connection.  For an already ESTABLISHED
      connection, this will generated a renegotiation as if the
      authentication had not been previously performed.  Since then we
      consider the following case as part of the NON ESTABLISHED case.




Migault                 Expires September 3, 2009              [Page 15]


Internet-Draft           IPSEC_API requirements               March 2009


   o  An application can interact with the IPsec layer in the
      authentication process :
   o
      *  Proceed to authentication on behalf of the IKE daemon.
      *  Ask the IKE daemon to proceed to authentication, providing a
         list of authentication method.
      *  Ask the IKE daemon to application confirmation for
         authentication validation.  A peer might have correctly been
         authenticated but is black listed by the application, or
         further local checks must be performed by the application.
      *  Provide ACL, black white lists to the IPSEC_API.
      *  Require the authentication to be proceeded.

   Unlike protection parameters, authentication is a local process, i.e;
   not shared between the two nodes, and so MUST be considered different
   when in local and remote peers.  In the following description of the
   parameters (LR) indicates that the parameter should be considered for
   local and peer entities.  Thus PARAMETER (LR) stands for the two
   names PARAMETER_LOCAL and PARAMETER_REMOTE.

7.1.1.  NON ESTABLISHED parameters

   The application should be able to choose who is proceeding to the
   authentication, i.e. to say if the authentication will be proceeded
   by the IPsec layer or the application it self.

   Then an application should be able to accept/refuse an IPsec
   authenticated peer.  An application should also be able to provide
   blacklist and white list to the IPsec layer.

   It should also be able to provide how the authentication should be
   done.  Some parameters like who is proceeding to the authentication
   can be defined when the application is launched or when the
   application is receiving/sending packets.

   By default IPsec and applications are considering their own
   authentication rules.  The IPsec authentication rules are defined in
   the PAD.  [RFC5386] is providing some unauthenticated IPsec
   connection.

   By default, the IPsec is proceeding to the authentication according
   to the PAD.  Application proceeding to authentication might
   "overwrite" IPsec rules of the PAD.  Thus such applications should be
   with CREATE or UPDATE privilege in the APPDB [I-D.mglt-ipsec-appdb].
   If not, the authentication cannot be proceeded by the application
   layer only, and should match the PAD policies.  If the IPsec SPD /
   PAD rules cannot be changed, the IPSEC_API should send a warning
   message.  If more authentication is done then requested (i.e.; by



Migault                 Expires September 3, 2009              [Page 16]


Internet-Draft           IPSEC_API requirements               March 2009


   application and IPsec layer) then the IPSEC_API should send a warning
   message.  If the IPsec rule do not enable the connection to be
   initiated, and error message should be sent.  On the other hand
   changes requested by applications MUST NOT survive crash, so changes
   on the PAD or SPD MUST by default be registered in application driven
   IPsec Databases.  Only administrators SHOULD change the reference SPD
   / PAD.  When both application layer and IPsec layer are required,
   then the peer is considered authenticated when both authentication
   have been proceeded.

   An application can REQUIRE the following authentication parameters :

   o  AUTH_LAYER_PROP indicates where the authentication MUST be
      performed possible values are APP_ONLY, IKE_ONLY, IKE_APP_ACK,
      NONE.
   o  AUTH_LAYER_PROP: Where the authentication is / has / will be
      proceeded.  Possible values are APPlication, IPSEC, NONE.
   o  AUTH_METHOD_PROP: Method used for the authentication.
   o  AUTH_PARAMETERS_PROP: Parameters required for the authentication,
      or at least their location.

   Most of if not all of those information MUST be stored into the
   IPSEC_API.  Such information is not already stored in usual IPsec
   databases except for some of the AUTH_PARAMETERS.

   When an application proceeds to the authentication phase on behalf of
   the IKE daemon, the Authentication channel MUST be bound to the
   secured channel.  This means that applications MUST return a value
   from authentication that will be considered while deriving keys. (cf
   TLS).

   When an application asks to validate the authenticated peer.  The
   authentication MUST be performed by IKE.  If successful, the IKE
   daemon MUST send to the application the identity of the peer and wait
   for an answer from the application.  The answer can be an
   ACKnowledgment or a NACKnowledgment.  When receiving an NACK the IKE
   daemon MUST go on.  When receiving NACK IKE MUST send an
   authentication failure message to the peer.

   An application can REQUIRE that some peer will be black listed.  An
   authentication will be considered done by IKE if the usual
   authentication has been performed properly by IKE AND the peer is not
   black listed.  If the peer is black listed an ERROR message MUST be
   sent to the application.

   An application might require the authentication to be performed.
   When a connection is already in an ESTABLISHED state, performing the
   authentication means that no more packets MUST be accepted before



Migault                 Expires September 3, 2009              [Page 17]


Internet-Draft           IPSEC_API requirements               March 2009


   authentication is validated.  This action SHOULD be followed by a re-
   keying operation. [need to check how an authentication in IKE can be
   re-done]

7.1.2.  ESTABLISHED connection parameters

   For an ESTABLISHED connection, applications can request the following
   parameters :

   o  AUTH_STATUS [LR]: The status of the authentication.  Possible
      values are: NONE, PROCCEDING, ESTABLISHED, FAILED.
   o  AUTH_LAYER_STATUS [LR]: Where the authentication is / has / will
      be proceeded.
   o  AUTH_LAYER_PROP [LR] indicates where the authentication MUST be
      performed possible values are APP_ONLY, IKE_ONLY, IKE_APP_ACK,
      NONE.
   o  AUTH_METHOD_STATUS [LR]: Methods used for the authentication.
   o  AUTH_LAYER_PROP [LR]: Where the authentication is / has / will be
      proceeded.  Possible values are APPlication, IPSEC, NONE.
   o  AUTH_PARAMETERS_PROP [LR]: Parameters required for the
      authentication, or at least their location.

   Most of if not all of those information MUST be stored into the
   IPSEC_API.  Such information is not already stored in usual IPsec
   databases.

7.1.3.  Actions performed by the application

   An application MUST be able to set some parameters and to require the
   authentication to be performed.

   By default, setting parameters SHOULD NOT affect the IPsec databases,
   and SHOULD NOT subsist to crash.  Changed parameters SHOULD be stored
   into application driven databases.  Location of such databases
   depends on the implementation but they are most likely to be in the
   kernel space.  Some application like administrator's application that
   set the Security Policy can change the IPsec database.

   Requiring authentication means that for a given connection in
   ESTABLISH state, the application wants to proceed to an
   authentication.  The given connection might already have been
   authenticated or not.  This operation requires the authentication be
   bound to the communication.  Wherever authentication is being
   proceeded by the IPsec suite or by a third application, the
   authentication MUST include a token derived from IP connectivity
   parameters.





Migault                 Expires September 3, 2009              [Page 18]


Internet-Draft           IPSEC_API requirements               March 2009


7.2.  Simple Security Request Method

   REQUEST [APP_ID] CONNECTION_ID PARAM

                       REQUEST message to IPSEC_API

   where :

   o  APP_ID: is the application identifier.  It can be option if the
      connection between the application and the IPSEC_API identifies
      the application.  We do not specify here how application is
      identified by the IPSEC_API.  It could be by the port, or another
      ID.
   o  CONNECTION_ID identifies the connection (@IP_src, @IP_dst,
      port_src, port_dst).  Value "ANY" could also be used.
   o  PARAM can be :
   o
      *  AUTH_APP_STATUS [LR].  Response will be of the following NONE,
         PROCCEDING, ESTABLISHED, FAILED.
      *  AUTH_IPSEC_STATUS [LR].  Response will be of the following
         NONE, PROCCEDING, ESTABLISHED, FAILED.
      *  AUTH_LAYER_STATUS [LR].  Response will be of the following
         APP_ONLY, IKE_ONLY, IKE_APP_ACK, NONE.
      *  AUTH_IPSEC_METHOD_STATUS [LR]: Methods used for the
         authentication.  Response will be of the following [NONE, BTNS,
         LEATOFFAITH, PRESHAREDKEY, GROUPKEY, XAUTH, EAP, PKIX_TRUSTED,
         PKIX_INLINE, PKIX_OFFLINE].
      *  AUTH_APP_METHOD_STATUS [LR]: Methods used for the
         authentication.
      *  ACTION: an action to perform like DELETE, AUTHENTICATE...

   REQUIRE [APP_ID] CONNECTION_ID PARAM

                       REQUIRE message to IPSEC_API

   where :

   o  APP_ID: is the application identifier.  It can be option if the
      connection between the application and the IPSEC_API identifies
      the application.  We do not specify here how applications are
      identified by the IPSEC_API.  It could be by the port, or another
      ID.
   o  CONNECTION_ID identifies the connection (@IP_src, @IP_dst,
      port_src, port_dst).  Value "ANY" could also be used.
   o  PARAM can be :
   o





Migault                 Expires September 3, 2009              [Page 19]


Internet-Draft           IPSEC_API requirements               March 2009


      *  AUTH_LAYER_PROP [LR] with its associated value: APP_ONLY,
         IKE_ONLY, IKE_APP_ACK, NONE.
      *  AUTH_IPSEC_METHOD_PROP [LR]: is an ordered list of
         authentication methods.  If one authentication method is not
         recognized, a warning message is sent.  If no authentication
         method is recognized, an error message is sent.  Possible
         values for the list elements are [I-D.ietf-btns-c-api]: [NONE,
         BTNS, LEATOFFAITH, PRESHAREDKEY, GROUPKEY, XAUTH, EAP,
         PKIX_TRUSTED, PKIX_INLINE, PKIX_OFFLINE].
      *  AUTH_APP_METHOD_PROP [LR]: is an ordered list of authentication
         methods of application.  A common list MUST be set in
         [I-D.ietf-btns-abstract-api].
      *  AUTH_PARAMETERS_PROP [LR]: Parameters required for the
         authentication, or at least their location.  Possible values
         are : AUTHCTX_IPSEC_ sharedKeyID : list of shared key to
         consider, AUTHCTX_IPSEC_ sharedKey : list of public key to
         consider, AUTHCTX_IPSEC_ sharedKey_DIR : list of directories
         with the public keys to consider, AUTHCTX_IPSEC_ pukKeyID :
         list or public key id to consider, AUTHCTX_IPSEC_ pukKey : list
         of public key to consider, AUTHCTX_IPSEC_ pukKey_DIR : list of
         directories with the public keys to consider,
         AUTHCTX_IPSEC_certificateDN : list of certificate DN to
         consider, AUTHCTX_IPSEC_certificateCERT : list of certificates
         to consider for peer authentication,
         AUTHCTX_IPSEC_certificateCERT_DIR : directory with certificates
         to consider for peer authentication,
         AUTHCTX_IPSEC_certificateAuthorityDN : list of certificate
         authority DN to consider,
         AUTHCTX_IPSEC_certificateAuthorityCERT : list of certificates
         authority to consider for peer authentication,
         AUTHCTX_IPSEC_certificateAuthorityCERT_DIR : directory
         containing certificates authority to consider for peer
         authentication
      *  AUTHCTX_IPSEC_ACL_file
      *  ACTION: an action to perform like DELETE, AUTHENTICATE...


8.  Security Considerations

   This paper provides a description of application requirements to take
   benefit of the IPsec layer.  Security considerations concerns are
   that remote and local applications can interact and potentially
   modify IPsec databases.

      Access and application privileges MUST be configured properly.
      Access policy is described in [I-D.mglt-ipsec-appdb].





Migault                 Expires September 3, 2009              [Page 20]


Internet-Draft           IPSEC_API requirements               March 2009


      Changes on IPsec Databases SHOULD NOT subsist to crash.  Changes
      SHOULD be stored, at least for regular application in application
      driven databases.
      When IPsec databases are changed by applications; one MUST
      identify the requester application.  An application can use the
      APP_ID of another application to be assigned more privileges.
      This problematic MUST clearly be described but is out of scope of
      this paper.  On a local system, PATH and application names can
      identify the application since the system is considered trusted.
      With remote applications, one can accept modifications only from
      nodes that are trusted or believed so.  This can be the case for
      end users accepting modifications from their ISP for example.  In
      that case network authentication is enough, and then application
      name can be trusted to identify applications.  [Can we do better?]


9.  IANA Considerations

   There are no IANA considerations.


10.  Acknowledgments

   Daniel Migault is partly funded by 3MING, a research project
   supported by the French 'National Research Agency'(ANR).


11.  References

11.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC4301]  Kent, S. and K. Seo, "Security Architecture for the
              Internet Protocol", RFC 4301, December 2005.

   [RFC4302]  Kent, S., "IP Authentication Header", RFC 4302,
              December 2005.

   [RFC4306]  Kaufman, C., "Internet Key Exchange (IKEv2) Protocol",
              RFC 4306, December 2005.

   [RFC4307]  Schiller, J., "Cryptographic Algorithms for Use in the
              Internet Key Exchange Version 2 (IKEv2)", RFC 4307,
              December 2005.

   [RFC5056]  Williams, N., "On the Use of Channel Bindings to Secure



Migault                 Expires September 3, 2009              [Page 21]


Internet-Draft           IPSEC_API requirements               March 2009


              Channels", RFC 5056, November 2007.

11.2.  Informative References

   [I-D.ietf-btns-abstract-api]
              Richardson, M., "An abstract interface between
              applications and IPsec", draft-ietf-btns-abstract-api-02
              (work in progress), February 2008.

   [I-D.ietf-btns-c-api]
              Richardson, M., Williams, N., Komu, M., and S. Tarkoma,
              "IPsec Application Programming Interfaces",
              draft-ietf-btns-c-api-03 (work in progress),
              February 2008.

   [I-D.ietf-btns-connection-latching]
              Williams, N., "IPsec Channels: Connection Latching",
              draft-ietf-btns-connection-latching-08 (work in progress),
              April 2008.

   [I-D.ietf-btns-ipsec-apireq]
              Richardson, M. and B. Sommerfeld, "Requirements for an
              IPsec API", draft-ietf-btns-ipsec-apireq-00 (work in
              progress), April 2006.

   [I-D.mglt-ipsec-appdb]
              Migault, D., "Application IPsec privileges Database",
              draft-mglt-ipsec-appdb-00 (work in progress),
              November 2008.

   [RFC2367]  McDonald, D., Metz, C., and B. Phan, "PF_KEY Key
              Management API, Version 2", RFC 2367, July 1998.

   [RFC5386]  Williams, N. and M. Richardson, "Better-Than-Nothing
              Security: An Unauthenticated Mode of IPsec", RFC 5386,
              November 2008.















Migault                 Expires September 3, 2009              [Page 22]


Internet-Draft           IPSEC_API requirements               March 2009


Author's Address

   Daniel Migault
   Orange Labs R&D
   38 rue du General Leclerc
   92794 Issy-les-Moulineaux Cedex 9
   France

   Phone: +33 1 45 29 60 52
   Email: mglt.ietf@gmail.com









































Migault                 Expires September 3, 2009              [Page 23]