Internet Engineering Task Force                          Jamie Jason
   INTERNET DRAFT                                      Michael Jeronimo
   24 March 1999                                      Intel Corporation



                            IPsec Policy Schema
                   draft-ietf-ipsec-policy-schema-00.txt


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

Abstract

   This document presents an object-oriented model of IPsec policy in
   order to facilitate agreement about the content and semantics of
   IPsec policy and to enable derivations of task-specific
   representations of IPsec policy such as storage schema, distribution
   representations, and policy specification languages.



















Jason and Jeronimo                                            [Page 1]


Internet Draft           IPsec Policy Schema               April 1999


Table of Contents

   Status of this Memo................................................1
   Abstract...........................................................1
   Table of Contents..................................................2
   1. Introduction....................................................3
   2. Overview of the classes.........................................3
   2.1 Endpoint.......................................................3
   2.2 Protocol.......................................................4
   2.3 Condition......................................................4
   2.4 Action.........................................................4
   2.5 Rule...........................................................4
   2.6 Policy.........................................................4
   3. Class Hierarchy.................................................5
   4. Class Diagram...................................................5
   5. Class Definitions...............................................7
   5.1 Unique Objects.................................................7
   5.2 Endpoints......................................................7
   5.3 Protocols......................................................9
   5.4 Conditions.....................................................9
   5.5 IKE Actions...................................................10
   5.6 IPsec Actions.................................................10
   5.7 Rules.........................................................11
   5.8 Policies......................................................11
   6. Security Considerations........................................12
   7. Intellectual Property..........................................12
   8. Acknowledgments................................................12
   9. References.....................................................12
   10. Disclaimer....................................................13
   11. Authors' Address..............................................13
























Jason and Jeronimo      Expires November 1999                [Page 2]


Internet Draft           IPsec Policy Schema               April 1999




1. Introduction

   IPsec policy may assume a variety of forms as it travels from
   storage to distribution point to decision point.  At each step, it
   may be represented in a way convenient for the current task.  For
   example, the policy could exist as an LDAP schema in a directory, or
   as an on-the-wire representation over a transport protocol, or in a
   text-based policy specification language suitable for editing by an
   administrator.  Each of these task-specific representations should
   be derived from a canonical representation that exactly specifies
   the content and semantics of IPsec policy.  The purpose of this
   document is to abstract IPsec policy into a task-independent
   representation.  The document is organized as follows:

   o Section 2 provides an informal description of the classes defined
     in the IPsec policy schema to give a framework for understanding
     subsequent sections.

   o Section 3 lists the IPsec policy schema class hierarchy,
     displaying the derived-from relationships contained in the schema.

   o Section 4 presents a detailed class diagram for the IPsec policy
     schema.  This view shows the static relationship between the
     various classes in the schema.

   o Section 5 informally describes the semantics of each of the
     classes in the policy schema.

2. Overview of the classes

   The IPsec policy schema is a model for IPsec policy that provides
   the structure to express when IPsec is to be applied and what
   specific IPsec settings are to be used.  This section will give an
   informal description for each of the classes in the IPsec policy
   schema and describe their relationships.

   When modeling IPsec policy, it is appropriate to answer the
   following questions:

   o WHO is sending/receiving the traffic?
   o WHAT are they sending/receiving?
   o WHEN should traffic be protected?
   o HOW should the traffic be treated?

2.1 Endpoint

   An Endpoint is meant to model a single communication endpoint - in
   other words, a sender or receiver of IP traffic.  An endpoint should
   not be confused with a single host - while a single host is a type
   of endpoint, an endpoint is not necessarily a single host.  An
   endpoint is an abstraction upon which concrete specializations are

Jason and Jeronimo      Expires November 1999                [Page 3]


Internet Draft           IPsec Policy Schema               April 1999


   derived.  The endpoint answers the first question above - who is
   sending/receiving data.

2.2 Protocol

   A Protocol is a specification that characterizes the type of
   traffic.  As with the endpoint, a protocol is an abstraction upon
   which are derived concrete specializations that specify protocol and
   possibly ports.  The Protocol class is used to separate out the
   communication protocol that an endpoint is using from the endpoint
   itself.  The protocol answers the second question above - what is
   being sent/received.

2.3 Condition

   A condition element is a condition type (endpoints and protocols are
   examples of condition types) along with its associated value.

   A condition is defined as a predicate that is evaluated against the
   information provided to determine if there is a match (in other
   words, a true evaluation).  The predicate is a logical expression of
   one or more condition elements, combined using binary logical
   operators (AND, OR), and possibly grouped using precedence operators
   (parentheses).  Any part of a condition can be further modified
   using a unary negation (NOT) operator. The condition answers the
   third question - when should traffic be protected.

2.4 Action

   An Action is a group of Network Service-specific settings (in our
   example, IPsec) that are to be enforced when its related Condition
   evaluates to true.  The Action answers the fourth question - how
   should the traffic be treated.

2.5 Rule

   A Rule is an ordered sequence Conditions, ideally mutually
   exclusive, paired with a  set of Actions.  The Conditions are
   evaluated in order until either the sequence is exhausted or a
   condition evaluates to TRUE.  If a condition evaluates to TRUE, then
   the corresponding Actions are performed.

2.6 Policy

   A policy is an ordered sequence of rules defined to achieve a
   specific purpose û for example, one policy might be appropriate for
   a server while another policy contains rules more appropriate for a
   client.






Jason and Jeronimo      Expires November 1999                [Page 4]


Internet Draft           IPsec Policy Schema               April 1999


3. Class Hierarchy

   The following illustrates the class hierarchy for the IPsec policy
   classes.

      Top
       |
       +---Policy
       +---Rule
       +---Condition
       +---ConditionElement
       |       |
       |       +---EndPoint
       |       |       |
       |       |       +---IPv4
       |       |       +---IPv4Range
       |       |       +---IPv4Subnet
       |       |       +---IPv6
       |       |       +---IPv6Range
       |       |       +---IPv6Subnet
       |       |       +---FQDN
       |       |       +---EndpointGroup
       |       +---Protocol
       |               |
       |               +---GenericProtocol
       |               +---TCPProtocol
       |               +---UDPProtocol
       |               +---ProtocolGroup
       +---Action
       |       |
       |       +---IKEAction
       |       +---IPsecAction
       |               |
       |               +---IPsecTransportAction
       |               +---IPsecTunnelAction
       +---IKEProposal
       +---IPsecProposal


4. Class Diagram

   The following is a high-level representation of policy.  A Unified
   Modeling Language (UML) class diagram is used to represent the
   objects.

   In the following class diagram:

   o  Each box represent class with the class name provided.
   o  Class names in brackets ([]) denotes a virtual class.
   o  A line terminated by a "o" represents aggregation.  For example,
      a Policy contains 1 to n rules and a Rule may be contained in 0
      to n policies.  In aggregation, the class being aggregated has a
      lifetime that is independent of the class that contains it.

Jason and Jeronimo      Expires November 1999                [Page 5]


Internet Draft           IPsec Policy Schema               April 1999


   o  A line terminated by an asterisk (*) represents composition.  For
      example, a Condition contains 1 to n Condition Elements and a
      Condition Element is contained in one and only one Condition.
      Composition differs from aggregation in that a contained object
      only exists as long as the containing object.
   o  A line terminated by a arrow (^, <, or >), denotes inheritance,
      with the arrow pointing to the parent class.

                            +-----------+
                            |           |
                            |  Policy   |
                            |           |
                            +-----+-----+
                                  o 0..n
                                  |
                                  | 1..n
          +-----------+     +-----+-----+     +-----------+
          |           |1..n |           |0..n |           |
          | Condition +----o|   Rule    |o----|  [Action] |
          |           | 1..1|           | 1..n|           |
          +-----+-----+     +-----------+     +-----------+
                * 1..1                              ^
                |                                   |
                | 1..n                +-------------+
          +-----+-----+         +-----+-----+ +-----+-----+
          |[Condition |         |           | |           |
          |  Element] |         |    IKE    | |  [IPsec   |<--+
          +-----------+         |   Action  | |  Action]  |   |
                ^               +-----------+ +-----------+   |
                |                     * 1..1        * 1..1    |
         +------+------+              |             |         |
         |             |              | 1..n        | 1..n    |
   +-----+-----+ +-----+-----+  +-----+-----+ +-----+-----+   |
   |           | |           |  |           | |           |   |
   |[Endpoint] | |[Protocol] |  |   IPsec   | |   IPsec   |   |
   |           | |           |  |  Proposal | |  Proposal |   |
   +-----------+ +-----------+  +-----------+ +-----------+   |
         | 2                                                  |
         |                                                    |
         |                                      +-------------+
         |                                      |             |
         |                                +-----+-----+ +-----+-----+
         |                                |   IPsec   | |   IPsec   |
         |                                | Transport | |   Tunnel  |
         |                                |  Action   | |   Action  |
         |                                +-----------+ +-----+-----+
         |                                                    | 1..1
         |                                                    |
         +----------------------------------------------------+





Jason and Jeronimo      Expires November 1999                [Page 6]


Internet Draft           IPsec Policy Schema               April 1999


5. Class Definitions

5.1 Unique Objects

   Something that is not conveyed in the preceeding class diagram is
   the notion of a unique object.  A unique object is an object that is
   used as a building block in the policy system.  Unique objects can
   exist independently of all other objects.  Each unique object has
   associated with it a universally unique identifier (UUID).  This
   UUID lives with the object for the existence of the object.  In
   addition to a UUID, a unique object also has associated with it a
   more user-friendly display name.  The following objects are unique
   objects in our system:

   o  Policies
   o  Rules
   o  Conditions
   o  Actions (IKE, IPSEC Transport, and IPSEC Tunnel)
   o  Endpoint Groups (described later)
   o  Protocol Groups (described later)

5.2 Endpoints

   An Endpoint identifies a sender or receiver of IP traffic.  An
   endpoint condition element can be specialized to be one of the
   following types:

   o  IPv4 Address
   o  IPv4 Address Range
   o  IPv4 Subnet/Mask
   o  IPv6 Address
   o  IPv6 Address Range
   o  IPv6 Subnet/Mask
   o  Fully Qualified Domain Name (FQDN)
   o  Endpoint Group

   The following is the class diagram for an endpoint.

                   +---------------------+
                   * 1..1            1..n|
             +-----+-----+         +-----+-----+         +-----------+
             |           |         |           |         |           |
             |  Endpoint +-------->+ [Endpoint]|<--------+   FQDN    |
             |   Group   |         |           |         |           |
             +-----------+         +-----------+         +-----------+
                                         ^
             +-----------+               |               +-----------+
             |           |               |               |           |
             |    IPv4   +---------------+---------------+    IPv6   |
             |  Address  |               |               |  Address  |
             +-----------+               |               +-----------+
                                         |
                                         |

Jason and Jeronimo      Expires November 1999                [Page 7]


Internet Draft           IPsec Policy Schema               April 1999


             +-----------+               |               +-----------+
             |    IPv4   |               |               |    Ipv6   |
             |  Address  +---------------+---------------+  Address  |
             |   Range   |               |               |   Range   |
             +-----------+               |               +-----------+
                                         |
             +-----------+               |               +-----------+
             |    IPv4   |               |               |    Ipv6   |
             |  Subnet/  +---------------+---------------+  Subnet/  |
             |    Mask   |                               |    Mask   |
             +-----------+                               +-----------+

   The only endpoint specialization that may require explanation is the
   endpoint group.  An endpoint group is a named, ordered sequence of
   (possibly) heterogeneous endpoints.  Endpoint groups are used to
   group together endpoints which are to be treated the same.  For
   example, there may exist an endpoint group named "Marketing" that
   contains the FQDNs of the systems in the Marketing department.

   Since an endpoint group is a unique object, a condition only
   contains a reference to it.  This makes it possible to have the same
   endpoint group appear in multiple conditions without duplication of
   the entire group.  More importantly, changes to an endpoint group
   are automatically reflected in the condition(s) in which it is
   referenced.  For example, say that a new machine in the Marketing
   department is added to the network.  By adding the system to the
   "Marketing" endpoint group, the system will be provided the same
   IPsec services as the other Marketing systems.

   Note that in the above class diagram an endpoint group not only
   contains endpoint objects, but also derives from an endpoint (in
   Design Pattern nomenclature, this is a Composite pattern).  The net
   result is that an endpoint group may contain one or more endpoint
   groups.  The only restriction is that circular references are not
   allowed - for example, an endpoint group may not contain a reference
   to itself or by following its endpoint group references recursively
   may not find a reference to itself.

















Jason and Jeronimo      Expires November 1999                [Page 8]


Internet Draft           IPsec Policy Schema               April 1999


5.3 Protocols

   A protocol object is used to specify the information about what two
   communicating host are "saying" to each other.  This information
   includes the IP protocol and in the case of UDP or TCP, the source
   and destination port ranges.  The following is a class diagram for a
   protocol.

                                   +-----------+
                               1..n| [Protocol]|
                   +---------------+           |
                   |               +-----------+
               1..1*                     ^
             +-----------+               |               +-----------+
             |  Protocol +---------------+---------------+    UDP    |
             |   Group   |               |               |  Protocol |
             +-----------+               |               +-----------+
                                         |
             +-----------+               |               +-----------+
             |  Generic  +---------------+---------------+    TCP    |
             |  Protocol |                               |  Protocol |
             +-----------+                               +-----------+

   It would be simple enough to have only one class that covers all
   protocols, however a non-UDP/TCP protocol does not need the port
   fields.  As with endpoints, there is a named, ordered sequence of
   protocols - protocol groups.

   Since a protocol group is a unique object, it exhibits the same
   properties as an endpoint group.  For example, assume there is a
   protocol group named "Essential Services".  If it is later
   determined that another protocol needs to be added to "Essential
   Services", this can be done by modifying the "Essential Services"
   protocol group instead of modifying all conditions which reference
   the protocol group.

   A protocol group, like an endpoint group, is restricted by the
   "circular reference" limitation.

5.4 Conditions

   In the case of IPSEC, we chose to simplify the condition to contain
   the following three components:

   o  a source endpoint group, SourceGroup
   o  a destination endpoint group, DestinationGroup
   o  a protocol group, ProtocolGroup

   The condition would be specified as:

   IF (SourceGroup AND DestinationGroup AND ProtocolGroup)

   In English, the condition could be phrased as:

Jason and Jeronimo      Expires November 1999                [Page 9]


Internet Draft           IPsec Policy Schema               April 1999



   "When communicating from SourceGroup to DestinationGroup using
        ProtocolGroup"

   It is also important to note that even though this was designed in
   the context of IPsec, the Condition is actually domain-independent.
   That is, the same Condition used to specify an IPsec Action could
   also be used for other domains such as Bandwidth and Access.
   However, this should not be taken to mean that Conditions may only
   contain domain-independent Condition Elements.  If appropriate, a
   Condition may contain domain-dependent Condition Elements.  For
   example, if we cared about CPU utilization and wanted to restrict a
   host to using 3-DES for only 5 active streams, a Condition Element
   that states this could be used.
   While we restricted ourselves to the traditional 5-tuple, there is
   nothing that restricts the use of other condition elements (for
   example, time-of-day).

5.5 IKE Actions

   An IKE Action contains the information necessary to perform the IKE
   Phase 1 negotiation:

   o  the IKE mode (main or aggressive)
   o  the SA kilobyte lifetime
   o  the SA seconds lifetime
   o  the credential type expected/provided (for example, preshared
      key)
   o  if the credential type is preshared key, the preshared key
   o  an ordered sequence of IKE proposals

   Each IKE proposal contains the following information:

   o  an ordered sequence of authentication methods
   o  an ordered sequence of encryption algorithms
   o  an ordered sequence of hash algorithms
   o  a Diffie-Hellman group

5.6 IPsec Actions

   An IPsecAction is an abstract class that contains settings that are
   common to both transport and tunnel actions:

   o  whether or not to employ IPsec replay detection
   o  the SA kilobyte lifetime
   o  the SA seconds lifetime
   o  the Diffie-Hellman group
   o  an ordered list of IPsec proposals






Jason and Jeronimo      Expires November 1999               [Page 10]


Internet Draft           IPsec Policy Schema               April 1999


   An IPsecTransportAction does not further specialize the IPsecAction.
   The IPsecTunnelAction adds the following:

   o  the local gateway - an IPv4/6 or FQDN endpoint
   o  the remote gateway - an IPv4/6 or FQDN endpoint

   Each IPsec proposal contains the following information:

   o  an ordered sequence of AH authentication algorithms
   o  an ordered sequence of ESP encryption algorithms
   o  an ordered sequence of ESP authentication algorithms

   Although not in the policy class diagram, there are also two more
   IPsec transport actions:

   o  IPsecPermitAction - allows traffic to be sent/received in the
      clear
   o  IPsecDenyAction - causes traffic that matches the parameters to
      be dropped

5.7 Rules

   As stated earlier, a rule is an ordered sequence of Conditions
   paired with a set of Actions:

   IF (Condition OR Condition ...) THEN (Action AND Action ...)

   For simplification, our system restricts a rule to being a
   condition/action pair.  This unfortunately does sometimes require
   duplication (of which we tried to avoid at all cost).  For example,
   assume host S is talking to host D and it is desirable to not only
   have end-to-end security, but also to use an encrypted tunnel
   between the two sites.  In our model, two rules will need to be
   specified - one for transport mode and one for tunnel mode (we will
   discuss later the evaluation process to make sure that tunnel mode
   rules are acted upon first).

   A rule is a unique object in the system and as such, may appear in
   more than one policy.  Updates to a rule are automatically reflected
   in the affected policies.

5.8 Policies
   In our system, a policy is a named, ordered sequence of rules.  The
   ordering of the rules within a policy is beyond the scope of this
   draft.  The rules in the policy are evaluated sequentially until
   either one of the rules evaluates to true or the sequence is
   exhausted.  On a host, there may be several policies, however, at
   any given time only one policy may be tagged as the active policy
   (in other words, the one that is consulted when a decision is to be
   made).




Jason and Jeronimo      Expires November 1999               [Page 11]


Internet Draft           IPsec Policy Schema               April 1999


6. Security Considerations

   This document describes a schema for IPsec policy.  It does not
   detail security requirements for storage or delivery of this schema.
   Storage and delivery security requirements should be detailed in a
   comprehensive policy architecture.

7. Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   intellectual property or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; neither does it represent that it
   has made any effort to identify any such rights. Information on the
   IETF's procedures with respect to rights in standards-track and
   standards-related documentation can be found in BCP-11.

   Copies of claims of rights made available for publication and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use
   of such proprietary rights by implementers or users of this
   specification can be obtained from the IETF Secretariat.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights which may cover technology that may be required to practice
   this standard. Please address the information to the IETF Executive
   Director.

8. Acknowledgments

   The authors would like to thank Baiju Patel, Ganesh Krishnan, and
   Ylian Saint-Hilaire for their discussions and contributions to this
   policy model.  We would also like to thank Allison Angus for her
   efforts in user-interface design and usability feedback.

9. References

   [1]  J. Strassner and E. Ellesson, ôTerminology for describing
   network policy and servicesö, draft-strassner-policy-terms-01.txt,
   February 1999.

   [2]  J. Strassner, E. Ellesson, B. Moore, ôPolicy Framework Core
   Information Modelö, draft-ietf-policy-core-schema-02.txt, February
   1999.

   [3]  R. Pereira, P. Bhattacharya, ôIPsec Policy Data Modelö, draft-
   ietf-ipsec-policy-model-00.txt, February 1998.





Jason and Jeronimo      Expires November 1999               [Page 12]


Internet Draft           IPsec Policy Schema               April 1999


   [4]  P. Bhattacharya, R. Adams, W. Dixon, R. Pereira, R. Rajan, ôAn
   LDAP Schema for Configuration and Administration of IPsec based
   Virtual Private Networks (VPNs)ö, draft-ietf-ipsec-vpn-policy-
   schema-00.txt, October 1998.

10. Disclaimer

   The views and specification herein are those of the authors and are
   not necessarily those of their employer.  The authors and their
   employer specifically disclaim responsibility for any problems
   arising from correct or incorrect implementation or use of this
   specification.

11. Authors' Address

   Jamie Jason
      Intel Corporation
      MS JF3-206
      2111 NE 25th Ave.
      Hillsboro, OR 97124
      Phone: +1-503-264-9531
      Fax: +1-503-264-9428
      E-Mail: Jamie.Jason@intel.com

   Michael Jeronimo
      Intel Corporation
      MS JF3-206
      2111 NE 25th Ave.
      Hillsboro, OR 97124
      Phone: +1-503-264-5970
      Fax: +1-503-264-9428
      E-Mail: Michael.Jeronimo@intel.com






















Jason and Jeronimo      Expires November 1999               [Page 13]