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

   1 module ietf-tls-common {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-tls-common";
   4   prefix tlscmn;
   5
   6   import iana-tls-cipher-suite-algs {
   7     prefix tlscsa;
   8     reference
   9       "RFC FFFF: YANG Groupings for TLS Clients and SSH Servers";
  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-keystore {
  19     prefix ks;
  20     reference
  21       "RFC CCCC: A YANG Data Model for a Keystore";
  22   }
  23
  24   organization
  25     "IETF NETCONF (Network Configuration) Working Group";
  26
  27   contact
  28     "WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  29      WG Web:   https://datatracker.ietf.org/wg/netconf
  30      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>
  31      Author:   Jeff Hartley <mailto:jeff.hartley@commscope.com>
  32      Author:   Gary Wu <mailto:garywu@cisco.com>";
  33
  34    description
  35     "This module defines a common features and groupings for
  36      Transport Layer Security (TLS).
  37
  38      Copyright (c) 2023 IETF Trust and the persons identified
  39      as authors of the code. All rights reserved.
  40
  41      Redistribution and use in source and binary forms, with
  42      or without modification, is permitted pursuant to, and
  43      subject to the license terms contained in, the Revised
  44      BSD License set forth in Section 4.c of the IETF Trust's
  45      Legal Provisions Relating to IETF Documents
  46      (https://trustee.ietf.org/license-info).
  47
  48      This version of this YANG module is part of RFC FFFF
  49      (https://www.rfc-editor.org/info/rfcFFFF); see the RFC
  50      itself for full legal notices.
  51
  52      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  53      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  54      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  55      are to be interpreted as described in BCP 14 (RFC 2119)
  56      (RFC 8174) when, and only when, they appear in all
  57      capitals, as shown here.";
  58
  59   revision 2023-12-28 {
  60     description
  61       "Initial version";
  62     reference
  63       "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
  64   }
  65
  66   // Features
  67
  68   feature tls10 {
  69     status "obsolete";
  70     description
  71       "TLS Protocol Version 1.0 is supported.  TLS 1.0 is obsolete
  72        and thus it is NOT RECOMMENDED to enable this feature.";
  73     reference
  74       "RFC 2246: The TLS Protocol Version 1.0";
  75   }
  76
  77   feature tls11 {
  78     status "obsolete";
  79     description
  80       "TLS Protocol Version 1.1 is supported.  TLS 1.1 is obsolete
  81        and thus it is NOT RECOMMENDED to enable this feature.";
  82     reference
  83       "RFC 4346: The Transport Layer Security (TLS) Protocol
  84                  Version 1.1";
  85   }
  86
  87   feature tls12 {
  88     status "deprecated";
  89     description
  90       "TLS Protocol Version 1.2 is supported. TLS 1.2 is obsolete
  91        and thus it is NOT RECOMMENDED to enable this feature.";
  92     reference
  93       "RFC 5246: The Transport Layer Security (TLS) Protocol
  94                  Version 1.2";
  95   }
  96
  97   feature tls13 {
  98     description
  99       "TLS Protocol Version 1.3 is supported.";
 100     reference
 101       "RFC 8446: The Transport Layer Security (TLS)
 102                  Protocol Version 1.3";
 103   }
 104
 105   feature hello-params {
 106     description
 107       "TLS hello message parameters are configurable.";
 108   }
 109
 110   feature public-key-generation {
 111     description
 112       "Indicates that the server implements the
 113        'generate-public-key' RPC.";
 114   }
 115
 116   // Identities
 117
 118   identity tls-version-base {
 119     description
 120       "Base identity used to identify TLS protocol versions.";
 121   }
 122
 123   identity tls10 {
 124     if-feature "tls10";
 125     base tls-version-base;
 126     status "obsolete";
 127     description
 128       "TLS Protocol Version 1.0.";
 129     reference
 130       "RFC 2246: The TLS Protocol Version 1.0";
 131   }
 132
 133   identity tls11 {
 134     if-feature "tls11";
 135     base tls-version-base;
 136     status "obsolete";
 137     description
 138       "TLS Protocol Version 1.1.";
 139     reference
 140       "RFC 4346: The Transport Layer Security (TLS) Protocol
 141                  Version 1.1";
 142   }
 143
 144   identity tls12 {
 145     if-feature "tls12";
 146     base tls-version-base;
 147     status "deprecated";
 148     description
 149       "TLS Protocol Version 1.2.";
 150     reference
 151       "RFC 5246: The Transport Layer Security (TLS) Protocol
 152                  Version 1.2";
 153   }
 154
 155   identity tls13 {
 156     if-feature "tls13";
 157     base tls-version-base;
 158     description
 159       "TLS Protocol Version 1.3.";
 160     reference
 161       "RFC 8446: The Transport Layer Security (TLS)
 162                  Protocol Version 1.3";
 163   }
 164
 165   // Typedefs
 166
 167   typedef epsk-supported-hash {
 168     type enumeration {
 169       enum sha-256 {
 170         description
 171           "The SHA-256 Hash.";
 172       }
 173       enum sha-384 {
 174         description
 175           "The SHA-384 Hash.";
 176       }
 177     }
 178     description
 179       "As per Section 4.2.11 of RFC 8446, the hash algorithm
 180        supported by an instance of an External Pre-Shared
 181        Key (EPSK).";
 182     reference
 183       "RFC 8446: The Transport Layer Security (TLS)
 184                  Protocol Version 1.3";
 185   }
 186
 187
 188   // Groupings
 189
 190   grouping hello-params-grouping {
 191     description
 192       "A reusable grouping for TLS hello message parameters.";
 193     reference
 194       "RFC 5246: The Transport Layer Security (TLS) Protocol
 195                  Version 1.2
 196        RFC 8446: The Transport Layer Security (TLS) Protocol
 197                  Version 1.3";
 198     container tls-versions {
 199       description
 200         "Parameters regarding TLS versions.";
 201       leaf-list tls-version {
 202         type identityref {
 203           base tls-version-base;
 204         }
 205         ordered-by user;
 206         description
 207           "Acceptable TLS protocol versions.
 208
 209            If this leaf-list is not configured (has zero elements)
 210            the acceptable TLS protocol versions are implementation-
 211            defined.";
 212       }
 213     }
 214     container cipher-suites {
 215       description
 216         "Parameters regarding cipher suites.";
 217       leaf-list cipher-suite {
 218         type identityref {
 219           base tlscsa:cipher-suite-alg-base;
 220         }
 221         ordered-by user;
 222         description
 223           "Acceptable cipher suites in order of descending
 224            preference.  The configured host key algorithms should
 225            be compatible with the algorithm used by the configured
 226            private key.  Please see Section 5 of RFC FFFF for
 227            valid combinations.
 228
 229            If this leaf-list is not configured (has zero elements)
 230            the acceptable cipher suites are implementation-
 231            defined.";
 232         reference
 233           "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
 234       }
 235     }
 236   } // hello-params-grouping
 237
 238   rpc generate-public-key {
 239     if-feature "public-key-generation";
 240     description
 241       "Requests the device to generate an public key using
 242        the specified key algorithm.";
 243     input {
 244       leaf algorithm {
 245         type tlscsa:cipher-suite-algorithm-ref;
 246         mandatory true;
 247         description
 248           "The cipher suite algorithm that the generated key is
 249            to work with.  Implementations derive the public key
 250            algorithm from the cipher suite algorithm.  Example:
 251            cipher suite 'tls-rsa-with-aes-256-cbc-sha256' maps
 252            to the RSA public key.";
 253       }
 254       leaf num-bits {
 255         type uint16;
 256         description
 257           "Specifies the number of bits in the key to create.
 258            For RSA keys, the minimum size is 1024 bits and
 259            the default is 3072 bits. Generally, 3072 bits is
 260            considered sufficient. DSA keys must be exactly 1024
 261            bits as specified by FIPS 186-2.  For elliptical
 262            keys, the 'num-bits' value determines the key length
 263            of the curve (e.g., 256, 384 or 521), where valid
 264            values supported by the server are conveyed via an
 265            unspecified mechanism.  For some public algorithms,
 266            the keys have a fixed length and thus the 'num-bits'
 267            value is not specified.";
 268       }
 269       container private-key-encoding {
 270         description
 271           "Indicates how the private key is to be encoded.";
 272         choice private-key-encoding {
 273           mandatory true;
 274           description
 275             "A choice amongst optional private key handling.";
 276           case cleartext {
 277             if-feature "ct:cleartext-private-keys";
 278             leaf cleartext {
 279               type empty;
 280               description
 281                 "Indicates that the private key is to be returned
 282                  as a cleartext value.";
 283             }
 284           }
 285           case encrypted {
 286             if-feature "ct:encrypted-private-keys";
 287             container encrypted {
 288               description
 289                  "Indicates that the key is to be encrypted using
 290                   the specified symmetric or asymmetric key.";
 291               uses ks:encrypted-by-grouping;
 292             }
 293           }
 294           case hidden {
 295             if-feature "ct:hidden-private-keys";
 296             leaf hidden {
 297               type empty;
 298               description
 299                 "Indicates that the private key is to be hidden.
 300
 301                  Unlike the 'cleartext' and 'encrypt' options, the
 302                  key returned is a placeholder for an internally
 303                  stored key.  See the 'Support for Built-in Keys'
 304                  section in RFC CCCC for information about hidden
 305                  keys.";
 306             }
 307           }
 308         }
 309       }
 310     }
 311     output {
 312       uses ct:asymmetric-key-pair-grouping;
 313     }
 314   } // end generate-public-key
 315
 316 }