transport/transport-tls/src/main/yang/ietf-tls-server@2023-12-28.yang

   1 module ietf-tls-server {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-tls-server";
   4   prefix tlss;
   5
   6   import ietf-netconf-acm {
   7     prefix nacm;
   8     reference
   9       "RFC 8341: Network Configuration Access Control Model";
  10   }
  11
  12   import ietf-crypto-types {
  13     prefix ct;
  14     reference
  15       "RFC AAAA: YANG Data Types and Groupings for Cryptography";
  16   }
  17
  18   import ietf-truststore {
  19     prefix ts;
  20     reference
  21       "RFC BBBB: A YANG Data Model for a Truststore";
  22   }
  23
  24   import ietf-keystore {
  25     prefix ks;
  26     reference
  27       "RFC CCCC: A YANG Data Model for a Keystore";
  28   }
  29
  30   import ietf-tls-common {
  31     prefix tlscmn;
  32     reference
  33       "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
  34   }
  35
  36   organization
  37     "IETF NETCONF (Network Configuration) Working Group";
  38
  39   contact
  40     "WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  41      WG Web:   https://datatracker.ietf.org/wg/netconf
  42      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>
  43      Author:   Jeff Hartley <mailto:jeff.hartley@commscope.com>";
  44
  45   description
  46     "This module defines reusable groupings for TLS servers that
  47      can be used as a basis for specific TLS server instances.
  48
  49      Copyright (c) 2023 IETF Trust and the persons identified
  50      as authors of the code. All rights reserved.
  51
  52      Redistribution and use in source and binary forms, with
  53      or without modification, is permitted pursuant to, and
  54      subject to the license terms contained in, the Revised
  55      BSD License set forth in Section 4.c of the IETF Trust's
  56      Legal Provisions Relating to IETF Documents
  57      (https://trustee.ietf.org/license-info).
  58
  59      This version of this YANG module is part of RFC FFFF
  60      (https://www.rfc-editor.org/info/rfcFFFF); see the RFC
  61      itself for full legal notices.
  62
  63      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  64      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  65      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  66      are to be interpreted as described in BCP 14 (RFC 2119)
  67      (RFC 8174) when, and only when, they appear in all
  68      capitals, as shown here.";
  69
  70   revision 2023-12-28 {
  71     description
  72       "Initial version";
  73     reference
  74       "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
  75   }
  76
  77   // Features
  78
  79   feature tls-server-keepalives {
  80     description
  81       "Per socket TLS keepalive parameters are configurable for
  82        TLS servers on the server implementing this feature.";
  83   }
  84
  85   feature server-ident-x509-cert {
  86     description
  87       "Indicates that the server supports identifying itself
  88        using X.509 certificates.";
  89     reference
  90       "RFC 5280:
  91          Internet X.509 Public Key Infrastructure Certificate
  92          and Certificate Revocation List (CRL) Profile";
  93   }
  94
  95   feature server-ident-raw-public-key {
  96     description
  97       "Indicates that the server supports identifying itself
  98        using raw public keys.";
  99     reference
 100       "RFC 7250:
 101          Using Raw Public Keys in Transport Layer Security (TLS)
 102          and Datagram Transport Layer Security (DTLS)";
 103   }
 104
 105   feature server-ident-tls12-psk {
 106     if-feature "tlscmn:tls12";
 107     description
 108       "Indicates that the server supports identifying itself
 109        using TLS-1.2 PSKs (pre-shared or pairwise-symmetric keys).";
 110     reference
 111       "RFC 4279:
 112          Pre-Shared Key Ciphersuites for Transport Layer Security
 113          (TLS)";
 114   }
 115
 116   feature server-ident-tls13-epsk {
 117     if-feature "tlscmn:tls13";
 118     description
 119       "Indicates that the server supports identifying itself
 120        using TLS-1.3 External PSKs (pre-shared keys).";
 121     reference
 122       "RFC 8446:
 123          The Transport Layer Security (TLS) Protocol Version 1.3";
 124   }
 125
 126   feature client-auth-supported {
 127     description
 128       "Indicates that the configuration for how to authenticate
 129        clients can be configured herein.  TLS-level client
 130        authentication may not be needed when client authentication
 131        is expected to occur only at another protocol layer.";
 132   }
 133
 134   feature client-auth-x509-cert {
 135     description
 136       "Indicates that the server supports authenticating clients
 137        using X.509 certificates.";
 138     reference
 139       "RFC 5280:
 140          Internet X.509 Public Key Infrastructure Certificate
 141          and Certificate Revocation List (CRL) Profile";
 142   }
 143
 144   feature client-auth-raw-public-key {
 145     description
 146       "Indicates that the server supports authenticating clients
 147        using raw public keys.";
 148     reference
 149       "RFC 7250:
 150          Using Raw Public Keys in Transport Layer Security (TLS)
 151          and Datagram Transport Layer Security (DTLS)";
 152   }
 153
 154   feature client-auth-tls12-psk {
 155     description
 156       "Indicates that the server supports authenticating clients
 157        using PSKs (pre-shared or pairwise-symmetric keys).";
 158     reference
 159       "RFC 4279:
 160          Pre-Shared Key Ciphersuites for Transport Layer Security
 161          (TLS)";
 162   }
 163
 164   feature client-auth-tls13-epsk {
 165     description
 166       "Indicates that the server supports authenticating clients
 167        using TLS-1.3 External PSKs (pre-shared keys).";
 168     reference
 169       "RFC 8446:
 170          The Transport Layer Security (TLS) Protocol Version 1.3";
 171   }
 172
 173   // Groupings
 174
 175   grouping tls-server-grouping {
 176     description
 177       "A reusable grouping for configuring a TLS server without
 178        any consideration for how underlying TCP sessions are
 179        established.
 180
 181        Note that this grouping uses fairly typical descendant
 182        node names such that a stack of 'uses' statements will
 183        have name conflicts.  It is intended that the consuming
 184        data model will resolve the issue (e.g., by wrapping
 185        the 'uses' statement in a container called
 186        'tls-server-parameters').  This model purposely does
 187        not do this itself so as to provide maximum flexibility
 188        to consuming models.";
 189
 190     container server-identity {
 191       nacm:default-deny-write;
 192       description
 193         "A locally-defined or referenced end-entity certificate,
 194          including any configured intermediate certificates, the
 195          TLS server will present when establishing a TLS connection
 196          in its Certificate message, as defined in Section 7.4.2
 197          in RFC 5246 and Section 4.4.2 in RFC 8446.";
 198       reference
 199         "RFC 5246: The Transport Layer Security (TLS) Protocol
 200                    Version 1.2
 201          RFC 8446: The Transport Layer Security (TLS) Protocol
 202                    Version 1.3
 203          RFC CCCC: A YANG Data Model for a Keystore";
 204       choice auth-type {
 205         mandatory true;
 206         description
 207           "A choice amongst authentication types, of which one must
 208            be enabled (via its associated 'feature') and selected.";
 209         case certificate {
 210           if-feature "server-ident-x509-cert";
 211           container certificate {
 212             description
 213               "Specifies the server identity using a certificate.";
 214             uses
 215               "ks:inline-or-keystore-end-entity-cert-with-key-"
 216               + "grouping" {
 217               refine "inline-or-keystore/inline/inline-definition" {
 218                 must 'not(public-key-format) or derived-from-or-self'
 219                    + '(public-key-format,' + ' "ct:subject-public-'
 220                    + 'key-info-format")';
 221               }
 222               refine "inline-or-keystore/central-keystore/"
 223                    + "central-keystore-reference/asymmetric-key" {
 224                 must 'not(deref(.)/../ks:public-key-format) or '
 225                    + 'derived-from-or-self(deref(.)/../ks:public-key'
 226                    + '-format, "ct:subject-public-key-info-format")';
 227               }
 228             }
 229           }
 230         }
 231         case raw-private-key {
 232           if-feature "server-ident-raw-public-key";
 233           container raw-private-key {
 234             description
 235               "Specifies the server identity using a raw
 236                private key.";
 237             uses ks:inline-or-keystore-asymmetric-key-grouping {
 238               refine "inline-or-keystore/inline/inline-definition" {
 239                 must 'not(public-key-format) or derived-from-or-self'
 240                    + '(public-key-format,' + ' "ct:subject-public-'
 241                    + 'key-info-format")';
 242               }
 243               refine "inline-or-keystore/central-keystore/"
 244                    + "central-keystore-reference" {
 245                 must 'not(deref(.)/../ks:public-key-format) or '
 246                    + 'derived-from-or-self(deref(.)/../ks:public-key'
 247                    + '-format, "ct:subject-public-key-info-format")';
 248               }
 249             }
 250           }
 251         }
 252         case tls12-psk {
 253           if-feature "server-ident-tls12-psk";
 254           container tls12-psk {
 255             description
 256               "Specifies the server identity using a PSK (pre-shared
 257                or pairwise-symmetric key).";
 258             uses ks:inline-or-keystore-symmetric-key-grouping;
 259             leaf id-hint {
 260               type string;
 261               description
 262                 "The key 'psk_identity_hint' value used in the TLS
 263                  'ServerKeyExchange' message.";
 264               reference
 265                 "RFC 4279: Pre-Shared Key Ciphersuites for
 266                            Transport Layer Security (TLS)";
 267             }
 268           }
 269         }
 270         case tls13-epsk {
 271           if-feature "server-ident-tls13-epsk";
 272           container tls13-epsk {
 273             description
 274               "An External Pre-Shared Key (EPSK) is established
 275               or provisioned out-of-band, i.e., not from a TLS
 276               connection.  An EPSK is a tuple of (Base Key,
 277               External Identity, Hash).  External PSKs MUST
 278               NOT be imported for (D)TLS 1.2 or prior versions.
 279               When PSKs are provisioned out of band, the PSK
 280               identity and the KDF hash algorithm to be used
 281               with the PSK MUST also be provisioned.
 282
 283               The structure of this container is designed to
 284               satisfy the requirements of RFC 8446 Section
 285               4.2.11, the recommendations from Section 6 in
 286               RFC 9257, and the EPSK input fields detailed in
 287               Section 5.1 in RFC 9258.  The base-key is based
 288               upon ks:inline-or-keystore-symmetric-key-grouping
 289               in order to provide users with flexible and
 290               secure storage options.";
 291             reference
 292               "RFC 8446: The Transport Layer Security (TLS)
 293                          Protocol Version 1.3
 294                RFC 9257: Guidance for External Pre-Shared Key
 295                          (PSK) Usage in TLS
 296                RFC 9258: Importing External Pre-Shared Keys
 297                          (PSKs) for TLS 1.3";
 298             uses ks:inline-or-keystore-symmetric-key-grouping;
 299             leaf external-identity {
 300               type string;
 301               mandatory true;
 302               description
 303                 "As per Section 4.2.11 of RFC 8446, and Section 4.1
 304                  of RFC 9257, a sequence of bytes used to identify
 305                  an EPSK. A label for a pre-shared key established
 306                  externally.";
 307               reference
 308                 "RFC 8446: The Transport Layer Security (TLS)
 309                            Protocol Version 1.3
 310                  RFC 9257: Guidance for External Pre-Shared Key
 311                            (PSK) Usage in TLS";
 312             }
 313             leaf hash {
 314               type tlscmn:epsk-supported-hash;
 315               default sha-256;
 316               description
 317                 "As per Section 4.2.11 of RFC 8446, for externally
 318                  established PSKs, the Hash algorithm MUST be set
 319                  when the PSK is established or default to SHA-256
 320                  if no such algorithm is defined.  The server MUST
 321                  ensure that it selects a compatible PSK (if any)
 322                  and cipher suite.  Each PSK MUST only be used
 323                  with a single hash function.";
 324               reference
 325                 "RFC 8446: The Transport Layer Security (TLS)
 326                            Protocol Version 1.3";
 327             }
 328             leaf context {
 329               type string;
 330               description
 331                 "Per Section 5.1 of RFC 9258, context MUST include
 332                  the context used to determine the EPSK, if
 333                  any exists. For example, context may include
 334                  information about peer roles or identities
 335                  to mitigate Selfie-style reflection attacks.
 336                  Since the EPSK is a key derived from an external
 337                  protocol or sequence of protocols, context MUST
 338                  include a channel binding for the deriving
 339                  protocols [RFC5056].  The details of this
 340                  binding are protocol specfic and out of scope
 341                  for this document.";
 342               reference
 343                 "RFC 9258: Importing External Pre-Shared Keys
 344                            (PSKs) for TLS 1.3";
 345             }
 346             leaf target-protocol {
 347               type uint16;
 348               description
 349                 "As per Section 3.1 of RFC 9258, the protocol
 350                  for which a PSK is imported for use.";
 351               reference
 352                 "RFC 9258: Importing External Pre-Shared Keys
 353                            (PSKs) for TLS 1.3";
 354             }
 355             leaf target-kdf {
 356               type uint16;
 357               description
 358                 "As per Section 3 of RFC 9258, the KDF for
 359                  which a PSK is imported for use.";
 360               reference
 361                 "RFC 9258: Importing External Pre-Shared Keys
 362                            (PSKs) for TLS 1.3";
 363             }
 364           }
 365         }
 366       }
 367     } // container server-identity
 368
 369     container client-authentication {
 370       if-feature "client-auth-supported";
 371       nacm:default-deny-write;
 372       must 'ca-certs or ee-certs or raw-public-keys or tls12-psks
 373         or tls13-epsks';
 374       presence
 375         "Indicates that client authentication is supported (i.e.,
 376          that the server will request clients send certificates).
 377          If not configured, the TLS server SHOULD NOT request the
 378          TLS clients provide authentication credentials.";
 379       description
 380         "Specifies how the TLS server can authenticate TLS clients.
 381          Any combination of credentials is additive and unordered.
 382
 383          Note that no configuration is required for PSK (pre-shared
 384          or pairwise-symmetric key) based authentication as the key
 385          is necessarily the same as configured in the '../server-
 386          identity' node.";
 387       container ca-certs {
 388         if-feature "client-auth-x509-cert";
 389         presence
 390           "Indicates that CA certificates have been configured.
 391            This statement is present so the mandatory descendant
 392            nodes do not imply that this node must be configured.";
 393         description
 394           "A set of certificate authority (CA) certificates used by
 395            the TLS server to authenticate TLS client certificates.
 396            A client certificate is authenticated if it has a valid
 397            chain of trust to a configured CA certificate.";
 398         reference
 399           "RFC BBBB: A YANG Data Model for a Truststore";
 400         uses ts:inline-or-truststore-certs-grouping;
 401       }
 402       container ee-certs {
 403         if-feature "client-auth-x509-cert";
 404         presence
 405           "Indicates that EE certificates have been configured.
 406            This statement is present so the mandatory descendant
 407            nodes do not imply that this node must be configured.";
 408         description
 409           "A set of client certificates (i.e., end entity
 410            certificates) used by the TLS server to authenticate
 411            certificates presented by TLS clients. A client
 412            certificate is authenticated if it is an exact
 413            match to a configured client certificate.";
 414         reference
 415           "RFC BBBB: A YANG Data Model for a Truststore";
 416         uses ts:inline-or-truststore-certs-grouping;
 417       }
 418       container raw-public-keys {
 419         if-feature "client-auth-raw-public-key";
 420         presence
 421           "Indicates that raw public keys have been configured.
 422            This statement is present so the mandatory descendant
 423            nodes do not imply that this node must be configured.";
 424         description
 425           "A set of raw public keys used by the TLS server to
 426            authenticate raw public keys presented by the TLS
 427            client.  A raw public key is authenticated if it
 428            is an exact match to a configured raw public key.";
 429         reference
 430           "RFC BBBB: A YANG Data Model for a Truststore";
 431         uses ts:inline-or-truststore-public-keys-grouping {
 432           refine "inline-or-truststore/inline/inline-definition/"
 433                + "public-key" {
 434             must 'derived-from-or-self(public-key-format,'
 435                + ' "ct:subject-public-key-info-format")';
 436           }
 437           refine "inline-or-truststore/central-truststore/"
 438                + "central-truststore-reference" {
 439             must 'not(deref(.)/../ts:public-key/ts:public-key-'
 440                + 'format[not(derived-from-or-self(., "ct:subject-'
 441                + 'public-key-info-format"))])';
 442           }
 443         }
 444       }
 445       leaf tls12-psks {
 446         if-feature "client-auth-tls12-psk";
 447         type empty;
 448         description
 449           "Indicates that the TLS server can authenticate TLS clients
 450            using configured PSKs (pre-shared or pairwise-symmetric
 451            keys).
 452
 453            No configuration is required since the PSK value is the
 454            same as PSK value configured in the 'server-identity'
 455            node.";
 456       }
 457       leaf tls13-epsks {
 458         if-feature "client-auth-tls13-epsk";
 459         type empty;
 460         description
 461           "Indicates that the TLS 1.3 server can authenticate TLS
 462            clients using configured external PSKs (pre-shared keys).
 463
 464            No configuration is required since the PSK value is the
 465            same as PSK value configured in the 'server-identity'
 466            node.";
 467       }
 468     } // container client-authentication
 469
 470     container hello-params {
 471       nacm:default-deny-write;
 472       if-feature "tlscmn:hello-params";
 473       uses tlscmn:hello-params-grouping;
 474       description
 475         "Configurable parameters for the TLS hello message.";
 476     } // container hello-params
 477
 478     container keepalives {
 479       nacm:default-deny-write;
 480       if-feature "tls-server-keepalives";
 481       description
 482         "Configures the keepalive policy for the TLS server.";
 483       leaf peer-allowed-to-send {
 484         type empty;
 485         description
 486           "Indicates that the remote TLS client is allowed to send
 487            HeartbeatRequest messages, as defined by RFC 6520
 488            to this TLS server.";
 489         reference
 490           "RFC 6520: Transport Layer Security (TLS) and Datagram
 491            Transport Layer Security (DTLS) Heartbeat Extension";
 492       }
 493       container test-peer-aliveness {
 494         presence
 495           "Indicates that the TLS server proactively tests the
 496            aliveness of the remote TLS client.";
 497         description
 498           "Configures the keep-alive policy to proactively test
 499            the aliveness of the TLS client.  An unresponsive
 500            TLS client is dropped after approximately max-wait
 501            * max-attempts seconds.";
 502         leaf max-wait {
 503           type uint16 {
 504             range "1..max";
 505           }
 506           units "seconds";
 507           default "30";
 508           description
 509             "Sets the amount of time in seconds after which if
 510              no data has been received from the TLS client, a
 511              TLS-level message will be sent to test the
 512              aliveness of the TLS client.";
 513         }
 514         leaf max-attempts {
 515           type uint8;
 516           default "3";
 517           description
 518             "Sets the maximum number of sequential keep-alive
 519              messages that can fail to obtain a response from
 520              the TLS client before assuming the TLS client is
 521              no longer alive.";
 522         }
 523       }
 524     } // container keepalives
 525   } // grouping tls-server-grouping
 526
 527 }