netconfcentral logo

ietf-ipsec-common

HTML

ietf-ipsec-common@2019-08-05



  module ietf-ipsec-common {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-ipsec-common";

    prefix ipsec-common;

    import ietf-inet-types {
      prefix inet;
    }
    import ietf-yang-types {
      prefix yang;
    }

    organization "IETF I2NSF Working Group";

    contact
      "WG Web:  <https://datatracker.ietf.org/wg/i2nsf/about/>
     WG List: <mailto:i2nsf@ietf.org>

    Author: Rafael Marin-Lopez
            <mailto:rafa@um.es>

    Author: Gabriel Lopez-Millan
            <mailto:gabilm@um.es>

    Author: Fernando Pereniguez-Garcia
            <mailto:fernando.pereniguez@cud.upct.es>
    ";

    description
      "Common Data model for the IKE and IKE-less cases
         defined by the SDN-based IPsec flow protection service.

        Copyright (c) 2019 IETF Trust and the persons
        identified as authors of the code.  All rights reserved.
        Redistribution and use in source and binary forms, with
        or without modification, is permitted pursuant to, and
        subject to the license terms contained in, the
        Simplified BSD License set forth in Section 4.c of the
        IETF Trust's Legal Provisions Relating to IETF Documents
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC XXXX;;
        see the RFC itself for full legal notices.

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
        'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
        'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this
        document are to be interpreted as described in BCP 14
        (RFC 2119) (RFC 8174) when, and only when, they appear
        in all capitals, as shown here.";

    revision "2019-08-05" {
      description "Revision 06";
      reference
        "RFC XXXX: YANG Groupings and typedef
        for IKE and IKE-less case";

    }


    typedef encryption-algorithm-type {
      type uint16;
      description
        "The encryption algorithm is specified with a 16-bit
            number extracted from IANA Registry. The acceptable
            values MUST follow the requirement levels for
            encryption algorithms for ESP and IKEv2.";
      reference
        "IANA Registry- Transform Type 1 - Encryption
        Algorithm Transform IDs. RFC 8221 - Cryptographic
        Algorithm Implementation Requirements and Usage
        Guidance for Encapsulating Security Payload (ESP)
        and Authentication Header (AH) and RFC 8247 -
        Algorithm Implementation Requirements and Usage
        Guidance for the Internet Key Exchange Protocol
        Version 2 (IKEv2).";

    }

    typedef integrity-algorithm-type {
      type uint16;
      description
        "The integrity algorithm is specified with a 16-bit
            number extracted from IANA Registry.
            The acceptable values MUST follow the requirement
            levels for encryption algorithms for ESP and IKEv2.";
      reference
        "IANA Registry- Transform Type 3 - Integrity
        Algorithm Transform IDs. RFC 8221 - Cryptographic
        Algorithm Implementation Requirements and Usage
        Guidance for Encapsulating Security Payload (ESP)
        and Authentication Header (AH) and RFC 8247 -
        Algorithm Implementation Requirements and Usage
        Guidance for the Internet Key Exchange Protocol
        Version 2 (IKEv2).";

    }

    typedef ipsec-mode {
      type enumeration {
        enum "transport" {
          value 0;
          description
            "IPsec transport mode. No Network Address
                     Translation (NAT) support.";
        }
        enum "tunnel" {
          value 1;
          description "IPsec tunnel mode.";
        }
      }
      description
        "Type definition of IPsec mode: transport or
             tunnel.";
      reference
        "Section 3.2 in RFC 4301.";

    }

    typedef esp-encap {
      type enumeration {
        enum "espintcp" {
          value 0;
          description
            "ESP in TCP encapsulation.";
          reference
            "RFC 8229 - TCP Encapsulation of IKE and
            IPsec Packets.";

        }
        enum "espintls" {
          value 1;
          description
            "ESP in TCP encapsulation using TLS.";
          reference
            "RFC 8229 - TCP Encapsulation of IKE and
            IPsec Packets.";

        }
        enum "espinudp" {
          value 2;
          description
            "ESP in UDP encapsulation.";
          reference
            "RFC 3948 - UDP Encapsulation of IPsec ESP
            Packets.";

        }
        enum "none" {
          value 3;
          description
            "NOT ESP encapsulation.";
        }
      }
      description
        "Types of ESP encapsulation when Network Address
             Translation (NAT) is present between two NSFs.";
      reference
        "RFC 8229 - TCP Encapsulation of IKE and IPsec
        Packets and RFC 3948 - UDP Encapsulation of IPsec
        ESP Packets.";

    }

    typedef ipsec-protocol-parameters {
      type enumeration {
        enum "esp" {
          value 0;
          description "IPsec ESP protocol.";
        }
      }
      description
        "Only the Encapsulation Security Protocol (ESP) is
             supported but it could be extended in the future.";
      reference
        "RFC 4303- IP Encapsulating Security Payload
        (ESP).";

    }

    typedef lifetime-action {
      type enumeration {
        enum "terminate-clear" {
          value 0;
          description
            "Terminates the IPsec SA and allows the
                     packets through.";
        }
        enum "terminate-hold" {
          value 1;
          description
            "Terminates the IPsec SA and drops the
                     packets.";
        }
        enum "replace" {
          value 2;
          description
            "Replaces the IPsec SA with a new one:
                    rekey. ";
        }
      }
      description
        "When the lifetime of an IPsec SA expires an action
             needs to be performed over the IPsec SA that
             reached the lifetime. There are three posible
             options: terminate-clear, terminate-hold and
             replace.";
      reference
        "Section 4.5 in RFC 4301.";

    }

    typedef ipsec-traffic-direction {
      type enumeration {
        enum "inbound" {
          value 0;
          description "Inbound traffic.";
        }
        enum "outbound" {
          value 1;
          description "Outbound traffic.";
        }
      }
      description
        "IPsec traffic direction is defined in two
             directions: inbound and outbound. From a NSF
             perspective inbound means the traffic that enters
             the NSF and outbound is the traffic that is sent
             from the NSF.";
      reference
        "Section 5 in RFC 4301.";

    }

    typedef ipsec-spd-action {
      type enumeration {
        enum "protect" {
          value 0;
          description
            "PROTECT the traffic with IPsec.";
        }
        enum "bypass" {
          value 1;
          description
            "BYPASS the traffic. The packet is forwarded
                     without IPsec protection.";
        }
        enum "discard" {
          value 2;
          description
            "DISCARD the traffic. The IP packet is
                     discarded.";
        }
      }
      description
        "The action when traffic matches an IPsec security
             policy. According to RFC 4301 there are three
             possible values: BYPASS, PROTECT AND DISCARD";
      reference
        "Section 4.4.1 in RFC 4301.";

    }

    typedef ipsec-inner-protocol {
      type union {
        type uint8;
        type enumeration {
          enum "any" {
            value 256;
            description
              "Any IP protocol number value.";
          }
        }
      }
      default 'any';
      description
        "IPsec protection can be applied to specific IP
             traffic and layer 4 traffic (TCP, UDP, SCTP, etc.)
             or ANY protocol in the IP packet payload. We
             specify the IP protocol number with an uint8 or
             ANY defining an enumerate with value 256 to
             indicate the protocol number.";
      reference
        "Section 4.4.1.1 in RFC 4301.
        IANA Registry - Protocol Numbers.";

    }

    grouping encap {
      description
        "This group of nodes allows to define the type of
             encapsulation in case NAT traversal is
             required and port information.";
      reference
        "RFC 3947 and RFC 8229.";

      leaf espencap {
        type esp-encap;
        description
          "ESP in TCP, ESP in UDP or ESP in TLS.";
      }

      leaf sport {
        type inet:port-number;
        default '4500';
        description
          "Encapsulation source port.";
      }

      leaf dport {
        type inet:port-number;
        default '4500';
        description
          "Encapsulation destination port.";
      }

      leaf-list oaddr {
        type inet:ip-address;
        description
          "If required, this is the original address that
                 was used before NAT was applied over the Packet.
                 ";
      }
    }  // grouping encap

    grouping lifetime {
      description
        "Different lifetime values limited to an IPsec SA.";
      reference
        "Section 4.4.2.1 in RFC 4301.";

      leaf time {
        type uint32;
        default '0';
        description
          "Time in seconds since the IPsec SA was added.
                 For example, if this value is 180 seconds it
                 means the IPsec SA expires in 180 seconds since
                 it was added. The value 0 implies infinite.";
      }

      leaf bytes {
        type uint32;
        default '0';
        description
          "If the IPsec SA processes the number of bytes
                expressed in this leaf, the IPsec SA expires and
                should be rekeyed. The value 0 implies
                infinite.";
      }

      leaf packets {
        type uint32;
        default '0';
        description
          "If the IPsec SA processes the number of packets
                expressed in this leaf, the IPsec SA expires and
                should be rekeyed. The value 0 implies
                infinite.";
      }

      leaf idle {
        type uint32;
        default '0';
        description
          "When a NSF stores an IPsec SA, it
                 consumes system resources. In an idle NSF this
                 is a waste of resources. If the IPsec SA is idle
                 during this number of seconds the IPsec SA
                 should be removed. The value 0 implies
                 infinite.";
      }
    }  // grouping lifetime

    grouping port-range {
      description
        "This grouping defines a port range, such as
             expressed in RFC 4301. For example: 1500 (Start
             Port Number)-1600 (End Port Number). A port range
             is used in the Traffic Selector.";
      reference
        "Section 4.4.1.2 in RFC 4301.";

      leaf start {
        type inet:port-number;
        description "Start port number.";
      }

      leaf end {
        type inet:port-number;
        description "End port number.";
      }
    }  // grouping port-range

    grouping tunnel-grouping {
      description
        "The parameters required to define the IP tunnel
             endpoints when IPsec SA requires tunnel mode. The
             tunnel is defined by two endpoints: the local IP
             address and the remote IP address.";
      leaf local {
        type inet:ip-address;
        mandatory true;
        description
          "Local IP address' tunnel endpoint.";
      }

      leaf remote {
        type inet:ip-address;
        mandatory true;
        description
          "Remote IP address' tunnel endpoint.";
      }

      leaf df-bit {
        type enumeration {
          enum "clear" {
            value 0;
            description
              "Disable the DF (Don't Fragment) bit
                         from the outer header. This is the
                         default value.";
          }
          enum "set" {
            value 1;
            description
              "Enable the DF bit in the outer header.";
          }
          enum "copy" {
            value 2;
            description
              "Copy the DF bit to the outer header.";
          }
        }
        default 'clear';
        description
          "Allow configuring the DF bit when encapsulating
                 tunnel mode IPsec traffic. RFC 4301 describes
                 three options to handle the DF bit during
                 tunnel encapsulation: clear, set and copy from
                 the inner IP header.";
        reference
          "Section 8.1 in RFC 4301.";

      }

      leaf bypass-dscp {
        type boolean;
        default 'true';
        description
          "If DSCP (Differentiated Services Code Point)
                 values in the inner header have to be used to
                 select one IPsec SA among several that match
                 the traffic selectors for an outbound packet";
        reference
          "Section 4.4.2.1. in RFC 4301.";

      }

      leaf dscp-mapping {
        type yang:hex-string;
        description
          "DSCP values allowed for packets carried over
                 this IPsec SA.";
        reference
          "Section 4.4.2.1. in RFC 4301.";

      }

      leaf ecn {
        type boolean;
        default 'false';
        description
          "Explicit Congestion Notification (ECN). If true
                 copy CE bits to inner header.";
        reference
          "Section 5.1.2 and Annex C in RFC 4301.";

      }
    }  // grouping tunnel-grouping

    grouping selector-grouping {
      description
        "This grouping contains the definition of a Traffic
             Selector, which is used in the IPsec policies and
             IPsec SAs.";
      reference
        "Section 4.4.1.2 in RFC 4301.";

      leaf local-subnet {
        type inet:ip-prefix;
        mandatory true;
        description
          "Local IP address subnet.";
      }

      leaf remote-subnet {
        type inet:ip-prefix;
        mandatory true;
        description
          "Remote IP address subnet.";
      }

      leaf inner-protocol {
        type ipsec-inner-protocol;
        default 'any';
        description
          "Inner Protocol that is going to be
                protected with IPsec.";
      }

      list local-ports {
        key "start end";
        description
          "List of local ports. When the inner
                 protocol is ICMP this 16 bit value represents
                 code and type.";
        uses port-range;
      }  // list local-ports

      list remote-ports {
        key "start end";
        description
          "List of remote ports. When the upper layer
                protocol is ICMP this 16 bit value represents
                code and type.";
        uses port-range;
      }  // list remote-ports
    }  // grouping selector-grouping

    grouping ipsec-policy-grouping {
      description
        "Holds configuration information for an IPsec SPD
             entry.";
      leaf anti-replay-window {
        type uint64;
        default '32';
        description
          "A 64-bit counter used to determine whether an
                 inbound ESP packet is a replay.";
        reference
          "Section 4.4.2.1 in RFC 4301.";

      }

      container traffic-selector {
        description
          "Packets are selected for
                 processing actions based on the IP and inner
                 protocol header information, selectors,
                 matched against entries in the SPD.";
        reference
          "Section 4.4.4.1 in RFC 4301.";

        uses selector-grouping;
      }  // container traffic-selector

      container processing-info {
        description
          "SPD processing. If the required processing
                 action is protect, it contains the required
                 information to process the packet.";
        reference
          "Section 4.4.1.2 in RFC 4301.";

        leaf action {
          type ipsec-spd-action;
          default 'discard';
          description
            "If bypass or discard, container
                    ipsec-sa-cfg is empty.";
        }

        container ipsec-sa-cfg {
          when "../action = 'protect'";
          description
            "IPsec SA configuration included in the SPD
                    entry.";
          leaf pfp-flag {
            type boolean;
            default 'false';
            description
              "Each selector has a Populate From
                          Packet (PFP) flag. If asserted for a
                          given selector X, the flag indicates
                          that the IPsec SA to be created should
                          take its value (local IP address,
                          remote IP address, Next Layer
                          Protocol, etc.) for X from the value
                          in the packet. Otherwise, the IPsec SA
                          should take its value(s) for X from
                          the value(s) in the SPD entry.";
          }

          leaf ext-seq-num {
            type boolean;
            default 'false';
            description
              "True if this IPsec SA is using extended
                          sequence numbers. True 64 bit counter,
                          False 32 bit.";
          }

          leaf seq-overflow {
            type boolean;
            default 'false';
            description
              "The flag indicating whether
                        overflow of the sequence number
                        counter should prevent transmission
                        of additional packets on the IPsec
                        SA (false) and, therefore needs to
                        be rekeyed, or whether rollover is
                        permitted (true). If Authenticated
                        Encryption with Associated Data
                        (AEAD) is used this flag MUST be
                        false.";
          }

          leaf stateful-frag-check {
            type boolean;
            default 'false';
            description
              "Indicates whether (true) or not (false)
                         stateful fragment checking applies to
                         the IPsec SA to be created.";
          }

          leaf mode {
            type ipsec-mode;
            default 'transport';
            description
              "IPsec SA has to be processed in
                         transport or tunnel mode.";
          }

          leaf protocol-parameters {
            type ipsec-protocol-parameters;
            default 'esp';
            description
              "Security protocol of the IPsec SA:
                         Only ESP is supported but it could be
                         extended in the future.";
          }

          container esp-algorithms {
            when
              "../protocol-parameters = 'esp'";
            description
              "Configuration of Encapsulating
                         Security Payload (ESP) parameters and
                         algorithms.";
            reference
              "RFC 4303.";

            leaf-list integrity {
              type integrity-algorithm-type;
              default "0";
              ordered-by user;
              description
                "Configuration of ESP authentication
                            based on the specified integrity
                            algorithm. With AEAD algorithms,
                            the integrity node is not
                            used.";
              reference
                "Section 3.2 in RFC 4303.";

            }

            leaf-list encryption {
              type encryption-algorithm-type;
              default "20";
              ordered-by user;
              description
                "Configuration of ESP encryption
                            algorithms. The default value is
                            20 (ENCR_AES_GCM_16).";
              reference
                "Section 3.2 in RFC 4303.";

            }

            leaf tfc-pad {
              type boolean;
              default 'false';
              description
                "If Traffic Flow Confidentiality
                             (TFC) padding for ESP encryption
                             can be used (true) or not (false)";
              reference
                "Section 2.7 in RFC 4303.";

            }
          }  // container esp-algorithms

          container tunnel {
            when "../mode = 'tunnel'";
            description
              "IPsec tunnel endpoints definition.";
            uses tunnel-grouping;
          }  // container tunnel
        }  // container ipsec-sa-cfg
      }  // container processing-info

      container spd-mark {
        description
          "The Mark to set for the IPsec SA of this
                     connection. This option is only available
                     on linux NETKEY/XFRM kernels. It can be
                     used with iptables to create custom
                     iptables rules using CONNMARK. It can also
                     be used with Virtual Tunnel Interfaces
                     (VTI) to direct marked traffic to
                     specific vtiXX devices.";
        leaf mark {
          type uint32;
          default '0';
          description
            "Mark used to match XFRM policies and
                         states.";
        }

        leaf mask {
          type yang:hex-string;
          default '00:00:00:00';
          description
            "Mask used to match XFRM policies and
                        states.";
        }
      }  // container spd-mark
    }  // grouping ipsec-policy-grouping
  }  // module ietf-ipsec-common

Summary

  
  
Organization IETF I2NSF Working Group
  
Module ietf-ipsec-common
Version 2019-08-05
File ietf-ipsec-common@2019-08-05.yang
  
Prefix ipsec-common
Namespace urn:ietf:params:xml:ns:yang:ietf-ipsec-common
  
Cooked /cookedmodules/ietf-ipsec-common/2019-08-05
YANG /src/ietf-ipsec-common@2019-08-05.yang
XSD /xsd/ietf-ipsec-common@2019-08-05.xsd
  
Abstract Common Data model for the IKE and IKE-less cases defined by the SDN-based IPsec flow protection service. Copyright (c) 2019 IET...
  
Contact
WG Web:  <https://datatracker.ietf.org/wg/i2nsf/about/>
WG List: <mailto:i2nsf@ietf.org>

Author: Rafael Marin-Lopez
       <mailto:rafa@um.es>

Author: Gabriel Lopez-Millan
       <mailto:gabilm@um.es>

Author: Fernando Pereniguez-Garcia
       <mailto:fernando.pereniguez@cud.upct.es>

Description

 
Common Data model for the IKE and IKE-less cases
defined by the SDN-based IPsec flow protection service.

Copyright (c) 2019 IETF Trust and the persons
identified as authors of the code.  All rights reserved.
Redistribution and use in source and binary forms, with
or without modification, is permitted pursuant to, and
subject to the license terms contained in, the
Simplified BSD License set forth in Section 4.c of the
IETF Trust's Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).

This version of this YANG module is part of RFC XXXX;;
see the RFC itself for full legal notices.

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in BCP 14
(RFC 2119) (RFC 8174) when, and only when, they appear
in all capitals, as shown here.

Typedefs

Typedef Base type Abstract
encryption-algorithm-type uint16 The encryption algorithm is specified with a 16-bit number extracted from IANA Registry. The acceptable values MUST follow the requirement levels for encryption algorithms for ESP and IKEv2.
esp-encap enumeration Types of ESP encapsulation when Network Address Translation (NAT) is present between two NSFs.
integrity-algorithm-type uint16 The integrity algorithm is specified with a 16-bit number extracted from IANA Registry. The acceptable values MUST follow the requirement levels for encryption algorithms for ESP and IKEv2.
ipsec-inner-protocol union IPsec protection can be applied to specific IP traffic and layer 4 traffic (TCP, UDP, SCTP, etc.) or ANY protocol in the IP packet payload. We specify the IP protocol number with an uint8 or ANY defining an enumerate with value 256 to indicate the protoco...
ipsec-mode enumeration Type definition of IPsec mode: transport or tunnel.
ipsec-protocol-parameters enumeration Only the Encapsulation Security Protocol (ESP) is supported but it could be extended in the future.
ipsec-spd-action enumeration The action when traffic matches an IPsec security policy. According to RFC 4301 there are three possible values: BYPASS, PROTECT AND DISCARD
ipsec-traffic-direction enumeration IPsec traffic direction is defined in two directions: inbound and outbound. From a NSF perspective inbound means the traffic that enters the NSF and outbound is the traffic that is sent from the NSF.
lifetime-action enumeration When the lifetime of an IPsec SA expires an action needs to be performed over the IPsec SA that reached the lifetime. There are three posible options: terminate-clear, terminate-hold and replace.

Groupings

Grouping Objects Abstract
encap espencap sport dport oaddr This group of nodes allows to define the type of encapsulation in case NAT traversal is required and port information.
ipsec-policy-grouping anti-replay-window traffic-selector processing-info spd-mark Holds configuration information for an IPsec SPD entry.
lifetime time bytes packets idle Different lifetime values limited to an IPsec SA.
port-range start end This grouping defines a port range, such as expressed in RFC 4301. For example: 1500 (Start Port Number)-1600 (End Port Number). A port range is used in the Traffic Selector.
selector-grouping local-subnet remote-subnet inner-protocol local-ports remote-ports This grouping contains the definition of a Traffic Selector, which is used in the IPsec policies and IPsec SAs.
tunnel-grouping local remote df-bit bypass-dscp dscp-mapping ecn The parameters required to define the IP tunnel endpoints when IPsec SA requires tunnel mode. The tunnel is defined by two endpoints: the local IP address and the remote IP address.