<?xml version='1.0'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc linkmailto="no" ?>
<?rfc editing="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes"?>
<?rfc rfcedstyle="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<!--<?rfc strict="no"?> -->

<rfc category="std"
     ipr="trust200902"
     docName="draft-ietf-netconf-tls-client-server-04" >
    <front>
        <title>YANG Groupings for TLS Clients and TLS Servers</title>
        <author initials="K.W." surname="Watsen" fullname="Kent Watsen">
            <organization>Juniper Networks</organization>
            <address>
                <email>kwatsen@juniper.net</email>
            </address>
        </author>
        <author initials="G.W." surname="Wu" fullname="Gary Wu">
            <organization>Cisco Systems</organization>
            <address>
                <email>garywu@cisco.com</email>
            </address>
        </author>
        <date/>
        <area>Operations</area>
        <workgroup>NETCONF Working Group</workgroup>
        <abstract>
            <t>This document defines three YANG modules: the first defines
            groupings for a generic TLS client, the second defines groupings
            for a generic TLS server, and the third defines common identities
            and groupings used by both the client and the server.  It is
            intended that these groupings will be used by applications using
            the TLS protocol.</t>
        </abstract>
        <note title="Editorial Note (To be removed by RFC Editor)">
          <t>This draft contains many placeholder values that need to be replaced
          with finalized values at the time of publication.  This note summarizes
          all of the substitutions that are needed.  No other RFC Editor
          instructions are specified elsewhere in this document.</t>

          <t>This document contains references to other drafts in progress, both in
          the Normative References section, as well as in body text throughout.  
          Please update the following references to reflect their final RFC assignments:
            <list style="symbols">
              <t>I-D.ietf-netconf-keystore</t>
            </list>
          </t>
          <t>Artwork in this document contains shorthand references to drafts in 
          progress.  Please apply the following replacements:
            <list  style="symbols">
              <t><spanx style="verb">XXXX</spanx> --&gt; the assigned RFC value for this draft</t>
              <t><spanx style="verb">YYYY</spanx> --&gt; the assigned RFC value for I-D.ietf-netconf-keystore</t>
            </list>
          </t>
          <t>Artwork in this document contains placeholder values for the date of 
          publication of this draft.  Please apply the following replacement:
            <list  style="symbols">
              <t><spanx style="verb">2017-10-19</spanx> --&gt; the publication date of this draft</t>
            </list>
          </t>
          <t>The following Appendix section is to be removed prior to publication:
            <list  style="symbols">
              <t>Appendix A.  Change Log</t>
            </list>
          </t>
        </note>
    </front>
    <middle>

        <section title="Introduction">

            <t>This document defines three YANG <xref target="RFC7950"/>
            modules: the first defines a grouping for a generic TLS client, the
            second defines a grouping for a generic TLS server, and the third
            defines identities and groupings common to both the client and the
            server (TLS is defined in <xref target="RFC5246"/>).  It is
            intended that these groupings will be used by applications using
            the TLS protocol.  For instance, these groupings could be used to
            help define the data model for an HTTPS <xref target="RFC2818"/>
            server or a NETCONF over TLS <xref target="RFC7589"/> based
            server.</t>

            <t>The client and server YANG modules in this document each define one grouping,
            which is focused on just TLS-specific configuration, and specifically
            avoids any transport-level configuration, such as what ports to
            listen-on or connect-to.  This enables applications the opportunity
            to define their own strategy for how the underlying TCP connection
            is established.  For instance, applications supporting NETCONF Call
            Home <xref target="RFC8071"/> could use the grouping for the TLS
            parts it provides, while adding data nodes for the TCP-level call-home
            configuration.</t>

            <section title="Terminology">
             <t>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 <xref target="RFC2119"/> <xref target="RFC8174"/>
             when, and only when, they appear in all capitals, as shown here.</t>
            </section>

            <section title="Tree Diagrams" anchor="tree-diagrams">
            <t>A simplified graphical representation of the data models
            is used in this document.  The meaning of the symbols in
            these diagrams is as follows:
              <list style="symbols">
                <t>Brackets "[" and "]" enclose list keys.</t>
                <t>Braces "{" and "}" enclose feature names, and indicate
                that the named feature must be present for the subtree
                to be present.</t>
                <t>Abbreviations before data node names: "rw" means
                configuration (read-write) and "ro" state data 
                (read-only).</t>
                <t>Symbols after data node names: "?" means an optional
                node, "!" means a presence container, and "*" denotes a
                list and leaf-list.</t>
                <t>Parentheses enclose choice and case nodes, and case
                nodes are also marked with a colon (":").</t>
                <t>Ellipsis ("...") stands for contents of subtrees that
                are not shown.</t>
              </list>
            </t>
            </section>
        </section>

      <section title="The TLS Client Model" anchor="tls-client-model">

       <t>The TLS client model presented in this section contains one
        YANG grouping, to just configure the TLS client, omitting, for
        instance, any configuration for which IP address or port the
        client should connect to.</t>

        <t>This grouping references data nodes defined by the
        keystore model <xref target="I-D.ietf-netconf-keystore"/>.  For
        instance, a reference to the keystore model is made to indicate
        which trusted CA certificate a client should use to authenticate
        the server's certificate.</t>

        <section title="Tree Diagram">
          <t>The following tree diagram presents the data model for
          the grouping defined in the ietf-tls-client module.  Please
          see <xref target="tree-diagrams"/> for tree diagram notation.</t>
          <t>
            <figure>
              <artwork><![CDATA[
module: ietf-tls-client

  grouping tls-client-grouping
    +---- client-auth
    |  +---- (auth-type)?
    |     +--:(certificate)
    |        +---- certificate?   leafref
    +---- server-auth
    |  +---- pinned-ca-certs?
    |  |       -> /ks:keystore/pinned-certificates/name
    |  +---- pinned-server-certs?
    |          -> /ks:keystore/pinned-certificates/name
    +---- hello-params {tls-client-hello-params-config}?
       +---- tls-versions
       |  +---- tls-version*   identityref
       +---- cipher-suites
          +---- cipher-suite*   identityref
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="Example Usage">
          <t>This section shows how it would appear if the
          tls-client-grouping were populated with some data.
          This example is consistent with the examples presented in
          Section 2.2 of <xref target="I-D.ietf-netconf-keystore"/>.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<!-- hypothetical example, as groupings don't have instance data -->
<tls-client xmlns="urn:ietf:params:xml:ns:yang:ietf-tls-client">

  <!-- how this client will authenticate itself to the server -->
  <client-auth>
    <certificate>builtin-idevid-cert</certificate>
  </client-auth>

  <!-- which certificates will this client trust -->
  <server-auth>
    <pinned-ca-certs>deployment-specific-ca-certs</pinned-ca-certs>
    <pinned-server-certs>explicitly-trusted-client-certs</pinned-server-certs>
  </server-auth>

</tls-client>
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="YANG Model" anchor="tls-client-yang-module">
          <t>This YANG module has a normative references to
          <xref target="RFC6991"/> and <xref target="I-D.ietf-netconf-keystore"/>.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<CODE BEGINS> file "ietf-tls-client@2017-10-19.yang"
module ietf-tls-client {
  yang-version 1.1;

  namespace "urn:ietf:params:xml:ns:yang:ietf-tls-client";
  prefix "tlsc";

  import ietf-tls-common {
    prefix tlscmn;
    revision-date 2017-10-19; // stable grouping definitions
    reference
      "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
  }

  import ietf-keystore {
    prefix ks;
    reference
      "RFC YYYY: Keystore Model";
  }

  organization
   "IETF NETCONF (Network Configuration) Working Group";

  contact
   "WG Web:   <http://tools.ietf.org/wg/netconf/>
    WG List:  <mailto:netconf@ietf.org>

    Author:   Kent Watsen
              <mailto:kwatsen@juniper.net>

    Author:   Gary Wu
              <mailto:garywu@cisco.com>";


  description
   "This module defines a reusable grouping for a TLS client that
    can be used as a basis for specific TLS client instances.

    Copyright (c) 2017 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
    (http://trustee.ietf.org/license-info).

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

  revision "2017-10-19" {
    description
     "Initial version";
    reference
     "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
  }

  feature tls-client-hello-params-config {
    description
      "TLS hello message parameters are configurable on a TLS
       client.";
  }

  grouping tls-client-grouping {
    description
      "A reusable grouping for configuring a TLS client without
       any consideration for how an underlying TCP session is
       established.";

    container client-auth {
      description
        "The credentials used by the client to authenticate to
         the TLS server.";

      choice auth-type {
        description
          "The authentication type.";
        leaf certificate {
          type leafref {
            path "/ks:keystore/ks:keys/ks:key/ks:certificates"
                 + "/ks:certificate/ks:name";
          }
          description
            "A certificates to be used for user authentication.";
        }
      }
    }

    container server-auth {
      must 'pinned-ca-certs or pinned-server-certs';
      description
        "Trusted server identities.";
      leaf pinned-ca-certs {
        type leafref {
          path "/ks:keystore/ks:pinned-certificates/ks:name";
        }
        description
          "A reference to a list of certificate authority (CA)
           certificates used by the TLS client to authenticate
           TLS server certificates.  A server certificate is
           authenticated if it has a valid chain of trust to
           a configured pinned CA certificate.";
      }

      leaf pinned-server-certs {
        type leafref {
          path "/ks:keystore/ks:pinned-certificates/ks:name";
        }
        description
          "A reference to a list of server certificates used by
           the TLS client to authenticate TLS server certificates.
           A server certificate is authenticated if it is an
           exact match to a configured pinned server certificate.";
      }
    }

    container hello-params {
      if-feature tls-client-hello-params-config;
      uses tlscmn:hello-params-grouping;
      description
        "Configurable parameters for the TLS hello message.";
    }

  } // end tls-client-grouping

}
<CODE ENDS>
]]></artwork>
            </figure>
          </t>
        </section>
      </section>

      <section title="The TLS Server Model" anchor="tls-server-model">

        <t>The TLS server model presented in this section contains one
        YANG grouping, for just the TLS-level configuration, omitting,
        for instance, configuration for which ports to open to listen
        for connections on.</t>

        <t>This grouping references data nodes defined by the
        keystore model <xref target="I-D.ietf-netconf-keystore"/>.
        For instance, a reference to the keystore model is made to indicate
        which certificate a server should present.</t>

        <section title="Tree Diagram">
          <t>The following tree diagram presents the data model for
          the grouping defined in the ietf-tls-server module. Please
          see <xref target="tree-diagrams"/> for tree diagram notation.</t>
          <t>
            <figure>
              <artwork><![CDATA[
module: ietf-tls-server

  grouping tls-server-grouping
    +---- certificates
    |  +---- certificate* [name]
    |     +---- name?   leafref
    +---- client-auth
    |  +---- pinned-ca-certs?
    |  |       -> /ks:keystore/pinned-certificates/name
    |  +---- pinned-client-certs?
    |          -> /ks:keystore/pinned-certificates/name
    +---- hello-params {tls-server-hello-params-config}?
       +---- tls-versions
       |  +---- tls-version*   identityref
       +---- cipher-suites
          +---- cipher-suite*   identityref
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="Example Usage">
          <t>This section shows how it would appear if the
          tls-server-grouping were populated with some data.
          This example is consistent with the examples presented in
          Section 2.2 of <xref target="I-D.ietf-netconf-keystore"/>.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<tls-server xmlns="urn:ietf:params:xml:ns:yang:ietf-tls-server">

  <!-- how this server will authenticate itself to the client -->
  <certificates>
    <certificate>
      <name>tls-ec-cert</name>
    </certificate>
  </certificates>

  <!-- which certificates will this server trust -->
  <client-auth>
    <pinned-ca-certs>deployment-specific-ca-certs</pinned-ca-certs>
    <pinned-client-certs>explicitly-trusted-client-certs</pinned-client-certs>
  </client-auth>

</tls-server>
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="YANG Model" anchor="tls-server-yang-module">
          <t>This YANG module has a normative references to <xref target="RFC6991"/>,
          and <xref target="I-D.ietf-netconf-keystore"/>.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<CODE BEGINS> file "ietf-tls-server@2017-10-19.yang"
module ietf-tls-server {
  yang-version 1.1;

  namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server";
  prefix "tlss";

  import ietf-tls-common {
    prefix tlscmn;
    revision-date 2017-10-19; // stable grouping definitions
    reference
      "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
  }

  import ietf-keystore {
    prefix ks;
    reference
      "RFC YYYY: Keystore Model";
  }

  organization
   "IETF NETCONF (Network Configuration) Working Group";

  contact
   "WG Web:   <http://tools.ietf.org/wg/netconf/>
    WG List:  <mailto:netconf@ietf.org>

    Author:   Kent Watsen
              <mailto:kwatsen@juniper.net>

    Author:   Gary Wu
              <mailto:garywu@cisco.com>";


  description
   "This module defines a reusable grouping for a TLS server that
    can be used as a basis for specific TLS server instances.

    Copyright (c) 2017 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
    (http://trustee.ietf.org/license-info).

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

  revision "2017-10-19" {
    description
     "Initial version";
    reference
     "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
  }

  feature tls-server-hello-params-config {
    description
      "TLS hello message parameters are configurable on a TLS
       server.";
  }

  
  // groupings

  grouping tls-server-grouping {
    description
      "A reusable grouping for configuring a TLS server without
       any consideration for how underlying TCP sessions are
       established.";

    container certificates {
      description
        "The list of certificates the TLS server will present when
         establishing a TLS connection in its Certificate message,
         as defined in Section 7.4.2 in RFC 5246.";
      reference
        "RFC 5246:
           The Transport Layer Security (TLS) Protocol Version 1.2";
      list certificate {
        key name;
        min-elements 1;
        description
          "An unordered list of certificates the TLS server can pick 
           from when sending its Server Certificate message.";
        reference
          "RFC 5246: The TLS Protocol, Section 7.4.2";
        leaf name {
          type leafref {
            path "/ks:keystore/ks:keys/ks:key/ks:certificates/"
                 + "ks:certificate/ks:name";
          }
          description
            "The name of the certificate in the keystore.";
        }
      }
    }

    container client-auth {
      description
        "A reference to a list of pinned certificate authority (CA)
         certificates and a reference to a list of pinned client
         certificates.";
      leaf pinned-ca-certs {
        type leafref {
          path "/ks:keystore/ks:pinned-certificates/ks:name";
        }
        description
          "A reference to a list of certificate authority (CA) 
           certificates used by the TLS server to authenticate
           TLS client certificates.  A client certificate is
           authenticated if it has a valid chain of trust to
           a configured pinned CA certificate.";
      }
      leaf pinned-client-certs {
        type leafref {
          path "/ks:keystore/ks:pinned-certificates/ks:name";
        }
        description
          "A reference to a list of client certificates used by 
           the TLS server to authenticate TLS client certificates.
           A clients certificate is authenticated if it is an
           exact match to a configured pinned client certificate.";
      }
    }

    container hello-params {
      if-feature tls-server-hello-params-config;
      uses tlscmn:hello-params-grouping;
      description
        "Configurable parameters for the TLS hello message.";
    }

  } // end tls-server-grouping

}
<CODE ENDS>
]]></artwork>
            </figure>
          </t>
        </section>
      </section>

      <section title="The TLS Common Model" anchor="tls-common-model">

        <t>The TLS common model presented in this section contains identities
        and groupings common to both TLS clients and TLS servers.  The
        hello-params-grouping can be used to configure the list of TLS
        algorithms permitted by the TLS client or TLS server.  The lists of
        algorithms are ordered such that, if multiple algorithms are permitted
        by the client, the algorithm that appears first in its list that is
        also permitted by the server is used for the TLS transport layer
        connection.  The ability to restrict the the algorithms allowed is
        provided in this grouping for TLS clients and TLS servers that are
        capable of doing so and may serve to make TLS clients and TLS servers
        compliant with security policies.</t>

        <t>Features are defined for algorithms that are OPTIONAL or are not
        widely supported by popular implementations.  Note that the list of
        algorithms is not exhaustive.</t>

        <section title="Tree Diagram">
          <t>The following tree diagram presents the data model for
          the grouping defined in the ietf-tls-common module.  Please
          see <xref target="tree-diagrams"/> for tree diagram notation.</t>
          <t>
            <figure>
              <artwork><![CDATA[
module: ietf-tls-common

  grouping hello-params-grouping
    +---- tls-versions
    |  +---- tls-version*   identityref
    +---- cipher-suites
       +---- cipher-suite*   identityref
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="Example Usage">
          <t>This section shows how it would appear if the
          transport-params-grouping were populated with some data.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<!-- hypothetical example, as groupings don't have instance data -->
<hello-params
   xmlns:tlscmn="urn:ietf:params:xml:ns:yang:ietf-tls-common">
  <tls-versions>
    <tls-version>tlscmn:tls-1.1</tls-version>
    <tls-version>tlscmn:tls-1.2</tls-version>
  </tls-versions>
  <cipher-suites>
    <cipher-suite>tlscmn:dhe-rsa-with-aes-128-cbc-sha</cipher-suite>
    <cipher-suite>tlscmn:rsa-with-aes-128-cbc-sha</cipher-suite>
    <cipher-suite>tlscmn:rsa-with-3des-ede-cbc-sha</cipher-suite>
  </cipher-suites>
</hello-params>
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="YANG Model" anchor="tls-common-yang-module">
          <t>This YANG module has a normative references to
          <xref target="RFC2246"/>,
          <xref target="RFC4346"/>,
          <xref target="RFC4492"/>,
          <xref target="RFC5246"/>,
          <xref target="RFC5288"/>,
          and <xref target="RFC5289"/>.</t>
          <t>
            <figure>
              <artwork><![CDATA[
<CODE BEGINS> file "ietf-tls-common@2017-10-19.yang"
module ietf-tls-common {
  yang-version 1.1;

  namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common";
  prefix "tlscmn";

  organization
   "IETF NETCONF (Network Configuration) Working Group";

  contact
   "WG Web:   <http://tools.ietf.org/wg/netconf/>
    WG List:  <mailto:netconf@ietf.org>

    Author:   Kent Watsen
              <mailto:kwatsen@juniper.net>

    Author:   Gary Wu
              <mailto:garywu@cisco.com>";


  description
   "This module defines a common features, identities, and groupings
    for Transport Layer Security (TLS).

    Copyright (c) 2017 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
    (http://trustee.ietf.org/license-info).

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

  revision "2017-10-19" {
    description
     "Initial version";
    reference
     "RFC XXXX: YANG Groupings for TLS Clients and TLS Servers";
  }

  // features
  feature tls-1_0 {
    description
      "TLS Protocol Version 1.0 is supported.";
    reference
      "RFC 2246: The TLS Protocol Version 1.0";
  }

  feature tls-1_1 {
    description
      "TLS Protocol Version 1.1 is supported.";
    reference
      "RFC 4346: The Transport Layer Security (TLS) Protocol
                 Version 1.1";
  }

  feature tls-1_2 {
    description
      "TLS Protocol Version 1.2 is supported.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  feature tls-ecc {
    description
      "Elliptic Curve Cryptography (ECC) is supported for TLS.";
    reference
      "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
                 for Transport Layer Security (TLS)";
  }

  feature tls-dhe {
    description
      "Ephemeral Diffie-Hellman key exchange is supported for TLS.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  feature tls-3des {
    description
      "The Triple-DES block cipher is supported for TLS.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  feature tls-gcm {
    description
      "The Galois/Counter Mode authenticated encryption mode is
       supported for TLS.";
    reference
      "RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for
                 TLS";
  }

  feature tls-sha2 {
    description
      "The SHA2 family of cryptographic hash functions is supported
       for TLS.";
    reference
      "FIPS PUB 180-4: Secure Hash Standard (SHS)";
  }

  // identities
  identity tls-version-base {
    description
      "Base identity used to identify TLS protocol versions.";
  }

  identity tls-1.0 {
    base tls-version-base;
    if-feature tls-1_0;
    description
      "TLS Protocol Version 1.0.";
    reference
      "RFC 2246: The TLS Protocol Version 1.0";
  }

  identity tls-1.1 {
    base tls-version-base;
    if-feature tls-1_1;
    description
      "TLS Protocol Version 1.1.";
    reference
      "RFC 4346: The Transport Layer Security (TLS) Protocol
                 Version 1.1";
  }

  identity tls-1.2 {
    base tls-version-base;
    if-feature tls-1_2;
    description
      "TLS Protocol Version 1.2.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity cipher-suite-base {
    description
      "Base identity used to identify TLS cipher suites.";
  }

  identity rsa-with-aes-128-cbc-sha {
    base cipher-suite-base;
    description
      "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity rsa-with-aes-256-cbc-sha {
    base cipher-suite-base;
    description
      "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity rsa-with-aes-128-cbc-sha256 {
    base cipher-suite-base;
    if-feature tls-sha2;
    description
      "Cipher suite TLS_RSA_WITH_AES_128_CBC_SHA256.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity rsa-with-aes-256-cbc-sha256 {
    base cipher-suite-base;
    if-feature tls-sha2;
    description
      "Cipher suite TLS_RSA_WITH_AES_256_CBC_SHA256.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity dhe-rsa-with-aes-128-cbc-sha {
    base cipher-suite-base;
    if-feature tls-dhe;
    description
      "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity dhe-rsa-with-aes-256-cbc-sha {
    base cipher-suite-base;
    if-feature tls-dhe;
    description
      "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity dhe-rsa-with-aes-128-cbc-sha256 {
    base cipher-suite-base;
    if-feature "tls-dhe and tls-sha2";
    description
      "Cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity dhe-rsa-with-aes-256-cbc-sha256 {
    base cipher-suite-base;
    if-feature "tls-dhe and tls-sha2";
    description
      "Cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity ecdhe-ecdsa-with-aes-128-cbc-sha256 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-ecdsa-with-aes-256-cbc-sha384 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-rsa-with-aes-128-cbc-sha256 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-rsa-with-aes-256-cbc-sha384 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-ecdsa-with-aes-128-gcm-sha256 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-gcm and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-ecdsa-with-aes-256-gcm-sha384 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-gcm and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-rsa-with-aes-128-gcm-sha256 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-gcm and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity ecdhe-rsa-with-aes-256-gcm-sha384 {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-gcm and tls-sha2";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.";
    reference
      "RFC 5289: TLS Elliptic Curve Cipher Suites with
                 SHA-256/384 and AES Galois Counter Mode (GCM)";
  }

  identity rsa-with-3des-ede-cbc-sha {
    base cipher-suite-base;
    if-feature tls-3des;
    description
      "Cipher suite TLS_RSA_WITH_3DES_EDE_CBC_SHA.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";
  }

  identity ecdhe-rsa-with-3des-ede-cbc-sha {
    base cipher-suite-base;
    if-feature "tls-ecc and tls-3des";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA.";
    reference
      "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
                 for Transport Layer Security (TLS)";
  }

  identity ecdhe-rsa-with-aes-128-cbc-sha {
    base cipher-suite-base;
    if-feature "tls-ecc";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA.";
    reference
      "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
                 for Transport Layer Security (TLS)";
  }

  identity ecdhe-rsa-with-aes-256-cbc-sha {
    base cipher-suite-base;
    if-feature "tls-ecc";
    description
      "Cipher suite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA.";
    reference
      "RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites
                 for Transport Layer Security (TLS)";
  }

  // groupings

  grouping hello-params-grouping {
    description
      "A reusable grouping for TLS hello message parameters.";
    reference
      "RFC 5246: The Transport Layer Security (TLS) Protocol
                 Version 1.2";

    container tls-versions {
      description
        "Parameters regarding TLS versions.";
      leaf-list tls-version {
        type identityref {
          base tls-version-base;
        }
        description
          "Acceptable TLS protocol versions.

           If this leaf-list is not configured (has zero elements)
           the acceptable TLS protocol versions are implementation-
           defined.";
      }
    }
    container cipher-suites {
      description
        "Parameters regarding cipher suites.";
      leaf-list cipher-suite {
        type identityref {
          base cipher-suite-base;
        }
        ordered-by user;
        description
          "Acceptable cipher suites in order of descending
           preference.

           If this leaf-list is not configured (has zero elements)
           the acceptable cipher suites are implementation-
           defined.";
      }
    }

  } // end hello-params-grouping

}
<CODE ENDS>
]]></artwork>
            </figure>
          </t>
        </section>
      </section>

      <section title="Security Considerations">
        <t>The YANG modules defined in this document are designed to be accessed via YANG
        based management protocols, such as NETCONF <xref target="RFC6241"/> and
        RESTCONF <xref target="RFC8040"/>.  Both of these protocols have mandatory-to-implement
        secure transport layers (e.g., SSH, TLS) with mutual authentication.</t>

        <t>The NETCONF access control model (NACM) <xref target="RFC6536"/> provides the means
        to restrict access for particular users to a pre-configured subset of all available
        protocol operations and content.</t>

        <t>Since the modules defined in this document only define groupings, these
        considerations are primarily for the designers of other modules that use
        these groupings.</t>

        <t>There are a number of data nodes defined in the YANG modules that are
        writable/creatable/deletable (i.e., config true, which is the default). These data
        nodes may be considered sensitive or vulnerable in some network environments. Write
        operations (e.g., edit-config) to these data nodes without proper protection can
        have a negative effect on network operations. These are the subtrees and data nodes
        and their sensitivity/vulnerability:
          <list style="hanging" hangIndent="6">
            <t hangText="   /:">The entire data tree of all the groupings defined in
              this draft is sensitive to write operations.  For instance, the addition or
              removal of references to keys, certificates, trusted anchors, etc., can 
              dramatically alter the implemented security policy.  However, no NACM 
              annotations are applied as the data SHOULD be editable by users other than 
              a designated 'recovery session'.</t>
          </list>
        </t>

        <t>Some of the readable data nodes in the YANG modules may be considered sensitive
        or vulnerable in some network environments. It is thus important to control read
        access (e.g., via get, get-config, or notification) to these data nodes. These are
        the subtrees and data nodes and their sensitivity/vulnerability:
          <list style="hanging" hangIndent="6">
            <t hangText="   NONE"></t>
          </list>
        </t>

        <t>Some of the RPC operations in this YANG module may be considered sensitive or
        vulnerable in some network environments. It is thus important to control access
        to these operations. These are the operations and their sensitivity/vulnerability:
          <list style="hanging" hangIndent="6">
            <t hangText="   NONE"></t>
          </list>
        </t>
      </section>

      <section title="IANA Considerations">
        <section title="The IETF XML Registry">
          <t>This document registers three URIs in the IETF XML 
          registry <xref target="RFC3688"/>.  Following the format in 
          <xref target="RFC3688"/>, the following registrations are
          requested:</t>
          <t>
            <figure>
                <artwork><![CDATA[
   URI: urn:ietf:params:xml:ns:yang:ietf-tls-client
   Registrant Contact: The NETCONF WG of the IETF.
   XML: N/A, the requested URI is an XML namespace.

   URI: urn:ietf:params:xml:ns:yang:ietf-tls-server
   Registrant Contact: The NETCONF WG of the IETF.
   XML: N/A, the requested URI is an XML namespace.

   URI: urn:ietf:params:xml:ns:yang:ietf-tls-common
   Registrant Contact: The NETCONF WG of the IETF.
   XML: N/A, the requested URI is an XML namespace.
]]></artwork>
            </figure>
          </t>
        </section>

        <section title="The YANG Module Names Registry">
          <t>This document registers three YANG modules in the
          YANG Module Names registry <xref target="RFC7950"/>.
          Following the format in <xref target="RFC7950"/>, the
          the following registrations are requested:</t>
          <t>
            <figure>
                <artwork><![CDATA[
   name:         ietf-tls-client
   namespace:    urn:ietf:params:xml:ns:yang:ietf-tls-client
   prefix:       tlsc
   reference:    RFC XXXX

   name:         ietf-tls-server
   namespace:    urn:ietf:params:xml:ns:yang:ietf-tls-server
   prefix:       tlss
   reference:    RFC XXXX

   name:         ietf-tls-common
   namespace:    urn:ietf:params:xml:ns:yang:ietf-tls-common
   prefix:       tlscmn
   reference:    RFC XXXX
]]></artwork>
            </figure>
          </t>
        </section>
      </section>

      <section title="Acknowledgements">
        <t>The authors would like to thank for following for
        lively discussions on list and in the halls (ordered
        by last name): Andy Bierman, Martin Bjorklund, Benoit Claise,
        Mehmet Ersue, Balázs Kovács, David Lamparter, Alan Luchuk, Ladislav Lhotka,
        Radek Krejci, Tom Petch, Juergen Schoenwaelder, Phil Shafer,
        Sean Turner, and Bert Wijnen.</t>
     </section>

    </middle>

    <back>
      <references title="Normative References">
        <?rfc include="reference.RFC.2119.xml"?>
        <?rfc include="reference.RFC.2246.xml"?>
        <?rfc include="reference.RFC.4346.xml"?>
        <?rfc include="reference.RFC.4492.xml"?>
        <?rfc include="reference.RFC.5246.xml"?>
        <?rfc include="reference.RFC.5288.xml"?>
        <?rfc include="reference.RFC.5289.xml"?>
        <?rfc include="reference.RFC.6536.xml"?>
        <?rfc include="reference.RFC.6991.xml"?>
        <?rfc include="reference.RFC.7589.xml"?>
        <?rfc include="reference.RFC.7950.xml"?>
        <?rfc include="reference.RFC.8174.xml"?>
        <?rfc include="reference.I-D.ietf-netconf-keystore"?>
      </references>

      <references title="Informative References">
        <?rfc include="reference.RFC.2818.xml"?>
        <?rfc include="reference.RFC.3688.xml"?>
        <?rfc include="reference.RFC.6241.xml"?>
        <?rfc include="reference.RFC.8040.xml"?>
        <?rfc include="reference.RFC.8071.xml"?>
      </references>

      <section title="Change Log">
        <section title="server-model-09 to 00">
          <t>
            <list style="symbols">
              <t>This draft was split out from draft-ietf-netconf-server-model-09.</t>
              <t>Noted that '0.0.0.0' and '::' might have special meanings.</t>
            </list>
          </t>
        </section>
        <section title="00 to 01">
          <t>
            <list style="symbols">
              <t>Renamed "keychain" to "keystore".</t>
            </list>
          </t>
        </section>
        <section title="01 to 02">
          <t>
            <list style="symbols">
              <t>Removed the groupings containing transport-level configuration.
              Now modules contain only the transport-independent groupings.</t>
              <t>Filled in previously incomplete 'ietf-tls-client' module.</t>
              <t>Added cipher suites for various algorithms into new 
              'ietf-tls-common' module.</t>
            </list>
          </t>
        </section>
        <section title="02 to 03">
          <t>
            <list style="symbols">
              <t>Added a 'must' statement to container 'server-auth' asserting
                 that at least one of the various auth mechanisms must be specified.</t>
              <t>Fixed description statement for leaf 'trusted-ca-certs'.</t>
            </list>
          </t>
        </section>
        <section title="03 to 04">
          <t>
            <list style="symbols">
              <t>Updated title to "YANG Groupings for TLS Clients and TLS Servers"</t>
              <t>Updated leafref paths to point to new keystore path</t>
              <t>Changed the YANG prefix for ietf-tls-common from 'tlscom' to 'tlscmn'.</t>
              <t>Added TLS protocol verions 1.0 and 1.1.</t>
              <t>Made author lists consistent</t>
            </list>
          </t>
        </section>
      </section>
    </back>
</rfc>

