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]