transport/transport-tls/src/main/yang/ietf-tls-server@2023-04-17.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-04-17 {
  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     description
 107       "Indicates that the server supports identifying itself
 108        using TLS-1.2 PSKs (pre-shared or pairwise-symmetric keys).";
 109     reference
 110       "RFC 4279:
 111          Pre-Shared Key Ciphersuites for Transport Layer Security
 112          (TLS)";
 113   }
 114
 115   feature server-ident-tls13-epsk {
 116     description
 117       "Indicates that the server supports identifying itself
 118        using TLS-1.3 External PSKs (pre-shared keys).";
 119     reference
 120       "RFC 8446:
 121          The Transport Layer Security (TLS) Protocol Version 1.3";
 122   }
 123
 124   feature client-auth-supported {
 125     description
 126       "Indicates that the configuration for how to authenticate
 127        clients can be configured herein.  TLS-level client
 128        authentication may not be needed when client authentication
 129        is expected to occur only at another protocol layer.";
 130   }
 131
 132   feature client-auth-x509-cert {
 133     description
 134       "Indicates that the server supports authenticating clients
 135        using X.509 certificates.";
 136     reference
 137       "RFC 5280:
 138          Internet X.509 Public Key Infrastructure Certificate
 139          and Certificate Revocation List (CRL) Profile";
 140   }
 141
 142   feature client-auth-raw-public-key {
 143     description
 144       "Indicates that the server supports authenticating clients
 145        using raw public keys.";
 146     reference
 147       "RFC 7250:
 148          Using Raw Public Keys in Transport Layer Security (TLS)
 149          and Datagram Transport Layer Security (DTLS)";
 150   }
 151
 152   feature client-auth-tls12-psk {
 153     description
 154       "Indicates that the server supports authenticating clients
 155        using PSKs (pre-shared or pairwise-symmetric keys).";
 156     reference
 157       "RFC 4279:
 158          Pre-Shared Key Ciphersuites for Transport Layer Security
 159          (TLS)";
 160   }
 161
 162   feature client-auth-tls13-epsk {
 163     description
 164       "Indicates that the server supports authenticating clients
 165        using TLS-1.3 External PSKs (pre-shared keys).";
 166     reference
 167       "RFC 8446:
 168          The Transport Layer Security (TLS) Protocol Version 1.3";
 169   }
 170
 171   // Groupings
 172
 173   grouping tls-server-grouping {
 174     description
 175       "A reusable grouping for configuring a TLS server without
 176        any consideration for how underlying TCP sessions are
 177        established.
 178
 179        Note that this grouping uses fairly typical descendant
 180        node names such that a stack of 'uses' statements will
 181        have name conflicts.  It is intended that the consuming
 182        data model will resolve the issue (e.g., by wrapping
 183        the 'uses' statement in a container called
 184        'tls-server-parameters').  This model purposely does
 185        not do this itself so as to provide maximum flexibility
 186        to consuming models.";
 187
 188     container server-identity {
 189       nacm:default-deny-write;
 190       description
 191         "A locally-defined or referenced end-entity certificate,
 192          including any configured intermediate certificates, the
 193          TLS server will present when establishing a TLS connection
 194          in its Certificate message, as defined in Section 7.4.2
 195          in RFC 5246 and Section 4.4.2 in RFC 8446.";
 196       reference
 197         "RFC 5246: The Transport Layer Security (TLS) Protocol
 198                    Version 1.2
 199          RFC 8446: The Transport Layer Security (TLS) Protocol
 200                    Version 1.3
 201          RFC CCCC: A YANG Data Model for a Keystore";
 202       choice auth-type {
 203         mandatory true;
 204         description
 205           "A choice amongst authentication types, of which one must
 206            be enabled (via its associated 'feature') and selected.";
 207         case certificate {
 208           if-feature "server-ident-x509-cert";
 209           container certificate {
 210             description
 211               "Specifies the server identity using a certificate.";
 212             uses
 213               "ks:inline-or-keystore-end-entity-cert-with-key-"
 214               + "grouping" {
 215               refine "inline-or-keystore/inline/inline-definition" {
 216                 must 'derived-from-or-self(public-key-format,'
 217                    + ' "ct:subject-public-key-info-format")';
 218               }
 219               refine "inline-or-keystore/keystore/keystore-reference"
 220                    + "/asymmetric-key" {
 221                 must 'derived-from-or-self(deref(.)/../ks:public-'
 222                    + 'key-format, "ct:subject-public-key-info-'
 223                    + 'format")';
 224               }
 225             }
 226           }
 227         }
 228         case raw-private-key {
 229           if-feature "server-ident-raw-public-key";
 230           container raw-private-key {
 231             description
 232               "Specifies the server identity using a raw
 233                private key.";
 234             uses ks:inline-or-keystore-asymmetric-key-grouping {
 235               refine "inline-or-keystore/inline/inline-definition" {
 236                 must 'derived-from-or-self(public-key-format,'
 237                    + ' "ct:subject-public-key-info-format")';
 238               }
 239               refine
 240                 "inline-or-keystore/keystore/keystore-reference" {
 241                 must 'derived-from-or-self(deref(.)/../ks:public-'
 242                    + 'key-format, "ct:subject-public-key-info-'
 243                    + 'format")';
 244               }
 245             }
 246           }
 247         }
 248         case tls12-psk {
 249           if-feature "server-ident-tls12-psk";
 250           container tls12-psk {
 251             description
 252               "Specifies the server identity using a PSK (pre-shared
 253                or pairwise-symmetric key).";
 254             uses ks:inline-or-keystore-symmetric-key-grouping;
 255             leaf id_hint {
 256               type string;
 257               description
 258                 "The key 'psk_identity_hint' value used in the TLS
 259                  'ServerKeyExchange' message.";
 260               reference
 261                 "RFC 4279: Pre-Shared Key Ciphersuites for
 262                            Transport Layer Security (TLS)";
 263             }
 264           }
 265         }
 266         case tls13-epsk {
 267           if-feature "server-ident-tls13-epsk";
 268           container tls13-epsk {
 269             description
 270               "An External Pre-Shared Key (EPSK) is established
 271               or provisioned out-of-band, i.e., not from a TLS
 272               connection.  An EPSK is a tuple of (Base Key,
 273               External Identity, Hash).  External PSKs MUST
 274               NOT be imported for (D)TLS 1.2 or prior versions.
 275               When PSKs are provisioned out of band, the PSK
 276               identity and the KDF hash algorithm to be used
 277               with the PSK MUST also be provisioned.
 278
 279               The structure of this container is designed
 280               to satisfy the requirements of RFC 8446
 281               Section 4.2.11, the recommendations from
 282               I-D ietf-tls-external-psk-guidance Section 6,
 283               and the EPSK input fields detailed in
 284               I-D draft-ietf-tls-external-psk-importer
 285               Section 3.1.  The base-key is based upon
 286               ks:inline-or-keystore-symmetric-key-grouping
 287               in order to provide users with flexible and
 288               secure storage options.";
 289             reference
 290               "RFC 8446: The Transport Layer Security (TLS)
 291                          Protocol Version 1.3
 292                I-D.ietf-tls-external-psk-importer: Importing
 293                          External PSKs for TLS
 294                I-D.ietf-tls-external-psk-guidance: Guidance
 295                          for External PSK Usage in TLS";
 296             uses ks:inline-or-keystore-symmetric-key-grouping;
 297             leaf external-identity {
 298               type string;
 299               mandatory true;
 300               description
 301                 "As per Section 4.2.11 of RFC 8446, and Section 4.1
 302                  of I-D. ietf-tls-external-psk-guidance: A sequence
 303                  of bytes used to identify an EPSK. A label for a
 304                  pre-shared key established externally.";
 305               reference
 306                 "RFC 8446: The Transport Layer Security (TLS)
 307                            Protocol Version 1.3
 308                  I-D.ietf-tls-external-psk-guidance:
 309                            Guidance for External PSK Usage in TLS";
 310             }
 311             leaf hash {
 312               type tlscmn:epsk-supported-hash;
 313               mandatory true;
 314               description
 315                 "As per Section 4.2.11 of RFC 8446, for externally
 316                  established PSKs, the Hash algorithm MUST be set
 317                  when the PSK is established or default to SHA-256
 318                  if no such algorithm is defined.  The server MUST
 319                  ensure that it selects a compatible PSK (if any)
 320                  and cipher suite.  Each PSK MUST only be used
 321                  with a single hash function.";
 322               reference
 323                 "RFC 8446: The Transport Layer Security (TLS)
 324                            Protocol Version 1.3";
 325             }
 326             leaf context {
 327               type string;
 328               description
 329                 "As per Section 4.1 of I-D.
 330                  ietf-tls-external-psk-guidance: Context
 331                  may include information about peer roles or
 332                  identities to mitigate Selfie-style reflection
 333                  attacks [Selfie].  If the EPSK is a key derived
 334                  from some other protocol or sequence of protocols,
 335                  context MUST include a channel binding for the
 336                  deriving protocols [RFC5056].  The details of
 337                  this binding are protocol specific.";
 338               reference
 339                 "I-D.ietf-tls-external-psk-importer:
 340                            Importing External PSKs for TLS
 341                  I-D.ietf-tls-external-psk-guidance:
 342                            Guidance for External PSK Usage in TLS";
 343             }
 344             leaf target-protocol {
 345               type uint16;
 346               description
 347                 "As per Section 3.1 of I-D.
 348                  ietf-tls-external-psk-guidance: The protocol
 349                  for which a PSK is imported for use.";
 350               reference
 351                 "I-D.ietf-tls-external-psk-importer:
 352                            Importing External PSKs for TLS";
 353             }
 354             leaf target-kdf {
 355               type uint16;
 356               description
 357                 "As per Section 3.1 of I-D.
 358                  ietf-tls-external-psk-guidance: The specific Key
 359                  Derivation Function (KDF) for which a PSK is
 360                  imported for use.";
 361               reference
 362                 "I-D.ietf-tls-external-psk-importer:
 363                            Importing External PSKs for TLS";
 364             }
 365           }
 366         }
 367       }
 368     } // container server-identity
 369
 370     container client-authentication {
 371       if-feature "client-auth-supported";
 372       nacm:default-deny-write;
 373       must 'ca-certs or ee-certs or raw-public-keys or tls12-psks
 374         or tls13-epsks';
 375       presence
 376         "Indicates that client authentication is supported (i.e.,
 377          that the server will request clients send certificates).
 378          If not configured, the TLS server SHOULD NOT request the
 379          TLS clients provide authentication credentials.";
 380       description
 381         "Specifies how the TLS server can authenticate TLS clients.
 382          Any combination of credentials is additive and unordered.
 383
 384          Note that no configuration is required for PSK (pre-shared
 385          or pairwise-symmetric key) based authentication as the key
 386          is necessarily the same as configured in the '../server-
 387          identity' node.";
 388       container ca-certs {
 389         if-feature "client-auth-x509-cert";
 390         presence
 391           "Indicates that CA certificates have been configured.
 392            This statement is present so the mandatory descendant
 393            nodes do not imply that this node must be configured.";
 394         description
 395           "A set of certificate authority (CA) certificates used by
 396            the TLS server to authenticate TLS client certificates.
 397            A client certificate is authenticated if it has a valid
 398            chain of trust to a configured CA certificate.";
 399         reference
 400           "RFC BBBB: A YANG Data Model for a Truststore";
 401         uses ts:inline-or-truststore-certs-grouping;
 402       }
 403       container ee-certs {
 404         if-feature "client-auth-x509-cert";
 405         presence
 406           "Indicates that EE certificates have been configured.
 407            This statement is present so the mandatory descendant
 408            nodes do not imply that this node must be configured.";
 409         description
 410           "A set of client certificates (i.e., end entity
 411            certificates) used by the TLS server to authenticate
 412            certificates presented by TLS clients. A client
 413            certificate is authenticated if it is an exact
 414            match to a configured client certificate.";
 415         reference
 416           "RFC BBBB: A YANG Data Model for a Truststore";
 417         uses ts:inline-or-truststore-certs-grouping;
 418       }
 419       container raw-public-keys {
 420         if-feature "client-auth-raw-public-key";
 421         presence
 422           "Indicates that raw public keys have been configured.
 423            This statement is present so the mandatory descendant
 424            nodes do not imply that this node must be configured.";
 425         description
 426           "A set of raw public keys used by the TLS server to
 427            authenticate raw public keys presented by the TLS
 428            client.  A raw public key is authenticated if it
 429            is an exact match to a configured raw public key.";
 430         reference
 431           "RFC BBBB: A YANG Data Model for a Truststore";
 432         uses ts:inline-or-truststore-public-keys-grouping {
 433           refine "inline-or-truststore/inline/inline-definition/"
 434                + "public-key" {
 435             must 'derived-from-or-self(public-key-format,'
 436                + ' "ct:subject-public-key-info-format")';
 437           }
 438           refine "inline-or-truststore/truststore/truststore-"
 439                + "reference" {
 440             must 'not(deref(.)/../ts:public-key/ts:public-key-'
 441                + 'format[not(derived-from-or-self(., "ct:subject-'
 442                + 'public-key-info-format"))])';
 443           }
 444         }
 445       }
 446       leaf tls12-psks {
 447         if-feature "client-auth-tls12-psk";
 448         type empty;
 449         description
 450           "Indicates that the TLS server can authenticate TLS clients
 451            using configured PSKs (pre-shared or pairwise-symmetric
 452            keys).
 453
 454            No configuration is required since the PSK value is the
 455            same as PSK value configured in the 'server-identity'
 456            node.";
 457       }
 458       leaf tls13-epsks {
 459         if-feature "client-auth-tls13-epsk";
 460         type empty;
 461         description
 462           "Indicates that the TLS 1.3 server can authenticate TLS
 463            clients using configured external PSKs (pre-shared keys).
 464
 465            No configuration is required since the PSK value is the
 466            same as PSK value configured in the 'server-identity'
 467            node.";
 468       }
 469     } // container client-authentication
 470
 471     container hello-params {
 472       nacm:default-deny-write;
 473       if-feature "tlscmn:hello-params";
 474       uses tlscmn:hello-params-grouping;
 475       description
 476         "Configurable parameters for the TLS hello message.";
 477     } // container hello-params
 478
 479     container keepalives {
 480       nacm:default-deny-write;
 481       if-feature "tls-server-keepalives";
 482       description
 483         "Configures the keepalive policy for the TLS server.";
 484       leaf peer-allowed-to-send {
 485         type empty;
 486         description
 487           "Indicates that the remote TLS client is allowed to send
 488            HeartbeatRequest messages, as defined by RFC 6520
 489            to this TLS server.";
 490         reference
 491           "RFC 6520: Transport Layer Security (TLS) and Datagram
 492            Transport Layer Security (DTLS) Heartbeat Extension";
 493       }
 494       container test-peer-aliveness {
 495         presence
 496           "Indicates that the TLS server proactively tests the
 497            aliveness of the remote TLS client.";
 498         description
 499           "Configures the keep-alive policy to proactively test
 500            the aliveness of the TLS client.  An unresponsive
 501            TLS client is dropped after approximately max-wait
 502            * max-attempts seconds.";
 503         leaf max-wait {
 504           type uint16 {
 505             range "1..max";
 506           }
 507           units "seconds";
 508           default "30";
 509           description
 510             "Sets the amount of time in seconds after which if
 511              no data has been received from the TLS client, a
 512              TLS-level message will be sent to test the
 513              aliveness of the TLS client.";
 514         }
 515         leaf max-attempts {
 516           type uint8;
 517           default "3";
 518           description
 519             "Sets the maximum number of sequential keep-alive
 520              messages that can fail to obtain a response from
 521              the TLS client before assuming the TLS client is
 522              no longer alive.";
 523         }
 524       }
 525     } // container keepalives
 526   } // grouping tls-server-grouping
 527
 528 }