keystore/keystore-api/src/main/yang/ietf-keystore@2022-12-12.yang

   1 module ietf-keystore {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-keystore";
   4   prefix ks;
   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   organization
  19     "IETF NETCONF (Network Configuration) Working Group";
  20
  21   contact
  22     "WG Web:   https://datatracker.ietf.org/wg/netconf
  23      WG List:  NETCONF WG list <mailto:netconf@ietf.org>
  24      Author:   Kent Watsen <mailto:kent+ietf@watsen.net>";
  25
  26   description
  27     "This module defines a 'keystore' to centralize management
  28      of security credentials.
  29
  30      Copyright (c) 2022 IETF Trust and the persons identified
  31      as authors of the code. All rights reserved.
  32
  33      Redistribution and use in source and binary forms, with
  34      or without modification, is permitted pursuant to, and
  35      subject to the license terms contained in, the Revised
  36      BSD License set forth in Section 4.c of the IETF Trust's
  37      Legal Provisions Relating to IETF Documents
  38      (https://trustee.ietf.org/license-info).
  39
  40      This version of this YANG module is part of RFC CCCC
  41      (https://www.rfc-editor.org/info/rfcCCCC); see the RFC
  42      itself for full legal notices.
  43
  44      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
  45      'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
  46      'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
  47      are to be interpreted as described in BCP 14 (RFC 2119)
  48      (RFC 8174) when, and only when, they appear in all
  49      capitals, as shown here.";
  50
  51   revision 2022-12-12 {
  52     description
  53       "Initial version";
  54     reference
  55       "RFC CCCC: A YANG Data Model for a Keystore";
  56   }
  57
  58   /****************/
  59   /*   Features   */
  60   /****************/
  61
  62   feature central-keystore-supported {
  63     description
  64       "The 'central-keystore-supported' feature indicates that
  65        the server supports the keystore (i.e., implements the
  66        'ietf-keystore' module).";
  67   }
  68
  69   feature local-definitions-supported {
  70     description
  71       "The 'local-definitions-supported' feature indicates that
  72        the server supports locally-defined keys.";
  73   }
  74
  75   feature asymmetric-keys {
  76     description
  77       "The 'asymmetric-keys' feature indicates that the server
  78        implements the /keystore/asymmetric-keys subtree.";
  79
  80   }
  81
  82   feature symmetric-keys {
  83     description
  84       "The 'symmetric-keys' feature indicates that the server
  85        implements the /keystore/symmetric-keys subtree.";
  86   }
  87
  88   /****************/
  89   /*   Typedefs   */
  90   /****************/
  91
  92   typedef symmetric-key-ref {
  93     type leafref {
  94       path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key"
  95          + "/ks:name";
  96     }
  97     description
  98       "This typedef enables modules to easily define a reference
  99        to a symmetric key stored in the keystore, when this
 100        module is implemented.";
 101   }
 102
 103   typedef asymmetric-key-ref {
 104     type leafref {
 105       path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
 106          + "/ks:name";
 107     }
 108     description
 109       "This typedef enables modules to easily define a reference
 110        to an asymmetric key stored in the keystore, when this
 111        module is implemented.";
 112   }
 113
 114   /*****************/
 115   /*   Groupings   */
 116   /*****************/
 117
 118   grouping encrypted-by-choice-grouping {
 119     description
 120       "A grouping that defines a 'choice' statement that can be
 121        augmented into the 'encrypted-by' node, present in the
 122        'symmetric-key-grouping' and 'asymmetric-key-pair-grouping'
 123        groupings defined in RFC AAAA, enabling references to keys
 124        in the keystore, when this module is implemented.";
 125     choice encrypted-by-choice {
 126       nacm:default-deny-write;
 127       mandatory true;
 128       description
 129         "A choice amongst other symmetric or asymmetric keys.";
 130       case symmetric-key-ref {
 131         if-feature "central-keystore-supported";
 132         if-feature "symmetric-keys";
 133         leaf symmetric-key-ref {
 134           type ks:symmetric-key-ref;
 135           description
 136             "Identifies the symmetric key used to encrypt the
 137              associated key.";
 138         }
 139       }
 140       case asymmetric-key-ref {
 141         if-feature "central-keystore-supported";
 142         if-feature "asymmetric-keys";
 143         leaf asymmetric-key-ref {
 144           type ks:asymmetric-key-ref;
 145           description
 146             "Identifies the asymmetric key whose public key
 147              encrypted the associated key.";
 148         }
 149       }
 150     }
 151   }
 152
 153   grouping asymmetric-key-certificate-ref-grouping {
 154     description
 155       "This grouping defines a reference to a specific certificate
 156        associated with an asymmetric key stored in the keystore,
 157        when this module is implemented.";
 158     leaf asymmetric-key {
 159       nacm:default-deny-write;
 160       if-feature "central-keystore-supported";
 161       if-feature "asymmetric-keys";
 162       type ks:asymmetric-key-ref;
 163       must '../certificate';
 164       description
 165         "A reference to an asymmetric key in the keystore.";
 166     }
 167     leaf certificate {
 168       nacm:default-deny-write;
 169       type leafref {
 170         path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
 171            + "[ks:name = current()/../asymmetric-key]/"
 172            + "ks:certificates/ks:certificate/ks:name";
 173       }
 174       must '../asymmetric-key';
 175       description
 176         "A reference to a specific certificate of the
 177          asymmetric key in the keystore.";
 178     }
 179   }
 180
 181   // local-or-keystore-* groupings
 182
 183   grouping local-or-keystore-symmetric-key-grouping {
 184     description
 185       "A grouping that expands to allow the symmetric key to be
 186        either stored locally, i.e., within the using data model,
 187        or a reference to a symmetric key stored in the keystore.
 188
 189        Servers that do not 'implement' this module, and hence
 190        'central-keystore-supported' is not defined, SHOULD
 191        augment in custom 'case' statements enabling references
 192        to the alternate keystore locations.";
 193     choice local-or-keystore {
 194       nacm:default-deny-write;
 195       mandatory true;
 196       description
 197         "A choice between an inlined definition and a definition
 198          that exists in the keystore.";
 199       case local {
 200         if-feature "local-definitions-supported";
 201         container local-definition {
 202           description
 203             "Container to hold the local key definition.";
 204           uses ct:symmetric-key-grouping;
 205         }
 206       }
 207       case keystore {
 208         if-feature "central-keystore-supported";
 209         if-feature "symmetric-keys";
 210         leaf keystore-reference {
 211           type ks:symmetric-key-ref;
 212           description
 213             "A reference to an symmetric key that exists in
 214              the keystore, when this module is implemented.";
 215         }
 216       }
 217     }
 218   }
 219   grouping local-or-keystore-asymmetric-key-grouping {
 220     description
 221       "A grouping that expands to allow the asymmetric key to be
 222        either stored locally, i.e., within the using data model,
 223        or a reference to an asymmetric key stored in the keystore.
 224
 225        Servers that do not 'implement' this module, and hence
 226        'central-keystore-supported' is not defined, SHOULD
 227        augment in custom 'case' statements enabling references
 228        to the alternate keystore locations.";
 229     choice local-or-keystore {
 230       nacm:default-deny-write;
 231       mandatory true;
 232       description
 233         "A choice between an inlined definition and a definition
 234          that exists in the keystore.";
 235       case local {
 236         if-feature "local-definitions-supported";
 237         container local-definition {
 238           description
 239             "Container to hold the local key definition.";
 240           uses ct:asymmetric-key-pair-grouping;
 241         }
 242       }
 243       case keystore {
 244         if-feature "central-keystore-supported";
 245         if-feature "asymmetric-keys";
 246         leaf keystore-reference {
 247           type ks:asymmetric-key-ref;
 248           description
 249             "A reference to an asymmetric key that exists in
 250              the keystore, when this module is implemented.  The
 251              intent is to reference just the asymmetric key
 252              without any regard for any certificates that may
 253              be associated with it.";
 254         }
 255       }
 256     }
 257   }
 258
 259   grouping local-or-keystore-asymmetric-key-with-certs-grouping {
 260     description
 261       "A grouping that expands to allow an asymmetric key and
 262        its associated certificates to be either stored locally,
 263        i.e., within the using data model, or a reference to an
 264        asymmetric key (and its associated certificates) stored
 265        in the keystore.
 266
 267        Servers that do not 'implement' this module, and hence
 268        'central-keystore-supported' is not defined, SHOULD
 269        augment in custom 'case' statements enabling references
 270        to the alternate keystore locations.";
 271     choice local-or-keystore {
 272       nacm:default-deny-write;
 273       mandatory true;
 274       description
 275         "A choice between an inlined definition and a definition
 276          that exists in the keystore.";
 277       case local {
 278         if-feature "local-definitions-supported";
 279         container local-definition {
 280           description
 281             "Container to hold the local key definition.";
 282           uses ct:asymmetric-key-pair-with-certs-grouping;
 283         }
 284       }
 285       case keystore {
 286         if-feature "central-keystore-supported";
 287         if-feature "asymmetric-keys";
 288         leaf keystore-reference {
 289           type ks:asymmetric-key-ref;
 290           description
 291             "A reference to an asymmetric-key (and all of its
 292              associated certificates) in the keystore, when
 293              this module is implemented.";
 294         }
 295       }
 296     }
 297   }
 298
 299   grouping local-or-keystore-end-entity-cert-with-key-grouping {
 300     description
 301       "A grouping that expands to allow an end-entity certificate
 302        (and its associated asymmetric key pair) to be either stored
 303        locally, i.e., within the using data model, or a reference
 304        to a specific certificate in the keystore.
 305
 306        Servers that do not 'implement' this module, and hence
 307        'central-keystore-supported' is not defined, SHOULD
 308        augment in custom 'case' statements enabling references
 309        to the alternate keystore locations.";
 310     choice local-or-keystore {
 311       nacm:default-deny-write;
 312       mandatory true;
 313       description
 314         "A choice between an inlined definition and a definition
 315          that exists in the keystore.";
 316       case local {
 317         if-feature "local-definitions-supported";
 318         container local-definition {
 319           description
 320             "Container to hold the local key definition.";
 321           uses ct:asymmetric-key-pair-with-cert-grouping;
 322         }
 323       }
 324       case keystore {
 325         if-feature "central-keystore-supported";
 326         if-feature "asymmetric-keys";
 327         container keystore-reference {
 328           uses asymmetric-key-certificate-ref-grouping;
 329           description
 330             "A reference to a specific certificate associated with
 331              an asymmetric key stored in the keystore, when this
 332              module is implemented.";
 333         }
 334       }
 335     }
 336   }
 337
 338   grouping keystore-grouping {
 339     description
 340       "Grouping definition enables use in other contexts.  If ever
 341        done, implementations MUST augment new 'case' statements
 342        into the various local-or-keystore 'choice' statements to
 343        supply leafrefs to the model-specific location(s).";
 344     container asymmetric-keys {
 345       nacm:default-deny-write;
 346       if-feature "asymmetric-keys";
 347       description
 348         "A list of asymmetric keys.";
 349       list asymmetric-key {
 350         key "name";
 351         description
 352           "An asymmetric key.";
 353         leaf name {
 354           type string;
 355           description
 356             "An arbitrary name for the asymmetric key.";
 357         }
 358         uses ct:asymmetric-key-pair-with-certs-grouping;
 359       }
 360     }
 361     container symmetric-keys {
 362       nacm:default-deny-write;
 363       if-feature "symmetric-keys";
 364       description
 365         "A list of symmetric keys.";
 366       list symmetric-key {
 367         key "name";
 368         description
 369           "A symmetric key.";
 370         leaf name {
 371           type string;
 372           description
 373             "An arbitrary name for the symmetric key.";
 374         }
 375         uses ct:symmetric-key-grouping;
 376       }
 377     }
 378   }
 379
 380   /*********************************/
 381   /*   Protocol accessible nodes   */
 382   /*********************************/
 383
 384   container keystore {
 385     if-feature central-keystore-supported;
 386     description
 387       "A central keystore containing a list of symmetric keys and
 388        a list of asymmetric keys.";
 389     nacm:default-deny-write;
 390     uses keystore-grouping {
 391       augment "symmetric-keys/symmetric-key/key-type/encrypted-key/"
 392             + "encrypted-key/encrypted-by" {
 393         description
 394           "Augments in a choice statement enabling the encrypting
 395            key to be any other symmetric or asymmetric key in the
 396            central keystore.";
 397         uses encrypted-by-choice-grouping;
 398       }
 399       augment "asymmetric-keys/asymmetric-key/private-key-type/"
 400             + "encrypted-private-key/encrypted-private-key/"
 401             + "encrypted-by" {
 402         description
 403           "Augments in a choice statement enabling the encrypting
 404            key to be any other symmetric or asymmetric key in the
 405            central keystore.";
 406         uses encrypted-by-choice-grouping;
 407       }
 408     }
 409   }
 410 }