truststore/truststore-api/src/main/yang/ietf-truststore@2024-02-08.yang

   1 module ietf-truststore {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-truststore";
   4   prefix ts;
   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 <kent+ietf@watsen.net>";
  25
  26   description
  27     "This module defines a 'truststore' to centralize management
  28      of trust anchors including certificates and public keys.
  29
  30      Copyright (c) 2024 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 BBBB
  41      (https://www.rfc-editor.org/info/rfcBBBB); 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 2024-02-08 {
  52     description
  53       "Initial version";
  54     reference
  55       "RFC BBBB: A YANG Data Model for a Truststore";
  56   }
  57
  58   /****************/
  59   /*   Features   */
  60   /****************/
  61
  62   feature central-truststore-supported {
  63     description
  64       "The 'central-truststore-supported' feature indicates that
  65        the server supports the truststore (i.e., implements the
  66        'ietf-truststore' module).";
  67   }
  68
  69   feature inline-definitions-supported {
  70     description
  71       "The 'inline-definitions-supported' feature indicates that
  72        the server supports locally-defined trust anchors.";
  73   }
  74
  75   feature certificates {
  76     description
  77       "The 'certificates' feature indicates that the server
  78        implements the /truststore/certificate-bags subtree.";
  79   }
  80
  81   feature public-keys {
  82     description
  83       "The 'public-keys' feature indicates that the server
  84        implements the /truststore/public-key-bags subtree.";
  85   }
  86
  87   /****************/
  88   /*   Typedefs   */
  89   /****************/
  90
  91   typedef central-certificate-bag-ref {
  92     type leafref {
  93       path "/ts:truststore/ts:certificate-bags/"
  94          + "ts:certificate-bag/ts:name";
  95     }
  96     description
  97       "This typedef defines a reference to a certificate bag
  98        in the central truststore.";
  99   }
 100
 101   typedef central-certificate-ref {
 102     type leafref {
 103       path "/ts:truststore/ts:certificate-bags/ts:certificate-bag"
 104          + "[ts:name = current()/../certificate-bag]/"
 105          + "ts:certificate/ts:name";
 106     }
 107     description
 108       "This typedef defines a reference to a specific certificate
 109        in a certificate bag in the central truststore. This typedef
 110        requires that there exist a sibling 'leaf' node called
 111        'certificate-bag' that SHOULD have the typedef
 112        'central-certificate-bag-ref'.";
 113   }
 114
 115   typedef central-public-key-bag-ref {
 116     type leafref {
 117       path "/ts:truststore/ts:public-key-bags/"
 118          + "ts:public-key-bag/ts:name";
 119     }
 120     description
 121       "This typedef defines a reference to a public key bag
 122        in the central truststore.";
 123   }
 124
 125   typedef central-public-key-ref {
 126     type leafref {
 127       path "/ts:truststore/ts:public-key-bags/ts:public-key-bag"
 128          + "[ts:name = current()/../public-key-bag]/"
 129          + "ts:public-key/ts:name";
 130     }
 131     description
 132       "This typedef defines a reference to a specific public key
 133        in a public key bag in the truststore.  This typedef
 134        requires that there exist a sibling 'leaf' node called
 135        'public-key-bag' that SHOULD have the typedef
 136        'central-public-key-bag-ref'.";
 137   }
 138
 139   /*****************/
 140   /*   Groupings   */
 141   /*****************/
 142
 143   // *-ref groupings
 144
 145   grouping central-certificate-ref-grouping {
 146     description
 147       "Grouping for the reference to a certificate in a
 148        certificate-bag in the central truststore.";
 149     leaf certificate-bag {
 150       nacm:default-deny-write;
 151       if-feature "central-truststore-supported";
 152       if-feature "certificates";
 153       type ts:central-certificate-bag-ref;
 154       must "../certificate";
 155       description
 156         "Reference to a certificate-bag in the truststore.";
 157     }
 158     leaf certificate {
 159       nacm:default-deny-write;
 160       if-feature "central-truststore-supported";
 161       if-feature "certificates";
 162       type ts:central-certificate-ref;
 163       must "../certificate-bag";
 164       description
 165         "Reference to a specific certificate in the
 166          referenced certificate-bag.";
 167     }
 168   }
 169
 170   grouping central-public-key-ref-grouping {
 171     description
 172       "Grouping for the reference to a public key in a
 173        public-key-bag in the central truststore.";
 174     leaf public-key-bag {
 175       nacm:default-deny-write;
 176       if-feature "central-truststore-supported";
 177       if-feature "public-keys";
 178       type ts:central-public-key-bag-ref;
 179       description
 180         "Reference of a public key bag in the truststore including
 181          the certificate to authenticate the TLS client.";
 182     }
 183     leaf public-key {
 184       nacm:default-deny-write;
 185       if-feature "central-truststore-supported";
 186       if-feature "public-keys";
 187       type ts:central-public-key-ref;
 188       description
 189         "Reference to a specific public key in the
 190          referenced public-key-bag.";
 191     }
 192   }
 193
 194   // inline-or-truststore-* groupings
 195
 196   grouping inline-or-truststore-certs-grouping {
 197     description
 198       "A grouping for the configuration of a list of certificates.
 199        The list of certificate may be defined inline or as a
 200        reference to a certificate bag in the central truststore.
 201
 202        Servers that wish to define alternate truststore locations
 203        MUST augment in custom 'case' statements enabling
 204        references to those alternate truststore locations.";
 205     choice inline-or-truststore {
 206       nacm:default-deny-write;
 207       mandatory true;
 208       description
 209         "A choice between an inlined definition and a definition
 210          that exists in the truststore.";
 211       case inline {
 212         if-feature "inline-definitions-supported";
 213         container inline-definition {
 214           description
 215             "A container for locally configured trust anchor
 216              certificates.";
 217           list certificate {
 218             key "name";
 219             min-elements 1;
 220             description
 221               "A trust anchor certificate or chain of certificates.";
 222             leaf name {
 223               type string;
 224               description
 225                 "An arbitrary name for this certificate.";
 226             }
 227             uses ct:trust-anchor-cert-grouping {
 228               refine "cert-data" {
 229                 mandatory true;
 230               }
 231             }
 232           }
 233         }
 234       }
 235       case central-truststore {
 236         if-feature "central-truststore-supported";
 237         if-feature "certificates";
 238         leaf central-truststore-reference {
 239           type ts:central-certificate-bag-ref;
 240           description
 241             "A reference to a certificate bag that exists in the
 242              central truststore.";
 243         }
 244       }
 245     }
 246   }
 247
 248   grouping inline-or-truststore-public-keys-grouping {
 249     description
 250       "A grouping that allows the public keys to be either
 251        configured locally, within the using data model, or be a
 252        reference to a public key bag stored in the truststore.
 253
 254        Servers that wish to define alternate truststore locations
 255        SHOULD augment in custom 'case' statements enabling
 256        references to those alternate truststore locations.";
 257     choice inline-or-truststore {
 258       nacm:default-deny-write;
 259       mandatory true;
 260       description
 261         "A choice between an inlined definition and a definition
 262          that exists in the truststore.";
 263       case inline {
 264         if-feature "inline-definitions-supported";
 265         container inline-definition {
 266           description
 267             "A container to hold local public key definitions.";
 268           list public-key {
 269             key "name";
 270             description
 271               "A public key definition.";
 272             leaf name {
 273               type string;
 274               description
 275                 "An arbitrary name for this public key.";
 276             }
 277             uses ct:public-key-grouping;
 278           }
 279         }
 280       }
 281       case central-truststore {
 282         if-feature "central-truststore-supported";
 283         if-feature "public-keys";
 284         leaf central-truststore-reference {
 285           type ts:central-public-key-bag-ref;
 286           description
 287             "A reference to a bag of public keys that exists
 288              in the central truststore.";
 289         }
 290       }
 291     }
 292   }
 293
 294
 295   // the truststore grouping
 296
 297   grouping truststore-grouping {
 298     description
 299       "A grouping definition that enables use in other contexts.
 300        Where used, implementations MUST augment new 'case'
 301        statements into the various inline-or-truststore 'choice'
 302        statements to supply leafrefs to the model-specific
 303        location(s).";
 304     container certificate-bags {
 305       nacm:default-deny-write;
 306       if-feature "certificates";
 307       description
 308         "A collection of certificate bags.";
 309       list certificate-bag {
 310         key "name";
 311         description
 312           "A bag of certificates.  Each bag of certificates should
 313            be for a specific purpose.  For instance, one bag could
 314            be used to authenticate a specific set of servers, while
 315            another could be used to authenticate a specific set of
 316            clients.";
 317         leaf name {
 318           type string;
 319           description
 320             "An arbitrary name for this bag of certificates.";
 321         }
 322         leaf description {
 323           type string;
 324           description
 325             "A description for this bag of certificates.  The
 326              intended purpose for the bag SHOULD be described.";
 327         }
 328         list certificate {
 329           key "name";
 330           description
 331             "A trust anchor certificate or chain of certificates.";
 332           leaf name {
 333             type string;
 334             description
 335               "An arbitrary name for this certificate.";
 336           }
 337           uses ct:trust-anchor-cert-grouping {
 338             refine "cert-data" {
 339               mandatory true;
 340             }
 341           }
 342         }
 343       }
 344     }
 345     container public-key-bags {
 346       nacm:default-deny-write;
 347       if-feature "public-keys";
 348       description
 349         "A collection of public key bags.";
 350       list public-key-bag {
 351         key "name";
 352         description
 353           "A bag of public keys.  Each bag of keys SHOULD be for
 354            a specific purpose.  For instance, one bag could be used
 355            authenticate a specific set of servers, while another
 356            could be used to authenticate a specific set of clients.";
 357         leaf name {
 358           type string;
 359           description
 360             "An arbitrary name for this bag of public keys.";
 361         }
 362         leaf description {
 363           type string;
 364           description
 365             "A description for this bag public keys.  The
 366              intended purpose for the bag MUST be described.";
 367         }
 368         list public-key {
 369           key "name";
 370           description
 371             "A public key.";
 372           leaf name {
 373             type string;
 374             description
 375               "An arbitrary name for this public key.";
 376           }
 377           uses ct:public-key-grouping;
 378         }
 379       }
 380     }
 381   }
 382
 383   /*********************************/
 384   /*   Protocol accessible nodes   */
 385   /*********************************/
 386
 387   container truststore {
 388     if-feature central-truststore-supported;
 389     nacm:default-deny-write;
 390     description
 391       "The truststore contains bags of certificates and
 392        public keys.";
 393     uses truststore-grouping;
 394   }
 395 }