keystore/keystore-api/src/main/yang/ietf-keystore@2023-12-28.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-12-28 {
  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 central keystore (i.e., fully
  66        implements the '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 central keystore.";
 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 central keystore.";
 110   }
 111
 112   /*****************/
 113   /*   Groupings   */
 114   /*****************/
 115
 116   grouping encrypted-by-grouping {
 117     description
 118       "A grouping that defines a 'choice' statement that can be
 119        augmented into the 'encrypted-by' node, present in the
 120        'symmetric-key-grouping' and 'asymmetric-key-pair-grouping'
 121        groupings defined in RFC AAAA, enabling references to keys
 122        in the central keystore.";
 123     choice encrypted-by {
 124       nacm:default-deny-write;
 125       mandatory true;
 126       description
 127         "A choice amongst other symmetric or asymmetric keys.";
 128       case symmetric-key-ref {
 129         if-feature "central-keystore-supported";
 130         if-feature "symmetric-keys";
 131         leaf symmetric-key-ref {
 132           type ks:symmetric-key-ref;
 133           description
 134             "Identifies the symmetric key used to encrypt the
 135              associated key.";
 136         }
 137       }
 138       case asymmetric-key-ref {
 139         if-feature "central-keystore-supported";
 140         if-feature "asymmetric-keys";
 141         leaf asymmetric-key-ref {
 142           type ks:asymmetric-key-ref;
 143           description
 144             "Identifies the asymmetric key whose public key
 145              encrypted the associated key.";
 146         }
 147       }
 148     }
 149   }
 150
 151   // *-ref groupings
 152
 153   grouping asymmetric-key-certificate-ref-grouping {
 154     description
 155       "Grouping for the reference to a certificate associated
 156        with an asymmetric key stored in the central keystore.";
 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   // inline-or-keystore-* groupings
 181
 182   grouping inline-or-keystore-symmetric-key-grouping {
 183     description
 184       "A grouping for the configuration of a symmetric key.  The
 185        symmetric key may be defined inline or as a reference to
 186        a symmetric key stored in the central keystore.
 187
 188        Servers that do not define the 'central-keystore-supported'
 189        feature SHOULD augment in custom 'case' statements enabling
 190        references to alternate keystore locations.";
 191     choice inline-or-keystore {
 192       nacm:default-deny-write;
 193       mandatory true;
 194       description
 195         "A choice between an inlined definition and a definition
 196          that exists in the keystore.";
 197       case inline {
 198         if-feature "inline-definitions-supported";
 199         container inline-definition {
 200           description
 201             "Container to hold the local key definition.";
 202           uses ct:symmetric-key-grouping;
 203         }
 204       }
 205       case central-keystore {
 206         if-feature "central-keystore-supported";
 207         if-feature "symmetric-keys";
 208         leaf central-keystore-reference {
 209           type ks:symmetric-key-ref;
 210           description
 211             "A reference to an symmetric key that exists in
 212              the central keystore.";
 213         }
 214       }
 215     }
 216   }
 217
 218   grouping inline-or-keystore-asymmetric-key-grouping {
 219     description
 220       "A grouping for the configuration of an asymmetric key. The
 221        asymmetric key may be defined inline or as a reference to
 222        an asymmetric key stored in the central keystore.
 223
 224        Servers that do not define the 'central-keystore-supported'
 225        feature SHOULD augment in custom 'case' statements enabling
 226        references to alternate keystore locations.";
 227     choice inline-or-keystore {
 228       nacm:default-deny-write;
 229       mandatory true;
 230       description
 231         "A choice between an inlined definition and a definition
 232          that exists in the keystore.";
 233       case inline {
 234         if-feature "inline-definitions-supported";
 235         container inline-definition {
 236           description
 237             "Container to hold the local key definition.";
 238           uses ct:asymmetric-key-pair-grouping;
 239         }
 240       }
 241       case central-keystore {
 242         if-feature "central-keystore-supported";
 243         if-feature "asymmetric-keys";
 244         leaf central-keystore-reference {
 245           type ks:asymmetric-key-ref;
 246           description
 247             "A reference to an asymmetric key that exists in
 248              the central keystore.  The intent is to reference
 249              just the asymmetric key without any regard for
 250              any certificates that may be associated with it.";
 251         }
 252       }
 253     }
 254   }
 255
 256   grouping inline-or-keystore-asymmetric-key-with-certs-grouping {
 257     description
 258       "A grouping for the configuration of an asymmetric key and
 259        its associated certificates.  The asymmetric key and its
 260        associated certificates may be defined inline or as a
 261        reference to an asymmetric key (and its associated
 262        certificates) in the central keystore.
 263
 264        Servers that do not define the 'central-keystore-supported'
 265        feature SHOULD augment in custom 'case' statements enabling
 266        references to alternate keystore locations.";
 267     choice inline-or-keystore {
 268       nacm:default-deny-write;
 269       mandatory true;
 270       description
 271         "A choice between an inlined definition and a definition
 272          that exists in the keystore.";
 273       case inline {
 274         if-feature "inline-definitions-supported";
 275         container inline-definition {
 276           description
 277             "Container to hold the local key definition.";
 278           uses ct:asymmetric-key-pair-with-certs-grouping;
 279         }
 280       }
 281       case central-keystore {
 282         if-feature "central-keystore-supported";
 283         if-feature "asymmetric-keys";
 284         leaf central-keystore-reference {
 285           type ks:asymmetric-key-ref;
 286           description
 287             "A reference to an asymmetric-key (and all of its
 288              associated certificates) in the keystore, when
 289              this module is implemented.";
 290         }
 291       }
 292     }
 293   }
 294
 295   grouping inline-or-keystore-end-entity-cert-with-key-grouping {
 296     description
 297       "A grouping for the configuration of an asymmetric key and
 298        its associated end-entity certificate.  The asymmetric key
 299        and its associated end-entity certificate may be defined
 300        inline or as a reference to an asymmetric key (and its
 301        associated end-entity certificate) in the central keystore.
 302
 303        Servers that do not define the 'central-keystore-supported'
 304        feature SHOULD augment in custom 'case' statements enabling
 305        references to alternate keystore locations.";
 306     choice inline-or-keystore {
 307       nacm:default-deny-write;
 308       mandatory true;
 309       description
 310         "A choice between an inlined definition and a definition
 311          that exists in the keystore.";
 312       case inline {
 313         if-feature "inline-definitions-supported";
 314         container inline-definition {
 315           description
 316             "Container to hold the local key definition.";
 317           uses ct:asymmetric-key-pair-with-cert-grouping;
 318         }
 319       }
 320       case central-keystore {
 321         if-feature "central-keystore-supported";
 322         if-feature "asymmetric-keys";
 323         container central-keystore-reference {
 324           uses asymmetric-key-certificate-ref-grouping;
 325           description
 326             "A reference to a specific certificate associated with
 327              an asymmetric key stored in the central keystore.";
 328         }
 329       }
 330     }
 331   }
 332
 333   // the keystore grouping
 334
 335   grouping keystore-grouping {
 336     description
 337       "Grouping definition enables use in other contexts.  If ever
 338        done, implementations MUST augment new 'case' statements
 339        into the various inline-or-keystore 'choice' statements to
 340        supply leafrefs to the model-specific location(s).";
 341     container asymmetric-keys {
 342       nacm:default-deny-write;
 343       if-feature "asymmetric-keys";
 344       description
 345         "A list of asymmetric keys.";
 346       list asymmetric-key {
 347         key "name";
 348         description
 349           "An asymmetric key.";
 350         leaf name {
 351           type string;
 352           description
 353             "An arbitrary name for the asymmetric key.";
 354         }
 355         uses ct:asymmetric-key-pair-with-certs-grouping;
 356       }
 357     }
 358     container symmetric-keys {
 359       nacm:default-deny-write;
 360       if-feature "symmetric-keys";
 361       description
 362         "A list of symmetric keys.";
 363       list symmetric-key {
 364         key "name";
 365         description
 366           "A symmetric key.";
 367         leaf name {
 368           type string;
 369           description
 370             "An arbitrary name for the symmetric key.";
 371         }
 372         uses ct:symmetric-key-grouping;
 373       }
 374     }
 375   }
 376
 377   /*********************************/
 378   /*   Protocol accessible nodes   */
 379   /*********************************/
 380
 381   container keystore {
 382     if-feature central-keystore-supported;
 383     description
 384       "A central keystore containing a list of symmetric keys and
 385        a list of asymmetric keys.";
 386     nacm:default-deny-write;
 387     uses keystore-grouping {
 388       augment "symmetric-keys/symmetric-key/key-type/encrypted-key/"
 389             + "encrypted-key/encrypted-by" {
 390         description
 391           "Augments in a choice statement enabling the encrypting
 392            key to be any other symmetric or asymmetric key in the
 393            central keystore.";
 394         uses encrypted-by-grouping;
 395       }
 396       augment "asymmetric-keys/asymmetric-key/private-key-type/"
 397             + "encrypted-private-key/encrypted-private-key/"
 398             + "encrypted-by" {
 399         description
 400           "Augments in a choice statement enabling the encrypting
 401            key to be any other symmetric or asymmetric key in the
 402            central keystore.";
 403         uses encrypted-by-grouping;
 404       }
 405     }
 406   }
 407 }