transport/transport-tls/src/main/yang/ietf-tls-common@2024-02-08.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:intensifysecurity@gmail.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) 2024 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 2024-02-08 {
  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 tls12 {
  69     status "deprecated";
  70     description
  71       "TLS Protocol Version 1.2 is supported. TLS 1.2 is obsolete
  72        and thus it is NOT RECOMMENDED to enable this feature.";
  73     reference
  74       "RFC 5246: The Transport Layer Security (TLS) Protocol
  75                  Version 1.2";
  76   }
  77
  78   feature tls13 {
  79     description
  80       "TLS Protocol Version 1.3 is supported.";
  81     reference
  82       "RFC 8446: The Transport Layer Security (TLS)
  83                  Protocol Version 1.3";
  84   }
  85
  86   feature hello-params {
  87     description
  88       "TLS hello message parameters are configurable.";
  89   }
  90
  91   feature algorithm-discovery {
  92     description
  93       "Indicates that the server implements the
  94        'supported-algorithms' container.";
  95   }
  96
  97   feature asymmetric-key-pair-generation {
  98     description
  99       "Indicates that the server implements the
 100        'generate-asymmetric-key-pair' RPC.";
 101   }
 102
 103   // Identities
 104
 105   identity tls-version-base {
 106     description
 107       "Base identity used to identify TLS protocol versions.";
 108   }
 109
 110   identity tls12 {
 111     if-feature "tls12";
 112     base tls-version-base;
 113     status "deprecated";
 114     description
 115       "TLS Protocol Version 1.2.";
 116     reference
 117       "RFC 5246: The Transport Layer Security (TLS) Protocol
 118                  Version 1.2";
 119   }
 120
 121   identity tls13 {
 122     if-feature "tls13";
 123     base tls-version-base;
 124     description
 125       "TLS Protocol Version 1.3.";
 126     reference
 127       "RFC 8446: The Transport Layer Security (TLS)
 128                  Protocol Version 1.3";
 129   }
 130
 131   // Typedefs
 132
 133   typedef epsk-supported-hash {
 134     type enumeration {
 135       enum sha-256 {
 136         description
 137           "The SHA-256 Hash.";
 138       }
 139       enum sha-384 {
 140         description
 141           "The SHA-384 Hash.";
 142       }
 143     }
 144     description
 145       "As per Section 4.2.11 of RFC 8446, the hash algorithm
 146        supported by an instance of an External Pre-Shared
 147        Key (EPSK).";
 148     reference
 149       "RFC 8446: The Transport Layer Security (TLS)
 150                  Protocol Version 1.3";
 151   }
 152
 153
 154   // Groupings
 155
 156   grouping hello-params-grouping {
 157     description
 158       "A reusable grouping for TLS hello message parameters.";
 159     reference
 160       "RFC 5246: The Transport Layer Security (TLS) Protocol
 161                  Version 1.2
 162        RFC 8446: The Transport Layer Security (TLS) Protocol
 163                  Version 1.3";
 164     container tls-versions {
 165       description
 166         "Parameters regarding TLS versions.";
 167       leaf-list tls-version {
 168         type identityref {
 169           base tls-version-base;
 170         }
 171         ordered-by user;
 172         description
 173           "Acceptable TLS protocol versions.
 174
 175            If this leaf-list is not configured (has zero elements)
 176            the acceptable TLS protocol versions are implementation-
 177            defined.";
 178       }
 179     }
 180     container cipher-suites {
 181       description
 182         "Parameters regarding cipher suites.";
 183       leaf-list cipher-suite {
 184         type identityref {
 185           base tlscsa:cipher-suite-alg-base;
 186         }
 187         ordered-by user;
 188         description
 189           "Acceptable cipher suites in order of descending
 190            preference.  The configured host key algorithms should
 191            be compatible with the algorithm used by the configured
 192            private key.  Please see Section 5 of RFC FFFF for
 193            valid combinations.
 194
 195            If this leaf-list is not configured (has zero elements)
 196            the acceptable cipher suites are implementation-
 197            defined.";
 198         reference
 199           "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers";
 200       }
 201     }
 202   } // hello-params-grouping
 203
 204
 205   // Protocol-accessible Nodes
 206
 207   container supported-algorithms {
 208     if-feature "algorithm-discovery";
 209     config false;
 210     description
 211       "A container for a list of cipher suite algorithms supported
 212        by the server.";
 213     leaf-list supported-algorithm {
 214       type tlscsa:cipher-suite-algorithm-ref;
 215       description
 216         "A cipher suite algorithm supported by the server.";
 217     }
 218   }
 219
 220   rpc generate-asymmetric-key-pair {
 221     if-feature "asymmetric-key-pair-generation";
 222     description
 223       "Requests the device to generate an asymmetric-key-pair
 224        key using the specified key algorithm.";
 225     input {
 226       leaf algorithm {
 227         type tlscsa:cipher-suite-algorithm-ref;
 228         mandatory true;
 229         description
 230           "The cipher suite algorithm that the generated key is
 231            to work with.  Implementations derive the public key
 232            algorithm from the cipher suite algorithm.  Example:
 233            cipher suite 'tls-rsa-with-aes-256-cbc-sha256' maps
 234            to the RSA public key.";
 235       }
 236       leaf num-bits {
 237         type uint16;
 238         description
 239           "Specifies the number of bits in the key to create.
 240            For RSA keys, the minimum size is 1024 bits and
 241            the default is 3072 bits. Generally, 3072 bits is
 242            considered sufficient. DSA keys must be exactly 1024
 243            bits as specified by FIPS 186-2.  For elliptical
 244            keys, the 'num-bits' value determines the key length
 245            of the curve (e.g., 256, 384 or 521), where valid
 246            values supported by the server are conveyed via an
 247            unspecified mechanism.  For some public algorithms,
 248            the keys have a fixed length and thus the 'num-bits'
 249            value is not specified.";
 250       }
 251       container private-key-encoding {
 252         description
 253           "Indicates how the private key is to be encoded.";
 254         choice private-key-encoding {
 255           mandatory true;
 256           description
 257             "A choice amongst optional private key handling.";
 258           case cleartext {
 259             if-feature "ct:cleartext-private-keys";
 260             leaf cleartext {
 261               type empty;
 262               description
 263                 "Indicates that the private key is to be returned
 264                  as a cleartext value.";
 265             }
 266           }
 267           case encrypted {
 268             if-feature "ct:encrypted-private-keys";
 269             container encrypted {
 270               description
 271                  "Indicates that the key is to be encrypted using
 272                   the specified symmetric or asymmetric key.";
 273               uses ks:encrypted-by-grouping;
 274             }
 275           }
 276           case hidden {
 277             if-feature "ct:hidden-private-keys";
 278             leaf hidden {
 279               type empty;
 280               description
 281                 "Indicates that the private key is to be hidden.
 282
 283                  Unlike the 'cleartext' and 'encrypt' options, the
 284                  key returned is a placeholder for an internally
 285                  stored key.  See the 'Support for Built-in Keys'
 286                  section in RFC CCCC for information about hidden
 287                  keys.";
 288             }
 289           }
 290         }
 291       }
 292     }
 293     output {
 294       uses ct:asymmetric-key-pair-grouping;
 295     }
 296   } // end generate-asymmetric-key-pair
 297
 298 }