keystore/keystore-api/src/main/yang/ietf-keystore@2023-04-17.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) 2023 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 2023-04-17 {
  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 inline-definitions-supported {
  70     description
  71       "The 'inline-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   // inline-or-keystore-* groupings
 182
 183   grouping inline-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 inline-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 inline {
 200         if-feature "inline-definitions-supported";
 201         container inline-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
 220   grouping inline-or-keystore-asymmetric-key-grouping {
 221     description
 222       "A grouping that expands to allow the asymmetric key to be
 223        either stored locally, i.e., within the using data model,
 224        or a reference to an asymmetric key stored in the keystore.
 225
 226        Servers that do not 'implement' this module, and hence
 227        'central-keystore-supported' is not defined, SHOULD
 228        augment in custom 'case' statements enabling references
 229        to the alternate keystore locations.";
 230     choice inline-or-keystore {
 231       nacm:default-deny-write;
 232       mandatory true;
 233       description
 234         "A choice between an inlined definition and a definition
 235          that exists in the keystore.";
 236       case inline {
 237         if-feature "inline-definitions-supported";
 238         container inline-definition {
 239           description
 240             "Container to hold the local key definition.";
 241           uses ct:asymmetric-key-pair-grouping;
 242         }
 243       }
 244       case keystore {
 245         if-feature "central-keystore-supported";
 246         if-feature "asymmetric-keys";
 247         leaf keystore-reference {
 248           type ks:asymmetric-key-ref;
 249           description
 250             "A reference to an asymmetric key that exists in
 251              the keystore, when this module is implemented.  The
 252              intent is to reference just the asymmetric key
 253              without any regard for any certificates that may
 254              be associated with it.";
 255         }
 256       }
 257     }
 258   }
 259
 260   grouping inline-or-keystore-asymmetric-key-with-certs-grouping {
 261     description
 262       "A grouping that expands to allow an asymmetric key and
 263        its associated certificates to be either stored locally,
 264        i.e., within the using data model, or a reference to an
 265        asymmetric key (and its associated certificates) stored
 266        in the keystore.
 267
 268        Servers that do not 'implement' this module, and hence
 269        'central-keystore-supported' is not defined, SHOULD
 270        augment in custom 'case' statements enabling references
 271        to the alternate keystore locations.";
 272     choice inline-or-keystore {
 273       nacm:default-deny-write;
 274       mandatory true;
 275       description
 276         "A choice between an inlined definition and a definition
 277          that exists in the keystore.";
 278       case inline {
 279         if-feature "inline-definitions-supported";
 280         container inline-definition {
 281           description
 282             "Container to hold the local key definition.";
 283           uses ct:asymmetric-key-pair-with-certs-grouping;
 284         }
 285       }
 286       case keystore {
 287         if-feature "central-keystore-supported";
 288         if-feature "asymmetric-keys";
 289         leaf keystore-reference {
 290           type ks:asymmetric-key-ref;
 291           description
 292             "A reference to an asymmetric-key (and all of its
 293              associated certificates) in the keystore, when
 294              this module is implemented.";
 295         }
 296       }
 297     }
 298   }
 299
 300   grouping inline-or-keystore-end-entity-cert-with-key-grouping {
 301     description
 302       "A grouping that expands to allow an end-entity certificate
 303        (and its associated asymmetric key pair) to be either stored
 304        locally, i.e., within the using data model, or a reference
 305        to a specific certificate in the keystore.
 306
 307        Servers that do not 'implement' this module, and hence
 308        'central-keystore-supported' is not defined, SHOULD
 309        augment in custom 'case' statements enabling references
 310        to the alternate keystore locations.";
 311     choice inline-or-keystore {
 312       nacm:default-deny-write;
 313       mandatory true;
 314       description
 315         "A choice between an inlined definition and a definition
 316          that exists in the keystore.";
 317       case inline {
 318         if-feature "inline-definitions-supported";
 319         container inline-definition {
 320           description
 321             "Container to hold the local key definition.";
 322           uses ct:asymmetric-key-pair-with-cert-grouping;
 323         }
 324       }
 325       case keystore {
 326         if-feature "central-keystore-supported";
 327         if-feature "asymmetric-keys";
 328         container keystore-reference {
 329           uses asymmetric-key-certificate-ref-grouping;
 330           description
 331             "A reference to a specific certificate associated with
 332              an asymmetric key stored in the keystore, when this
 333              module is implemented.";
 334         }
 335       }
 336     }
 337   }
 338
 339   grouping keystore-grouping {
 340     description
 341       "Grouping definition enables use in other contexts.  If ever
 342        done, implementations MUST augment new 'case' statements
 343        into the various inline-or-keystore 'choice' statements to
 344        supply leafrefs to the model-specific location(s).";
 345     container asymmetric-keys {
 346       nacm:default-deny-write;
 347       if-feature "asymmetric-keys";
 348       description
 349         "A list of asymmetric keys.";
 350       list asymmetric-key {
 351         key "name";
 352         description
 353           "An asymmetric key.";
 354         leaf name {
 355           type string;
 356           description
 357             "An arbitrary name for the asymmetric key.";
 358         }
 359         uses ct:asymmetric-key-pair-with-certs-grouping;
 360       }
 361     }
 362     container symmetric-keys {
 363       nacm:default-deny-write;
 364       if-feature "symmetric-keys";
 365       description
 366         "A list of symmetric keys.";
 367       list symmetric-key {
 368         key "name";
 369         description
 370           "A symmetric key.";
 371         leaf name {
 372           type string;
 373           description
 374             "An arbitrary name for the symmetric key.";
 375         }
 376         uses ct:symmetric-key-grouping;
 377       }
 378     }
 379   }
 380
 381   /*********************************/
 382   /*   Protocol accessible nodes   */
 383   /*********************************/
 384
 385   container keystore {
 386     if-feature central-keystore-supported;
 387     description
 388       "A central keystore containing a list of symmetric keys and
 389        a list of asymmetric keys.";
 390     nacm:default-deny-write;
 391     uses keystore-grouping {
 392       augment "symmetric-keys/symmetric-key/key-type/encrypted-key/"
 393             + "encrypted-key/encrypted-by" {
 394         description
 395           "Augments in a choice statement enabling the encrypting
 396            key to be any other symmetric or asymmetric key in the
 397            central keystore.";
 398         uses encrypted-by-choice-grouping;
 399       }
 400       augment "asymmetric-keys/asymmetric-key/private-key-type/"
 401             + "encrypted-private-key/encrypted-private-key/"
 402             + "encrypted-by" {
 403         description
 404           "Augments in a choice statement enabling the encrypting
 405            key to be any other symmetric or asymmetric key in the
 406            central keystore.";
 407         uses encrypted-by-choice-grouping;
 408       }
 409     }
 410   }
 411 }