transport/transport-tls/src/main/yang/ietf-tls-common@2023-04-17.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-04-17 {
  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   typedef epsk-supported-hash {
 166     type enumeration {
 167       enum sha-256 {
 168         description
 169           "The SHA-256 Hash.";
 170       }
 171       enum sha-384 {
 172         description
 173           "The SHA-384 Hash.";
 174       }
 175     }
 176     description
 177       "As per Section 4.2.11 of RFC 8446, the hash algorithm
 178        supported by an instance of an External Pre-Shared
 179        Key (EPSK).";
 180     reference
 181       "RFC 8446: The Transport Layer Security (TLS)
 182                  Protocol Version 1.3
 183        I-D.ietf-tls-external-psk-importer: Importing
 184                  External PSKs for TLS
 185        I-D.ietf-tls-external-psk-guidance: Guidance
 186                  for External PSK Usage in TLS";
 187   }
 188
 189   // Groupings
 190
 191   grouping hello-params-grouping {
 192     description
 193       "A reusable grouping for TLS hello message parameters.";
 194     reference
 195       "RFC 5246: The Transport Layer Security (TLS) Protocol
 196                  Version 1.2
 197        RFC 8446: The Transport Layer Security (TLS) Protocol
 198                  Version 1.3";
 199     container tls-versions {
 200       description
 201         "Parameters regarding TLS versions.";
 202       leaf-list tls-version {
 203         type identityref {
 204           base tls-version-base;
 205         }
 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 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 '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 the 'bits' value,
 267            if specified, will be ignored.";
 268       }
 269       choice private-key-encoding {
 270         default cleartext;
 271         description
 272           "A choice amongst optional private key handling.";
 273         case cleartext {
 274           if-feature "ct:cleartext-private-keys";
 275           leaf cleartext {
 276             type empty;
 277             description
 278               "Indicates that the private key is to be returned
 279                as a cleartext value.";
 280           }
 281         }
 282         case encrypt {
 283           if-feature "ct:encrypted-private-keys";
 284           container encrypt-with {
 285             description
 286                "Indicates that the key is to be encrypted using
 287                 the specified symmetric or asymmetric key.";
 288             uses ks:encrypted-by-choice-grouping;
 289           }
 290         }
 291         case hide {
 292           if-feature "ct:hidden-private-keys";
 293           leaf hide {
 294             type empty;
 295             description
 296               "Indicates that the private key is to be hidden.
 297
 298                Unlike the 'cleartext' and 'encrypt' options, the
 299                key returned is a placeholder for an internally
 300                stored key.  See the 'Support for Built-in Keys'
 301                section in RFC CCCC for information about hidden
 302                keys.";
 303           }
 304         }
 305       }
 306     }
 307     output {
 308       uses ct:asymmetric-key-pair-grouping;
 309     }
 310   } // end generate-public-key
 311
 312 }