truststore/truststore-api/src/main/yang/ietf-truststore@2023-12-28.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) 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 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 2023-12-28 {
  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 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 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        'certificate-bag-ref'.";
 113   }
 114
 115   typedef 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 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        'public-key-bag-ref'.";
 137   }
 138
 139   /*****************/
 140   /*   Groupings   */
 141   /*****************/
 142
 143   // *-ref groupings
 144
 145   grouping 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: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
 161       // FIXME: these two lines are missing in the published model
 162       if-feature "central-truststore-supported";
 163       if-feature "certificates";
 164
 165       type ts:certificate-ref;
 166       must "../certificate-bag";
 167       description
 168         "Reference to a specific certificate in the
 169          referenced certificate-bag.";
 170     }
 171   }
 172
 173   grouping public-key-ref-grouping {
 174     description
 175       "Grouping for the reference to a public key in a
 176        public-key-bag in the central truststore.";
 177     leaf public-key-bag {
 178       nacm:default-deny-write;
 179       if-feature "central-truststore-supported";
 180       if-feature "public-keys";
 181       type ts:public-key-bag-ref;
 182       description
 183         "Reference of a public key bag in the truststore inlucding
 184          the certificate to authenticate the TLS client.";
 185     }
 186     leaf public-key {
 187       nacm:default-deny-write;
 188
 189       // FIXME: these two lines are missing in the published model
 190       if-feature "central-truststore-supported";
 191       if-feature "public-keys";
 192
 193       type ts:public-key-ref;
 194       description
 195         "Reference to a specific public key in the
 196          referenced public-key-bag.";
 197     }
 198   }
 199
 200   // inline-or-truststore-* groupings
 201
 202   grouping inline-or-truststore-certs-grouping {
 203     description
 204       "A grouping for the configuration of a list of certificates.
 205        The list of certificate may be defined inline or as a
 206        reference to a certificate bag in the central truststore.
 207
 208        Servers that do not define the 'central-truststore-supported'
 209        feature SHOULD augment in custom 'case' statements enabling
 210        references to alternate truststore locations.";
 211     choice inline-or-truststore {
 212       nacm:default-deny-write;
 213       mandatory true;
 214       description
 215         "A choice between an inlined definition and a definition
 216          that exists in the truststore.";
 217       case inline {
 218         if-feature "inline-definitions-supported";
 219         container inline-definition {
 220           description
 221             "A container for locally configured trust anchor
 222              certificates.";
 223           list certificate {
 224             key "name";
 225             min-elements 1;
 226             description
 227               "A trust anchor certificate.";
 228             leaf name {
 229               type string;
 230               description
 231                 "An arbitrary name for this certificate.";
 232             }
 233             uses ct:trust-anchor-cert-grouping {
 234               refine "cert-data" {
 235                 mandatory true;
 236               }
 237             }
 238           }
 239         }
 240       }
 241       case central-truststore {
 242         if-feature "central-truststore-supported";
 243         if-feature "certificates";
 244         leaf central-truststore-reference {
 245           type ts:certificate-bag-ref;
 246           description
 247             "A reference to a certificate bag that exists in the
 248              central truststore.";
 249         }
 250       }
 251     }
 252   }
 253
 254   grouping inline-or-truststore-public-keys-grouping {
 255     description
 256       "A grouping that allows the public keys to be either
 257        configured locally, within the using data model, or be a
 258        reference to a public key bag stored in the truststore.
 259
 260        Servers that do not define the 'central-truststore-supported'
 261        feature SHOULD augment in custom 'case' statements enabling
 262        references to alternate truststore locations.";
 263     choice inline-or-truststore {
 264       nacm:default-deny-write;
 265       mandatory true;
 266       description
 267         "A choice between an inlined definition and a definition
 268          that exists in the truststore.";
 269       case inline {
 270         if-feature "inline-definitions-supported";
 271         container inline-definition {
 272           description
 273             "A container to hold local public key definitions.";
 274           list public-key {
 275             key "name";
 276             description
 277               "A public key definition.";
 278             leaf name {
 279               type string;
 280               description
 281                 "An arbitrary name for this public key.";
 282             }
 283             uses ct:public-key-grouping;
 284           }
 285         }
 286       }
 287       case central-truststore {
 288         if-feature "central-truststore-supported";
 289         if-feature "public-keys";
 290         leaf central-truststore-reference {
 291           type ts:public-key-bag-ref;
 292           description
 293             "A reference to a bag of public keys that exists
 294              in the central truststore.";
 295         }
 296       }
 297     }
 298   }
 299
 300
 301   // the truststore grouping
 302
 303   grouping truststore-grouping {
 304     description
 305       "A grouping definition that enables use in other contexts.
 306        Where used, implementations MUST augment new 'case'
 307        statements into the various inline-or-truststore 'choice'
 308        statements to supply leafrefs to the model-specific
 309        location(s).";
 310     container certificate-bags {
 311       nacm:default-deny-write;
 312       if-feature "certificates";
 313       description
 314         "A collection of certificate bags.";
 315       list certificate-bag {
 316         key "name";
 317         description
 318           "A bag of certificates.  Each bag of certificates SHOULD
 319            be for a specific purpose.  For instance, one bag could
 320            be used to authenticate a specific set of servers, while
 321            another could be used to authenticate a specific set of
 322            clients.";
 323         leaf name {
 324           type string;
 325           description
 326             "An arbitrary name for this bag of certificates.";
 327         }
 328         leaf description {
 329           type string;
 330           description
 331             "A description for this bag of certificates.  The
 332              intended purpose for the bag SHOULD be described.";
 333         }
 334         list certificate {
 335           key "name";
 336           description
 337             "A trust anchor certificate.";
 338           leaf name {
 339             type string;
 340             description
 341               "An arbitrary name for this certificate.";
 342           }
 343           uses ct:trust-anchor-cert-grouping {
 344             refine "cert-data" {
 345               mandatory true;
 346             }
 347           }
 348         }
 349       }
 350     }
 351     container public-key-bags {
 352       nacm:default-deny-write;
 353       if-feature "public-keys";
 354       description
 355         "A collection of public key bags.";
 356       list public-key-bag {
 357         key "name";
 358         description
 359           "A bag of public keys.  Each bag of keys SHOULD be for
 360            a specific purpose.  For instance, one bag could be used
 361            authenticate a specific set of servers, while another
 362            could be used to authenticate a specific set of clients.";
 363         leaf name {
 364           type string;
 365           description
 366             "An arbitrary name for this bag of public keys.";
 367         }
 368         leaf description {
 369           type string;
 370           description
 371             "A description for this bag public keys.  The
 372              intended purpose for the bag SHOULD be described.";
 373         }
 374         list public-key {
 375           key "name";
 376           description
 377             "A public key.";
 378           leaf name {
 379             type string;
 380             description
 381               "An arbitrary name for this public key.";
 382           }
 383           uses ct:public-key-grouping;
 384         }
 385       }
 386     }
 387   }
 388
 389   /*********************************/
 390   /*   Protocol accessible nodes   */
 391   /*********************************/
 392
 393   container truststore {
 394     if-feature central-truststore-supported;
 395     nacm:default-deny-write;
 396     description
 397       "The truststore contains bags of certificates and
 398        public keys.";
 399     uses truststore-grouping;
 400   }
 401 }