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

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