idnits 2.17.1 draft-ietf-netconf-crypto-types-17.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 320 has weird spacing: '...d-value bin...' == Line 366 has weird spacing: '...d-value bin...' == Line 395 has weird spacing: '...-format ide...' == Line 442 has weird spacing: '...d-value bin...' == Line 474 has weird spacing: '...on-date yan...' == (18 more instances...) -- The document date (10 July 2020) is 1357 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 (-24) 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 10 July 2020 5 Expires: 11 January 2021 7 YANG Data Types and Groupings for Cryptography 8 draft-ietf-netconf-crypto-types-17 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-10" --> 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 11 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 . . . . . . . . . . . . . . . . . . . 40 79 3.1. No Support for CRMF . . . . . . . . . . . . . . . . . . . 41 80 3.2. No Support for Key Generation . . . . . . . . . . . . . . 41 81 3.3. Strength of Keys Configured . . . . . . . . . . . . . . . 41 82 3.4. Deletion of Cleartext Key Values . . . . . . . . . . . . 41 83 3.5. The "ietf-crypto-types" YANG Module . . . . . . . . . . . 41 84 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 85 4.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 43 86 4.2. The "YANG Module Names" Registry . . . . . . . . . . . . 43 87 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 88 5.1. Normative References . . . . . . . . . . . . . . . . . . 43 89 5.2. Informative References . . . . . . . . . . . . . . . . . 45 90 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 91 A.1. I-D to 00 . . . . . . . . . . . . . . . . . . . . . . . . 47 92 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 47 93 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 48 94 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 48 95 A.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 49 96 A.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 49 97 A.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 49 98 A.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 50 99 A.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 50 100 A.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 50 101 A.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 50 102 A.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 51 103 A.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 51 104 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 51 105 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 51 106 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 52 107 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 52 108 A.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 52 109 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 53 110 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 53 112 1. Introduction 114 This document presents a YANG 1.1 [RFC7950] module defining 115 identities, typedefs, and groupings useful to cryptographic 116 applications. 118 1.1. Relation to other RFCs 120 This document presents one or more YANG modules [RFC7950] that are 121 part of a collection of RFCs that work together to define 122 configuration modules for clients and servers of both the NETCONF 123 [RFC6241] and RESTCONF [RFC8040] protocols. 125 The modules have been defined in a modular fashion to enable their 126 use by other efforts, some of which are known to be in progress at 127 the time of this writing, with many more expected to be defined in 128 time. 130 The relationship between the various RFCs in the collection is 131 presented in the below diagram. The labels in the diagram represent 132 the primary purpose provided by each RFC. Links the each RFC are 133 provided below the diagram. 135 crypto-types 136 ^ ^ 137 / \ 138 / \ 139 truststore keystore 140 ^ ^ ^ ^ 141 | +---------+ | | 142 | | | | 143 | +------------+ | 144 tcp-client-server | / | | 145 ^ ^ ssh-client-server | | 146 | | ^ tls-client-server 147 | | | ^ ^ http-client-server 148 | | | | | ^ 149 | | | +-----+ +---------+ | 150 | | | | | | 151 | +-----------|--------|--------------+ | | 152 | | | | | | 153 +-----------+ | | | | | 154 | | | | | | 155 | | | | | | 156 netconf-client-server restconf-client-server 158 +=======================+===========================================+ 159 | Label in Diagram | Originating RFC | 160 +=======================+===========================================+ 161 | crypto-types | [I-D.ietf-netconf-crypto-types] | 162 +-----------------------+-------------------------------------------+ 163 | truststore | [I-D.ietf-netconf-trust-anchors] | 164 +-----------------------+-------------------------------------------+ 165 | keystore | [I-D.ietf-netconf-keystore] | 166 +-----------------------+-------------------------------------------+ 167 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 168 +-----------------------+-------------------------------------------+ 169 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 170 +-----------------------+-------------------------------------------+ 171 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 172 +-----------------------+-------------------------------------------+ 173 | http-client-server | [I-D.ietf-netconf-http-client-server] | 174 +-----------------------+-------------------------------------------+ 175 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 176 +-----------------------+-------------------------------------------+ 177 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 178 +-----------------------+-------------------------------------------+ 180 Table 1: Label to RFC Mapping 182 1.2. Specification Language 184 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 185 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 186 "OPTIONAL" in this document are to be interpreted as described in BCP 187 14 [RFC2119] [RFC8174] when, and only when, they appear in all 188 capitals, as shown here. 190 1.3. Adherence to the NMDA 192 This document in compliant with the Network Management Datastore 193 Architecture (NMDA) [RFC8342]. It does not define any protocol 194 accessible nodes that are "config false". 196 2. The "ietf-crypto-types" Module 198 This section defines a YANG 1.1 [RFC7950] module that defines data 199 types (typedefs and identities) and groupings supporting downstream 200 models needing cryptographic primitives. 202 2.1. Data Model Overview 204 2.1.1. Features 206 The following diagram lists all the "feature" statements defined in 207 the "ietf-crypt-types" module: 209 Features: 210 +-- one-symmetric-key-format 211 +-- one-asymmetric-key-format 212 +-- encrypted-one-symmetric-key-format 213 +-- encrypted-one-asymmetric-key-format 214 +-- certificate-signing-request-generation 216 2.1.2. Identities 218 The following diagram illustrates the relationship amongst the 219 "identity" statements defined in the "ietf-crypto-types" module: 221 Identities: 222 +-- public-key-format 223 | +-- subject-public-key-info-format 224 | +-- ssh-public-key-format 225 +-- private-key-format 226 | +-- rsa-private-key-format 227 | +-- ec-private-key-format 228 | +-- one-asymmetric-key-format 229 | | {one-asymmetric-key-format}? 230 | +-- encrypted-one-asymmetric-key-format 231 | {encrypted-one-asymmetric-key-format}? 232 +-- symmetric-key-format 233 +-- octet-string-key-format 234 +-- one-symmetric-key-format 235 | {one-symmetric-key-format}? 236 +-- encrypted-one-symmetric-key-format 237 {encrypted-one-symmetric-key-format}? 239 Comments: 241 * The diagram shows that there are three base identities. These 242 identities are used by this module to define the format that key 243 data is encoded in. The base identities are "abstract", in the 244 object orientied programming sense, in that they only define a 245 "class" of formats, rather than a specific format. 247 * The various derived identities define specific key encoding 248 formats. The derived identities defined in this document are 249 sufficient for the effort described in Section 1.1 but, by nature 250 of them being identities, additional derived identities MAY be 251 defined by future efforts. 253 * Identities use to specify uncommon formats are enabled by 254 "feature" statements, enabling applications to support them when 255 needed. 257 2.1.3. Typedefs 259 The following diagram illustrates the relationship amongst the 260 "typedef" statements defined in the "ietf-crypto-types" module: 262 Typedefs: 263 binary 264 +-- csr-info 265 +-- csr 266 +-- x509 267 | +-- trust-anchor-cert-x509 268 | +-- end-entity-cert-x509 269 +-- crl 270 +-- ocsp-request 271 +-- ocsp-response 272 +-- cms 273 +-- data-content-cms 274 +-- signed-data-cms 275 | +-- trust-anchor-cert-cms 276 | +-- end-entity-cert-cms 277 +-- enveloped-data-cms 278 +-- digested-data-cms 279 +-- encrypted-data-cms 280 +-- authenticated-data-cms 282 Comments: 284 * All of the typedefs defined in the "ietf-crypto-types" module 285 extend the "binary" type defined in [RFC7950]. 287 * Additionally, all the typedefs define a type for encoding an ASN.1 288 [ITU.X680.2015] structure using DER [ITU.X690.2015]. 290 * The "trust-anchor-*" and "end-entity-*" typedefs are syntactically 291 identical to their base typedefs and only distiguish themselves by 292 the expected nature of their content. These typedefs are defined 293 to facilitate common modeling needs. 295 2.1.4. Groupings 297 The following diagram lists all the "grouping" statements defined in 298 the "ietf-crypto-types" module: 300 Groupings: 301 +-- encrypted-key-value-grouping 302 +-- symmetric-key-grouping 303 +-- public-key-grouping 304 +-- asymmetric-key-pair-grouping 305 +-- trust-anchor-cert-grouping 306 +-- end-entity-cert-grouping 307 +-- generate-csr-grouping 308 +-- asymmetric-key-pair-with-cert-grouping 309 +-- asymmetric-key-pair-with-certs-grouping 311 Each of these groupings are presented in the following subsections. 313 2.1.4.1. The "encrypted-key-value-grouping" Grouping 315 The following tree diagram [RFC8340] illustrates the "encrypted-key- 316 value-grouping" grouping: 318 grouping encrypted-key-value-grouping 319 +-- encrypted-by 320 +-- encrypted-value binary 322 Comments: 324 * The "encrypted-by" node is an empty container (difficult to see in 325 the diagram) that a consuming module MUST augment key references 326 into. The "ietf-crypto-types" module is unable to populate this 327 container as the module only defines groupings. Section 2.2.1 328 presents an example illustrating a consuming module populating the 329 "encrypted-by" container. 331 * The "encrypted-value" node is the key, encrypted by the other key 332 referenced by the "encrypted-by" node, encoded in the format 333 specified by the "format" identity Section 2.1.2 associated with 334 the ancestor node using this grouping. 336 2.1.4.2. The "symmetric-key-grouping" Grouping 338 This section presents two tree diagrams [RFC8340] illustrating the 339 "symmetric-key-grouping" grouping. The first tree diagram does not 340 expand the internally used grouping statement(s): 342 grouping symmetric-key-grouping 343 +-- key-format? identityref 344 +-- (key-type) 345 +--:(cleartext-key) 346 | +-- cleartext-key? binary 347 +--:(hidden-key) 348 | +-- hidden-key? empty 349 +--:(encrypted-key) 350 +-- encrypted-key 351 +---u encrypted-key-value-grouping 353 The following tree diagram expands the internally used grouping 354 statement(s), enabling the grouping's full structure to be seen: 356 grouping symmetric-key-grouping 357 +-- key-format? identityref 358 +-- (key-type) 359 +--:(cleartext-key) 360 | +-- cleartext-key? binary 361 +--:(hidden-key) 362 | +-- hidden-key? empty 363 +--:(encrypted-key) 364 +-- encrypted-key 365 +-- encrypted-by 366 +-- encrypted-value binary 368 Comments: 370 * For the referenced grouping statement(s): 372 - The "encrypted-key-value-grouping" grouping is discussed in 373 Section 2.1.4.1. 375 * The "key-format" node is an identity-reference to the "symmetric- 376 key-format" abstract base identity discussed in Section 2.1.2, 377 enabling the symmetric key to be encoded using the format defined 378 by any of the derived identities. 380 * The "choice" statement enables the private key data to be plain- 381 text, encrypted, or hidden, as follows: 383 - The "key" node can encode any plain-text key value. 384 - The "hidden-key" node is of type "empty" as the real value 385 cannot be presented via the management interface. 386 - The "encrypted-key" node's structure is discussed in 387 Section 2.1.4.1. 389 2.1.4.3. The "public-key-grouping" Grouping 391 The following tree diagram [RFC8340] illustrates the "public-key- 392 grouping" grouping: 394 grouping public-key-grouping 395 +-- public-key-format identityref 396 +-- public-key binary 398 Comments: 400 * The "public-key-format" node is an identity-reference to the 401 "public-key-format" abstract base identity discussed in 402 Section 2.1.2, enabling the public key to be encoded using the 403 format defined by any of the derived identities. 405 * The "public-key" node is the public key data in the selected 406 format. No "choice" statement is used to hide or encrypt the 407 public key data because it is unecessary to do so for public keys. 409 2.1.4.4. The "asymmetric-key-pair-grouping" Grouping 411 This section presents two tree diagrams [RFC8340] illustrating the 412 "asymmetric-key-pair-grouping" grouping. The first tree diagram does 413 not expand the internally used grouping statement(s): 415 grouping asymmetric-key-pair-grouping 416 +---u public-key-grouping 417 +-- private-key-format? identityref 418 +-- (private-key-type) 419 +--:(cleartext-private-key) 420 | +-- cleartext-private-key? binary 421 +--:(hidden-private-key) 422 | +-- hidden-private-key? empty 423 +--:(encrypted-private-key) 424 +-- encrypted-private-key 425 +---u encrypted-key-value-grouping 427 The following tree diagram expands the internally used grouping 428 statement(s), enabling the grouping's full structure to be seen: 430 grouping asymmetric-key-pair-grouping 431 +-- public-key-format identityref 432 +-- public-key binary 433 +-- private-key-format? identityref 434 +-- (private-key-type) 435 +--:(cleartext-private-key) 436 | +-- cleartext-private-key? binary 437 +--:(hidden-private-key) 438 | +-- hidden-private-key? empty 439 +--:(encrypted-private-key) 440 +-- encrypted-private-key 441 +-- encrypted-by 442 +-- encrypted-value binary 444 Comments: 446 * For the referenced grouping statement(s): 448 - The "public-key-grouping" grouping is discussed in 449 Section 2.1.4.3. 450 - The "encrypted-key-value-grouping" grouping is discussed in 451 Section 2.1.4.1. 453 * The "private-key-format" node is an identity-reference to the 454 "private-key-format" abstract base identity discussed in 455 Section 2.1.2, enabling the private key to be encoded using the 456 format defined by any of the derived identities. 458 * The "choice" statement enables the private key data to be plain- 459 text, encrypted, or hidden, as follows: 461 - The "private-key" node can encode any plain-text key value. 462 - The "hidden-private-key" node is of type "empty" as the real 463 value cannot be presented via the management interface. 464 - The "encrypted-private-key" node's structure is discussed in 465 Section 2.1.4.1. 467 2.1.4.5. The "certificate-expiration-grouping" Grouping 469 The following tree diagram [RFC8340] illustrates the "certificate- 470 expiration-grouping" grouping: 472 grouping certificate-expiration-grouping 473 +---n certificate-expiration 474 +-- expiration-date yang:date-and-time 476 Comments: 478 * This grouping's only purpose is to define the "certificate- 479 expiration" notification statement, used by the groupings defined 480 in Section 2.1.4.6 and Section 2.1.4.7. 482 * The "certificate-expiration" notification enables servers to 483 notify clients when certificates are nearing expiration. 485 * The "expiration-date" node indicates when the designated 486 certificate will (or did) expire. 488 * Identification of the certificate that is expiring is built into 489 the notification itself. For an example, please see 490 Section 2.2.3. 492 2.1.4.6. The "trust-anchor-cert-grouping" Grouping 494 This section presents two tree diagrams [RFC8340] illustrating the 495 "trust-anchor-cert-grouping" grouping. The first tree diagram does 496 not expand the internally used grouping statement(s): 498 grouping trust-anchor-cert-grouping 499 +-- cert-data? trust-anchor-cert-cms 500 +---u certificate-expiration-grouping 502 The following tree diagram expands the internally used grouping 503 statement(s), enabling the grouping's full structure to be seen: 505 grouping trust-anchor-cert-grouping 506 +-- cert-data? trust-anchor-cert-cms 507 +---n certificate-expiration 508 +-- expiration-date yang:date-and-time 510 Comments: 512 * For the referenced grouping statement(s): 514 - The "certificate-expiration-grouping" grouping is discussed in 515 Section 2.1.4.5. 517 * The "cert-data" node contains a chain of one or more certificates 518 encoded using a "signed-data-cms" typedef discussed in 519 Section 2.1.3. 521 2.1.4.7. The "end-entity-cert-grouping" Grouping 523 This section presents two tree diagrams [RFC8340] illustrating the 524 "end-entity-cert-grouping" grouping. The first tree diagram does not 525 expand the internally used grouping statement(s): 527 grouping end-entity-cert-grouping 528 +-- cert-data? end-entity-cert-cms 529 +---u certificate-expiration-grouping 531 The following tree diagram expands the internally used grouping 532 statement(s), enabling the grouping's full structure to be seen: 534 grouping end-entity-cert-grouping 535 +-- cert-data? end-entity-cert-cms 536 +---n certificate-expiration 537 +-- expiration-date yang:date-and-time 539 Comments: 541 * For the referenced grouping statement(s): 543 - The "certificate-expiration-grouping" grouping is discussed in 544 Section 2.1.4.5. 546 * The "cert-data" node contains a chain of one or more certificates 547 encoded using a "signed-data-cms" typedef discussed in 548 Section 2.1.3. 550 2.1.4.8. The "generate-csr-grouping" Grouping 552 The following tree diagram [RFC8340] illustrates the "generate-csr- 553 grouping" grouping: 555 grouping generate-csr-grouping 556 +---x generate-certificate-signing-request 557 {certificate-signing-request-generation}? 558 +---w input 559 | +---w csr-info ct:csr-info 560 +--ro output 561 +--ro certificate-signing-request ct:csr 563 Comments: 565 * This grouping's only purpose is to define the "generate- 566 certificate-signing-request" action statement, used by the 567 groupings defined in Section 2.1.4.9 and Section 2.1.4.10. 569 * This action takes as input a "csr-info" type and returns a "csr" 570 type, both of which are discussed in Section 2.1.3. 572 * For an example, please see Section 2.2.2. 574 2.1.4.9. The "asymmetric-key-pair-with-cert-grouping" Grouping 576 This section presents two tree diagrams [RFC8340] illustrating the 577 "asymmetric-key-pair-with-cert-grouping" grouping. The first tree 578 diagram does not expand the internally used grouping statement(s): 580 grouping asymmetric-key-pair-with-cert-grouping 581 +---u asymmetric-key-pair-grouping 582 +---u end-entity-cert-grouping 583 +---u generate-csr-grouping 585 The following tree diagram expands the internally used grouping 586 statement(s), enabling the grouping's full structure to be seen: 588 grouping asymmetric-key-pair-with-cert-grouping 589 +-- public-key-format identityref 590 +-- public-key binary 591 +-- private-key-format? identityref 592 +-- (private-key-type) 593 | +--:(cleartext-private-key) 594 | | +-- cleartext-private-key? binary 595 | +--:(hidden-private-key) 596 | | +-- hidden-private-key? empty 597 | +--:(encrypted-private-key) 598 | +-- encrypted-private-key 599 | +-- encrypted-by 600 | +-- encrypted-value binary 601 +-- cert-data? end-entity-cert-cms 602 +---n certificate-expiration 603 | +-- expiration-date yang:date-and-time 604 +---x generate-certificate-signing-request 605 {certificate-signing-request-generation}? 606 +---w input 607 | +---w csr-info ct:csr-info 608 +--ro output 609 +--ro certificate-signing-request ct:csr 611 Comments: 613 * This grouping defines an asymmetric key with at most one 614 associated certificate, a commonly needed combination in protocol 615 models. 617 * For the referenced grouping statement(s): 619 - The "asymmetric-key-pair-grouping" grouping is discussed in 620 Section 2.1.4.4. 621 - The "end-entity-cert-grouping" grouping is discussed in 622 Section 2.1.4.7. 623 - The "generate-csr-grouping" grouping is discussed in 624 Section 2.1.4.8. 626 2.1.4.10. The "asymmetric-key-pair-with-certs-grouping" Grouping 628 This section presents two tree diagrams [RFC8340] illustrating the 629 "asymmetric-key-pair-with-certs-grouping" grouping. The first tree 630 diagram does not expand the internally used grouping statement(s): 632 grouping asymmetric-key-pair-with-certs-grouping 633 +---u asymmetric-key-pair-grouping 634 +-- certificates 635 | +-- certificate* [name] 636 | +-- name? string 637 | +---u end-entity-cert-grouping 638 +---u generate-csr-grouping 640 The following tree diagram expands the internally used grouping 641 statement(s), enabling the grouping's full structure to be seen: 643 grouping asymmetric-key-pair-with-certs-grouping 644 +-- public-key-format identityref 645 +-- public-key binary 646 +-- private-key-format? identityref 647 +-- (private-key-type) 648 | +--:(cleartext-private-key) 649 | | +-- cleartext-private-key? binary 650 | +--:(hidden-private-key) 651 | | +-- hidden-private-key? empty 652 | +--:(encrypted-private-key) 653 | +-- encrypted-private-key 654 | +-- encrypted-by 655 | +-- encrypted-value binary 656 +-- certificates 657 | +-- certificate* [name] 658 | +-- name? string 659 | +-- cert-data end-entity-cert-cms 660 | +---n certificate-expiration 661 | +-- expiration-date yang:date-and-time 662 +---x generate-certificate-signing-request 663 {certificate-signing-request-generation}? 664 +---w input 665 | +---w csr-info ct:csr-info 666 +--ro output 667 +--ro certificate-signing-request ct:csr 669 Comments: 671 * This grouping defines an asymmetric key with one or more 672 associated certificates, a commonly needed combination in 673 configuration models. 675 * For the referenced grouping statement(s): 677 - The "asymmetric-key-pair-grouping" grouping is discussed in 678 Section 2.1.4.4. 680 - The "end-entity-cert-grouping" grouping is discussed in 681 Section 2.1.4.7. 682 - The "generate-csr-grouping" grouping is discussed in 683 Section 2.1.4.8. 685 2.1.5. Protocol-accessible Nodes 687 The "ietf-crypto-types" module does not contain any protocol- 688 accessible nodes, but the module needs to be "implemented", as 689 described in Section 5.6.5 of [RFC7950], in order for the identities 690 in Section 2.1.2 to be defined. 692 2.2. Example Usage 694 2.2.1. The "symmetric-key-grouping" and "asymmetric-key-pair-with- 695 certs-grouping" Grouping 697 The following non-normative module is constructed in order to 698 illustrate the use of the "symmetric-key-grouping" (Section 2.1.4.2) 699 and the "asymmetric-key-pair-with-certs-grouping" (Section 2.1.4.10) 700 grouping statements: 702 module ex-crypto-types-usage { 703 yang-version 1.1; 705 namespace "http://example.com/ns/example-crypto-types-usage"; 706 prefix "ectu"; 708 import ietf-crypto-types { 709 prefix ct; 710 reference 711 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 712 } 714 organization "Example Corporation"; 715 contact "YANG Designer "; 717 description 718 "This module illustrates the 'symmetric-key-grouping' 719 and 'asymmetric-key-grouping' groupings defined in 720 the 'ietf-crypto-types' module defined in RFC AAAA."; 722 revision "2020-07-10" { 723 description 724 "Initial version"; 725 reference 726 "RFC AAAA: Common YANG Data Types for Cryptography"; 727 } 728 container symmetric-keys { 729 description 730 "A container of symmetric keys."; 731 list symmetric-key { 732 key name; 733 description 734 "A symmetric key"; 735 leaf name { 736 type string; 737 description 738 "An arbitrary name for this key."; 739 } 740 uses ct:symmetric-key-grouping { 741 augment "key-type/encrypted-key/encrypted-key/" 742 + "encrypted-by" { 743 description 744 "Augments in a choice statement enabling the 745 encrypting key to be any other symmetric or 746 asymmetric key."; 747 uses encrypted-by-choice-grouping; 748 } 749 } 750 } 751 } 753 container asymmetric-keys { 754 description 755 "A container of asymmetric keys."; 756 list asymmetric-key { 757 key name; 758 leaf name { 759 type string; 760 description 761 "An arbitrary name for this key."; 762 } 763 uses ct:asymmetric-key-pair-with-certs-grouping { 764 augment "private-key-type/encrypted-private-key/" 765 + "encrypted-private-key/encrypted-by" { 766 description 767 "Augments in a choice statement enabling the 768 encrypting key to be any other symmetric or 769 asymmetric key."; 770 uses encrypted-by-choice-grouping; 771 } 772 } 773 description 774 "An asymmetric key pair with associated certificates."; 775 } 777 } 779 grouping encrypted-by-choice-grouping { 780 description 781 "A grouping that defines a choice enabling references 782 to other keys."; 783 choice encrypted-by-choice { 784 mandatory true; 785 description 786 "A choice amongst other symmetric or asymmetric keys."; 787 case symmetric-key-ref { 788 leaf symmetric-key-ref { 789 type leafref { 790 path "/ectu:symmetric-keys/ectu:symmetric-key/" 791 + "ectu:name"; 792 } 793 description 794 "Identifies the symmetric key used to encrypt this key."; 795 } 796 } 797 case asymmetric-key-ref { 798 leaf asymmetric-key-ref { 799 type leafref { 800 path "/ectu:asymmetric-keys/ectu:asymmetric-key/" 801 + "ectu:name"; 802 } 803 description 804 "Identifies the asymmetric key used to encrypt this key."; 805 } 806 } 807 } 808 } 809 } 811 The tree diagram [RFC8340] for this example module follows: 813 module: ex-crypto-types-usage 814 +--rw symmetric-keys 815 | +--rw symmetric-key* [name] 816 | +--rw name string 817 | +--rw key-format? identityref 818 | +--rw (key-type) 819 | +--:(cleartext-key) 820 | | +--rw cleartext-key? binary 821 | +--:(hidden-key) 822 | | +--rw hidden-key? empty 823 | +--:(encrypted-key) 824 | +--rw encrypted-key 825 | +--rw encrypted-by 826 | | +--rw (encrypted-by-choice) 827 | | +--:(symmetric-key-ref) 828 | | | +--rw symmetric-key-ref? leafref 829 | | +--:(asymmetric-key-ref) 830 | | +--rw asymmetric-key-ref? leafref 831 | +--rw encrypted-value binary 832 +--rw asymmetric-keys 833 +--rw asymmetric-key* [name] 834 +--rw name string 835 +--rw public-key-format identityref 836 +--rw public-key binary 837 +--rw private-key-format? identityref 838 +--rw (private-key-type) 839 | +--:(cleartext-private-key) 840 | | +--rw cleartext-private-key? binary 841 | +--:(hidden-private-key) 842 | | +--rw hidden-private-key? empty 843 | +--:(encrypted-private-key) 844 | +--rw encrypted-private-key 845 | +--rw encrypted-by 846 | | +--rw (encrypted-by-choice) 847 | | +--:(symmetric-key-ref) 848 | | | +--rw symmetric-key-ref? leafref 849 | | +--:(asymmetric-key-ref) 850 | | +--rw asymmetric-key-ref? leafref 851 | +--rw encrypted-value binary 852 +--rw certificates 853 | +--rw certificate* [name] 854 | +--rw name string 855 | +--rw cert-data end-entity-cert-cms 856 | +---n certificate-expiration 857 | +-- expiration-date yang:date-and-time 858 +---x generate-certificate-signing-request 859 {certificate-signing-request-generation}? 860 +---w input 861 | +---w csr-info ct:csr-info 862 +--ro output 863 +--ro certificate-signing-request ct:csr 865 grouping encrypted-by-choice-grouping 866 +-- (encrypted-by-choice) 867 +--:(symmetric-key-ref) 868 | +-- symmetric-key-ref? 869 | -> /symmetric-keys/symmetric-key/name 870 +--:(asymmetric-key-ref) 871 +-- asymmetric-key-ref? 872 -> /asymmetric-keys/asymmetric-key/name 874 Finally, the following example illustrates various symmetric and 875 asymmetric keys as they might appear in confugration: 877 =============== NOTE: '\' line wrapping per RFC 8792 ================ 879 882 883 ex-hidden-symmetric-key 884 885 886 887 ex-octet-string-based-symmetric-key 888 ct:octet-string-key-format 889 base64encodedvalue== 890 891 892 ex-one-symmetric-based-symmetric-key 893 ct:one-symmetric-key-format 894 base64encodedvalue== 895 896 897 ex-encrypted-one-symmetric-based-symmetric-key 898 ct:encrypted-one-symmetric-key-format 899 900 901 ex-hidden-asymmetric-key 903 904 base64encodedvalue== 905 906 907 909 912 913 ex-hidden-asymmetric-key 914 915 ct:subject-public-key-info-format 916 917 base64encodedvalue== 918 919 920 921 ex-hidden-asymmetric-key-cert 922 base64encodedvalue== 923 924 925 926 927 ex-subject-public-info-based-asymmetric-key 928 929 ct:subject-public-key-info-format 930 931 base64encodedvalue== 932 933 ct:rsa-private-key-format 934 935 base64encodedvalue== 937 938 939 ex-cert 940 base64encodedvalue== 941 942 943 944 945 ex-one-asymmetric-based-symmetric-key 946 947 ct:subject-public-key-info-format 948 949 base64encodedvalue== 950 951 ct:one-asymmetric-key-format 952 953 base64encodedvalue== 955 956 957 ex-encrypted-one-asymmetric-based-symmetric-key 958 959 ct:subject-public-key-info-format 960 961 base64encodedvalue== 962 963 ct:encrypted-one-asymmetric-key-format 964 965 966 967 ex-encrypted-one-symmetric-based-symmetri\ 968 c-key 969 970 base64encodedvalue== 971 972 973 975 2.2.2. The "generate-certificate-signing-request" Action 977 The following example illustrates the "generate-certificate-signing- 978 request" action, discussed in Section 2.1.4.8, with the NETCONF 979 protocol. 981 REQUEST 983 985 986 988 989 ex-key-sect571r1 990 991 base64encodedvalue== 992 993 994 995 996 998 RESPONSE 1000 1002 1004 base64encodedvalue== 1005 1006 1008 2.2.3. The "certificate-expiration" Notification 1010 The following example illustrates the "certificate-expiration" 1011 notification, discussed in Section 2.1.4.5, with the NETCONF 1012 protocol. 1014 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1016 1018 2018-05-25T00:01:00Z 1019 1021 1022 ex-hidden-asymmetric-key 1023 1024 1025 ex-hidden-asymmetric-key 1026 1027 2018-08-05T14:18:53-05:00 1029 1030 1031 1032 1033 1034 1036 2.3. YANG Module 1038 This module has normative references to [RFC2119], [RFC2986], 1039 [RFC3447], [RFC4253], [RFC5280], [RFC5652], [RFC5915], [RFC5958], 1040 [RFC6031], [RFC6125], [RFC6991], [RFC8174], [RFC8341], and 1041 [ITU.X690.2015]. 1043 file "ietf-crypto-types@2020-07-10.yang" 1045 module ietf-crypto-types { 1046 yang-version 1.1; 1047 namespace "urn:ietf:params:xml:ns:yang:ietf-crypto-types"; 1048 prefix ct; 1050 import ietf-yang-types { 1051 prefix yang; 1052 reference 1053 "RFC 6991: Common YANG Data Types"; 1054 } 1056 import ietf-netconf-acm { 1057 prefix nacm; 1058 reference 1059 "RFC 8341: Network Configuration Access Control Model"; 1060 } 1061 organization 1062 "IETF NETCONF (Network Configuration) Working Group"; 1064 contact 1065 "WG Web: 1066 WG List: 1067 Author: Kent Watsen "; 1069 description 1070 "This module defines common YANG types for cryptographic 1071 applications. 1073 Copyright (c) 2020 IETF Trust and the persons identified 1074 as authors of the code. All rights reserved. 1076 Redistribution and use in source and binary forms, with 1077 or without modification, is permitted pursuant to, and 1078 subject to the license terms contained in, the Simplified 1079 BSD License set forth in Section 4.c of the IETF Trust's 1080 Legal Provisions Relating to IETF Documents 1081 (https://trustee.ietf.org/license-info). 1083 This version of this YANG module is part of RFC AAAA 1084 (https://www.rfc-editor.org/info/rfcAAAA); see the RFC 1085 itself for full legal notices. 1087 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1088 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1089 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1090 are to be interpreted as described in BCP 14 (RFC 2119) 1091 (RFC 8174) when, and only when, they appear in all 1092 capitals, as shown here."; 1094 revision 2020-07-10 { 1095 description 1096 "Initial version"; 1097 reference 1098 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1099 } 1101 /****************/ 1102 /* Features */ 1103 /****************/ 1105 feature one-symmetric-key-format { 1106 description 1107 "Indicates that the server supports the 1108 'one-symmetric-key-format' identity."; 1109 } 1111 feature one-asymmetric-key-format { 1112 description 1113 "Indicates that the server supports the 1114 'one-asymmetric-key-format' identity."; 1115 } 1117 feature encrypted-one-symmetric-key-format { 1118 description 1119 "Indicates that the server supports the 1120 'encrypted-one-symmetric-key-format' identity."; 1121 } 1123 feature encrypted-one-asymmetric-key-format { 1124 description 1125 "Indicates that the server supports the 1126 'encrypted-one-asymmetric-key-format' identity."; 1127 } 1129 feature certificate-signing-request-generation { 1130 description 1131 "Indicates that the server implements the 1132 'generate-certificate-signing-request' action."; 1133 } 1135 /*************************************************/ 1136 /* Base Identities for Key Format Structures */ 1137 /*************************************************/ 1139 identity symmetric-key-format { 1140 description "Base key-format identity for symmetric keys."; 1141 } 1143 identity public-key-format { 1144 description "Base key-format identity for public keys."; 1145 } 1147 identity private-key-format { 1148 description "Base key-format identity for private keys."; 1149 } 1151 /****************************************************/ 1152 /* Identities for Private Key Format Structures */ 1153 /****************************************************/ 1154 identity rsa-private-key-format { 1155 base "private-key-format"; 1156 description 1157 "Indicates that the private key value is encoded 1158 as an RSAPrivateKey (from RFC 3447)."; 1159 reference 1160 "RFC 3447: PKCS #1: RSA Cryptography 1161 Specifications Version 2.2"; 1162 } 1164 identity ec-private-key-format { 1165 base "private-key-format"; 1166 description 1167 "Indicates that the private key value is encoded 1168 as an ECPrivateKey (from RFC 5915)"; 1169 reference 1170 "RFC 5915: Elliptic Curve Private Key Structure"; 1171 } 1173 identity one-asymmetric-key-format { 1174 if-feature "one-asymmetric-key-format"; 1175 base "private-key-format"; 1176 description 1177 "Indicates that the private key value is a CMS 1178 OneAsymmetricKey structure, as defined in RFC 5958, 1179 encoded using ASN.1 distinguished encoding rules 1180 (DER), as specified in ITU-T X.690."; 1181 reference 1182 "RFC 5958: Asymmetric Key Packages 1183 ITU-T X.690: 1184 Information technology - ASN.1 encoding rules: 1185 Specification of Basic Encoding Rules (BER), 1186 Canonical Encoding Rules (CER) and Distinguished 1187 Encoding Rules (DER)."; 1188 } 1190 identity encrypted-one-asymmetric-key-format { 1191 if-feature "encrypted-one-asymmetric-key-format"; 1192 base "private-key-format"; 1193 description 1194 "Indicates that the private key value is a CMS EnvelopedData 1195 structure, per Section 8 in RFC 5652, containing a 1196 OneAsymmetricKey structure, as defined in RFC 5958, 1197 encoded using ASN.1 distinguished encoding rules (DER), 1198 as specified in ITU-T X.690."; 1199 reference 1200 "RFC 5652: Cryptographic Message Syntax (CMS) 1201 RFC 5958: Asymmetric Key Packages 1202 ITU-T X.690: 1203 Information technology - ASN.1 encoding rules: 1204 Specification of Basic Encoding Rules (BER), 1205 Canonical Encoding Rules (CER) and Distinguished 1206 Encoding Rules (DER)."; 1207 } 1209 /***************************************************/ 1210 /* Identities for Public Key Format Structures */ 1211 /***************************************************/ 1213 identity ssh-public-key-format { 1214 base "public-key-format"; 1215 description 1216 "Indicates that the public key value is an SSH public key, 1217 as specified by RFC 4253, Section 6.6, i.e.: 1219 string certificate or public key format 1220 identifier 1221 byte[n] key/certificate data."; 1222 reference 1223 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1224 } 1226 identity subject-public-key-info-format { 1227 base "public-key-format"; 1228 description 1229 "Indicates that the public key value is a SubjectPublicKeyInfo 1230 structure, as described in RFC 5280 encoded using ASN.1 1231 distinguished encoding rules (DER), as specified in 1232 ITU-T X.690."; 1233 reference 1234 "RFC 5280: 1235 Internet X.509 Public Key Infrastructure Certificate 1236 and Certificate Revocation List (CRL) Profile 1237 ITU-T X.690: 1238 Information technology - ASN.1 encoding rules: 1239 Specification of Basic Encoding Rules (BER), 1240 Canonical Encoding Rules (CER) and Distinguished 1241 Encoding Rules (DER)."; 1242 } 1244 /******************************************************/ 1245 /* Identities for Symmetric Key Format Structures */ 1246 /******************************************************/ 1247 identity octet-string-key-format { 1248 base "symmetric-key-format"; 1249 description 1250 "Indicates that the key is encoded as a raw octet string. 1251 The length of the octet string MUST be appropriate for 1252 the associated algorithm's block size."; 1253 } 1255 identity one-symmetric-key-format { 1256 if-feature "one-symmetric-key-format"; 1257 base "symmetric-key-format"; 1258 description 1259 "Indicates that the private key value is a CMS 1260 OneSymmetricKey structure, as defined in RFC 6031, 1261 encoded using ASN.1 distinguished encoding rules 1262 (DER), as specified in ITU-T X.690."; 1263 reference 1264 "RFC 6031: Cryptographic Message Syntax (CMS) 1265 Symmetric Key Package Content Type 1266 ITU-T X.690: 1267 Information technology - ASN.1 encoding rules: 1268 Specification of Basic Encoding Rules (BER), 1269 Canonical Encoding Rules (CER) and Distinguished 1270 Encoding Rules (DER)."; 1271 } 1273 identity encrypted-one-symmetric-key-format { 1274 if-feature "encrypted-one-symmetric-key-format"; 1275 base "symmetric-key-format"; 1276 description 1277 "Indicates that the private key value is a CMS 1278 EnvelopedData structure, per Section 8 in RFC 5652, 1279 containing a OneSymmetricKey structure, as defined 1280 in RFC 6031, encoded using ASN.1 distinguished 1281 encoding rules (DER), as specified in ITU-T X.690."; 1282 reference 1283 "RFC 5652: Cryptographic Message Syntax (CMS) 1284 RFC 6031: Cryptographic Message Syntax (CMS) 1285 Symmetric Key Package Content Type 1286 ITU-T X.690: 1287 Information technology - ASN.1 encoding rules: 1288 Specification of Basic Encoding Rules (BER), 1289 Canonical Encoding Rules (CER) and Distinguished 1290 Encoding Rules (DER)."; 1291 } 1293 /***************************************************/ 1294 /* Typedefs for ASN.1 structures from RFC 2986 */ 1295 /***************************************************/ 1297 typedef csr-info { 1298 type binary; 1299 description 1300 "A CertificationRequestInfo structure, as defined in 1301 RFC 2986, encoded using ASN.1 distinguished encoding 1302 rules (DER), as specified in ITU-T X.690."; 1303 reference 1304 "RFC 2986: PKCS #10: Certification Request Syntax 1305 Specification Version 1.7 1306 ITU-T X.690: 1307 Information technology - ASN.1 encoding rules: 1308 Specification of Basic Encoding Rules (BER), 1309 Canonical Encoding Rules (CER) and Distinguished 1310 Encoding Rules (DER)."; 1311 } 1313 typedef csr { 1314 type binary; 1315 description 1316 "A CertificationRequest structure, as specified in 1317 RFC 2986, encoded using ASN.1 distinguished encoding 1318 rules (DER), as specified in ITU-T X.690."; 1319 reference 1320 "RFC 2986: 1321 PKCS #10: Certification Request Syntax Specification 1322 Version 1.7 1323 ITU-T X.690: 1324 Information technology - ASN.1 encoding rules: 1325 Specification of Basic Encoding Rules (BER), 1326 Canonical Encoding Rules (CER) and Distinguished 1327 Encoding Rules (DER)."; 1328 } 1330 /***************************************************/ 1331 /* Typedefs for ASN.1 structures from RFC 5280 */ 1332 /***************************************************/ 1334 typedef x509 { 1335 type binary; 1336 description 1337 "A Certificate structure, as specified in RFC 5280, 1338 encoded using ASN.1 distinguished encoding rules (DER), 1339 as specified in ITU-T X.690."; 1340 reference 1341 "RFC 5280: 1343 Internet X.509 Public Key Infrastructure Certificate 1344 and Certificate Revocation List (CRL) Profile 1345 ITU-T X.690: 1346 Information technology - ASN.1 encoding rules: 1347 Specification of Basic Encoding Rules (BER), 1348 Canonical Encoding Rules (CER) and Distinguished 1349 Encoding Rules (DER)."; 1350 } 1352 typedef crl { 1353 type binary; 1354 description 1355 "A CertificateList structure, as specified in RFC 5280, 1356 encoded using ASN.1 distinguished encoding rules (DER), 1357 as specified in ITU-T X.690."; 1358 reference 1359 "RFC 5280: 1360 Internet X.509 Public Key Infrastructure Certificate 1361 and Certificate Revocation List (CRL) Profile 1362 ITU-T X.690: 1363 Information technology - ASN.1 encoding rules: 1364 Specification of Basic Encoding Rules (BER), 1365 Canonical Encoding Rules (CER) and Distinguished 1366 Encoding Rules (DER)."; 1367 } 1369 /***************************************************/ 1370 /* Typedefs for ASN.1 structures from RFC 6960 */ 1371 /***************************************************/ 1373 typedef oscp-request { 1374 type binary; 1375 description 1376 "A OCSPRequest structure, as specified in RFC 6960, 1377 encoded using ASN.1 distinguished encoding rules 1378 (DER), as specified in ITU-T X.690."; 1379 reference 1380 "RFC 6960: 1381 X.509 Internet Public Key Infrastructure Online 1382 Certificate Status Protocol - OCSP 1383 ITU-T X.690: 1384 Information technology - ASN.1 encoding rules: 1385 Specification of Basic Encoding Rules (BER), 1386 Canonical Encoding Rules (CER) and Distinguished 1387 Encoding Rules (DER)."; 1388 } 1389 typedef oscp-response { 1390 type binary; 1391 description 1392 "A OCSPResponse structure, as specified in RFC 6960, 1393 encoded using ASN.1 distinguished encoding rules 1394 (DER), as specified in ITU-T X.690."; 1395 reference 1396 "RFC 6960: 1397 X.509 Internet Public Key Infrastructure Online 1398 Certificate Status Protocol - OCSP 1399 ITU-T X.690: 1400 Information technology - ASN.1 encoding rules: 1401 Specification of Basic Encoding Rules (BER), 1402 Canonical Encoding Rules (CER) and Distinguished 1403 Encoding Rules (DER)."; 1404 } 1406 /***********************************************/ 1407 /* Typedefs for ASN.1 structures from 5652 */ 1408 /***********************************************/ 1410 typedef cms { 1411 type binary; 1412 description 1413 "A ContentInfo structure, as specified in RFC 5652, 1414 encoded using ASN.1 distinguished encoding rules (DER), 1415 as specified in ITU-T X.690."; 1416 reference 1417 "RFC 5652: 1418 Cryptographic Message Syntax (CMS) 1419 ITU-T X.690: 1420 Information technology - ASN.1 encoding rules: 1421 Specification of Basic Encoding Rules (BER), 1422 Canonical Encoding Rules (CER) and Distinguished 1423 Encoding Rules (DER)."; 1424 } 1426 typedef data-content-cms { 1427 type cms; 1428 description 1429 "A CMS structure whose top-most content type MUST be the 1430 data content type, as described by Section 4 in RFC 5652."; 1431 reference 1432 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1433 } 1435 typedef signed-data-cms { 1436 type cms; 1437 description 1438 "A CMS structure whose top-most content type MUST be the 1439 signed-data content type, as described by Section 5 in 1440 RFC 5652."; 1441 reference 1442 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1443 } 1445 typedef enveloped-data-cms { 1446 type cms; 1447 description 1448 "A CMS structure whose top-most content type MUST be the 1449 enveloped-data content type, as described by Section 6 1450 in RFC 5652."; 1451 reference 1452 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1453 } 1455 typedef digested-data-cms { 1456 type cms; 1457 description 1458 "A CMS structure whose top-most content type MUST be the 1459 digested-data content type, as described by Section 7 1460 in RFC 5652."; 1461 reference 1462 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1463 } 1465 typedef encrypted-data-cms { 1466 type cms; 1467 description 1468 "A CMS structure whose top-most content type MUST be the 1469 encrypted-data content type, as described by Section 8 1470 in RFC 5652."; 1471 reference 1472 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1473 } 1475 typedef authenticated-data-cms { 1476 type cms; 1477 description 1478 "A CMS structure whose top-most content type MUST be the 1479 authenticated-data content type, as described by Section 9 1480 in RFC 5652."; 1481 reference 1482 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1483 } 1484 /*********************************************************/ 1485 /* Typedefs for ASN.1 structures related to RFC 5280 */ 1486 /*********************************************************/ 1488 typedef trust-anchor-cert-x509 { 1489 type x509; 1490 description 1491 "A Certificate structure that MUST encode a self-signed 1492 root certificate."; 1493 } 1495 typedef end-entity-cert-x509 { 1496 type x509; 1497 description 1498 "A Certificate structure that MUST encode a certificate 1499 that is neither self-signed nor having Basic constraint 1500 CA true."; 1501 } 1503 /*********************************************************/ 1504 /* Typedefs for ASN.1 structures related to RFC 5652 */ 1505 /*********************************************************/ 1507 typedef trust-anchor-cert-cms { 1508 type signed-data-cms; 1509 description 1510 "A CMS SignedData structure that MUST contain the chain of 1511 X.509 certificates needed to authenticate the certificate 1512 presented by a client or end-entity. 1514 The CMS MUST contain only a single chain of certificates. 1515 The client or end-entity certificate MUST only authenticate 1516 to last intermediate CA certificate listed in the chain. 1518 In all cases, the chain MUST include a self-signed root 1519 certificate. In the case where the root certificate is 1520 itself the issuer of the client or end-entity certificate, 1521 only one certificate is present. 1523 This CMS structure MAY (as applicable where this type is 1524 used) also contain suitably fresh (as defined by local 1525 policy) revocation objects with which the device can 1526 verify the revocation status of the certificates. 1528 This CMS encodes the degenerate form of the SignedData 1529 structure that is commonly used to disseminate X.509 1530 certificates and revocation objects (RFC 5280)."; 1532 reference 1533 "RFC 5280: 1534 Internet X.509 Public Key Infrastructure Certificate 1535 and Certificate Revocation List (CRL) Profile."; 1536 } 1538 typedef end-entity-cert-cms { 1539 type signed-data-cms; 1540 description 1541 "A CMS SignedData structure that MUST contain the end 1542 entity certificate itself, and MAY contain any number 1543 of intermediate certificates leading up to a trust 1544 anchor certificate. The trust anchor certificate 1545 MAY be included as well. 1547 The CMS MUST contain a single end entity certificate. 1548 The CMS MUST NOT contain any spurious certificates. 1550 This CMS structure MAY (as applicable where this type is 1551 used) also contain suitably fresh (as defined by local 1552 policy) revocation objects with which the device can 1553 verify the revocation status of the certificates. 1555 This CMS encodes the degenerate form of the SignedData 1556 structure that is commonly used to disseminate X.509 1557 certificates and revocation objects (RFC 5280)."; 1558 reference 1559 "RFC 5280: 1560 Internet X.509 Public Key Infrastructure Certificate 1561 and Certificate Revocation List (CRL) Profile."; 1562 } 1564 /**********************************************/ 1565 /* Groupings for keys and/or certificates */ 1566 /**********************************************/ 1568 grouping encrypted-key-value-grouping { 1569 description 1570 "A reusable grouping for a value that has been encrypted by 1571 a symmetric or asymmetric key in the Keystore."; 1572 container encrypted-by { 1573 nacm:default-deny-write; 1574 description 1575 "An empty container enabling references to other keys that 1576 encrypt these keys to be augmented in. The referenced key 1577 MAY be a symmetric or an asymmetric key."; 1578 } 1579 leaf encrypted-value { 1580 nacm:default-deny-write; 1581 type binary; 1582 must "../encrypted-by"; 1583 mandatory true; 1584 description 1585 "The key data, encrypted using the referenced symmetric 1586 or asymmetric key. The format of the encrypted value 1587 is identicated by the associated key format identity."; 1588 } 1589 } 1591 grouping symmetric-key-grouping { 1592 description 1593 "A symmetric key."; 1594 leaf key-format { 1595 nacm:default-deny-write; 1596 type identityref { 1597 base symmetric-key-format; 1598 } 1599 description "Identifies the symmetric key's format."; 1600 } 1601 choice key-type { 1602 nacm:default-deny-write; 1603 mandatory true; 1604 description 1605 "Choice between key types."; 1606 case cleartext-key { 1607 leaf cleartext-key { 1608 nacm:default-deny-all; 1609 type binary; 1610 must "../key-format"; 1611 description 1612 "The binary value of the key. The interpretation of 1613 the value is defined by the 'key-format' field."; 1614 } 1615 } 1616 case hidden-key { 1617 leaf hidden-key { 1618 type empty; 1619 must "not(../key-format)"; 1620 description 1621 "A hidden key. How such keys are created is outside 1622 the scope of this module."; 1623 } 1624 } 1625 case encrypted-key { 1626 container encrypted-key { 1627 must "../key-format"; 1628 description 1629 "A container for the encrypted symmetric key value."; 1630 uses encrypted-key-value-grouping; 1631 } 1632 } 1633 } 1634 } 1636 grouping public-key-grouping { 1637 description 1638 "A public key."; 1639 leaf public-key-format { 1640 nacm:default-deny-write; 1641 type identityref { 1642 base public-key-format; 1643 } 1644 mandatory true; 1645 description "Identifies the key's format."; 1646 } 1647 leaf public-key { 1648 nacm:default-deny-write; 1649 type binary; 1650 mandatory true; 1651 description 1652 "The binary value of the public key. The interpretation 1653 of the value is defined by 'public-key-format' field."; 1654 } 1655 } 1657 grouping asymmetric-key-pair-grouping { 1658 description 1659 "A private key and its associated public key."; 1660 uses public-key-grouping; 1661 leaf private-key-format { 1662 nacm:default-deny-write; 1663 type identityref { 1664 base private-key-format; 1665 } 1666 description "Identifies the key's format."; 1667 } 1668 choice private-key-type { 1669 nacm:default-deny-write; 1670 mandatory true; 1671 description 1672 "Choice between key types."; 1673 case cleartext-private-key { 1674 leaf cleartext-private-key { 1675 nacm:default-deny-all; 1676 type binary; 1677 must "../private-key-format"; 1678 description 1679 "The value of the binary key The key's value is 1680 interpreted by the 'private-key-format' field."; 1681 } 1682 } 1683 case hidden-private-key { 1684 leaf hidden-private-key { 1685 type empty; 1686 must "not(../private-key-format)"; 1687 description 1688 "A hidden key. How such keys are created is 1689 outside the scope of this module."; 1690 } 1691 } 1692 case encrypted-private-key { 1693 container encrypted-private-key { 1694 must "../private-key-format"; 1695 description 1696 "A container for the encrypted asymmetric private 1697 key value."; 1698 uses encrypted-key-value-grouping; 1699 } 1700 } 1701 } 1702 } 1704 grouping certificate-expiration-grouping { 1705 description 1706 "A notification for when a certificate is about to, or 1707 already has, expired."; 1708 notification certificate-expiration { 1709 description 1710 "A notification indicating that the configured certificate 1711 is either about to expire or has already expired. When to 1712 send notifications is an implementation specific decision, 1713 but it is RECOMMENDED that a notification be sent once a 1714 month for 3 months, then once a week for four weeks, and 1715 then once a day thereafter until the issue is resolved."; 1716 leaf expiration-date { 1717 type yang:date-and-time; 1718 mandatory true; 1719 description 1720 "Identifies the expiration date on the certificate."; 1721 } 1722 } 1724 } 1726 grouping trust-anchor-cert-grouping { 1727 description 1728 "A trust anchor certificate, and a notification for when 1729 it is about to (or already has) expire."; 1730 leaf cert-data { 1731 nacm:default-deny-write; 1732 type trust-anchor-cert-cms; 1733 description 1734 "The binary certificate data for this certificate."; 1735 } 1736 uses certificate-expiration-grouping; 1737 } 1739 grouping end-entity-cert-grouping { 1740 description 1741 "An end entity certificate, and a notification for when 1742 it is about to (or already has) expire. Implementations 1743 SHOULD assert that, where used, the end entity certificate 1744 contains the expected public key."; 1745 leaf cert-data { 1746 nacm:default-deny-write; 1747 type end-entity-cert-cms; 1748 description 1749 "The binary certificate data for this certificate."; 1750 } 1751 uses certificate-expiration-grouping; 1752 } 1754 grouping generate-csr-grouping { 1755 description 1756 "Defines the 'generate-certificate-signing-request' action."; 1757 action generate-certificate-signing-request { 1758 if-feature certificate-signing-request-generation; 1759 nacm:default-deny-all; 1760 description 1761 "Generates a certificate signing request structure for 1762 the associated asymmetric key using the passed subject 1763 and attribute values. 1765 This action statement is only available when the 1766 associated 'public-key-format' node's value is 1767 'subject-public-key-info-format'."; 1768 reference 1769 "RFC 6125: 1770 Representation and Verification of Domain-Based 1771 Application Service Identity within Internet Public Key 1772 Infrastructure Using X.509 (PKIX) Certificates in the 1773 Context of Transport Layer Security (TLS)"; 1774 input { 1775 leaf csr-info { 1776 type ct:csr-info; 1777 mandatory true; 1778 description 1779 "A CertificationRequestInfo structure, as defined in 1780 RFC 2986. 1782 Enables the client to provide a fully-populated 1783 CertificationRequestInfo structure that the server 1784 only needs to sign in order to generate the complete 1785 'CertificationRequest' structure to return in the 1786 'output'. 1788 The 'AlgorithmIdentifier' field contained inside 1789 the 'SubjectPublicKeyInfo' field MUST be one known 1790 to be supported by the device."; 1791 reference 1792 "RFC 2986: 1793 PKCS #10: Certification Request Syntax Specification 1794 RFC AAAA: 1795 YANG Data Types and Groupings for Cryptography"; 1796 } 1797 } 1798 output { 1799 leaf certificate-signing-request { 1800 type ct:csr; 1801 mandatory true; 1802 description 1803 "A CertificationRequest structure, as defined in 1804 RFC 2986."; 1805 reference 1806 "RFC 2986: 1807 PKCS #10: Certification Request Syntax Specification 1808 RFC AAAA: 1809 YANG Data Types and Groupings for Cryptography"; 1810 } 1811 } 1812 } 1813 } // generate-csr-grouping 1815 grouping asymmetric-key-pair-with-cert-grouping { 1816 description 1817 "A private/public key pair and an associated certificate. 1818 Implementations SHOULD assert that certificates contain 1819 the matching public key."; 1821 uses asymmetric-key-pair-grouping; 1822 uses end-entity-cert-grouping; 1823 uses generate-csr-grouping; 1824 } // asymmetric-key-pair-with-cert-grouping 1826 grouping asymmetric-key-pair-with-certs-grouping { 1827 description 1828 "A private/public key pair and associated certificates. 1829 Implementations SHOULD assert that certificates contain 1830 the matching public key."; 1831 uses asymmetric-key-pair-grouping; 1832 container certificates { 1833 nacm:default-deny-write; 1834 description 1835 "Certificates associated with this asymmetric key. 1836 More than one certificate supports, for instance, 1837 a TPM-protected asymmetric key that has both IDevID 1838 and LDevID certificates associated."; 1839 list certificate { 1840 key "name"; 1841 description 1842 "A certificate for this asymmetric key."; 1843 leaf name { 1844 type string; 1845 description 1846 "An arbitrary name for the certificate. If the name 1847 matches the name of a certificate that exists 1848 independently in (i.e., an IDevID), 1849 then the 'cert' node MUST NOT be configured."; 1850 } 1851 uses end-entity-cert-grouping { 1852 refine cert-data { 1853 mandatory true; 1854 } 1855 } 1856 } 1857 } 1858 uses generate-csr-grouping; 1859 } // asymmetric-key-pair-with-certs-grouping 1861 } 1863 1865 3. Security Considerations 1866 3.1. No Support for CRMF 1868 This document uses PKCS #10 [RFC2986] for the "generate-certificate- 1869 signing-request" action. The use of Certificate Request Message 1870 Format (CRMF) [RFC4211] was considered, but is was unclear if there 1871 was market demand for it. If it is desired to support CRMF in the 1872 future, a backwards compatible solution can be defined at that time. 1874 3.2. No Support for Key Generation 1876 Early revisions of this document included "rpc" statements for 1877 generating symmetric and asymmetric keys. There statements were 1878 removed due to an inability to obtain consensus for how to identify 1879 the key-algorithm to use. Thusly, the solution presented in this 1880 document only supports keys to be configured via an external client, 1881 which does not support Security best practice. 1883 3.3. Strength of Keys Configured 1885 When configuring key values, implementations SHOULD ensure that the 1886 strength of the key being configured is not greater than the strength 1887 of the underlying secure transport connection over which it is 1888 communicated. Implementations SHOULD fail the write-request if ever 1889 the strength of the private key is greater then the strength of the 1890 underlying transport. 1892 3.4. Deletion of Cleartext Key Values 1894 This module defines storage for cleartext key values that SHOULD be 1895 zeroized when deleted, so as to prevent the remnants of their 1896 persisted storage locations from being analyzed in any meaningful 1897 way. 1899 The cleartext key nodes are the "key" node defined in the "symmetric- 1900 key-grouping" grouping (Section 2.1.4.2) and the "private-key" node 1901 defined in the "asymmetric-key-pair-grouping" grouping 1902 ("Section 2.1.4.4). 1904 3.5. The "ietf-crypto-types" YANG Module 1906 The YANG module in this document defines "grouping" statements that 1907 are designed to be accessed via YANG based management protocols, such 1908 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1909 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1910 with mutual authentication. 1912 The NETCONF access control model (NACM) [RFC8341] provides the means 1913 to restrict access for particular users to a pre-configured subset of 1914 all available protocol operations and content. 1916 Since the module in this document only define groupings, these 1917 considerations are primarily for the designers of other modules that 1918 use these groupings. 1920 Some of the readable data nodes defined in this YANG module may be 1921 considered sensitive or vulnerable in some network environments. It 1922 is thus important to control read access (e.g., via get, get-config, 1923 or notification) to these data nodes. These are the subtrees and 1924 data nodes and their sensitivity/vulnerability: 1926 * The "key" node: 1928 The cleartext "key" node defined in the "symmetric-key- 1929 grouping" grouping is additionally sensitive to read operations 1930 such that, in normal use cases, it should never be returned to 1931 a client. For this reason, the NACM extension "default-deny- 1932 all" has been applied to it. 1934 * The "private-key" node: 1936 The cleartext "private-key" node defined in the "asymmetric- 1937 key-pair-grouping" grouping is additionally sensitive to read 1938 operations such that, in normal use cases, it should never be 1939 returned to a client. For this reason, the NACM extension 1940 "default-deny-all" has been applied. 1942 All of the writable data nodes defined by all the groupings defined 1943 in this module may be considered sensitive or vulnerable in some 1944 network environments. For instance, even the modification of a 1945 public key or a certificate can dramatically alter the implemented 1946 security policy. For this reason, the NACM extension "default-deny- 1947 write" has been applied to all the data nodes defined in the module. 1949 Some of the operations in this YANG module may be considered 1950 sensitive or vulnerable in some network environments. It is thus 1951 important to control access to these operations. These are the 1952 operations and their sensitivity/vulnerability: 1954 * generate-certificate-signing-request: 1956 This "action" statement SHOULD only be executed by authorized 1957 users. For this reason, the NACM extension "default-deny-all" 1958 has been applied. Note that NACM uses "default-deny-all" to 1959 protect "RPC" and "action" statements; it does not define, 1960 e.g., an extension called "default-deny-execute". 1962 For this action, it is RECOMMENDED that implementations assert 1963 channel binding [RFC5056], so as to ensure that the application 1964 layer that sent the request is the same as the device 1965 authenticated when the secure transport layer was established. 1967 4. IANA Considerations 1969 4.1. The "IETF XML" Registry 1971 This document registers one URI in the "ns" subregistry of the "IETF 1972 XML" registry [RFC3688]. Following the format in [RFC3688], the 1973 following registration is requested: 1975 URI: urn:ietf:params:xml:ns:yang:ietf-crypto-types 1976 Registrant Contact: The NETCONF WG of the IETF. 1977 XML: N/A, the requested URI is an XML namespace. 1979 4.2. The "YANG Module Names" Registry 1981 This document registers one YANG module in the "YANG Module Names" 1982 registry [RFC6020]. Following the format in [RFC6020], the the 1983 following registration is requested: 1985 name: ietf-crypto-types 1986 namespace: urn:ietf:params:xml:ns:yang:ietf-crypto-types 1987 prefix: ct 1988 reference: RFC AAAA 1990 5. References 1992 5.1. Normative References 1994 [ITU.X680.2015] 1995 International Telecommunication Union, "Information 1996 technology - Abstract Syntax Notation One (ASN.1): 1997 Specification of basic notation", ITU-T Recommendation 1998 X.680, ISO/IEC 8824-1:2015, August 2015, 1999 . 2001 [ITU.X690.2015] 2002 International Telecommunication Union, "Information 2003 Technology - ASN.1 encoding rules: Specification of Basic 2004 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2005 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2006 X.690, ISO/IEC 8825-1:2015, August 2015, 2007 . 2009 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2010 Requirement Levels", BCP 14, RFC 2119, 2011 DOI 10.17487/RFC2119, March 1997, 2012 . 2014 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2015 Standards (PKCS) #1: RSA Cryptography Specifications 2016 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 2017 2003, . 2019 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2020 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2021 January 2006, . 2023 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2024 Housley, R., and W. Polk, "Internet X.509 Public Key 2025 Infrastructure Certificate and Certificate Revocation List 2026 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2027 . 2029 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2030 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2031 . 2033 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, 2034 DOI 10.17487/RFC5958, August 2010, 2035 . 2037 [RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax 2038 (CMS) Symmetric Key Package Content Type", RFC 6031, 2039 DOI 10.17487/RFC6031, December 2010, 2040 . 2042 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2043 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2044 . 2046 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2047 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2048 . 2050 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2051 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2052 May 2017, . 2054 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2055 Access Control Model", STD 91, RFC 8341, 2056 DOI 10.17487/RFC8341, March 2018, 2057 . 2059 5.2. Informative References 2061 [I-D.ietf-netconf-crypto-types] 2062 Watsen, K., "Common YANG Data Types for Cryptography", 2063 Work in Progress, Internet-Draft, draft-ietf-netconf- 2064 crypto-types-15, 20 May 2020, 2065 . 2068 [I-D.ietf-netconf-http-client-server] 2069 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2070 Servers", Work in Progress, Internet-Draft, draft-ietf- 2071 netconf-http-client-server-03, 20 May 2020, 2072 . 2075 [I-D.ietf-netconf-keystore] 2076 Watsen, K., "A YANG Data Model for a Keystore", Work in 2077 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 2078 20 May 2020, . 2081 [I-D.ietf-netconf-netconf-client-server] 2082 Watsen, K., "NETCONF Client and Server Models", Work in 2083 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2084 client-server-19, 20 May 2020, 2085 . 2088 [I-D.ietf-netconf-restconf-client-server] 2089 Watsen, K., "RESTCONF Client and Server Models", Work in 2090 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2091 client-server-19, 20 May 2020, 2092 . 2095 [I-D.ietf-netconf-ssh-client-server] 2096 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2097 SSH Servers", Work in Progress, Internet-Draft, draft- 2098 ietf-netconf-ssh-client-server-19, 20 May 2020, 2099 . 2102 [I-D.ietf-netconf-tcp-client-server] 2103 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2104 and TCP Servers", Work in Progress, Internet-Draft, draft- 2105 ietf-netconf-tcp-client-server-06, 16 June 2020, 2106 . 2109 [I-D.ietf-netconf-tls-client-server] 2110 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2111 TLS Servers", Work in Progress, Internet-Draft, draft- 2112 ietf-netconf-tls-client-server-19, 20 May 2020, 2113 . 2116 [I-D.ietf-netconf-trust-anchors] 2117 Watsen, K., "A YANG Data Model for a Truststore", Work in 2118 Progress, Internet-Draft, draft-ietf-netconf-trust- 2119 anchors-10, 20 May 2020, . 2122 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 2123 Request Syntax Specification Version 1.7", RFC 2986, 2124 DOI 10.17487/RFC2986, November 2000, 2125 . 2127 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2128 DOI 10.17487/RFC3688, January 2004, 2129 . 2131 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 2132 Certificate Request Message Format (CRMF)", RFC 4211, 2133 DOI 10.17487/RFC4211, September 2005, 2134 . 2136 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 2137 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 2138 . 2140 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 2141 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 2142 . 2144 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2145 the Network Configuration Protocol (NETCONF)", RFC 6020, 2146 DOI 10.17487/RFC6020, October 2010, 2147 . 2149 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2150 Verification of Domain-Based Application Service Identity 2151 within Internet Public Key Infrastructure Using X.509 2152 (PKIX) Certificates in the Context of Transport Layer 2153 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2154 2011, . 2156 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2157 and A. Bierman, Ed., "Network Configuration Protocol 2158 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2159 . 2161 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2162 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2163 . 2165 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2166 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2167 . 2169 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2170 and R. Wilton, "Network Management Datastore Architecture 2171 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2172 . 2174 Appendix A. Change Log 2176 This section is to be removed before publishing as an RFC. 2178 A.1. I-D to 00 2180 * Removed groupings and notifications. 2182 * Added typedefs for identityrefs. 2184 * Added typedefs for other RFC 5280 structures. 2186 * Added typedefs for other RFC 5652 structures. 2188 * Added convenience typedefs for RFC 4253, RFC 5280, and RFC 5652. 2190 A.2. 00 to 01 2191 * Moved groupings from the draft-ietf-netconf-keystore here. 2193 A.3. 01 to 02 2195 * Removed unwanted "mandatory" and "must" statements. 2197 * Added many new crypto algorithms (thanks Haiguang!) 2199 * Clarified in asymmetric-key-pair-with-certs-grouping, in 2200 certificates/certificate/name/description, that if the name MUST 2201 NOT match the name of a certificate that exists independently in 2202 , enabling certs installed by the manufacturer (e.g., 2203 an IDevID). 2205 A.4. 02 to 03 2207 * renamed base identity 'asymmetric-key-encryption-algorithm' to 2208 'asymmetric-key-algorithm'. 2210 * added new 'asymmetric-key-algorithm' identities for secp192r1, 2211 secp224r1, secp256r1, secp384r1, and secp521r1. 2213 * removed 'mac-algorithm' identities for mac-aes-128-ccm, mac-aes- 2214 192-ccm, mac-aes-256-ccm, mac-aes-128-gcm, mac-aes-192-gcm, mac- 2215 aes-256-gcm, and mac-chacha20-poly1305. 2217 * for all -cbc and -ctr identities, renamed base identity 2218 'symmetric-key-encryption-algorithm' to 'encryption-algorithm'. 2220 * for all -ccm and -gcm identities, renamed base identity 2221 'symmetric-key-encryption-algorithm' to 'encryption-and-mac- 2222 algorithm' and renamed the identity to remove the "enc-" prefix. 2224 * for all the 'signature-algorithm' based identities, renamed from 2225 'rsa-*' to 'rsassa-*'. 2227 * removed all of the "x509v3-" prefixed 'signature-algorithm' based 2228 identities. 2230 * added 'key-exchange-algorithm' based identities for 'rsaes-oaep' 2231 and 'rsaes-pkcs1-v1_5'. 2233 * renamed typedef 'symmetric-key-encryption-algorithm-ref' to 2234 'symmetric-key-algorithm-ref'. 2236 * renamed typedef 'asymmetric-key-encryption-algorithm-ref' to 2237 'asymmetric-key-algorithm-ref'. 2239 * added typedef 'encryption-and-mac-algorithm-ref'. 2241 * Updated copyright date, boilerplate template, affiliation, and 2242 folding algorithm. 2244 A.5. 03 to 04 2246 * ran YANG module through formatter. 2248 A.6. 04 to 05 2250 * fixed broken symlink causing reformatted YANG module to not show. 2252 A.7. 05 to 06 2254 * Added NACM annotations. 2256 * Updated Security Considerations section. 2258 * Added 'asymmetric-key-pair-with-cert-grouping' grouping. 2260 * Removed text from 'permanently-hidden' enum regarding such keys 2261 not being backed up or restored. 2263 * Updated the boilerplate text in module-level "description" 2264 statement to match copyeditor convention. 2266 * Added an explanation to the 'public-key-grouping' and 'asymmetric- 2267 key-pair-grouping' statements as for why the nodes are not 2268 mandatory (e.g., because they may exist only in . 2270 * Added 'must' expressions to the 'public-key-grouping' and 2271 'asymmetric-key-pair-grouping' statements ensuring sibling nodes 2272 are either all exist or do not all exist. 2274 * Added an explanation to the 'permanently-hidden' that the value 2275 cannot be configured directly by clients and servers MUST fail any 2276 attempt to do so. 2278 * Added 'trust-anchor-certs-grouping' and 'end-entity-certs- 2279 grouping' (the plural form of existing groupings). 2281 * Now states that keys created in by the *-hidden-key 2282 actions are bound to the lifetime of the parent 'config true' 2283 node, and that subsequent invocations of either action results in 2284 a failure. 2286 A.8. 06 to 07 2288 * Added clarifications that implementations SHOULD assert that 2289 configured certificates contain the matching public key. 2291 * Replaced the 'generate-hidden-key' and 'install-hidden-key' 2292 actions with special 'crypt-hash' -like input/output values. 2294 A.9. 07 to 08 2296 * Removed the 'generate-key and 'hidden-key' features. 2298 * Added grouping symmetric-key-grouping 2300 * Modified 'asymmetric-key-pair-grouping' to have a 'choice' 2301 statement for the keystone module to augment into, as well as 2302 replacing the 'union' with leafs (having different NACM settings. 2304 A.10. 08 to 09 2306 * Converting algorithm from identities to enumerations. 2308 A.11. 09 to 10 2310 * All of the below changes are to the algorithm enumerations defined 2311 in ietf-crypto-types. 2313 * Add in support for key exchange over x.25519 and x.448 based on 2314 RFC 8418. 2316 * Add in SHAKE-128, SHAKE-224, SHAKE-256, SHAKE-384 and SHAKE 512 2318 * Revise/add in enum of signature algorithm for x25519 and x448 2320 * Add in des3-cbc-sha1 for IPSec 2322 * Add in sha1-des3-kd for IPSec 2324 * Add in definit for rc4-hmac and rc4-hmac-exp. These two 2325 algorithms have been deprecated in RFC 8429. But some existing 2326 draft in i2nsf may still want to use them. 2328 * Add x25519 and x448 curve for asymmetric algorithms 2330 * Add signature algorithms ed25519, ed25519-cts, ed25519ph 2332 * add signature algorithms ed448, ed448ph 2333 * Add in rsa-sha2-256 and rsa-sha2-512 for SSH protocols (rfc8332) 2335 A.12. 10 to 11 2337 * Added a "key-format" identity. 2339 * Added symmetric keys to the example in Section 2.2. 2341 A.13. 11 to 12 2343 * Removed all non-essential (to NC/RC) algorithm types. 2345 * Moved remaining algorithm types each into its own module. 2347 * Added a 'config false' "algorithms-supported" list to each of the 2348 algorithm-type modules. 2350 A.14. 12 to 13 2352 * Added the four features: "[encrypted-]one-[a]symmetric-key- 2353 format", each protecting a 'key-format' identity of the same name. 2355 * Added 'must' expressions asserting that the 'key-format' leaf 2356 exists whenever a non-hidden key is specified. 2358 * Improved the 'description' statements and added 'reference' 2359 statements for the 'key-format' identities. 2361 * Added a questionable forward reference to "encrypted-*" leafs in a 2362 couple 'when' expressions. 2364 * Did NOT move "config false" alg-supported lists to SSH/TLS drafts. 2366 A.15. 13 to 14 2368 * Resolved the "FIXME: forward ref" issue by modulating 'must', 2369 'when', and 'mandatory' expressions. 2371 * Moved the 'generatesymmetric-key' and 'generate-asymmetric-key' 2372 actions from ietf-keystore to ietf-crypto-types, now as RPCs. 2374 * Cleaned up various description statements and removed lingering 2375 FIXMEs. 2377 * Converted the "iana--algs" YANG modules to IANA 2378 registries with instructions for how to generate modules from the 2379 registries, whenever they may be updated. 2381 A.16. 14 to 15 2383 * Removed the IANA-maintained registries for symmetric, asymmetric, 2384 and hash algorithms. 2386 * Removed the "generate-symmetric-key" and "generate-asymmetric-key" 2387 RPCs. 2389 * Removed the "algorithm" node in the various symmetric and 2390 asymmetric key groupings. 2392 * Added 'typedef csr' and 'feature certificate-signing-request- 2393 generation'. 2395 * Refined a usage of "end-entity-cert-grouping" to make the "cert" 2396 node mandatory true. 2398 * Added a "Note to Reviewers" note to first page. 2400 A.17. 15 to 16 2402 * Updated draft title (refer to "Groupings" too). 2404 * Removed 'end-entity-certs-grouping' as it wasn't being used 2405 anywhere. 2407 * Removed 'trust-anchor-certs-grouping' as it was no longer being 2408 used after modifying 'local-or-truststore-certs-grouping' to use 2409 lists (not leaf-lists). 2411 * Renamed "cert" to "cert-data" in trust-anchor-cert-grouping. 2413 * Added "csr-info" typedef, to complement the existing "csr" 2414 typedef. 2416 * Added "ocsp-request" and "ocsp-response" typedefs, to complement 2417 the existing "crl" typedef. 2419 * Added "encrypted" cases to both symmetric-key-grouping and 2420 asymmetric-key-pair-grouping (Moved from Keystore draft). 2422 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2423 diagrams]. 2425 * Updated the Security Considerations section. 2427 A.18. 16 to 17 2428 * [Re]-added a "Strength of Keys Configured" Security Consideration 2430 * Prefixed "cleartext-" in the "key" and "private-key" node names. 2432 Acknowledgements 2434 The authors would like to thank for following for lively discussions 2435 on list and in the halls (ordered by first name): Balazs Kovacs, Eric 2436 Voit, Juergen Schoenwaelder, Liang Xia, Martin Bjorklund, Nick 2437 Hancock, Rich Salz, Rob Wilton, Tom Petch, and Wang Haiguang. 2439 Author's Address 2441 Kent Watsen 2442 Watsen Networks 2444 Email: kent+ietf@watsen.net