idnits 2.17.1 draft-ietf-netconf-crypto-types-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 318 has weird spacing: '...d-value bin...' == Line 364 has weird spacing: '...d-value bin...' == Line 393 has weird spacing: '...-format ide...' == Line 440 has weird spacing: '...d-value bin...' == Line 472 has weird spacing: '...on-date yan...' == (18 more instances...) -- The document date (8 July 2020) is 1381 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X680.2015' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.2015' ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-15 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-03 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) Summary: 1 error (**), 0 flaws (~~), 16 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track 8 July 2020 5 Expires: 9 January 2021 7 YANG Data Types and Groupings for Cryptography 8 draft-ietf-netconf-crypto-types-16 10 Abstract 12 This document presents a YANG 1.1 (RFC 7950) module defining 13 identities, typedefs, and groupings useful to cryptographic 14 applications. 16 Editorial Note (To be removed by RFC Editor) 18 This draft contains placeholder values that need to be replaced with 19 finalized values at the time of publication. This note summarizes 20 all of the substitutions that are needed. No other RFC Editor 21 instructions are specified elsewhere in this document. 23 Artwork in this document contains shorthand references to drafts in 24 progress. Please apply the following replacements: 26 * "AAAA" --> the assigned RFC value for this draft 28 Artwork in this document contains placeholder values for the date of 29 publication of this draft. Please apply the following replacement: 31 * "2020-07-08" --> the publication date of this draft 33 The following Appendix section is to be removed prior to publication: 35 * Appendix A. Change Log 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on 9 January 2021. 54 Copyright Notice 56 Copyright (c) 2020 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 61 license-info) in effect on the date of publication of this document. 62 Please review these documents carefully, as they describe your rights 63 and restrictions with respect to this document. Code Components 64 extracted from this document must include Simplified BSD License text 65 as described in Section 4.e of the Trust Legal Provisions and are 66 provided without warranty as described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 3 72 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 73 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 74 2. The "ietf-crypto-types" Module . . . . . . . . . . . . . . . 5 75 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 5 76 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 16 77 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 23 78 3. Security Considerations . . . . . . . . . . . . . . . . . . . 41 79 3.1. No Support for CRMF . . . . . . . . . . . . . . . . . . . 41 80 3.2. No Support for Key Generation . . . . . . . . . . . . . . 41 81 3.3. Deletion of Cleartext Key Values . . . . . . . . . . . . 41 82 3.4. The "ietf-crypto-types" YANG Module . . . . . . . . . . . 41 83 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 84 4.1. Update the "IETF XML" Registry . . . . . . . . . . . . . 43 85 4.2. Update the "YANG Module Names" Registry . . . . . . . . . 43 86 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 87 5.1. Normative References . . . . . . . . . . . . . . . . . . 43 88 5.2. Informative References . . . . . . . . . . . . . . . . . 44 89 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 90 A.1. I-D to 00 . . . . . . . . . . . . . . . . . . . . . . . . 47 91 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 47 92 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 47 93 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 48 94 A.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 49 95 A.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 49 96 A.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 49 97 A.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 49 98 A.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 50 99 A.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 50 100 A.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 50 101 A.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 51 102 A.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 51 103 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 51 104 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 51 105 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 51 106 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 52 107 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 53 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 53 110 1. Introduction 112 This document presents a YANG 1.1 [RFC7950] module defining 113 identities, typedefs, and groupings useful to cryptographic 114 applications. 116 1.1. Relation to other RFCs 118 This document presents one or more YANG modules [RFC7950] that are 119 part of a collection of RFCs that work together to define 120 configuration modules for clients and servers of both the NETCONF 121 [RFC6241] and RESTCONF [RFC8040] protocols. 123 The modules have been defined in a modular fashion to enable their 124 use by other efforts, some of which are known to be in progress at 125 the time of this writing, with many more expected to be defined in 126 time. 128 The relationship between the various RFCs in the collection is 129 presented in the below diagram. The labels in the diagram represent 130 the primary purpose provided by each RFC. Links the each RFC are 131 provided below the diagram. 133 crypto-types 134 ^ ^ 135 / \ 136 / \ 137 truststore keystore 138 ^ ^ ^ ^ 139 | +---------+ | | 140 | | | | 141 | +------------+ | 142 tcp-client-server | / | | 143 ^ ^ ssh-client-server | | 144 | | ^ tls-client-server 145 | | | ^ ^ http-client-server 146 | | | | | ^ 147 | | | +-----+ +---------+ | 148 | | | | | | 149 | +-----------|--------|--------------+ | | 150 | | | | | | 151 +-----------+ | | | | | 152 | | | | | | 153 | | | | | | 154 netconf-client-server restconf-client-server 156 +=======================+===========================================+ 157 | Label in Diagram | Originating RFC | 158 +=======================+===========================================+ 159 | crypto-types | [I-D.ietf-netconf-crypto-types] | 160 +-----------------------+-------------------------------------------+ 161 | truststore | [I-D.ietf-netconf-trust-anchors] | 162 +-----------------------+-------------------------------------------+ 163 | keystore | [I-D.ietf-netconf-keystore] | 164 +-----------------------+-------------------------------------------+ 165 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 166 +-----------------------+-------------------------------------------+ 167 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 168 +-----------------------+-------------------------------------------+ 169 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 170 +-----------------------+-------------------------------------------+ 171 | http-client-server | [I-D.ietf-netconf-http-client-server] | 172 +-----------------------+-------------------------------------------+ 173 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 174 +-----------------------+-------------------------------------------+ 175 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 176 +-----------------------+-------------------------------------------+ 178 Table 1: Label to RFC Mapping 180 1.2. Specification Language 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 184 "OPTIONAL" in this document are to be interpreted as described in BCP 185 14 [RFC2119] [RFC8174] when, and only when, they appear in all 186 capitals, as shown here. 188 1.3. Adherence to the NMDA 190 This document in compliant with the Network Management Datastore 191 Architecture (NMDA) [RFC8342]. It does not define any protocol 192 accessible nodes that are "config false". 194 2. The "ietf-crypto-types" Module 196 This section defines a YANG 1.1 [RFC7950] module that defines data 197 types (typedefs and identities) and groupings supporting downstream 198 models needing cryptographic primitives. 200 2.1. Data Model Overview 202 2.1.1. Features 204 The following diagram lists all the "feature" statements defined in 205 the "ietf-crypt-types" module: 207 Features: 208 +-- one-symmetric-key-format 209 +-- one-asymmetric-key-format 210 +-- encrypted-one-symmetric-key-format 211 +-- encrypted-one-asymmetric-key-format 212 +-- certificate-signing-request-generation 214 2.1.2. Identities 216 The following diagram illustrates the relationship amongst the 217 "identity" statements defined in the "ietf-crypto-types" module: 219 Identities: 220 +-- public-key-format 221 | +-- subject-public-key-info-format 222 | +-- ssh-public-key-format 223 +-- private-key-format 224 | +-- rsa-private-key-format 225 | +-- ec-private-key-format 226 | +-- one-asymmetric-key-format 227 | | {one-asymmetric-key-format}? 228 | +-- encrypted-one-asymmetric-key-format 229 | {encrypted-one-asymmetric-key-format}? 230 +-- symmetric-key-format 231 +-- octet-string-key-format 232 +-- one-symmetric-key-format 233 | {one-symmetric-key-format}? 234 +-- encrypted-one-symmetric-key-format 235 {encrypted-one-symmetric-key-format}? 237 Comments: 239 * The diagram shows that there are three base identities. These 240 identities are used by this module to define the format that key 241 data is encoded in. The base identities are "abstract", in the 242 object orientied programming sense, in that they only define a 243 "class" of formats, rather than a specific format. 245 * The various derived identities define specific key encoding 246 formats. The derived identities defined in this document are 247 sufficient for the effort described in Section 1.1 but, by nature 248 of them being identities, additional derived identities MAY be 249 defined by future efforts. 251 * Identities use to specify uncommon formats are enabled by 252 "feature" statements, enabling applications to support them when 253 needed. 255 2.1.3. Typedefs 257 The following diagram illustrates the relationship amongst the 258 "typedef" statements defined in the "ietf-crypto-types" module: 260 Typedefs: 261 binary 262 +-- csr-info 263 +-- csr 264 +-- x509 265 | +-- trust-anchor-cert-x509 266 | +-- end-entity-cert-x509 267 +-- crl 268 +-- ocsp-request 269 +-- ocsp-response 270 +-- cms 271 +-- data-content-cms 272 +-- signed-data-cms 273 | +-- trust-anchor-cert-cms 274 | +-- end-entity-cert-cms 275 +-- enveloped-data-cms 276 +-- digested-data-cms 277 +-- encrypted-data-cms 278 +-- authenticated-data-cms 280 Comments: 282 * All of the typedefs defined in the "ietf-crypto-types" module 283 extend the "binary" type defined in [RFC7950]. 285 * Additionally, all the typedefs define a type for encoding an ASN.1 286 [ITU.X680.2015] structure using DER [ITU.X690.2015]. 288 * The "trust-anchor-*" and "end-entity-*" typedefs are syntactically 289 identical to their base typedefs and only distiguish themselves by 290 the expected nature of their content. These typedefs are defined 291 to facilitate common modeling needs. 293 2.1.4. Groupings 295 The following diagram lists all the "grouping" statements defined in 296 the "ietf-crypto-types" module: 298 Groupings: 299 +-- encrypted-key-value-grouping 300 +-- symmetric-key-grouping 301 +-- public-key-grouping 302 +-- asymmetric-key-pair-grouping 303 +-- trust-anchor-cert-grouping 304 +-- end-entity-cert-grouping 305 +-- generate-csr-grouping 306 +-- asymmetric-key-pair-with-cert-grouping 307 +-- asymmetric-key-pair-with-certs-grouping 309 Each of these groupings are presented in the following subsections. 311 2.1.4.1. The "encrypted-key-value-grouping" Grouping 313 The following tree diagram [RFC8340] illustrates the "encrypted-key- 314 value-grouping" grouping: 316 grouping encrypted-key-value-grouping 317 +-- encrypted-by 318 +-- encrypted-value binary 320 Comments: 322 * The "encrypted-by" node is an empty container (difficult to see in 323 the diagram) that a consuming module MUST augment key references 324 into. The "ietf-crypto-types" module is unable to populate this 325 container as the module only defines groupings. Section 2.2.1 326 presents an example illustrating a consuming module populating the 327 "encrypted-by" container. 329 * The "encrypted-value" node is the key, encrypted by the other key 330 referenced by the "encrypted-by" node, encoded in the format 331 specified by the "format" identity Section 2.1.2 associated with 332 the ancestor node using this grouping. 334 2.1.4.2. The "symmetric-key-grouping" Grouping 336 This section presents two tree diagrams [RFC8340] illustrating the 337 "symmetric-key-grouping" grouping. The first tree diagram does not 338 expand the internally used grouping statement(s): 340 grouping symmetric-key-grouping 341 +-- key-format? identityref 342 +-- (key-type) 343 +--:(key) 344 | +-- key? binary 345 +--:(hidden-key) 346 | +-- hidden-key? empty 347 +--:(encrypted-key) 348 +-- encrypted-key 349 +---u encrypted-key-value-grouping 351 The following tree diagram expands the internally used grouping 352 statement(s), enabling the grouping's full structure to be seen: 354 grouping symmetric-key-grouping 355 +-- key-format? identityref 356 +-- (key-type) 357 +--:(key) 358 | +-- key? binary 359 +--:(hidden-key) 360 | +-- hidden-key? empty 361 +--:(encrypted-key) 362 +-- encrypted-key 363 +-- encrypted-by 364 +-- encrypted-value binary 366 Comments: 368 * For the referenced grouping statement(s): 370 - The "encrypted-key-value-grouping" grouping is discussed in 371 Section 2.1.4.1. 373 * The "key-format" node is an identity-reference to the "symmetric- 374 key-format" abstract base identity discussed in Section 2.1.2, 375 enabling the symmetric key to be encoded using the format defined 376 by any of the derived identities. 378 * The "choice" statement enables the private key data to be plain- 379 text, encrypted, or hidden, as follows: 381 - The "key" node can encode any plain-text key value. 382 - The "hidden-key" node is of type "empty" as the real value 383 cannot be presented via the management interface. 384 - The "encrypted-key" node's structure is discussed in 385 Section 2.1.4.1. 387 2.1.4.3. The "public-key-grouping" Grouping 389 The following tree diagram [RFC8340] illustrates the "public-key- 390 grouping" grouping: 392 grouping public-key-grouping 393 +-- public-key-format identityref 394 +-- public-key binary 396 Comments: 398 * The "public-key-format" node is an identity-reference to the 399 "public-key-format" abstract base identity discussed in 400 Section 2.1.2, enabling the public key to be encoded using the 401 format defined by any of the derived identities. 403 * The "public-key" node is the public key data in the selected 404 format. No "choice" statement is used to hide or encrypt the 405 public key data because it is unecessary to do so for public keys. 407 2.1.4.4. The "asymmetric-key-pair-grouping" Grouping 409 This section presents two tree diagrams [RFC8340] illustrating the 410 "asymmetric-key-pair-grouping" grouping. The first tree diagram does 411 not expand the internally used grouping statement(s): 413 grouping asymmetric-key-pair-grouping 414 +---u public-key-grouping 415 +-- private-key-format? identityref 416 +-- (private-key-type) 417 +--:(private-key) 418 | +-- private-key? binary 419 +--:(hidden-private-key) 420 | +-- hidden-private-key? empty 421 +--:(encrypted-private-key) 422 +-- encrypted-private-key 423 +---u encrypted-key-value-grouping 425 The following tree diagram expands the internally used grouping 426 statement(s), enabling the grouping's full structure to be seen: 428 grouping asymmetric-key-pair-grouping 429 +-- public-key-format identityref 430 +-- public-key binary 431 +-- private-key-format? identityref 432 +-- (private-key-type) 433 +--:(private-key) 434 | +-- private-key? binary 435 +--:(hidden-private-key) 436 | +-- hidden-private-key? empty 437 +--:(encrypted-private-key) 438 +-- encrypted-private-key 439 +-- encrypted-by 440 +-- encrypted-value binary 442 Comments: 444 * For the referenced grouping statement(s): 446 - The "public-key-grouping" grouping is discussed in 447 Section 2.1.4.3. 448 - The "encrypted-key-value-grouping" grouping is discussed in 449 Section 2.1.4.1. 451 * The "private-key-format" node is an identity-reference to the 452 "private-key-format" abstract base identity discussed in 453 Section 2.1.2, enabling the private key to be encoded using the 454 format defined by any of the derived identities. 456 * The "choice" statement enables the private key data to be plain- 457 text, encrypted, or hidden, as follows: 459 - The "private-key" node can encode any plain-text key value. 460 - The "hidden-private-key" node is of type "empty" as the real 461 value cannot be presented via the management interface. 462 - The "encrypted-private-key" node's structure is discussed in 463 Section 2.1.4.1. 465 2.1.4.5. The "certificate-expiration-grouping" Grouping 467 The following tree diagram [RFC8340] illustrates the "certificate- 468 expiration-grouping" grouping: 470 grouping certificate-expiration-grouping 471 +---n certificate-expiration 472 +-- expiration-date yang:date-and-time 474 Comments: 476 * This grouping's only purpose is to define the "certificate- 477 expiration" notification statement, used by the groupings defined 478 in Section 2.1.4.6 and Section 2.1.4.7. 480 * The "certificate-expiration" notification enables servers to 481 notify clients when certificates are nearing expiration. 483 * The "expiration-date" node indicates when the designated 484 certificate will (or did) expire. 486 * Identification of the certificate that is expiring is built into 487 the notification itself. For an example, please see 488 Section 2.2.3. 490 2.1.4.6. The "trust-anchor-cert-grouping" Grouping 492 This section presents two tree diagrams [RFC8340] illustrating the 493 "trust-anchor-cert-grouping" grouping. The first tree diagram does 494 not expand the internally used grouping statement(s): 496 grouping trust-anchor-cert-grouping 497 +-- cert-data? trust-anchor-cert-cms 498 +---u certificate-expiration-grouping 500 The following tree diagram expands the internally used grouping 501 statement(s), enabling the grouping's full structure to be seen: 503 grouping trust-anchor-cert-grouping 504 +-- cert-data? trust-anchor-cert-cms 505 +---n certificate-expiration 506 +-- expiration-date yang:date-and-time 508 Comments: 510 * For the referenced grouping statement(s): 512 - The "certificate-expiration-grouping" grouping is discussed in 513 Section 2.1.4.5. 515 * The "cert-data" node contains a chain of one or more certificates 516 encoded using a "signed-data-cms" typedef discussed in 517 Section 2.1.3. 519 2.1.4.7. The "end-entity-cert-grouping" Grouping 521 This section presents two tree diagrams [RFC8340] illustrating the 522 "end-entity-cert-grouping" grouping. The first tree diagram does not 523 expand the internally used grouping statement(s): 525 grouping end-entity-cert-grouping 526 +-- cert-data? end-entity-cert-cms 527 +---u certificate-expiration-grouping 529 The following tree diagram expands the internally used grouping 530 statement(s), enabling the grouping's full structure to be seen: 532 grouping end-entity-cert-grouping 533 +-- cert-data? end-entity-cert-cms 534 +---n certificate-expiration 535 +-- expiration-date yang:date-and-time 537 Comments: 539 * For the referenced grouping statement(s): 541 - The "certificate-expiration-grouping" grouping is discussed in 542 Section 2.1.4.5. 544 * The "cert-data" node contains a chain of one or more certificates 545 encoded using a "signed-data-cms" typedef discussed in 546 Section 2.1.3. 548 2.1.4.8. The "generate-csr-grouping" Grouping 550 The following tree diagram [RFC8340] illustrates the "generate-csr- 551 grouping" grouping: 553 grouping generate-csr-grouping 554 +---x generate-certificate-signing-request 555 {certificate-signing-request-generation}? 556 +---w input 557 | +---w csr-info ct:csr-info 558 +--ro output 559 +--ro certificate-signing-request ct:csr 561 Comments: 563 * This grouping's only purpose is to define the "generate- 564 certificate-signing-request" action statement, used by the 565 groupings defined in Section 2.1.4.9 and Section 2.1.4.10. 567 * This action takes as input a "csr-info" type and returns a "csr" 568 type, both of which are discussed in Section 2.1.3. 570 * For an example, please see Section 2.2.2. 572 2.1.4.9. The "asymmetric-key-pair-with-cert-grouping" Grouping 574 This section presents two tree diagrams [RFC8340] illustrating the 575 "asymmetric-key-pair-with-cert-grouping" grouping. The first tree 576 diagram does not expand the internally used grouping statement(s): 578 grouping asymmetric-key-pair-with-cert-grouping 579 +---u asymmetric-key-pair-grouping 580 +---u end-entity-cert-grouping 581 +---u generate-csr-grouping 583 The following tree diagram expands the internally used grouping 584 statement(s), enabling the grouping's full structure to be seen: 586 grouping asymmetric-key-pair-with-cert-grouping 587 +-- public-key-format identityref 588 +-- public-key binary 589 +-- private-key-format? identityref 590 +-- (private-key-type) 591 | +--:(private-key) 592 | | +-- private-key? binary 593 | +--:(hidden-private-key) 594 | | +-- hidden-private-key? empty 595 | +--:(encrypted-private-key) 596 | +-- encrypted-private-key 597 | +-- encrypted-by 598 | +-- encrypted-value binary 599 +-- cert-data? end-entity-cert-cms 600 +---n certificate-expiration 601 | +-- expiration-date yang:date-and-time 602 +---x generate-certificate-signing-request 603 {certificate-signing-request-generation}? 604 +---w input 605 | +---w csr-info ct:csr-info 606 +--ro output 607 +--ro certificate-signing-request ct:csr 609 Comments: 611 * This grouping defines an asymmetric key with at most one 612 associated certificate, a commonly needed combination in protocol 613 models. 615 * For the referenced grouping statement(s): 617 - The "asymmetric-key-pair-grouping" grouping is discussed in 618 Section 2.1.4.4. 619 - The "end-entity-cert-grouping" grouping is discussed in 620 Section 2.1.4.7. 621 - The "generate-csr-grouping" grouping is discussed in 622 Section 2.1.4.8. 624 2.1.4.10. The "asymmetric-key-pair-with-certs-grouping" Grouping 626 This section presents two tree diagrams [RFC8340] illustrating the 627 "asymmetric-key-pair-with-certs-grouping" grouping. The first tree 628 diagram does not expand the internally used grouping statement(s): 630 grouping asymmetric-key-pair-with-certs-grouping 631 +---u asymmetric-key-pair-grouping 632 +-- certificates 633 | +-- certificate* [name] 634 | +-- name? string 635 | +---u end-entity-cert-grouping 636 +---u generate-csr-grouping 638 The following tree diagram expands the internally used grouping 639 statement(s), enabling the grouping's full structure to be seen: 641 grouping asymmetric-key-pair-with-certs-grouping 642 +-- public-key-format identityref 643 +-- public-key binary 644 +-- private-key-format? identityref 645 +-- (private-key-type) 646 | +--:(private-key) 647 | | +-- private-key? binary 648 | +--:(hidden-private-key) 649 | | +-- hidden-private-key? empty 650 | +--:(encrypted-private-key) 651 | +-- encrypted-private-key 652 | +-- encrypted-by 653 | +-- encrypted-value binary 654 +-- certificates 655 | +-- certificate* [name] 656 | +-- name? string 657 | +-- cert-data end-entity-cert-cms 658 | +---n certificate-expiration 659 | +-- expiration-date yang:date-and-time 660 +---x generate-certificate-signing-request 661 {certificate-signing-request-generation}? 662 +---w input 663 | +---w csr-info ct:csr-info 664 +--ro output 665 +--ro certificate-signing-request ct:csr 667 Comments: 669 * This grouping defines an asymmetric key with one or more 670 associated certificates, a commonly needed combination in 671 configuration models. 673 * For the referenced grouping statement(s): 675 - The "asymmetric-key-pair-grouping" grouping is discussed in 676 Section 2.1.4.4. 678 - The "end-entity-cert-grouping" grouping is discussed in 679 Section 2.1.4.7. 680 - The "generate-csr-grouping" grouping is discussed in 681 Section 2.1.4.8. 683 2.1.5. Protocol-accessible Nodes 685 The "ietf-crypto-types" module does not contain any protocol- 686 accessible nodes, but the module needs to be "implemented", as 687 described in Section 5.6.5 of [RFC7950], in order for the identities 688 in Section 2.1.2 to be defined. 690 2.2. Example Usage 692 2.2.1. The "symmetric-key-grouping" and "asymmetric-key-pair-with- 693 certs-grouping" Grouping 695 The following non-normative module is constructed in order to 696 illustrate the use of the "symmetric-key-grouping" (Section 2.1.4.2) 697 and the "asymmetric-key-pair-with-certs-grouping" (Section 2.1.4.10) 698 grouping statements: 700 module ex-crypto-types-usage { 701 yang-version 1.1; 703 namespace "http://example.com/ns/example-crypto-types-usage"; 704 prefix "ectu"; 706 import ietf-crypto-types { 707 prefix ct; 708 reference 709 "RFC AAAA: Common YANG Data Types for Cryptography"; 710 } 712 organization "Example Corporation"; 713 contact "YANG Designer "; 715 description 716 "This module illustrates the 'symmetric-key-grouping' 717 and 'asymmetric-key-grouping' groupings defined in 718 the 'ietf-crypto-types' module defined in RFC AAAA."; 720 revision "2020-07-08" { 721 description 722 "Initial version"; 723 reference 724 "RFC AAAA: Common YANG Data Types for Cryptography"; 725 } 726 container symmetric-keys { 727 description 728 "A container of symmetric keys."; 729 list symmetric-key { 730 key name; 731 description 732 "A symmetric key"; 733 leaf name { 734 type string; 735 description 736 "An arbitrary name for this key."; 737 } 738 uses ct:symmetric-key-grouping { 739 augment "key-type/encrypted-key/encrypted-key/" 740 + "encrypted-by" { 741 description 742 "Augments in a choice statement enabling the 743 encrypting key to be any other symmetric or 744 asymmetric key."; 745 uses encrypted-by-choice-grouping; 746 } 747 } 748 } 749 } 751 container asymmetric-keys { 752 description 753 "A container of asymmetric keys."; 754 list asymmetric-key { 755 key name; 756 leaf name { 757 type string; 758 description 759 "An arbitrary name for this key."; 760 } 761 uses ct:asymmetric-key-pair-with-certs-grouping { 762 augment "private-key-type/encrypted-private-key/" 763 + "encrypted-private-key/encrypted-by" { 764 description 765 "Augments in a choice statement enabling the 766 encrypting key to be any other symmetric or 767 asymmetric key."; 768 uses encrypted-by-choice-grouping; 769 } 770 } 771 description 772 "An asymmetric key pair with associated certificates."; 773 } 775 } 777 grouping encrypted-by-choice-grouping { 778 description 779 "A grouping that defines a choice enabling references 780 to other keys."; 781 choice encrypted-by-choice { 782 mandatory true; 783 description 784 "A choice amongst other symmetric or asymmetric keys."; 785 case symmetric-key-ref { 786 leaf symmetric-key-ref { 787 type leafref { 788 path "/ectu:symmetric-keys/ectu:symmetric-key/" 789 + "ectu:name"; 790 } 791 description 792 "Identifies the symmetric key used to encrypt this key."; 793 } 794 } 795 case asymmetric-key-ref { 796 leaf asymmetric-key-ref { 797 type leafref { 798 path "/ectu:asymmetric-keys/ectu:asymmetric-key/" 799 + "ectu:name"; 800 } 801 description 802 "Identifies the asymmetric key used to encrypt this key."; 803 } 804 } 805 } 806 } 807 } 809 The tree diagram [RFC8340] for this example module follows: 811 module: ex-crypto-types-usage 812 +--rw symmetric-keys 813 | +--rw symmetric-key* [name] 814 | +--rw name string 815 | +--rw key-format? identityref 816 | +--rw (key-type) 817 | +--:(key) 818 | | +--rw key? binary 819 | +--:(hidden-key) 820 | | +--rw hidden-key? empty 821 | +--:(encrypted-key) 822 | +--rw encrypted-key 823 | +--rw encrypted-by 824 | | +--rw (encrypted-by-choice) 825 | | +--:(symmetric-key-ref) 826 | | | +--rw symmetric-key-ref? leafref 827 | | +--:(asymmetric-key-ref) 828 | | +--rw asymmetric-key-ref? leafref 829 | +--rw encrypted-value binary 830 +--rw asymmetric-keys 831 +--rw asymmetric-key* [name] 832 +--rw name string 833 +--rw public-key-format identityref 834 +--rw public-key binary 835 +--rw private-key-format? identityref 836 +--rw (private-key-type) 837 | +--:(private-key) 838 | | +--rw private-key? binary 839 | +--:(hidden-private-key) 840 | | +--rw hidden-private-key? empty 841 | +--:(encrypted-private-key) 842 | +--rw encrypted-private-key 843 | +--rw encrypted-by 844 | | +--rw (encrypted-by-choice) 845 | | +--:(symmetric-key-ref) 846 | | | +--rw symmetric-key-ref? leafref 847 | | +--:(asymmetric-key-ref) 848 | | +--rw asymmetric-key-ref? leafref 849 | +--rw encrypted-value binary 850 +--rw certificates 851 | +--rw certificate* [name] 852 | +--rw name string 853 | +--rw cert-data end-entity-cert-cms 854 | +---n certificate-expiration 855 | +-- expiration-date yang:date-and-time 856 +---x generate-certificate-signing-request 857 {certificate-signing-request-generation}? 858 +---w input 859 | +---w csr-info ct:csr-info 860 +--ro output 861 +--ro certificate-signing-request ct:csr 863 grouping encrypted-by-choice-grouping 864 +-- (encrypted-by-choice) 865 +--:(symmetric-key-ref) 866 | +-- symmetric-key-ref? 867 | -> /symmetric-keys/symmetric-key/name 868 +--:(asymmetric-key-ref) 869 +-- asymmetric-key-ref? 870 -> /asymmetric-keys/asymmetric-key/name 872 Finally, the following example illustrates various symmetric and 873 asymmetric keys as they might appear in confugration: 875 =============== NOTE: '\' line wrapping per RFC 8792 ================ 877 880 881 ex-hidden-symmetric-key 882 883 884 885 ex-octet-string-based-symmetric-key 886 ct:octet-string-key-format 887 base64encodedvalue== 888 889 890 ex-one-symmetric-based-symmetric-key 891 ct:one-symmetric-key-format 892 base64encodedvalue== 893 894 895 ex-encrypted-one-symmetric-based-symmetric-key 896 ct:encrypted-one-symmetric-key-format 897 898 899 ex-hidden-asymmetric-key 901 902 base64encodedvalue== 903 904 905 907 910 911 ex-hidden-asymmetric-key 912 913 ct:subject-public-key-info-format 914 915 base64encodedvalue== 916 917 918 919 ex-hidden-asymmetric-key-cert 920 base64encodedvalue== 921 922 923 924 925 ex-subject-public-info-based-asymmetric-key 926 927 ct:subject-public-key-info-format 928 929 base64encodedvalue== 930 931 ct:rsa-private-key-format 932 933 base64encodedvalue== 934 935 936 ex-cert 937 base64encodedvalue== 938 939 940 941 942 ex-one-asymmetric-based-symmetric-key 943 944 ct:subject-public-key-info-format 945 946 base64encodedvalue== 947 948 ct:one-asymmetric-key-format 949 950 base64encodedvalue== 951 952 953 ex-encrypted-one-asymmetric-based-symmetric-key 954 955 ct:subject-public-key-info-format 956 957 base64encodedvalue== 958 959 ct:encrypted-one-asymmetric-key-format 960 961 962 963 ex-encrypted-one-symmetric-based-symmetri\ 964 c-key 965 966 base64encodedvalue== 967 969 970 972 2.2.2. The "generate-certificate-signing-request" Action 974 The following example illustrates the "generate-certificate-signing- 975 request" action, discussed in Section 2.1.4.8, with the NETCONF 976 protocol. 978 REQUEST 980 982 983 985 986 ex-key-sect571r1 987 988 base64encodedvalue== 989 990 991 992 993 995 RESPONSE 997 999 1001 base64encodedvalue== 1002 1003 1005 2.2.3. The "certificate-expiration" Notification 1007 The following example illustrates the "certificate-expiration" 1008 notification, discussed in Section 2.1.4.5, with the NETCONF 1009 protocol. 1011 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1013 1015 2018-05-25T00:01:00Z 1016 1018 1019 ex-hidden-asymmetric-key 1020 1021 1022 ex-hidden-asymmetric-key 1023 1024 2018-08-05T14:18:53-05:00 1026 1027 1028 1029 1030 1031 1033 2.3. YANG Module 1035 This module has normative references to [RFC2119], [RFC2986], 1036 [RFC3447], [RFC4253], [RFC5280], [RFC5652], [RFC5915], [RFC5958], 1037 [RFC6031], [RFC6125], [RFC6991], [RFC8174], [RFC8341], and 1038 [ITU.X690.2015]. 1040 file "ietf-crypto-types@2020-07-08.yang" 1042 module ietf-crypto-types { 1043 yang-version 1.1; 1044 namespace "urn:ietf:params:xml:ns:yang:ietf-crypto-types"; 1045 prefix ct; 1047 import ietf-yang-types { 1048 prefix yang; 1049 reference 1050 "RFC 6991: Common YANG Data Types"; 1051 } 1053 import ietf-netconf-acm { 1054 prefix nacm; 1055 reference 1056 "RFC 8341: Network Configuration Access Control Model"; 1057 } 1058 organization 1059 "IETF NETCONF (Network Configuration) Working Group"; 1061 contact 1062 "WG Web: 1063 WG List: 1064 Author: Kent Watsen "; 1066 description 1067 "This module defines common YANG types for cryptographic 1068 applications. 1070 Copyright (c) 2020 IETF Trust and the persons identified 1071 as authors of the code. All rights reserved. 1073 Redistribution and use in source and binary forms, with 1074 or without modification, is permitted pursuant to, and 1075 subject to the license terms contained in, the Simplified 1076 BSD License set forth in Section 4.c of the IETF Trust's 1077 Legal Provisions Relating to IETF Documents 1078 (https://trustee.ietf.org/license-info). 1080 This version of this YANG module is part of RFC AAAA 1081 (https://www.rfc-editor.org/info/rfcAAAA); see the RFC 1082 itself for full legal notices. 1084 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1085 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1086 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1087 are to be interpreted as described in BCP 14 (RFC 2119) 1088 (RFC 8174) when, and only when, they appear in all 1089 capitals, as shown here."; 1091 revision 2020-07-08 { 1092 description 1093 "Initial version"; 1094 reference 1095 "RFC AAAA: Common YANG Data Types for Cryptography"; 1096 } 1098 /****************/ 1099 /* Features */ 1100 /****************/ 1102 feature one-symmetric-key-format { 1103 description 1104 "Indicates that the server supports the 1105 'one-symmetric-key-format' identity."; 1106 } 1108 feature one-asymmetric-key-format { 1109 description 1110 "Indicates that the server supports the 1111 'one-asymmetric-key-format' identity."; 1112 } 1114 feature encrypted-one-symmetric-key-format { 1115 description 1116 "Indicates that the server supports the 1117 'encrypted-one-symmetric-key-format' identity."; 1118 } 1120 feature encrypted-one-asymmetric-key-format { 1121 description 1122 "Indicates that the server supports the 1123 'encrypted-one-asymmetric-key-format' identity."; 1124 } 1126 feature certificate-signing-request-generation { 1127 description 1128 "Indicates that the server implements the 1129 'generate-certificate-signing-request' action."; 1130 } 1132 /*************************************************/ 1133 /* Base Identities for Key Format Structures */ 1134 /*************************************************/ 1136 identity symmetric-key-format { 1137 description "Base key-format identity for symmetric keys."; 1138 } 1140 identity public-key-format { 1141 description "Base key-format identity for public keys."; 1142 } 1144 identity private-key-format { 1145 description "Base key-format identity for private keys."; 1146 } 1148 /****************************************************/ 1149 /* Identities for Private Key Format Structures */ 1150 /****************************************************/ 1151 identity rsa-private-key-format { 1152 base "private-key-format"; 1153 description 1154 "Indicates that the private key value is encoded 1155 as an RSAPrivateKey (from RFC 3447)."; 1156 reference 1157 "RFC 3447: PKCS #1: RSA Cryptography 1158 Specifications Version 2.2"; 1159 } 1161 identity ec-private-key-format { 1162 base "private-key-format"; 1163 description 1164 "Indicates that the private key value is encoded 1165 as an ECPrivateKey (from RFC 5915)"; 1166 reference 1167 "RFC 5915: Elliptic Curve Private Key Structure"; 1168 } 1170 identity one-asymmetric-key-format { 1171 if-feature "one-asymmetric-key-format"; 1172 base "private-key-format"; 1173 description 1174 "Indicates that the private key value is a CMS 1175 OneAsymmetricKey structure, as defined in RFC 5958, 1176 encoded using ASN.1 distinguished encoding rules 1177 (DER), as specified in ITU-T X.690."; 1178 reference 1179 "RFC 5958: Asymmetric Key Packages 1180 ITU-T X.690: 1181 Information technology - ASN.1 encoding rules: 1182 Specification of Basic Encoding Rules (BER), 1183 Canonical Encoding Rules (CER) and Distinguished 1184 Encoding Rules (DER)."; 1185 } 1187 identity encrypted-one-asymmetric-key-format { 1188 if-feature "encrypted-one-asymmetric-key-format"; 1189 base "private-key-format"; 1190 description 1191 "Indicates that the private key value is a CMS EnvelopedData 1192 structure, per Section 8 in RFC 5652, containing a 1193 OneAsymmetricKey structure, as defined in RFC 5958, 1194 encoded using ASN.1 distinguished encoding rules (DER), 1195 as specified in ITU-T X.690."; 1196 reference 1197 "RFC 5652: Cryptographic Message Syntax (CMS) 1198 RFC 5958: Asymmetric Key Packages 1199 ITU-T X.690: 1200 Information technology - ASN.1 encoding rules: 1201 Specification of Basic Encoding Rules (BER), 1202 Canonical Encoding Rules (CER) and Distinguished 1203 Encoding Rules (DER)."; 1204 } 1206 /***************************************************/ 1207 /* Identities for Public Key Format Structures */ 1208 /***************************************************/ 1210 identity ssh-public-key-format { 1211 base "public-key-format"; 1212 description 1213 "Indicates that the public key value is an SSH public key, 1214 as specified by RFC 4253, Section 6.6, i.e.: 1216 string certificate or public key format 1217 identifier 1218 byte[n] key/certificate data."; 1219 reference 1220 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1221 } 1223 identity subject-public-key-info-format { 1224 base "public-key-format"; 1225 description 1226 "Indicates that the public key value is a SubjectPublicKeyInfo 1227 structure, as described in RFC 5280 encoded using ASN.1 1228 distinguished encoding rules (DER), as specified in 1229 ITU-T X.690."; 1230 reference 1231 "RFC 5280: 1232 Internet X.509 Public Key Infrastructure Certificate 1233 and Certificate Revocation List (CRL) Profile 1234 ITU-T X.690: 1235 Information technology - ASN.1 encoding rules: 1236 Specification of Basic Encoding Rules (BER), 1237 Canonical Encoding Rules (CER) and Distinguished 1238 Encoding Rules (DER)."; 1239 } 1241 /******************************************************/ 1242 /* Identities for Symmetric Key Format Structures */ 1243 /******************************************************/ 1244 identity octet-string-key-format { 1245 base "symmetric-key-format"; 1246 description 1247 "Indicates that the key is encoded as a raw octet string. 1248 The length of the octet string MUST be appropriate for 1249 the associated algorithm's block size."; 1250 } 1252 identity one-symmetric-key-format { 1253 if-feature "one-symmetric-key-format"; 1254 base "symmetric-key-format"; 1255 description 1256 "Indicates that the private key value is a CMS 1257 OneSymmetricKey structure, as defined in RFC 6031, 1258 encoded using ASN.1 distinguished encoding rules 1259 (DER), as specified in ITU-T X.690."; 1260 reference 1261 "RFC 6031: Cryptographic Message Syntax (CMS) 1262 Symmetric Key Package Content Type 1263 ITU-T X.690: 1264 Information technology - ASN.1 encoding rules: 1265 Specification of Basic Encoding Rules (BER), 1266 Canonical Encoding Rules (CER) and Distinguished 1267 Encoding Rules (DER)."; 1268 } 1270 identity encrypted-one-symmetric-key-format { 1271 if-feature "encrypted-one-symmetric-key-format"; 1272 base "symmetric-key-format"; 1273 description 1274 "Indicates that the private key value is a CMS 1275 EnvelopedData structure, per Section 8 in RFC 5652, 1276 containing a OneSymmetricKey structure, as defined 1277 in RFC 6031, encoded using ASN.1 distinguished 1278 encoding rules (DER), as specified in ITU-T X.690."; 1279 reference 1280 "RFC 5652: Cryptographic Message Syntax (CMS) 1281 RFC 6031: Cryptographic Message Syntax (CMS) 1282 Symmetric Key Package Content Type 1283 ITU-T X.690: 1284 Information technology - ASN.1 encoding rules: 1285 Specification of Basic Encoding Rules (BER), 1286 Canonical Encoding Rules (CER) and Distinguished 1287 Encoding Rules (DER)."; 1288 } 1290 /***************************************************/ 1291 /* Typedefs for ASN.1 structures from RFC 2986 */ 1292 /***************************************************/ 1294 typedef csr-info { 1295 type binary; 1296 description 1297 "A CertificationRequestInfo structure, as defined in 1298 RFC 2986, encoded using ASN.1 distinguished encoding 1299 rules (DER), as specified in ITU-T X.690."; 1300 reference 1301 "RFC 2986: PKCS #10: Certification Request Syntax 1302 Specification Version 1.7 1303 ITU-T X.690: 1304 Information technology - ASN.1 encoding rules: 1305 Specification of Basic Encoding Rules (BER), 1306 Canonical Encoding Rules (CER) and Distinguished 1307 Encoding Rules (DER)."; 1308 } 1310 typedef csr { 1311 type binary; 1312 description 1313 "A CertificationRequest structure, as specified in 1314 RFC 2986, encoded using ASN.1 distinguished encoding 1315 rules (DER), as specified in ITU-T X.690."; 1316 reference 1317 "RFC 2986: 1318 PKCS #10: Certification Request Syntax Specification 1319 Version 1.7 1320 ITU-T X.690: 1321 Information technology - ASN.1 encoding rules: 1322 Specification of Basic Encoding Rules (BER), 1323 Canonical Encoding Rules (CER) and Distinguished 1324 Encoding Rules (DER)."; 1325 } 1327 /***************************************************/ 1328 /* Typedefs for ASN.1 structures from RFC 5280 */ 1329 /***************************************************/ 1331 typedef x509 { 1332 type binary; 1333 description 1334 "A Certificate structure, as specified in RFC 5280, 1335 encoded using ASN.1 distinguished encoding rules (DER), 1336 as specified in ITU-T X.690."; 1337 reference 1338 "RFC 5280: 1340 Internet X.509 Public Key Infrastructure Certificate 1341 and Certificate Revocation List (CRL) Profile 1342 ITU-T X.690: 1343 Information technology - ASN.1 encoding rules: 1344 Specification of Basic Encoding Rules (BER), 1345 Canonical Encoding Rules (CER) and Distinguished 1346 Encoding Rules (DER)."; 1347 } 1349 typedef crl { 1350 type binary; 1351 description 1352 "A CertificateList structure, as specified in RFC 5280, 1353 encoded using ASN.1 distinguished encoding rules (DER), 1354 as specified in ITU-T X.690."; 1355 reference 1356 "RFC 5280: 1357 Internet X.509 Public Key Infrastructure Certificate 1358 and Certificate Revocation List (CRL) Profile 1359 ITU-T X.690: 1360 Information technology - ASN.1 encoding rules: 1361 Specification of Basic Encoding Rules (BER), 1362 Canonical Encoding Rules (CER) and Distinguished 1363 Encoding Rules (DER)."; 1364 } 1366 /***************************************************/ 1367 /* Typedefs for ASN.1 structures from RFC 6960 */ 1368 /***************************************************/ 1370 typedef oscp-request { 1371 type binary; 1372 description 1373 "A OCSPRequest structure, as specified in RFC 6960, 1374 encoded using ASN.1 distinguished encoding rules 1375 (DER), as specified in ITU-T X.690."; 1376 reference 1377 "RFC 6960: 1378 X.509 Internet Public Key Infrastructure Online 1379 Certificate Status Protocol - OCSP 1380 ITU-T X.690: 1381 Information technology - ASN.1 encoding rules: 1382 Specification of Basic Encoding Rules (BER), 1383 Canonical Encoding Rules (CER) and Distinguished 1384 Encoding Rules (DER)."; 1385 } 1386 typedef oscp-response { 1387 type binary; 1388 description 1389 "A OCSPResponse structure, as specified in RFC 6960, 1390 encoded using ASN.1 distinguished encoding rules 1391 (DER), as specified in ITU-T X.690."; 1392 reference 1393 "RFC 6960: 1394 X.509 Internet Public Key Infrastructure Online 1395 Certificate Status Protocol - OCSP 1396 ITU-T X.690: 1397 Information technology - ASN.1 encoding rules: 1398 Specification of Basic Encoding Rules (BER), 1399 Canonical Encoding Rules (CER) and Distinguished 1400 Encoding Rules (DER)."; 1401 } 1403 /***********************************************/ 1404 /* Typedefs for ASN.1 structures from 5652 */ 1405 /***********************************************/ 1407 typedef cms { 1408 type binary; 1409 description 1410 "A ContentInfo structure, as specified in RFC 5652, 1411 encoded using ASN.1 distinguished encoding rules (DER), 1412 as specified in ITU-T X.690."; 1413 reference 1414 "RFC 5652: 1415 Cryptographic Message Syntax (CMS) 1416 ITU-T X.690: 1417 Information technology - ASN.1 encoding rules: 1418 Specification of Basic Encoding Rules (BER), 1419 Canonical Encoding Rules (CER) and Distinguished 1420 Encoding Rules (DER)."; 1421 } 1423 typedef data-content-cms { 1424 type cms; 1425 description 1426 "A CMS structure whose top-most content type MUST be the 1427 data content type, as described by Section 4 in RFC 5652."; 1428 reference 1429 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1430 } 1432 typedef signed-data-cms { 1433 type cms; 1434 description 1435 "A CMS structure whose top-most content type MUST be the 1436 signed-data content type, as described by Section 5 in 1437 RFC 5652."; 1438 reference 1439 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1440 } 1442 typedef enveloped-data-cms { 1443 type cms; 1444 description 1445 "A CMS structure whose top-most content type MUST be the 1446 enveloped-data content type, as described by Section 6 1447 in RFC 5652."; 1448 reference 1449 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1450 } 1452 typedef digested-data-cms { 1453 type cms; 1454 description 1455 "A CMS structure whose top-most content type MUST be the 1456 digested-data content type, as described by Section 7 1457 in RFC 5652."; 1458 reference 1459 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1460 } 1462 typedef encrypted-data-cms { 1463 type cms; 1464 description 1465 "A CMS structure whose top-most content type MUST be the 1466 encrypted-data content type, as described by Section 8 1467 in RFC 5652."; 1468 reference 1469 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1470 } 1472 typedef authenticated-data-cms { 1473 type cms; 1474 description 1475 "A CMS structure whose top-most content type MUST be the 1476 authenticated-data content type, as described by Section 9 1477 in RFC 5652."; 1478 reference 1479 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1480 } 1481 /*********************************************************/ 1482 /* Typedefs for ASN.1 structures related to RFC 5280 */ 1483 /*********************************************************/ 1485 typedef trust-anchor-cert-x509 { 1486 type x509; 1487 description 1488 "A Certificate structure that MUST encode a self-signed 1489 root certificate."; 1490 } 1492 typedef end-entity-cert-x509 { 1493 type x509; 1494 description 1495 "A Certificate structure that MUST encode a certificate 1496 that is neither self-signed nor having Basic constraint 1497 CA true."; 1498 } 1500 /*********************************************************/ 1501 /* Typedefs for ASN.1 structures related to RFC 5652 */ 1502 /*********************************************************/ 1504 typedef trust-anchor-cert-cms { 1505 type signed-data-cms; 1506 description 1507 "A CMS SignedData structure that MUST contain the chain of 1508 X.509 certificates needed to authenticate the certificate 1509 presented by a client or end-entity. 1511 The CMS MUST contain only a single chain of certificates. 1512 The client or end-entity certificate MUST only authenticate 1513 to last intermediate CA certificate listed in the chain. 1515 In all cases, the chain MUST include a self-signed root 1516 certificate. In the case where the root certificate is 1517 itself the issuer of the client or end-entity certificate, 1518 only one certificate is present. 1520 This CMS structure MAY (as applicable where this type is 1521 used) also contain suitably fresh (as defined by local 1522 policy) revocation objects with which the device can 1523 verify the revocation status of the certificates. 1525 This CMS encodes the degenerate form of the SignedData 1526 structure that is commonly used to disseminate X.509 1527 certificates and revocation objects (RFC 5280)."; 1529 reference 1530 "RFC 5280: 1531 Internet X.509 Public Key Infrastructure Certificate 1532 and Certificate Revocation List (CRL) Profile."; 1533 } 1535 typedef end-entity-cert-cms { 1536 type signed-data-cms; 1537 description 1538 "A CMS SignedData structure that MUST contain the end 1539 entity certificate itself, and MAY contain any number 1540 of intermediate certificates leading up to a trust 1541 anchor certificate. The trust anchor certificate 1542 MAY be included as well. 1544 The CMS MUST contain a single end entity certificate. 1545 The CMS MUST NOT contain any spurious certificates. 1547 This CMS structure MAY (as applicable where this type is 1548 used) also contain suitably fresh (as defined by local 1549 policy) revocation objects with which the device can 1550 verify the revocation status of the certificates. 1552 This CMS encodes the degenerate form of the SignedData 1553 structure that is commonly used to disseminate X.509 1554 certificates and revocation objects (RFC 5280)."; 1555 reference 1556 "RFC 5280: 1557 Internet X.509 Public Key Infrastructure Certificate 1558 and Certificate Revocation List (CRL) Profile."; 1559 } 1561 /**********************************************/ 1562 /* Groupings for keys and/or certificates */ 1563 /**********************************************/ 1565 grouping encrypted-key-value-grouping { 1566 description 1567 "A reusable grouping for a value that has been encrypted by 1568 a symmetric or asymmetric key in the Keystore."; 1569 container encrypted-by { 1570 nacm:default-deny-write; 1571 description 1572 "An empty container enabling references to other keys that 1573 encrypt these keys to be augmented in. The referenced key 1574 MAY be a symmetric or an asymmetric key."; 1575 } 1576 leaf encrypted-value { 1577 nacm:default-deny-write; 1578 type binary; 1579 must "../encrypted-by"; 1580 mandatory true; 1581 description 1582 "The key data, encrypted using the referenced symmetric 1583 or asymmetric key. The format of the encrypted value 1584 is identicated by the associated key format identity."; 1585 } 1586 } 1588 grouping symmetric-key-grouping { 1589 description 1590 "A symmetric key."; 1591 leaf key-format { 1592 nacm:default-deny-write; 1593 type identityref { 1594 base symmetric-key-format; 1595 } 1596 description "Identifies the symmetric key's format."; 1597 } 1598 choice key-type { 1599 nacm:default-deny-write; 1600 mandatory true; 1601 description 1602 "Choice between key types."; 1603 case key { 1604 leaf key { 1605 nacm:default-deny-all; 1606 type binary; 1607 must "../key-format"; 1608 description 1609 "The binary value of the key. The interpretation of 1610 the value is defined by the 'key-format' field."; 1611 } 1612 } 1613 case hidden-key { 1614 leaf hidden-key { 1615 type empty; 1616 must "not(../key-format)"; 1617 description 1618 "A hidden key. How such keys are created is outside 1619 the scope of this module."; 1620 } 1621 } 1622 case encrypted-key { 1623 container encrypted-key { 1624 must "../key-format"; 1625 description 1626 "A container for the encrypted symmetric key value."; 1627 uses encrypted-key-value-grouping; 1628 } 1629 } 1630 } 1631 } 1633 grouping public-key-grouping { 1634 description 1635 "A public key."; 1636 leaf public-key-format { 1637 nacm:default-deny-write; 1638 type identityref { 1639 base public-key-format; 1640 } 1641 mandatory true; 1642 description "Identifies the key's format."; 1643 } 1644 leaf public-key { 1645 nacm:default-deny-write; 1646 type binary; 1647 mandatory true; 1648 description 1649 "The binary value of the public key. The interpretation 1650 of the value is defined by 'public-key-format' field."; 1651 } 1652 } 1654 grouping asymmetric-key-pair-grouping { 1655 description 1656 "A private key and its associated public key."; 1657 uses public-key-grouping; 1658 leaf private-key-format { 1659 nacm:default-deny-write; 1660 type identityref { 1661 base private-key-format; 1662 } 1663 description "Identifies the key's format."; 1664 } 1665 choice private-key-type { 1666 nacm:default-deny-write; 1667 mandatory true; 1668 description 1669 "Choice between key types."; 1670 case private-key { 1671 leaf private-key { 1672 nacm:default-deny-all; 1673 type binary; 1674 must "../private-key-format"; 1675 description 1676 "The value of the binary key The key's value is 1677 interpreted by the 'private-key-format' field."; 1678 } 1679 } 1680 case hidden-private-key { 1681 leaf hidden-private-key { 1682 type empty; 1683 must "not(../private-key-format)"; 1684 description 1685 "A hidden key. How such keys are created is 1686 outside the scope of this module."; 1687 } 1688 } 1689 case encrypted-private-key { 1690 container encrypted-private-key { 1691 must "../private-key-format"; 1692 description 1693 "A container for the encrypted asymmetric private 1694 key value."; 1695 uses encrypted-key-value-grouping; 1696 } 1697 } 1698 } 1699 } 1701 grouping certificate-expiration-grouping { 1702 description 1703 "A notification for when a certificate is about to, or 1704 already has, expired."; 1705 notification certificate-expiration { 1706 description 1707 "A notification indicating that the configured certificate 1708 is either about to expire or has already expired. When to 1709 send notifications is an implementation specific decision, 1710 but it is RECOMMENDED that a notification be sent once a 1711 month for 3 months, then once a week for four weeks, and 1712 then once a day thereafter until the issue is resolved."; 1713 leaf expiration-date { 1714 type yang:date-and-time; 1715 mandatory true; 1716 description 1717 "Identifies the expiration date on the certificate."; 1718 } 1719 } 1721 } 1723 grouping trust-anchor-cert-grouping { 1724 description 1725 "A trust anchor certificate, and a notification for when 1726 it is about to (or already has) expire."; 1727 leaf cert-data { 1728 nacm:default-deny-write; 1729 type trust-anchor-cert-cms; 1730 description 1731 "The binary certificate data for this certificate."; 1732 reference 1733 "RFC YYYY: Common YANG Data Types for Cryptography"; 1734 } 1735 uses certificate-expiration-grouping; 1736 } 1738 grouping end-entity-cert-grouping { 1739 description 1740 "An end entity certificate, and a notification for when 1741 it is about to (or already has) expire. Implementations 1742 SHOULD assert that, where used, the end entity certificate 1743 contains the expected public key."; 1744 leaf cert-data { 1745 nacm:default-deny-write; 1746 type end-entity-cert-cms; 1747 description 1748 "The binary certificate data for this certificate."; 1749 reference 1750 "RFC YYYY: Common YANG Data Types for Cryptography"; 1751 } 1752 uses certificate-expiration-grouping; 1753 } 1755 grouping generate-csr-grouping { 1756 description 1757 "Defines the 'generate-certificate-signing-request' action."; 1758 action generate-certificate-signing-request { 1759 if-feature certificate-signing-request-generation; 1760 nacm:default-deny-all; 1761 description 1762 "Generates a certificate signing request structure for 1763 the associated asymmetric key using the passed subject 1764 and attribute values. 1766 This action statement is only available when the 1767 associated 'public-key-format' node's value is 1768 'subject-public-key-info-format'."; 1770 reference 1771 "RFC 6125: 1772 Representation and Verification of Domain-Based 1773 Application Service Identity within Internet Public Key 1774 Infrastructure Using X.509 (PKIX) Certificates in the 1775 Context of Transport Layer Security (TLS)"; 1776 input { 1777 leaf csr-info { 1778 type ct:csr-info; 1779 mandatory true; 1780 description 1781 "A CertificationRequestInfo structure, as defined in 1782 RFC 2986. 1784 Enables the client to provide a fully-populated 1785 CertificationRequestInfo structure that the server 1786 only needs to sign in order to generate the complete 1787 'CertificationRequest' structure to return in the 1788 'output'. 1790 The 'AlgorithmIdentifier' field contained inside 1791 the 'SubjectPublicKeyInfo' field MUST be one known 1792 to be supported by the device."; 1793 reference 1794 "RFC 2986: 1795 PKCS #10: Certification Request Syntax Specification 1796 RFC AAAA: 1797 YANG Data Types and Groupings for Cryptography"; 1798 } 1799 } 1800 output { 1801 leaf certificate-signing-request { 1802 type ct:csr; 1803 mandatory true; 1804 description 1805 "A CertificationRequest structure, as defined in 1806 RFC 2986."; 1807 reference 1808 "RFC 2986: 1809 PKCS #10: Certification Request Syntax Specification 1810 RFC AAAA: 1811 YANG Data Types and Groupings for Cryptography"; 1812 } 1813 } 1814 } 1815 } // generate-csr-grouping 1817 grouping asymmetric-key-pair-with-cert-grouping { 1818 description 1819 "A private/public key pair and an associated certificate. 1820 Implementations SHOULD assert that certificates contain 1821 the matching public key."; 1822 uses asymmetric-key-pair-grouping; 1823 uses end-entity-cert-grouping; 1824 uses generate-csr-grouping; 1825 } // asymmetric-key-pair-with-cert-grouping 1827 grouping asymmetric-key-pair-with-certs-grouping { 1828 description 1829 "A private/public key pair and associated certificates. 1830 Implementations SHOULD assert that certificates contain 1831 the matching public key."; 1832 uses asymmetric-key-pair-grouping; 1833 container certificates { 1834 nacm:default-deny-write; 1835 description 1836 "Certificates associated with this asymmetric key. 1837 More than one certificate supports, for instance, 1838 a TPM-protected asymmetric key that has both IDevID 1839 and LDevID certificates associated."; 1840 list certificate { 1841 key "name"; 1842 description 1843 "A certificate for this asymmetric key."; 1844 leaf name { 1845 type string; 1846 description 1847 "An arbitrary name for the certificate. If the name 1848 matches the name of a certificate that exists 1849 independently in (i.e., an IDevID), 1850 then the 'cert' node MUST NOT be configured."; 1851 } 1852 uses end-entity-cert-grouping { 1853 refine cert-data { 1854 mandatory true; 1855 } 1856 } 1857 } 1858 } 1859 uses generate-csr-grouping; 1860 } // asymmetric-key-pair-with-certs-grouping 1862 } 1864 1866 3. Security Considerations 1868 3.1. No Support for CRMF 1870 This document uses PKCS #10 [RFC2986] for the "generate-certificate- 1871 signing-request" action. The use of Certificate Request Message 1872 Format (CRMF) [RFC4211] was considered, but is was unclear if there 1873 was market demand for it. If it is desired to support CRMF in the 1874 future, a backwards compatible solution can be defined at that time. 1876 3.2. No Support for Key Generation 1878 Early revisions of this document included "rpc" statements for 1879 generating symmetric and asymmetric keys. There statements were 1880 removed due to an inability to obtain consensus for how to identify 1881 the key-algorithm to use. Thusly, the solution presented in this 1882 document only supports keys to be configured via an external client, 1883 which does not support Security best practice. 1885 3.3. Deletion of Cleartext Key Values 1887 This module defines storage for cleartext key values that SHOULD be 1888 zeroized when deleted, so as to prevent the remnants of their 1889 persisted storage locations from being analyzed in any meaningful 1890 way. 1892 The cleartext key nodes are the "key" node defined in the "symmetric- 1893 key-grouping" grouping (Section 2.1.4.2) and the "private-key" node 1894 defined in the "asymmetric-key-pair-grouping" grouping 1895 ("Section 2.1.4.4). 1897 3.4. The "ietf-crypto-types" YANG Module 1899 The YANG module in this document defines "grouping" statements that 1900 are designed to be accessed via YANG based management protocols, such 1901 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1902 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1903 with mutual authentication. 1905 The NETCONF access control model (NACM) [RFC8341] provides the means 1906 to restrict access for particular users to a pre-configured subset of 1907 all available protocol operations and content. 1909 Since the module in this document only define groupings, these 1910 considerations are primarily for the designers of other modules that 1911 use these groupings. 1913 Some of the readable data nodes defined in this YANG module may be 1914 considered sensitive or vulnerable in some network environments. It 1915 is thus important to control read access (e.g., via get, get-config, 1916 or notification) to these data nodes. These are the subtrees and 1917 data nodes and their sensitivity/vulnerability: 1919 * The "key" node: 1921 The cleartext "key" node defined in the "symmetric-key- 1922 grouping" grouping is additionally sensitive to read operations 1923 such that, in normal use cases, it should never be returned to 1924 a client. For this reason, the NACM extension "default-deny- 1925 all" has been applied to it. 1927 * The "private-key" node: 1929 The cleartext "private-key" node defined in the "asymmetric- 1930 key-pair-grouping" grouping is additionally sensitive to read 1931 operations such that, in normal use cases, it should never be 1932 returned to a client. For this reason, the NACM extension 1933 "default-deny-all" has been applied. 1935 All of the writable data nodes defined by all the groupings defined 1936 in this module may be considered sensitive or vulnerable in some 1937 network environments. For instance, even the modification of a 1938 public key or a certificate can dramatically alter the implemented 1939 security policy. For this reason, the NACM extension "default-deny- 1940 write" has been applied to all the data nodes defined in the module. 1942 Some of the operations in this YANG module may be considered 1943 sensitive or vulnerable in some network environments. It is thus 1944 important to control access to these operations. These are the 1945 operations and their sensitivity/vulnerability: 1947 * generate-certificate-signing-request: 1949 This "action" statement SHOULD only be executed by authorized 1950 users. For this reason, the NACM extension "default-deny-all" 1951 has been applied. Note that NACM uses "default-deny-all" to 1952 protect "RPC" and "action" statements; it does not define, 1953 e.g., an extension called "default-deny-execute". 1955 For this action, it is RECOMMENDED that implementations assert 1956 channel binding [RFC5056], so as to ensure that the application 1957 layer that sent the request is the same as the device 1958 authenticated when the secure transport layer was established. 1960 4. IANA Considerations 1962 4.1. Update the "IETF XML" Registry 1964 This document registers one URI in the "ns" subregistry of the "IETF 1965 XML" registry [RFC3688]. Following the format in [RFC3688], the 1966 following registration is requested: 1968 URI: urn:ietf:params:xml:ns:yang:ietf-crypto-types 1969 Registrant Contact: The NETCONF WG of the IETF. 1970 XML: N/A, the requested URI is an XML namespace. 1972 4.2. Update the "YANG Module Names" Registry 1974 This document registers one YANG module in the "YANG Module Names" 1975 registry [RFC6020]. Following the format in [RFC6020], the the 1976 following registration is requested: 1978 name: ietf-crypto-types 1979 namespace: urn:ietf:params:xml:ns:yang:ietf-crypto-types 1980 prefix: ct 1981 reference: RFC AAAA 1983 5. References 1985 5.1. Normative References 1987 [ITU.X680.2015] 1988 International Telecommunication Union, "Information 1989 technology - Abstract Syntax Notation One (ASN.1): 1990 Specification of basic notation", ITU-T Recommendation 1991 X.680, ISO/IEC 8824-1:2015, August 2015, 1992 . 1994 [ITU.X690.2015] 1995 International Telecommunication Union, "Information 1996 Technology - ASN.1 encoding rules: Specification of Basic 1997 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1998 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1999 X.690, ISO/IEC 8825-1:2015, August 2015, 2000 . 2002 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2003 Requirement Levels", BCP 14, RFC 2119, 2004 DOI 10.17487/RFC2119, March 1997, 2005 . 2007 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2008 Standards (PKCS) #1: RSA Cryptography Specifications 2009 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 2010 2003, . 2012 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2013 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2014 January 2006, . 2016 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2017 Housley, R., and W. Polk, "Internet X.509 Public Key 2018 Infrastructure Certificate and Certificate Revocation List 2019 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2020 . 2022 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2023 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2024 . 2026 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, 2027 DOI 10.17487/RFC5958, August 2010, 2028 . 2030 [RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax 2031 (CMS) Symmetric Key Package Content Type", RFC 6031, 2032 DOI 10.17487/RFC6031, December 2010, 2033 . 2035 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2036 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2037 . 2039 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2040 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2041 . 2043 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2044 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2045 May 2017, . 2047 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2048 Access Control Model", STD 91, RFC 8341, 2049 DOI 10.17487/RFC8341, March 2018, 2050 . 2052 5.2. Informative References 2054 [I-D.ietf-netconf-crypto-types] 2055 Watsen, K., "Common YANG Data Types for Cryptography", 2056 Work in Progress, Internet-Draft, draft-ietf-netconf- 2057 crypto-types-15, 20 May 2020, 2058 . 2061 [I-D.ietf-netconf-http-client-server] 2062 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2063 Servers", Work in Progress, Internet-Draft, draft-ietf- 2064 netconf-http-client-server-03, 20 May 2020, 2065 . 2068 [I-D.ietf-netconf-keystore] 2069 Watsen, K., "A YANG Data Model for a Keystore", Work in 2070 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 2071 20 May 2020, . 2074 [I-D.ietf-netconf-netconf-client-server] 2075 Watsen, K., "NETCONF Client and Server Models", Work in 2076 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2077 client-server-19, 20 May 2020, 2078 . 2081 [I-D.ietf-netconf-restconf-client-server] 2082 Watsen, K., "RESTCONF Client and Server Models", Work in 2083 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2084 client-server-19, 20 May 2020, 2085 . 2088 [I-D.ietf-netconf-ssh-client-server] 2089 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2090 SSH Servers", Work in Progress, Internet-Draft, draft- 2091 ietf-netconf-ssh-client-server-19, 20 May 2020, 2092 . 2095 [I-D.ietf-netconf-tcp-client-server] 2096 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2097 and TCP Servers", Work in Progress, Internet-Draft, draft- 2098 ietf-netconf-tcp-client-server-06, 16 June 2020, 2099 . 2102 [I-D.ietf-netconf-tls-client-server] 2103 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2104 TLS Servers", Work in Progress, Internet-Draft, draft- 2105 ietf-netconf-tls-client-server-19, 20 May 2020, 2106 . 2109 [I-D.ietf-netconf-trust-anchors] 2110 Watsen, K., "A YANG Data Model for a Truststore", Work in 2111 Progress, Internet-Draft, draft-ietf-netconf-trust- 2112 anchors-10, 20 May 2020, . 2115 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 2116 Request Syntax Specification Version 1.7", RFC 2986, 2117 DOI 10.17487/RFC2986, November 2000, 2118 . 2120 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2121 DOI 10.17487/RFC3688, January 2004, 2122 . 2124 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 2125 Certificate Request Message Format (CRMF)", RFC 4211, 2126 DOI 10.17487/RFC4211, September 2005, 2127 . 2129 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 2130 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 2131 . 2133 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 2134 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 2135 . 2137 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2138 the Network Configuration Protocol (NETCONF)", RFC 6020, 2139 DOI 10.17487/RFC6020, October 2010, 2140 . 2142 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2143 Verification of Domain-Based Application Service Identity 2144 within Internet Public Key Infrastructure Using X.509 2145 (PKIX) Certificates in the Context of Transport Layer 2146 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2147 2011, . 2149 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2150 and A. Bierman, Ed., "Network Configuration Protocol 2151 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2152 . 2154 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2155 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2156 . 2158 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2159 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2160 . 2162 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2163 and R. Wilton, "Network Management Datastore Architecture 2164 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2165 . 2167 Appendix A. Change Log 2169 This section is to be removed before publishing as an RFC. 2171 A.1. I-D to 00 2173 * Removed groupings and notifications. 2175 * Added typedefs for identityrefs. 2177 * Added typedefs for other RFC 5280 structures. 2179 * Added typedefs for other RFC 5652 structures. 2181 * Added convenience typedefs for RFC 4253, RFC 5280, and RFC 5652. 2183 A.2. 00 to 01 2185 * Moved groupings from the draft-ietf-netconf-keystore here. 2187 A.3. 01 to 02 2189 * Removed unwanted "mandatory" and "must" statements. 2191 * Added many new crypto algorithms (thanks Haiguang!) 2192 * Clarified in asymmetric-key-pair-with-certs-grouping, in 2193 certificates/certificate/name/description, that if the name MUST 2194 NOT match the name of a certificate that exists independently in 2195 , enabling certs installed by the manufacturer (e.g., 2196 an IDevID). 2198 A.4. 02 to 03 2200 * renamed base identity 'asymmetric-key-encryption-algorithm' to 2201 'asymmetric-key-algorithm'. 2203 * added new 'asymmetric-key-algorithm' identities for secp192r1, 2204 secp224r1, secp256r1, secp384r1, and secp521r1. 2206 * removed 'mac-algorithm' identities for mac-aes-128-ccm, mac-aes- 2207 192-ccm, mac-aes-256-ccm, mac-aes-128-gcm, mac-aes-192-gcm, mac- 2208 aes-256-gcm, and mac-chacha20-poly1305. 2210 * for all -cbc and -ctr identities, renamed base identity 2211 'symmetric-key-encryption-algorithm' to 'encryption-algorithm'. 2213 * for all -ccm and -gcm identities, renamed base identity 2214 'symmetric-key-encryption-algorithm' to 'encryption-and-mac- 2215 algorithm' and renamed the identity to remove the "enc-" prefix. 2217 * for all the 'signature-algorithm' based identities, renamed from 2218 'rsa-*' to 'rsassa-*'. 2220 * removed all of the "x509v3-" prefixed 'signature-algorithm' based 2221 identities. 2223 * added 'key-exchange-algorithm' based identities for 'rsaes-oaep' 2224 and 'rsaes-pkcs1-v1_5'. 2226 * renamed typedef 'symmetric-key-encryption-algorithm-ref' to 2227 'symmetric-key-algorithm-ref'. 2229 * renamed typedef 'asymmetric-key-encryption-algorithm-ref' to 2230 'asymmetric-key-algorithm-ref'. 2232 * added typedef 'encryption-and-mac-algorithm-ref'. 2234 * Updated copyright date, boilerplate template, affiliation, and 2235 folding algorithm. 2237 A.5. 03 to 04 2239 * ran YANG module through formatter. 2241 A.6. 04 to 05 2243 * fixed broken symlink causing reformatted YANG module to not show. 2245 A.7. 05 to 06 2247 * Added NACM annotations. 2249 * Updated Security Considerations section. 2251 * Added 'asymmetric-key-pair-with-cert-grouping' grouping. 2253 * Removed text from 'permanently-hidden' enum regarding such keys 2254 not being backed up or restored. 2256 * Updated the boilerplate text in module-level "description" 2257 statement to match copyeditor convention. 2259 * Added an explanation to the 'public-key-grouping' and 'asymmetric- 2260 key-pair-grouping' statements as for why the nodes are not 2261 mandatory (e.g., because they may exist only in . 2263 * Added 'must' expressions to the 'public-key-grouping' and 2264 'asymmetric-key-pair-grouping' statements ensuring sibling nodes 2265 are either all exist or do not all exist. 2267 * Added an explanation to the 'permanently-hidden' that the value 2268 cannot be configured directly by clients and servers MUST fail any 2269 attempt to do so. 2271 * Added 'trust-anchor-certs-grouping' and 'end-entity-certs- 2272 grouping' (the plural form of existing groupings). 2274 * Now states that keys created in by the *-hidden-key 2275 actions are bound to the lifetime of the parent 'config true' 2276 node, and that subsequent invocations of either action results in 2277 a failure. 2279 A.8. 06 to 07 2281 * Added clarifications that implementations SHOULD assert that 2282 configured certificates contain the matching public key. 2284 * Replaced the 'generate-hidden-key' and 'install-hidden-key' 2285 actions with special 'crypt-hash' -like input/output values. 2287 A.9. 07 to 08 2289 * Removed the 'generate-key and 'hidden-key' features. 2291 * Added grouping symmetric-key-grouping 2293 * Modified 'asymmetric-key-pair-grouping' to have a 'choice' 2294 statement for the keystone module to augment into, as well as 2295 replacing the 'union' with leafs (having different NACM settings. 2297 A.10. 08 to 09 2299 * Converting algorithm from identities to enumerations. 2301 A.11. 09 to 10 2303 * All of the below changes are to the algorithm enumerations defined 2304 in ietf-crypto-types. 2306 * Add in support for key exchange over x.25519 and x.448 based on 2307 RFC 8418. 2309 * Add in SHAKE-128, SHAKE-224, SHAKE-256, SHAKE-384 and SHAKE 512 2311 * Revise/add in enum of signature algorithm for x25519 and x448 2313 * Add in des3-cbc-sha1 for IPSec 2315 * Add in sha1-des3-kd for IPSec 2317 * Add in definit for rc4-hmac and rc4-hmac-exp. These two 2318 algorithms have been deprecated in RFC 8429. But some existing 2319 draft in i2nsf may still want to use them. 2321 * Add x25519 and x448 curve for asymmetric algorithms 2323 * Add signature algorithms ed25519, ed25519-cts, ed25519ph 2325 * add signature algorithms ed448, ed448ph 2327 * Add in rsa-sha2-256 and rsa-sha2-512 for SSH protocols (rfc8332) 2329 A.12. 10 to 11 2331 * Added a "key-format" identity. 2333 * Added symmetric keys to the example in Section 2.2. 2335 A.13. 11 to 12 2337 * Removed all non-essential (to NC/RC) algorithm types. 2339 * Moved remaining algorithm types each into its own module. 2341 * Added a 'config false' "algorithms-supported" list to each of the 2342 algorithm-type modules. 2344 A.14. 12 to 13 2346 * Added the four features: "[encrypted-]one-[a]symmetric-key- 2347 format", each protecting a 'key-format' identity of the same name. 2349 * Added 'must' expressions asserting that the 'key-format' leaf 2350 exists whenever a non-hidden key is specified. 2352 * Improved the 'description' statements and added 'reference' 2353 statements for the 'key-format' identities. 2355 * Added a questionable forward reference to "encrypted-*" leafs in a 2356 couple 'when' expressions. 2358 * Did NOT move "config false" alg-supported lists to SSH/TLS drafts. 2360 A.15. 13 to 14 2362 * Resolved the "FIXME: forward ref" issue by modulating 'must', 2363 'when', and 'mandatory' expressions. 2365 * Moved the 'generatesymmetric-key' and 'generate-asymmetric-key' 2366 actions from ietf-keystore to ietf-crypto-types, now as RPCs. 2368 * Cleaned up various description statements and removed lingering 2369 FIXMEs. 2371 * Converted the "iana--algs" YANG modules to IANA 2372 registries with instructions for how to generate modules from the 2373 registries, whenever they may be updated. 2375 A.16. 14 to 15 2376 * Removed the IANA-maintained registries for symmetric, asymmetric, 2377 and hash algorithms. 2379 * Removed the "generate-symmetric-key" and "generate-asymmetric-key" 2380 RPCs. 2382 * Removed the "algorithm" node in the various symmetric and 2383 asymmetric key groupings. 2385 * Added 'typedef csr' and 'feature certificate-signing-request- 2386 generation'. 2388 * Refined a usage of "end-entity-cert-grouping" to make the "cert" 2389 node mandatory true. 2391 * Added a "Note to Reviewers" note to first page. 2393 A.17. 15 to 16 2395 * Updated draft title (refer to "Groupings" too). 2397 * Removed 'end-entity-certs-grouping' as it wasn't being used 2398 anywhere. 2400 * Removed 'trust-anchor-certs-grouping' as it was no longer being 2401 used after modifying 'local-or-truststore-certs-grouping' to use 2402 lists (not leaf-lists). 2404 * Renamed "cert" to "cert-data" in trust-anchor-cert-grouping. 2406 * Added "csr-info" typedef, to complement the existing "csr" 2407 typedef. 2409 * Added "ocsp-request" and "ocsp-response" typedefs, to complement 2410 the existing "crl" typedef. 2412 * Added "encrypted" cases to both symmetric-key-grouping and 2413 asymmetric-key-pair-grouping (Moved from Keystore draft). 2415 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2416 diagrams]. 2418 * Updated the Security Considerations section. 2420 Acknowledgements 2422 The authors would like to thank for following for lively discussions 2423 on list and in the halls (ordered by first name): Balazs Kovacs, Eric 2424 Voit, Juergen Schoenwaelder, Liang Xia, Martin Bjorklund, Nick 2425 Hancock, Rich Salz, Rob Wilton, Tom Petch, and Wang Haiguang. 2427 Author's Address 2429 Kent Watsen 2430 Watsen Networks 2432 Email: kent+ietf@watsen.net