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