keystore/keystore-api/src/main/yang/ietf-keystore@2022-05-24.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-05-24 {
  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        supports asymmetric keys in keystores.";
  79   }
  80
  81   feature symmetric-keys {
  82     description
  83       "The 'symmetric-keys' feature indicates that the server
  84        supports symmetric keys in keystores.";
  85   }
  86
  87   /****************/
  88   /*   Typedefs   */
  89   /****************/
  90
  91   typedef symmetric-key-ref {
  92     type leafref {
  93       path "/ks:keystore/ks:symmetric-keys/ks:symmetric-key"
  94          + "/ks:name";
  95     }
  96     description
  97       "This typedef enables modules to easily define a reference
  98        to a symmetric key stored in the keystore, when this
  99        module is implemented.";
 100   }
 101
 102   typedef asymmetric-key-ref {
 103     type leafref {
 104       path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
 105          + "/ks:name";
 106     }
 107     description
 108       "This typedef enables modules to easily define a reference
 109        to an asymmetric key stored in the keystore, when this
 110        module is implemented.";
 111   }
 112
 113   /*****************/
 114   /*   Groupings   */
 115   /*****************/
 116
 117   grouping encrypted-by-choice-grouping {
 118     description
 119       "A grouping that defines a 'choice' statement that can be
 120        augmented into the 'encrypted-by' node, present in the
 121        'symmetric-key-grouping' and 'asymmetric-key-pair-grouping'
 122        groupings defined in RFC AAAA, enabling references to keys
 123        in the keystore, when this module is implemented.";
 124     choice encrypted-by-choice {
 125       nacm:default-deny-write;
 126       mandatory true;
 127       description
 128         "A choice amongst other symmetric or asymmetric keys.";
 129       case symmetric-key-ref {
 130         if-feature "central-keystore-supported";
 131         if-feature "symmetric-keys";
 132         leaf symmetric-key-ref {
 133           type ks:symmetric-key-ref;
 134           description
 135             "Identifies the symmetric key used to encrypt the
 136              associated key.";
 137         }
 138       }
 139       case asymmetric-key-ref {
 140         if-feature "central-keystore-supported";
 141         if-feature "asymmetric-keys";
 142         leaf asymmetric-key-ref {
 143           type ks:asymmetric-key-ref;
 144           description
 145             "Identifies the asymmetric key whose public key
 146              encrypted the associated key.";
 147         }
 148       }
 149     }
 150   }
 151
 152   grouping asymmetric-key-certificate-ref-grouping {
 153     description
 154       "This grouping defines a reference to a specific certificate
 155        associated with an asymmetric key stored in the keystore,
 156        when this module is implemented.";
 157     leaf asymmetric-key {
 158       nacm:default-deny-write;
 159       if-feature "central-keystore-supported";
 160       if-feature "asymmetric-keys";
 161       type ks:asymmetric-key-ref;
 162       must '../certificate';
 163       description
 164         "A reference to an asymmetric key in the keystore.";
 165     }
 166     leaf certificate {
 167       nacm:default-deny-write;
 168       type leafref {
 169         path "/ks:keystore/ks:asymmetric-keys/ks:asymmetric-key"
 170            + "[ks:name = current()/../asymmetric-key]/"
 171            + "ks:certificates/ks:certificate/ks:name";
 172       }
 173       must '../asymmetric-key';
 174       description
 175         "A reference to a specific certificate of the
 176          asymmetric key in the keystore.";
 177     }
 178   }
 179
 180   // local-or-keystore-* groupings
 181
 182   grouping local-or-keystore-symmetric-key-grouping {
 183     description
 184       "A grouping that expands to allow the symmetric key to be
 185        either stored locally, i.e., within the using data model,
 186        or a reference to a symmetric key stored in the keystore.
 187
 188        Servers that do not 'implement' this module, and hence
 189        'central-keystore-supported' is not defined, SHOULD
 190        augment in custom 'case' statements enabling references
 191        to the alternate keystore locations.";
 192     choice local-or-keystore {
 193       nacm:default-deny-write;
 194       mandatory true;
 195       description
 196         "A choice between an inlined definition and a definition
 197          that exists in the keystore.";
 198       case local {
 199         if-feature "local-definitions-supported";
 200         if-feature "symmetric-keys";
 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         if-feature "asymmetric-keys";
 238         container local-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 local-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        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         if-feature "asymmetric-keys";
 280         container local-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 local-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 local-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 local {
 318         if-feature "local-definitions-supported";
 319         if-feature "asymmetric-keys";
 320         container local-definition {
 321           description
 322             "Container to hold the local key definition.";
 323           uses ct:asymmetric-key-pair-with-cert-grouping;
 324         }
 325       }
 326       case keystore {
 327         if-feature "central-keystore-supported";
 328         if-feature "asymmetric-keys";
 329         container keystore-reference {
 330           uses asymmetric-key-certificate-ref-grouping;
 331           description
 332             "A reference to a specific certificate associated with
 333              an asymmetric key stored in the keystore, when this
 334              module is implemented.";
 335         }
 336       }
 337     }
 338   }
 339
 340   grouping keystore-grouping {
 341     description
 342       "Grouping definition enables use in other contexts.  If ever
 343        done, implementations MUST augment new 'case' statements
 344        into the various local-or-keystore 'choice' statements to
 345        supply leafrefs to the model-specific location(s).";
 346     container asymmetric-keys {
 347       nacm:default-deny-write;
 348       if-feature "asymmetric-keys";
 349       description
 350         "A list of asymmetric keys.";
 351       list asymmetric-key {
 352         key "name";
 353         description
 354           "An asymmetric key.";
 355         leaf name {
 356           type string;
 357           description
 358             "An arbitrary name for the asymmetric key.";
 359         }
 360         uses ct:asymmetric-key-pair-with-certs-grouping;
 361       }
 362     }
 363     container symmetric-keys {
 364       nacm:default-deny-write;
 365       if-feature "symmetric-keys";
 366       description
 367         "A list of symmetric keys.";
 368       list symmetric-key {
 369         key "name";
 370         description
 371           "A symmetric key.";
 372         leaf name {
 373           type string;
 374           description
 375             "An arbitrary name for the symmetric key.";
 376         }
 377         uses ct:symmetric-key-grouping;
 378       }
 379     }
 380   }
 381
 382   /*********************************/
 383   /*   Protocol accessible nodes   */
 384   /*********************************/
 385
 386   container keystore {
 387     if-feature central-keystore-supported;
 388     description
 389       "A central keystore containing a list of symmetric keys and
 390        a list of asymmetric keys.";
 391     nacm:default-deny-write;
 392     uses keystore-grouping {
 393       augment "symmetric-keys/symmetric-key/key-type/encrypted-key/"
 394             + "encrypted-key/encrypted-by" {
 395         description
 396           "Augments in a choice statement enabling the encrypting
 397            key to be any other symmetric or asymmetric key in the
 398            central keystore.";
 399         uses encrypted-by-choice-grouping;
 400       }
 401       augment "asymmetric-keys/asymmetric-key/private-key-type/"
 402             + "encrypted-private-key/encrypted-private-key/"
 403             + "encrypted-by" {
 404         description
 405           "Augments in a choice statement enabling the encrypting
 406            key to be any other symmetric or asymmetric key in the
 407            central keystore.";
 408         uses encrypted-by-choice-grouping;
 409       }
 410     }
 411   }
 412 }