idnits 2.17.1 draft-ietf-netconf-crypto-types-18.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 340 has weird spacing: '...d-value bin...' == Line 380 has weird spacing: '...d-value bin...' == Line 422 has weird spacing: '...d-value bin...' == Line 451 has weird spacing: '...-format ide...' == Line 498 has weird spacing: '...d-value bin...' == (19 more instances...) -- The document date (20 August 2020) is 1338 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-17 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-04 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-20 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-21 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-07 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-21 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-12 -- 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 20 August 2020 5 Expires: 21 February 2021 7 YANG Data Types and Groupings for Cryptography 8 draft-ietf-netconf-crypto-types-18 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-08-20" --> 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 21 February 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 . . . . . . . . . . . . . . . . . . . . . . 17 77 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 24 78 3. Security Considerations . . . . . . . . . . . . . . . . . . . 43 79 3.1. No Support for CRMF . . . . . . . . . . . . . . . . . . . 43 80 3.2. No Support for Key Generation . . . . . . . . . . . . . . 43 81 3.3. Strength of Keys Configured . . . . . . . . . . . . . . . 44 82 3.4. Deletion of Cleartext Key Values . . . . . . . . . . . . 44 83 3.5. The "ietf-crypto-types" YANG Module . . . . . . . . . . . 44 84 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 85 4.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 45 86 4.2. The "YANG Module Names" Registry . . . . . . . . . . . . 46 87 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 88 5.1. Normative References . . . . . . . . . . . . . . . . . . 46 89 5.2. Informative References . . . . . . . . . . . . . . . . . 47 90 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 50 91 A.1. I-D to 00 . . . . . . . . . . . . . . . . . . . . . . . . 50 92 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 50 93 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 50 94 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 50 95 A.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 51 96 A.6. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 51 97 A.7. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 51 98 A.8. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 52 99 A.9. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 52 100 A.10. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 52 101 A.11. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 53 102 A.12. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 53 103 A.13. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 53 104 A.14. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 53 105 A.15. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 54 106 A.16. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 54 107 A.17. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 55 108 A.18. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 55 109 A.19. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 55 110 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 55 111 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 56 113 1. Introduction 115 This document presents a YANG 1.1 [RFC7950] module defining 116 identities, typedefs, and groupings useful to cryptographic 117 applications. 119 1.1. Relation to other RFCs 121 This document presents one or more YANG modules [RFC7950] that are 122 part of a collection of RFCs that work together to define 123 configuration modules for clients and servers of both the NETCONF 124 [RFC6241] and RESTCONF [RFC8040] protocols. 126 The modules have been defined in a modular fashion to enable their 127 use by other efforts, some of which are known to be in progress at 128 the time of this writing, with many more expected to be defined in 129 time. 131 The normative dependency relationship between the various RFCs in the 132 collection is presented in the below diagram. The labels in the 133 diagram represent the primary purpose provided by each RFC. 134 Hyperlinks to each RFC are provided below the diagram. 136 crypto-types 137 ^ ^ 138 / \ 139 / \ 140 truststore keystore 141 ^ ^ ^ ^ 142 | +---------+ | | 143 | | | | 144 | +------------+ | 145 tcp-client-server | / | | 146 ^ ^ ssh-client-server | | 147 | | ^ tls-client-server 148 | | | ^ ^ http-client-server 149 | | | | | ^ 150 | | | +-----+ +---------+ | 151 | | | | | | 152 | +-----------|--------|--------------+ | | 153 | | | | | | 154 +-----------+ | | | | | 155 | | | | | | 156 | | | | | | 157 netconf-client-server restconf-client-server 159 +=======================+===========================================+ 160 | Label in Diagram | Originating RFC | 161 +=======================+===========================================+ 162 | crypto-types | [I-D.ietf-netconf-crypto-types] | 163 +-----------------------+-------------------------------------------+ 164 | truststore | [I-D.ietf-netconf-trust-anchors] | 165 +-----------------------+-------------------------------------------+ 166 | keystore | [I-D.ietf-netconf-keystore] | 167 +-----------------------+-------------------------------------------+ 168 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 169 +-----------------------+-------------------------------------------+ 170 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 171 +-----------------------+-------------------------------------------+ 172 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 173 +-----------------------+-------------------------------------------+ 174 | http-client-server | [I-D.ietf-netconf-http-client-server] | 175 +-----------------------+-------------------------------------------+ 176 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 177 +-----------------------+-------------------------------------------+ 178 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 179 +-----------------------+-------------------------------------------+ 181 Table 1: Label to RFC Mapping 183 1.2. Specification Language 185 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 186 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 187 "OPTIONAL" in this document are to be interpreted as described in BCP 188 14 [RFC2119] [RFC8174] when, and only when, they appear in all 189 capitals, as shown here. 191 1.3. Adherence to the NMDA 193 This document in compliant with the Network Management Datastore 194 Architecture (NMDA) [RFC8342]. It does not define any protocol 195 accessible nodes that are "config false". 197 2. The "ietf-crypto-types" Module 199 This section defines a YANG 1.1 [RFC7950] module called "ietf-crypto- 200 types". A high-level overview of the module is provided in 201 Section 2.1. Examples illustatrating the module's use are provided 202 in Examples (Section 2.2). The YANG module itself is defined in 203 Section 2.3. 205 2.1. Data Model Overview 207 This section provides an overview of the "ietf-crypto-types" module 208 in terms of its features, indentities, typedefs, and groupings. 210 2.1.1. Features 212 The following diagram lists all the "feature" statements defined in 213 the "ietf-crypt-types" module: 215 Features: 216 +-- one-symmetric-key-format 217 +-- one-asymmetric-key-format 218 +-- encrypted-one-symmetric-key-format 219 +-- encrypted-one-asymmetric-key-format 220 +-- certificate-signing-request-generation 221 +-- certificate-expiration-notification 223 | The diagram above uses syntax that is similar to but not 224 | defined in [RFC8340]. 226 2.1.2. Identities 228 The following diagram illustrates the relationship amongst the 229 "identity" statements defined in the "ietf-crypto-types" module: 231 Identities: 232 +-- public-key-format 233 | +-- subject-public-key-info-format 234 | +-- ssh-public-key-format 235 +-- private-key-format 236 | +-- rsa-private-key-format 237 | +-- ec-private-key-format 238 | +-- one-asymmetric-key-format 239 | | {one-asymmetric-key-format}? 240 | +-- encrypted-one-asymmetric-key-format 241 | {encrypted-one-asymmetric-key-format}? 242 +-- symmetric-key-format 243 +-- octet-string-key-format 244 +-- one-symmetric-key-format 245 | {one-symmetric-key-format}? 246 +-- encrypted-one-symmetric-key-format 247 {encrypted-one-symmetric-key-format}? 249 | The diagram above uses syntax that is similar to but not 250 | defined in [RFC8340]. 252 Comments: 254 * The diagram shows that there are three base identities. These 255 identities are used by this module to define the format that key 256 data is encoded in. The base identities are "abstract", in the 257 object orientied programming sense, in that they only define a 258 "class" of formats, rather than a specific format. 260 * The various derived identities define specific key encoding 261 formats. The derived identities defined in this document are 262 sufficient for the effort described in Section 1.1 but, by nature 263 of them being identities, additional derived identities MAY be 264 defined by future efforts. 266 * Identities use to specify uncommon formats are enabled by 267 "feature" statements, enabling applications to support them when 268 needed. 270 2.1.3. Typedefs 272 The following diagram illustrates the relationship amongst the 273 "typedef" statements defined in the "ietf-crypto-types" module: 275 Typedefs: 276 binary 277 +-- csr-info 278 +-- csr 279 +-- x509 280 | +-- trust-anchor-cert-x509 281 | +-- end-entity-cert-x509 282 +-- crl 283 +-- ocsp-request 284 +-- ocsp-response 285 +-- cms 286 +-- data-content-cms 287 +-- signed-data-cms 288 | +-- trust-anchor-cert-cms 289 | +-- end-entity-cert-cms 290 +-- enveloped-data-cms 291 +-- digested-data-cms 292 +-- encrypted-data-cms 293 +-- authenticated-data-cms 295 | The diagram above uses syntax that is similar to but not 296 | defined in [RFC8340]. 298 Comments: 300 * All of the typedefs defined in the "ietf-crypto-types" module 301 extend the "binary" type defined in [RFC7950]. 303 * Additionally, all the typedefs define a type for encoding an ASN.1 304 [ITU.X680.2015] structure using DER [ITU.X690.2015]. 306 * The "trust-anchor-*" and "end-entity-*" typedefs are syntactically 307 identical to their base typedefs and only distiguish themselves by 308 the expected nature of their content. These typedefs are defined 309 to facilitate common modeling needs. 311 2.1.4. Groupings 313 The following diagram lists all the "grouping" statements defined in 314 the "ietf-crypto-types" module: 316 Groupings: 317 +-- encrypted-key-value-grouping 318 +-- password-grouping 319 +-- symmetric-key-grouping 320 +-- public-key-grouping 321 +-- asymmetric-key-pair-grouping 322 +-- trust-anchor-cert-grouping 323 +-- end-entity-cert-grouping 324 +-- generate-csr-grouping 325 +-- asymmetric-key-pair-with-cert-grouping 326 +-- asymmetric-key-pair-with-certs-grouping 328 | The diagram above uses syntax that is similar to but not 329 | defined in [RFC8340]. 331 Each of these groupings are presented in the following subsections. 333 2.1.4.1. The "encrypted-key-value-grouping" Grouping 335 The following tree diagram [RFC8340] illustrates the "encrypted-key- 336 value-grouping" grouping: 338 grouping encrypted-key-value-grouping 339 +-- encrypted-by 340 +-- encrypted-value binary 342 Comments: 344 * The "encrypted-by" node is an empty container (difficult to see in 345 the diagram) that a consuming module MUST augment key references 346 into. The "ietf-crypto-types" module is unable to populate this 347 container as the module only defines groupings. Section 2.2.1 348 presents an example illustrating a consuming module populating the 349 "encrypted-by" container. 351 * The "encrypted-value" node is the key, encrypted by the key 352 referenced by the "encrypted-by" node, encoded in the format 353 specified by the "format" identity Section 2.1.2 associated with 354 the ancestor node using this grouping. 356 2.1.4.2. The "password-grouping" Grouping 358 This section presents two tree diagrams [RFC8340] illustrating the 359 "password-grouping" grouping. The first tree diagram does not expand 360 the internally used grouping statement(s): 362 grouping password-grouping 363 +-- (password-type) 364 +--:(cleartext-password) 365 | +-- cleartext-password? string 366 +--:(encrypted-password) {password-encryption}? 367 +-- encrypted-password 368 +---u encrypted-key-value-grouping 370 The following tree diagram expands the internally used grouping 371 statement(s), enabling the grouping's full structure to be seen: 373 grouping password-grouping 374 +-- (password-type) 375 +--:(cleartext-password) 376 | +-- cleartext-password? string 377 +--:(encrypted-password) {password-encryption}? 378 +-- encrypted-password 379 +-- encrypted-by 380 +-- encrypted-value binary 382 Comments: 384 * The "choice" statement enables the password data to be plain-text 385 or encrypted, as follows: 387 - The "cleartext-password" node can encode any plain-text value. 388 - The "encrypted-password" node's structure is discussed in 389 Section 2.1.4.1, and is encoded using the CMS EnvelopedData 390 structure. 392 2.1.4.3. The "symmetric-key-grouping" Grouping 394 This section presents two tree diagrams [RFC8340] illustrating the 395 "symmetric-key-grouping" grouping. The first tree diagram does not 396 expand the internally used grouping statement(s): 398 grouping symmetric-key-grouping 399 +-- key-format? identityref 400 +-- (key-type) 401 +--:(cleartext-key) 402 | +-- cleartext-key? binary 403 +--:(hidden-key) 404 | +-- hidden-key? empty 405 +--:(encrypted-key) {symmetric-key-encryption}? 406 +-- encrypted-key 407 +---u encrypted-key-value-grouping 409 The following tree diagram expands the internally used grouping 410 statement(s), enabling the grouping's full structure to be seen: 412 grouping symmetric-key-grouping 413 +-- key-format? identityref 414 +-- (key-type) 415 +--:(cleartext-key) 416 | +-- cleartext-key? binary 417 +--:(hidden-key) 418 | +-- hidden-key? empty 419 +--:(encrypted-key) {symmetric-key-encryption}? 420 +-- encrypted-key 421 +-- encrypted-by 422 +-- encrypted-value binary 424 Comments: 426 * For the referenced grouping statement(s): 428 - The "encrypted-key-value-grouping" grouping is discussed in 429 Section 2.1.4.1. 431 * The "key-format" node is an identity-reference to the "symmetric- 432 key-format" abstract base identity discussed in Section 2.1.2, 433 enabling the symmetric key to be encoded using the format defined 434 by any of the derived identities. 436 * The "choice" statement enables the private key data to be plain- 437 text, encrypted, or hidden, as follows: 439 - The "cleartext-key" node can encode any plain-text key value. 440 - The "hidden-key" node is of type "empty" as the real value 441 cannot be presented via the management interface. 442 - The "encrypted-key" node's structure is discussed in 443 Section 2.1.4.1. 445 2.1.4.4. The "public-key-grouping" Grouping 447 The following tree diagram [RFC8340] illustrates the "public-key- 448 grouping" grouping: 450 grouping public-key-grouping 451 +-- public-key-format identityref 452 +-- public-key binary 454 Comments: 456 * The "public-key-format" node is an identity-reference to the 457 "public-key-format" abstract base identity discussed in 458 Section 2.1.2, enabling the public key to be encoded using the 459 format defined by any of the derived identities. 461 * The "public-key" node is the public key data in the selected 462 format. No "choice" statement is used to hide or encrypt the 463 public key data because it is unecessary to do so for public keys. 465 2.1.4.5. The "asymmetric-key-pair-grouping" Grouping 467 This section presents two tree diagrams [RFC8340] illustrating the 468 "asymmetric-key-pair-grouping" grouping. The first tree diagram does 469 not expand the internally used grouping statement(s): 471 grouping asymmetric-key-pair-grouping 472 +---u public-key-grouping 473 +-- private-key-format? identityref 474 +-- (private-key-type) 475 +--:(cleartext-private-key) 476 | +-- cleartext-private-key? binary 477 +--:(hidden-private-key) 478 | +-- hidden-private-key? empty 479 +--:(encrypted-private-key) {private-key-encryption}? 480 +-- encrypted-private-key 481 +---u encrypted-key-value-grouping 483 The following tree diagram expands the internally used grouping 484 statement(s), enabling the grouping's full structure to be seen: 486 grouping asymmetric-key-pair-grouping 487 +-- public-key-format identityref 488 +-- public-key binary 489 +-- private-key-format? identityref 490 +-- (private-key-type) 491 +--:(cleartext-private-key) 492 | +-- cleartext-private-key? binary 493 +--:(hidden-private-key) 494 | +-- hidden-private-key? empty 495 +--:(encrypted-private-key) {private-key-encryption}? 496 +-- encrypted-private-key 497 +-- encrypted-by 498 +-- encrypted-value binary 500 Comments: 502 * For the referenced grouping statement(s): 504 - The "public-key-grouping" grouping is discussed in 505 Section 2.1.4.4. 506 - The "encrypted-key-value-grouping" grouping is discussed in 507 Section 2.1.4.1. 509 * The "private-key-format" node is an identity-reference to the 510 "private-key-format" abstract base identity discussed in 511 Section 2.1.2, enabling the private key to be encoded using the 512 format defined by any of the derived identities. 514 * The "choice" statement enables the private key data to be plain- 515 text, encrypted, or hidden, as follows: 517 - The "cleartext-private-key" node can encode any plain-text key 518 value. 519 - The "hidden-private-key" node is of type "empty" as the real 520 value cannot be presented via the management interface. 521 - The "encrypted-private-key" node's structure is discussed in 522 Section 2.1.4.1. 524 2.1.4.6. The "certificate-expiration-grouping" Grouping 526 The following tree diagram [RFC8340] illustrates the "certificate- 527 expiration-grouping" grouping: 529 grouping certificate-expiration-grouping 530 +---n certificate-expiration 531 {certificate-expiration-notification}? 532 +-- expiration-date yang:date-and-time 534 Comments: 536 * This grouping's only purpose is to define the "certificate- 537 expiration" notification statement, used by the groupings defined 538 in Section 2.1.4.7 and Section 2.1.4.8. 540 * The "certificate-expiration" notification enables servers to 541 notify clients when certificates are nearing expiration. 543 * The "expiration-date" node indicates when the designated 544 certificate will (or did) expire. 546 * Identification of the certificate that is expiring is built into 547 the notification itself. For an example, please see 548 Section 2.2.3. 550 2.1.4.7. The "trust-anchor-cert-grouping" Grouping 552 This section presents two tree diagrams [RFC8340] illustrating the 553 "trust-anchor-cert-grouping" grouping. The first tree diagram does 554 not expand the internally used grouping statement(s): 556 grouping trust-anchor-cert-grouping 557 +-- cert-data? trust-anchor-cert-cms 558 +---u certificate-expiration-grouping 560 The following tree diagram expands the internally used grouping 561 statement(s), enabling the grouping's full structure to be seen: 563 grouping trust-anchor-cert-grouping 564 +-- cert-data? trust-anchor-cert-cms 565 +---n certificate-expiration 566 {certificate-expiration-notification}? 567 +-- expiration-date yang:date-and-time 569 Comments: 571 * For the referenced grouping statement(s): 573 - The "certificate-expiration-grouping" grouping is discussed in 574 Section 2.1.4.6. 576 * The "cert-data" node contains a chain of one or more certificates 577 encoded using a "signed-data-cms" typedef discussed in 578 Section 2.1.3. 580 2.1.4.8. The "end-entity-cert-grouping" Grouping 582 This section presents two tree diagrams [RFC8340] illustrating the 583 "end-entity-cert-grouping" grouping. The first tree diagram does not 584 expand the internally used grouping statement(s): 586 grouping end-entity-cert-grouping 587 +-- cert-data? end-entity-cert-cms 588 +---u certificate-expiration-grouping 590 The following tree diagram expands the internally used grouping 591 statement(s), enabling the grouping's full structure to be seen: 593 grouping end-entity-cert-grouping 594 +-- cert-data? end-entity-cert-cms 595 +---n certificate-expiration 596 {certificate-expiration-notification}? 597 +-- expiration-date yang:date-and-time 599 Comments: 601 * For the referenced grouping statement(s): 603 - The "certificate-expiration-grouping" grouping is discussed in 604 Section 2.1.4.6. 606 * The "cert-data" node contains a chain of one or more certificates 607 encoded using a "signed-data-cms" typedef discussed in 608 Section 2.1.3. 610 2.1.4.9. The "generate-csr-grouping" Grouping 612 The following tree diagram [RFC8340] illustrates the "generate-csr- 613 grouping" grouping: 615 grouping generate-csr-grouping 616 +---x generate-certificate-signing-request 617 {certificate-signing-request-generation}? 618 +---w input 619 | +---w csr-info ct:csr-info 620 +--ro output 621 +--ro certificate-signing-request ct:csr 623 Comments: 625 * This grouping's only purpose is to define the "generate- 626 certificate-signing-request" action statement, used by the 627 groupings defined in Section 2.1.4.10 and Section 2.1.4.11. 629 * This action takes as input a "csr-info" type and returns a "csr" 630 type, both of which are discussed in Section 2.1.3. 632 * For an example, please see Section 2.2.2. 634 2.1.4.10. The "asymmetric-key-pair-with-cert-grouping" Grouping 636 This section presents two tree diagrams [RFC8340] illustrating the 637 "asymmetric-key-pair-with-cert-grouping" grouping. The first tree 638 diagram does not expand the internally used grouping statement(s): 640 grouping asymmetric-key-pair-with-cert-grouping 641 +---u asymmetric-key-pair-grouping 642 +---u end-entity-cert-grouping 643 +---u generate-csr-grouping 645 The following tree diagram expands the internally used grouping 646 statement(s), enabling the grouping's full structure to be seen: 648 grouping asymmetric-key-pair-with-cert-grouping 649 +-- public-key-format identityref 650 +-- public-key binary 651 +-- private-key-format? identityref 652 +-- (private-key-type) 653 | +--:(cleartext-private-key) 654 | | +-- cleartext-private-key? binary 655 | +--:(hidden-private-key) 656 | | +-- hidden-private-key? empty 657 | +--:(encrypted-private-key) {private-key-encryption}? 658 | +-- encrypted-private-key 659 | +-- encrypted-by 660 | +-- encrypted-value binary 661 +-- cert-data? end-entity-cert-cms 662 +---n certificate-expiration 663 | {certificate-expiration-notification}? 664 | +-- expiration-date yang:date-and-time 665 +---x generate-certificate-signing-request 666 {certificate-signing-request-generation}? 667 +---w input 668 | +---w csr-info ct:csr-info 669 +--ro output 670 +--ro certificate-signing-request ct:csr 672 Comments: 674 * This grouping defines an asymmetric key with at most one 675 associated certificate, a commonly needed combination in protocol 676 models. 678 * For the referenced grouping statement(s): 680 - The "asymmetric-key-pair-grouping" grouping is discussed in 681 Section 2.1.4.5. 682 - The "end-entity-cert-grouping" grouping is discussed in 683 Section 2.1.4.8. 684 - The "generate-csr-grouping" grouping is discussed in 685 Section 2.1.4.9. 687 2.1.4.11. The "asymmetric-key-pair-with-certs-grouping" Grouping 689 This section presents two tree diagrams [RFC8340] illustrating the 690 "asymmetric-key-pair-with-certs-grouping" grouping. The first tree 691 diagram does not expand the internally used grouping statement(s): 693 grouping asymmetric-key-pair-with-certs-grouping 694 +---u asymmetric-key-pair-grouping 695 +-- certificates 696 | +-- certificate* [name] 697 | +-- name? string 698 | +---u end-entity-cert-grouping 699 +---u generate-csr-grouping 701 The following tree diagram expands the internally used grouping 702 statement(s), enabling the grouping's full structure to be seen: 704 grouping asymmetric-key-pair-with-certs-grouping 705 +-- public-key-format identityref 706 +-- public-key binary 707 +-- private-key-format? identityref 708 +-- (private-key-type) 709 | +--:(cleartext-private-key) 710 | | +-- cleartext-private-key? binary 711 | +--:(hidden-private-key) 712 | | +-- hidden-private-key? empty 713 | +--:(encrypted-private-key) {private-key-encryption}? 714 | +-- encrypted-private-key 715 | +-- encrypted-by 716 | +-- encrypted-value binary 717 +-- certificates 718 | +-- certificate* [name] 719 | +-- name? string 720 | +-- cert-data end-entity-cert-cms 721 | +---n certificate-expiration 722 | {certificate-expiration-notification}? 723 | +-- expiration-date yang:date-and-time 724 +---x generate-certificate-signing-request 725 {certificate-signing-request-generation}? 726 +---w input 727 | +---w csr-info ct:csr-info 728 +--ro output 729 +--ro certificate-signing-request ct:csr 731 Comments: 733 * This grouping defines an asymmetric key with one or more 734 associated certificates, a commonly needed combination in 735 configuration models. 737 * For the referenced grouping statement(s): 739 - The "asymmetric-key-pair-grouping" grouping is discussed in 740 Section 2.1.4.5. 742 - The "end-entity-cert-grouping" grouping is discussed in 743 Section 2.1.4.8. 744 - The "generate-csr-grouping" grouping is discussed in 745 Section 2.1.4.9. 747 2.1.5. Protocol-accessible Nodes 749 The "ietf-crypto-types" module does not contain any protocol- 750 accessible nodes, but the module needs to be "implemented", as 751 described in Section 5.6.5 of [RFC7950], in order for the identities 752 in Section 2.1.2 to be defined. 754 2.2. Example Usage 756 2.2.1. The "symmetric-key-grouping" and "asymmetric-key-pair-with- 757 certs-grouping" Grouping 759 The following non-normative module is constructed in order to 760 illustrate the use of the "symmetric-key-grouping" (Section 2.1.4.3) 761 and the "asymmetric-key-pair-with-certs-grouping" (Section 2.1.4.11) 762 grouping statements: 764 module ex-crypto-types-usage { 765 yang-version 1.1; 767 namespace "http://example.com/ns/example-crypto-types-usage"; 768 prefix "ectu"; 770 import ietf-crypto-types { 771 prefix ct; 772 reference 773 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 774 } 776 organization "Example Corporation"; 777 contact "YANG Designer "; 779 description 780 "This module illustrates the 'symmetric-key-grouping' 781 and 'asymmetric-key-grouping' groupings defined in 782 the 'ietf-crypto-types' module defined in RFC AAAA."; 784 revision "2020-08-20" { 785 description 786 "Initial version"; 787 reference 788 "RFC AAAA: Common YANG Data Types for Cryptography"; 789 } 790 container symmetric-keys { 791 description 792 "A container of symmetric keys."; 793 list symmetric-key { 794 key name; 795 description 796 "A symmetric key"; 797 leaf name { 798 type string; 799 description 800 "An arbitrary name for this key."; 801 } 802 uses ct:symmetric-key-grouping { 803 augment "key-type/encrypted-key/encrypted-key/" 804 + "encrypted-by" { 805 description 806 "Augments in a choice statement enabling the 807 encrypting key to be any other symmetric or 808 asymmetric key."; 809 uses encrypted-by-choice-grouping; 810 } 811 } 812 } 813 } 815 container asymmetric-keys { 816 description 817 "A container of asymmetric keys."; 818 list asymmetric-key { 819 key name; 820 leaf name { 821 type string; 822 description 823 "An arbitrary name for this key."; 824 } 825 uses ct:asymmetric-key-pair-with-certs-grouping { 826 augment "private-key-type/encrypted-private-key/" 827 + "encrypted-private-key/encrypted-by" { 828 description 829 "Augments in a choice statement enabling the 830 encrypting key to be any other symmetric or 831 asymmetric key."; 832 uses encrypted-by-choice-grouping; 833 } 834 } 835 description 836 "An asymmetric key pair with associated certificates."; 837 } 839 } 841 grouping encrypted-by-choice-grouping { 842 description 843 "A grouping that defines a choice enabling references 844 to other keys."; 845 choice encrypted-by-choice { 846 mandatory true; 847 description 848 "A choice amongst other symmetric or asymmetric keys."; 849 case symmetric-key-ref { 850 leaf symmetric-key-ref { 851 type leafref { 852 path "/ectu:symmetric-keys/ectu:symmetric-key/" 853 + "ectu:name"; 854 } 855 description 856 "Identifies the symmetric key used to encrypt this key."; 857 } 858 } 859 case asymmetric-key-ref { 860 leaf asymmetric-key-ref { 861 type leafref { 862 path "/ectu:asymmetric-keys/ectu:asymmetric-key/" 863 + "ectu:name"; 864 } 865 description 866 "Identifies the asymmetric key used to encrypt this key."; 867 } 868 } 869 } 870 } 871 } 873 The tree diagram [RFC8340] for this example module follows: 875 module: ex-crypto-types-usage 876 +--rw symmetric-keys 877 | +--rw symmetric-key* [name] 878 | +--rw name string 879 | +--rw key-format? identityref 880 | +--rw (key-type) 881 | +--:(cleartext-key) 882 | | +--rw cleartext-key? binary 883 | +--:(hidden-key) 884 | | +--rw hidden-key? empty 885 | +--:(encrypted-key) {symmetric-key-encryption}? 886 | +--rw encrypted-key 887 | +--rw encrypted-by 888 | | +--rw (encrypted-by-choice) 889 | | +--:(symmetric-key-ref) 890 | | | +--rw symmetric-key-ref? leafref 891 | | +--:(asymmetric-key-ref) 892 | | +--rw asymmetric-key-ref? leafref 893 | +--rw encrypted-value binary 894 +--rw asymmetric-keys 895 +--rw asymmetric-key* [name] 896 +--rw name string 897 +--rw public-key-format identityref 898 +--rw public-key binary 899 +--rw private-key-format? identityref 900 +--rw (private-key-type) 901 | +--:(cleartext-private-key) 902 | | +--rw cleartext-private-key? binary 903 | +--:(hidden-private-key) 904 | | +--rw hidden-private-key? empty 905 | +--:(encrypted-private-key) {private-key-encryption}? 906 | +--rw encrypted-private-key 907 | +--rw encrypted-by 908 | | +--rw (encrypted-by-choice) 909 | | +--:(symmetric-key-ref) 910 | | | +--rw symmetric-key-ref? leafref 911 | | +--:(asymmetric-key-ref) 912 | | +--rw asymmetric-key-ref? leafref 913 | +--rw encrypted-value binary 914 +--rw certificates 915 | +--rw certificate* [name] 916 | +--rw name string 917 | +--rw cert-data end-entity-cert-cms 918 | +---n certificate-expiration 919 | {certificate-expiration-notification}? 920 | +-- expiration-date yang:date-and-time 921 +---x generate-certificate-signing-request 922 {certificate-signing-request-generation}? 923 +---w input 924 | +---w csr-info ct:csr-info 925 +--ro output 926 +--ro certificate-signing-request ct:csr 928 grouping encrypted-by-choice-grouping 929 +-- (encrypted-by-choice) 930 +--:(symmetric-key-ref) 931 | +-- symmetric-key-ref? 932 | -> /symmetric-keys/symmetric-key/name 933 +--:(asymmetric-key-ref) 934 +-- asymmetric-key-ref? 935 -> /asymmetric-keys/asymmetric-key/name 937 Finally, the following example illustrates various symmetric and 938 asymmetric keys as they might appear in confugration: 940 =============== NOTE: '\' line wrapping per RFC 8792 ================ 942 945 946 ex-hidden-symmetric-key 947 948 949 950 ex-octet-string-based-symmetric-key 951 ct:octet-string-key-format 952 base64encodedvalue== 953 954 955 ex-one-symmetric-based-symmetric-key 956 ct:one-symmetric-key-format 957 base64encodedvalue== 958 959 960 ex-encrypted-one-symmetric-based-symmetric-key 961 ct:encrypted-one-symmetric-key-format 962 963 964 ex-hidden-asymmetric-key 966 967 base64encodedvalue== 968 969 970 972 975 976 ex-hidden-asymmetric-key 977 978 ct:subject-public-key-info-format 979 980 base64encodedvalue== 981 982 983 984 ex-hidden-asymmetric-key-cert 985 base64encodedvalue== 986 987 988 989 990 ex-subject-public-info-based-asymmetric-key 991 992 ct:subject-public-key-info-format 993 994 base64encodedvalue== 995 996 ct:rsa-private-key-format 997 998 base64encodedvalue== 1000 1001 1002 ex-cert 1003 base64encodedvalue== 1004 1005 1006 1007 1008 ex-one-asymmetric-based-symmetric-key 1009 1010 ct:subject-public-key-info-format 1011 1012 base64encodedvalue== 1013 1014 ct:one-asymmetric-key-format 1015 1016 base64encodedvalue== 1018 1019 1020 ex-encrypted-one-asymmetric-based-symmetric-key 1021 1022 ct:subject-public-key-info-format 1023 1024 base64encodedvalue== 1025 1026 ct:encrypted-one-asymmetric-key-format 1027 1028 1029 1030 ex-encrypted-one-symmetric-based-symmetri\ 1032 c-key 1033 1034 base64encodedvalue== 1035 1036 1037 1039 2.2.2. The "generate-certificate-signing-request" Action 1041 The following example illustrates the "generate-certificate-signing- 1042 request" action, discussed in Section 2.1.4.9, with the NETCONF 1043 protocol. 1045 REQUEST 1047 1049 1050 1052 1053 ex-key-sect571r1 1054 1055 base64encodedvalue== 1056 1057 1058 1059 1060 1062 RESPONSE 1064 1066 1068 base64encodedvalue== 1069 1070 1072 2.2.3. The "certificate-expiration" Notification 1074 The following example illustrates the "certificate-expiration" 1075 notification, discussed in Section 2.1.4.6, with the NETCONF 1076 protocol. 1078 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1080 1082 2018-05-25T00:01:00Z 1083 1085 1086 ex-hidden-asymmetric-key 1087 1088 1089 ex-hidden-asymmetric-key 1090 1091 2018-08-05T14:18:53-05:00 1093 1094 1095 1096 1097 1098 1100 2.3. YANG Module 1102 This module has normative references to [RFC2119], [RFC2986], 1103 [RFC3447], [RFC4253], [RFC5280], [RFC5652], [RFC5915], [RFC5958], 1104 [RFC6031], [RFC6125], [RFC6991], [RFC8174], [RFC8341], and 1105 [ITU.X690.2015]. 1107 file "ietf-crypto-types@2020-08-20.yang" 1109 module ietf-crypto-types { 1110 yang-version 1.1; 1111 namespace "urn:ietf:params:xml:ns:yang:ietf-crypto-types"; 1112 prefix ct; 1114 import ietf-yang-types { 1115 prefix yang; 1116 reference 1117 "RFC 6991: Common YANG Data Types"; 1118 } 1120 import ietf-netconf-acm { 1121 prefix nacm; 1122 reference 1123 "RFC 8341: Network Configuration Access Control Model"; 1124 } 1125 organization 1126 "IETF NETCONF (Network Configuration) Working Group"; 1128 contact 1129 "WG Web: 1130 WG List: 1131 Author: Kent Watsen "; 1133 description 1134 "This module defines common YANG types for cryptographic 1135 applications. 1137 Copyright (c) 2020 IETF Trust and the persons identified 1138 as authors of the code. All rights reserved. 1140 Redistribution and use in source and binary forms, with 1141 or without modification, is permitted pursuant to, and 1142 subject to the license terms contained in, the Simplified 1143 BSD License set forth in Section 4.c of the IETF Trust's 1144 Legal Provisions Relating to IETF Documents 1145 (https://trustee.ietf.org/license-info). 1147 This version of this YANG module is part of RFC AAAA 1148 (https://www.rfc-editor.org/info/rfcAAAA); see the RFC 1149 itself for full legal notices. 1151 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1152 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1153 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1154 are to be interpreted as described in BCP 14 (RFC 2119) 1155 (RFC 8174) when, and only when, they appear in all 1156 capitals, as shown here."; 1158 revision 2020-08-20 { 1159 description 1160 "Initial version"; 1161 reference 1162 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 1163 } 1165 /****************/ 1166 /* Features */ 1167 /****************/ 1169 feature one-symmetric-key-format { 1170 description 1171 "Indicates that the server supports the 1172 'one-symmetric-key-format' identity."; 1173 } 1175 feature one-asymmetric-key-format { 1176 description 1177 "Indicates that the server supports the 1178 'one-asymmetric-key-format' identity."; 1179 } 1181 feature encrypted-one-symmetric-key-format { 1182 description 1183 "Indicates that the server supports the 1184 'encrypted-one-symmetric-key-format' identity."; 1185 } 1187 feature encrypted-one-asymmetric-key-format { 1188 description 1189 "Indicates that the server supports the 1190 'encrypted-one-asymmetric-key-format' identity."; 1191 } 1193 feature certificate-signing-request-generation { 1194 description 1195 "Indicates that the server implements the 1196 'generate-certificate-signing-request' action."; 1197 } 1199 feature certificate-expiration-notification { 1200 description 1201 "Indicates that the server implements the 1202 'certificate-expiration' notification."; 1203 } 1205 feature password-encryption { 1206 description 1207 "Indicates that the server supports password 1208 encryption."; 1209 } 1211 feature symmetric-key-encryption { 1212 description 1213 "Indicates that the server supports password 1214 encryption."; 1215 } 1217 feature private-key-encryption { 1218 description 1219 "Indicates that the server supports password 1220 encryption."; 1221 } 1223 /*************************************************/ 1224 /* Base Identities for Key Format Structures */ 1225 /*************************************************/ 1227 identity symmetric-key-format { 1228 description "Base key-format identity for symmetric keys."; 1229 } 1231 identity public-key-format { 1232 description "Base key-format identity for public keys."; 1233 } 1235 identity private-key-format { 1236 description "Base key-format identity for private keys."; 1237 } 1239 /****************************************************/ 1240 /* Identities for Private Key Format Structures */ 1241 /****************************************************/ 1243 identity rsa-private-key-format { 1244 base "private-key-format"; 1245 description 1246 "Indicates that the private key value is encoded 1247 as an RSAPrivateKey (from RFC 3447)."; 1248 reference 1249 "RFC 3447: PKCS #1: RSA Cryptography 1250 Specifications Version 2.2"; 1251 } 1253 identity ec-private-key-format { 1254 base "private-key-format"; 1255 description 1256 "Indicates that the private key value is encoded 1257 as an ECPrivateKey (from RFC 5915)"; 1258 reference 1259 "RFC 5915: Elliptic Curve Private Key Structure"; 1260 } 1262 identity one-asymmetric-key-format { 1263 if-feature "one-asymmetric-key-format"; 1264 base "private-key-format"; 1265 description 1266 "Indicates that the private key value is a CMS 1267 OneAsymmetricKey structure, as defined in RFC 5958, 1268 encoded using ASN.1 distinguished encoding rules 1269 (DER), as specified in ITU-T X.690."; 1270 reference 1271 "RFC 5958: Asymmetric Key Packages 1272 ITU-T X.690: 1273 Information technology - ASN.1 encoding rules: 1274 Specification of Basic Encoding Rules (BER), 1275 Canonical Encoding Rules (CER) and Distinguished 1276 Encoding Rules (DER)."; 1277 } 1279 identity encrypted-one-asymmetric-key-format { 1280 if-feature "encrypted-one-asymmetric-key-format"; 1281 base "private-key-format"; 1282 description 1283 "Indicates that the private key value is a CMS EnvelopedData 1284 structure, per Section 8 in RFC 5652, containing a 1285 OneAsymmetricKey structure, as defined in RFC 5958, 1286 encoded using ASN.1 distinguished encoding rules (DER), 1287 as specified in ITU-T X.690."; 1288 reference 1289 "RFC 5652: Cryptographic Message Syntax (CMS) 1290 RFC 5958: Asymmetric Key Packages 1291 ITU-T X.690: 1292 Information technology - ASN.1 encoding rules: 1293 Specification of Basic Encoding Rules (BER), 1294 Canonical Encoding Rules (CER) and Distinguished 1295 Encoding Rules (DER)."; 1296 } 1298 /***************************************************/ 1299 /* Identities for Public Key Format Structures */ 1300 /***************************************************/ 1302 identity ssh-public-key-format { 1303 base "public-key-format"; 1304 description 1305 "Indicates that the public key value is an SSH public key, 1306 as specified by RFC 4253, Section 6.6, i.e.: 1308 string certificate or public key format 1309 identifier 1310 byte[n] key/certificate data."; 1311 reference 1312 "RFC 4253: The Secure Shell (SSH) Transport Layer Protocol"; 1313 } 1314 identity subject-public-key-info-format { 1315 base "public-key-format"; 1316 description 1317 "Indicates that the public key value is a SubjectPublicKeyInfo 1318 structure, as described in RFC 5280 encoded using ASN.1 1319 distinguished encoding rules (DER), as specified in 1320 ITU-T X.690."; 1321 reference 1322 "RFC 5280: 1323 Internet X.509 Public Key Infrastructure Certificate 1324 and Certificate Revocation List (CRL) Profile 1325 ITU-T X.690: 1326 Information technology - ASN.1 encoding rules: 1327 Specification of Basic Encoding Rules (BER), 1328 Canonical Encoding Rules (CER) and Distinguished 1329 Encoding Rules (DER)."; 1330 } 1332 /******************************************************/ 1333 /* Identities for Symmetric Key Format Structures */ 1334 /******************************************************/ 1336 identity octet-string-key-format { 1337 base "symmetric-key-format"; 1338 description 1339 "Indicates that the key is encoded as a raw octet string. 1340 The length of the octet string MUST be appropriate for 1341 the associated algorithm's block size."; 1342 } 1344 identity one-symmetric-key-format { 1345 if-feature "one-symmetric-key-format"; 1346 base "symmetric-key-format"; 1347 description 1348 "Indicates that the private key value is a CMS 1349 OneSymmetricKey structure, as defined in RFC 6031, 1350 encoded using ASN.1 distinguished encoding rules 1351 (DER), as specified in ITU-T X.690."; 1352 reference 1353 "RFC 6031: Cryptographic Message Syntax (CMS) 1354 Symmetric Key Package Content Type 1355 ITU-T X.690: 1356 Information technology - ASN.1 encoding rules: 1357 Specification of Basic Encoding Rules (BER), 1358 Canonical Encoding Rules (CER) and Distinguished 1359 Encoding Rules (DER)."; 1360 } 1361 identity encrypted-one-symmetric-key-format { 1362 if-feature "encrypted-one-symmetric-key-format"; 1363 base "symmetric-key-format"; 1364 description 1365 "Indicates that the private key value is a CMS 1366 EnvelopedData structure, per Section 8 in RFC 5652, 1367 containing a OneSymmetricKey structure, as defined 1368 in RFC 6031, encoded using ASN.1 distinguished 1369 encoding rules (DER), as specified in ITU-T X.690."; 1370 reference 1371 "RFC 5652: Cryptographic Message Syntax (CMS) 1372 RFC 6031: Cryptographic Message Syntax (CMS) 1373 Symmetric Key Package Content Type 1374 ITU-T X.690: 1375 Information technology - ASN.1 encoding rules: 1376 Specification of Basic Encoding Rules (BER), 1377 Canonical Encoding Rules (CER) and Distinguished 1378 Encoding Rules (DER)."; 1379 } 1381 /***************************************************/ 1382 /* Typedefs for ASN.1 structures from RFC 2986 */ 1383 /***************************************************/ 1385 typedef csr-info { 1386 type binary; 1387 description 1388 "A CertificationRequestInfo structure, as defined in 1389 RFC 2986, encoded using ASN.1 distinguished encoding 1390 rules (DER), as specified in ITU-T X.690."; 1391 reference 1392 "RFC 2986: PKCS #10: Certification Request Syntax 1393 Specification Version 1.7 1394 ITU-T X.690: 1395 Information technology - ASN.1 encoding rules: 1396 Specification of Basic Encoding Rules (BER), 1397 Canonical Encoding Rules (CER) and Distinguished 1398 Encoding Rules (DER)."; 1399 } 1401 typedef csr { 1402 type binary; 1403 description 1404 "A CertificationRequest structure, as specified in 1405 RFC 2986, encoded using ASN.1 distinguished encoding 1406 rules (DER), as specified in ITU-T X.690."; 1407 reference 1408 "RFC 2986: 1409 PKCS #10: Certification Request Syntax Specification 1410 Version 1.7 1411 ITU-T X.690: 1412 Information technology - ASN.1 encoding rules: 1413 Specification of Basic Encoding Rules (BER), 1414 Canonical Encoding Rules (CER) and Distinguished 1415 Encoding Rules (DER)."; 1416 } 1418 /***************************************************/ 1419 /* Typedefs for ASN.1 structures from RFC 5280 */ 1420 /***************************************************/ 1422 typedef x509 { 1423 type binary; 1424 description 1425 "A Certificate structure, as specified in RFC 5280, 1426 encoded using ASN.1 distinguished encoding rules (DER), 1427 as specified in ITU-T X.690."; 1428 reference 1429 "RFC 5280: 1430 Internet X.509 Public Key Infrastructure Certificate 1431 and Certificate Revocation List (CRL) Profile 1432 ITU-T X.690: 1433 Information technology - ASN.1 encoding rules: 1434 Specification of Basic Encoding Rules (BER), 1435 Canonical Encoding Rules (CER) and Distinguished 1436 Encoding Rules (DER)."; 1437 } 1439 typedef crl { 1440 type binary; 1441 description 1442 "A CertificateList structure, as specified in RFC 5280, 1443 encoded using ASN.1 distinguished encoding rules (DER), 1444 as specified in ITU-T X.690."; 1445 reference 1446 "RFC 5280: 1447 Internet X.509 Public Key Infrastructure Certificate 1448 and Certificate Revocation List (CRL) Profile 1449 ITU-T X.690: 1450 Information technology - ASN.1 encoding rules: 1451 Specification of Basic Encoding Rules (BER), 1452 Canonical Encoding Rules (CER) and Distinguished 1453 Encoding Rules (DER)."; 1454 } 1455 /***************************************************/ 1456 /* Typedefs for ASN.1 structures from RFC 6960 */ 1457 /***************************************************/ 1459 typedef oscp-request { 1460 type binary; 1461 description 1462 "A OCSPRequest structure, as specified in RFC 6960, 1463 encoded using ASN.1 distinguished encoding rules 1464 (DER), as specified in ITU-T X.690."; 1465 reference 1466 "RFC 6960: 1467 X.509 Internet Public Key Infrastructure Online 1468 Certificate Status Protocol - OCSP 1469 ITU-T X.690: 1470 Information technology - ASN.1 encoding rules: 1471 Specification of Basic Encoding Rules (BER), 1472 Canonical Encoding Rules (CER) and Distinguished 1473 Encoding Rules (DER)."; 1474 } 1476 typedef oscp-response { 1477 type binary; 1478 description 1479 "A OCSPResponse structure, as specified in RFC 6960, 1480 encoded using ASN.1 distinguished encoding rules 1481 (DER), as specified in ITU-T X.690."; 1482 reference 1483 "RFC 6960: 1484 X.509 Internet Public Key Infrastructure Online 1485 Certificate Status Protocol - OCSP 1486 ITU-T X.690: 1487 Information technology - ASN.1 encoding rules: 1488 Specification of Basic Encoding Rules (BER), 1489 Canonical Encoding Rules (CER) and Distinguished 1490 Encoding Rules (DER)."; 1491 } 1493 /***********************************************/ 1494 /* Typedefs for ASN.1 structures from 5652 */ 1495 /***********************************************/ 1497 typedef cms { 1498 type binary; 1499 description 1500 "A ContentInfo structure, as specified in RFC 5652, 1501 encoded using ASN.1 distinguished encoding rules (DER), 1502 as specified in ITU-T X.690."; 1503 reference 1504 "RFC 5652: 1505 Cryptographic Message Syntax (CMS) 1506 ITU-T X.690: 1507 Information technology - ASN.1 encoding rules: 1508 Specification of Basic Encoding Rules (BER), 1509 Canonical Encoding Rules (CER) and Distinguished 1510 Encoding Rules (DER)."; 1511 } 1513 typedef data-content-cms { 1514 type cms; 1515 description 1516 "A CMS structure whose top-most content type MUST be the 1517 data content type, as described by Section 4 in RFC 5652."; 1518 reference 1519 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1520 } 1522 typedef signed-data-cms { 1523 type cms; 1524 description 1525 "A CMS structure whose top-most content type MUST be the 1526 signed-data content type, as described by Section 5 in 1527 RFC 5652."; 1528 reference 1529 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1530 } 1532 typedef enveloped-data-cms { 1533 type cms; 1534 description 1535 "A CMS structure whose top-most content type MUST be the 1536 enveloped-data content type, as described by Section 6 1537 in RFC 5652."; 1538 reference 1539 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1540 } 1542 typedef digested-data-cms { 1543 type cms; 1544 description 1545 "A CMS structure whose top-most content type MUST be the 1546 digested-data content type, as described by Section 7 1547 in RFC 5652."; 1548 reference 1549 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1551 } 1553 typedef encrypted-data-cms { 1554 type cms; 1555 description 1556 "A CMS structure whose top-most content type MUST be the 1557 encrypted-data content type, as described by Section 8 1558 in RFC 5652."; 1559 reference 1560 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1561 } 1563 typedef authenticated-data-cms { 1564 type cms; 1565 description 1566 "A CMS structure whose top-most content type MUST be the 1567 authenticated-data content type, as described by Section 9 1568 in RFC 5652."; 1569 reference 1570 "RFC 5652: Cryptographic Message Syntax (CMS)"; 1571 } 1573 /*********************************************************/ 1574 /* Typedefs for ASN.1 structures related to RFC 5280 */ 1575 /*********************************************************/ 1577 typedef trust-anchor-cert-x509 { 1578 type x509; 1579 description 1580 "A Certificate structure that MUST encode a self-signed 1581 root certificate."; 1582 } 1584 typedef end-entity-cert-x509 { 1585 type x509; 1586 description 1587 "A Certificate structure that MUST encode a certificate 1588 that is neither self-signed nor having Basic constraint 1589 CA true."; 1590 } 1592 /*********************************************************/ 1593 /* Typedefs for ASN.1 structures related to RFC 5652 */ 1594 /*********************************************************/ 1596 typedef trust-anchor-cert-cms { 1597 type signed-data-cms; 1598 description 1599 "A CMS SignedData structure that MUST contain the chain of 1600 X.509 certificates needed to authenticate the certificate 1601 presented by a client or end-entity. 1603 The CMS MUST contain only a single chain of certificates. 1604 The client or end-entity certificate MUST only authenticate 1605 to last intermediate CA certificate listed in the chain. 1607 In all cases, the chain MUST include a self-signed root 1608 certificate. In the case where the root certificate is 1609 itself the issuer of the client or end-entity certificate, 1610 only one certificate is present. 1612 This CMS structure MAY (as applicable where this type is 1613 used) also contain suitably fresh (as defined by local 1614 policy) revocation objects with which the device can 1615 verify the revocation status of the certificates. 1617 This CMS encodes the degenerate form of the SignedData 1618 structure that is commonly used to disseminate X.509 1619 certificates and revocation objects (RFC 5280)."; 1620 reference 1621 "RFC 5280: 1622 Internet X.509 Public Key Infrastructure Certificate 1623 and Certificate Revocation List (CRL) Profile."; 1624 } 1626 typedef end-entity-cert-cms { 1627 type signed-data-cms; 1628 description 1629 "A CMS SignedData structure that MUST contain the end 1630 entity certificate itself, and MAY contain any number 1631 of intermediate certificates leading up to a trust 1632 anchor certificate. The trust anchor certificate 1633 MAY be included as well. 1635 The CMS MUST contain a single end entity certificate. 1636 The CMS MUST NOT contain any spurious certificates. 1638 This CMS structure MAY (as applicable where this type is 1639 used) also contain suitably fresh (as defined by local 1640 policy) revocation objects with which the device can 1641 verify the revocation status of the certificates. 1643 This CMS encodes the degenerate form of the SignedData 1644 structure that is commonly used to disseminate X.509 1645 certificates and revocation objects (RFC 5280)."; 1646 reference 1647 "RFC 5280: 1648 Internet X.509 Public Key Infrastructure Certificate 1649 and Certificate Revocation List (CRL) Profile."; 1650 } 1652 /*****************/ 1653 /* Groupings */ 1654 /*****************/ 1656 grouping encrypted-key-value-grouping { 1657 description 1658 "A reusable grouping for a value that has been encrypted by 1659 a symmetric or asymmetric key in the Keystore."; 1660 container encrypted-by { 1661 nacm:default-deny-write; 1662 description 1663 "An empty container enabling references to other keys that 1664 encrypt these keys to be augmented in. The referenced key 1665 MAY be a symmetric or an asymmetric key."; 1666 } 1667 leaf encrypted-value { 1668 nacm:default-deny-write; 1669 type binary; 1670 must "../encrypted-by"; 1671 mandatory true; 1672 description 1673 "The value, encrypted using the referenced symmetric 1674 or asymmetric key."; 1675 } 1676 } 1678 grouping password-grouping { 1679 description 1680 "A password that MAY be encrypted."; 1681 choice password-type { 1682 nacm:default-deny-write; 1683 mandatory true; 1684 description 1685 "Choice between password types."; 1686 case cleartext-password { 1687 leaf cleartext-password { 1688 nacm:default-deny-all; 1689 type string; 1690 description 1691 "The cleartext value of the password."; 1693 } 1694 } 1695 case encrypted-password { 1696 if-feature password-encryption; 1697 container encrypted-password { 1698 description 1699 "A container for the encrypted password value. The 1700 format of the 'encrypted-value' node is a CMS 1701 EnvelopedData structure, per Section 8 in RFC 5652, 1702 encoded using ASN.1 distinguished encoding rules 1703 (DER), as specified in ITU-T X.690."; 1704 reference 1705 "RFC 5652: Cryptographic Message Syntax (CMS) 1706 ITU-T X.690: 1707 Information technology - ASN.1 encoding rules: 1708 Specification of Basic Encoding Rules (BER), 1709 Canonical Encoding Rules (CER) and Distinguished 1710 Encoding Rules (DER)."; 1711 uses encrypted-key-value-grouping; 1712 } 1713 } 1714 } 1715 } 1717 grouping symmetric-key-grouping { 1718 description 1719 "A symmetric key."; 1720 leaf key-format { 1721 nacm:default-deny-write; 1722 type identityref { 1723 base symmetric-key-format; 1724 } 1725 description 1726 "Identifies the symmetric key's format. Implementations 1727 SHOULD ensure that the incoming symmetric key value is 1728 encoded in the specified format."; 1729 } 1730 choice key-type { 1731 nacm:default-deny-write; 1732 mandatory true; 1733 description 1734 "Choice between key types."; 1735 case cleartext-key { 1736 leaf cleartext-key { 1737 nacm:default-deny-all; 1738 type binary; 1739 must "../key-format"; 1740 description 1741 "The binary value of the key. The interpretation of 1742 the value is defined by the 'key-format' field."; 1743 } 1744 } 1745 case hidden-key { 1746 leaf hidden-key { 1747 type empty; 1748 must "not(../key-format)"; 1749 description 1750 "A hidden key. How such keys are created is outside 1751 the scope of this module."; 1752 } 1753 } 1754 case encrypted-key { 1755 if-feature symmetric-key-encryption; 1756 container encrypted-key { 1757 must "../key-format"; 1758 description 1759 "A container for the encrypted symmetric key value. 1760 The interpretation of the 'encrypted-value' node 1761 is via the 'key-format' node"; 1762 uses encrypted-key-value-grouping; 1763 } 1764 } 1765 } 1766 } 1768 grouping public-key-grouping { 1769 description 1770 "A public key."; 1771 leaf public-key-format { 1772 nacm:default-deny-write; 1773 type identityref { 1774 base public-key-format; 1775 } 1776 mandatory true; 1777 description 1778 "Identifies the public key's format. Implementations SHOULD 1779 ensure that the incoming public key value is encoded in the 1780 specified format."; 1781 } 1782 leaf public-key { 1783 nacm:default-deny-write; 1784 type binary; 1785 mandatory true; 1786 description 1787 "The binary value of the public key. The interpretation 1788 of the value is defined by 'public-key-format' field."; 1790 } 1791 } 1793 grouping asymmetric-key-pair-grouping { 1794 description 1795 "A private key and its associated public key. Implementations 1796 SHOULD ensure that the two keys are a matching pair."; 1797 uses public-key-grouping; 1798 leaf private-key-format { 1799 nacm:default-deny-write; 1800 type identityref { 1801 base private-key-format; 1802 } 1803 description 1804 "Identifies the private key's format. Implementations SHOULD 1805 ensure that the incoming private key value is encoded in the 1806 specified format."; 1807 } 1808 choice private-key-type { 1809 nacm:default-deny-write; 1810 mandatory true; 1811 description 1812 "Choice between key types."; 1813 case cleartext-private-key { 1814 leaf cleartext-private-key { 1815 nacm:default-deny-all; 1816 type binary; 1817 must "../private-key-format"; 1818 description 1819 "The value of the binary key The key's value is 1820 interpreted by the 'private-key-format' field."; 1821 } 1822 } 1823 case hidden-private-key { 1824 leaf hidden-private-key { 1825 type empty; 1826 must "not(../private-key-format)"; 1827 description 1828 "A hidden key. How such keys are created is 1829 outside the scope of this module."; 1830 } 1831 } 1832 case encrypted-private-key { 1833 if-feature private-key-encryption; 1834 container encrypted-private-key { 1835 must "../private-key-format"; 1836 description 1837 "A container for the encrypted asymmetric private key 1838 value. The interpretation of the 'encrypted-value' 1839 node is via the 'private-key-format' node"; 1840 uses encrypted-key-value-grouping; 1841 } 1842 } 1843 } 1844 } 1846 grouping certificate-expiration-grouping { 1847 description 1848 "A notification for when a certificate is about to, or 1849 already has, expired."; 1850 notification certificate-expiration { 1851 if-feature certificate-expiration-notification; 1852 description 1853 "A notification indicating that the configured certificate 1854 is either about to expire or has already expired. When to 1855 send notifications is an implementation specific decision, 1856 but it is RECOMMENDED that a notification be sent once a 1857 month for 3 months, then once a week for four weeks, and 1858 then once a day thereafter until the issue is resolved."; 1859 leaf expiration-date { 1860 type yang:date-and-time; 1861 mandatory true; 1862 description 1863 "Identifies the expiration date on the certificate."; 1864 } 1865 } 1866 } 1868 grouping trust-anchor-cert-grouping { 1869 description 1870 "A trust anchor certificate, and a notification for when 1871 it is about to (or already has) expire."; 1872 leaf cert-data { 1873 nacm:default-deny-write; 1874 type trust-anchor-cert-cms; 1875 description 1876 "The binary certificate data for this certificate."; 1877 } 1878 uses certificate-expiration-grouping; 1879 } 1881 grouping end-entity-cert-grouping { 1882 description 1883 "An end entity certificate, and a notification for when 1884 it is about to (or already has) expire. Implementations 1885 SHOULD assert that, where used, the end entity certificate 1886 contains the expected public key."; 1887 leaf cert-data { 1888 nacm:default-deny-write; 1889 type end-entity-cert-cms; 1890 description 1891 "The binary certificate data for this certificate."; 1892 } 1893 uses certificate-expiration-grouping; 1894 } 1896 grouping generate-csr-grouping { 1897 description 1898 "Defines the 'generate-certificate-signing-request' action."; 1899 action generate-certificate-signing-request { 1900 if-feature certificate-signing-request-generation; 1901 nacm:default-deny-all; 1902 description 1903 "Generates a certificate signing request structure for 1904 the associated asymmetric key using the passed subject 1905 and attribute values. 1907 This action statement is only available when the 1908 associated 'public-key-format' node's value is 1909 'subject-public-key-info-format'."; 1910 reference 1911 "RFC 6125: 1912 Representation and Verification of Domain-Based 1913 Application Service Identity within Internet Public Key 1914 Infrastructure Using X.509 (PKIX) Certificates in the 1915 Context of Transport Layer Security (TLS)"; 1916 input { 1917 leaf csr-info { 1918 type ct:csr-info; 1919 mandatory true; 1920 description 1921 "A CertificationRequestInfo structure, as defined in 1922 RFC 2986. 1924 Enables the client to provide a fully-populated 1925 CertificationRequestInfo structure that the server 1926 only needs to sign in order to generate the complete 1927 'CertificationRequest' structure to return in the 1928 'output'. 1930 The 'AlgorithmIdentifier' field contained inside 1931 the 'SubjectPublicKeyInfo' field MUST be one known 1932 to be supported by the device."; 1933 reference 1934 "RFC 2986: 1935 PKCS #10: Certification Request Syntax Specification 1936 RFC AAAA: 1937 YANG Data Types and Groupings for Cryptography"; 1938 } 1939 } 1940 output { 1941 leaf certificate-signing-request { 1942 type ct:csr; 1943 mandatory true; 1944 description 1945 "A CertificationRequest structure, as defined in 1946 RFC 2986."; 1947 reference 1948 "RFC 2986: 1949 PKCS #10: Certification Request Syntax Specification 1950 RFC AAAA: 1951 YANG Data Types and Groupings for Cryptography"; 1952 } 1953 } 1954 } 1955 } // generate-csr-grouping 1957 grouping asymmetric-key-pair-with-cert-grouping { 1958 description 1959 "A private/public key pair and an associated certificate. 1960 Implementations SHOULD assert that certificates contain 1961 the matching public key."; 1962 uses asymmetric-key-pair-grouping; 1963 uses end-entity-cert-grouping; 1964 uses generate-csr-grouping; 1965 } // asymmetric-key-pair-with-cert-grouping 1967 grouping asymmetric-key-pair-with-certs-grouping { 1968 description 1969 "A private/public key pair and associated certificates. 1970 Implementations SHOULD assert that certificates contain 1971 the matching public key."; 1972 uses asymmetric-key-pair-grouping; 1973 container certificates { 1974 nacm:default-deny-write; 1975 description 1976 "Certificates associated with this asymmetric key. 1977 More than one certificate supports, for instance, 1978 a TPM-protected asymmetric key that has both IDevID 1979 and LDevID certificates associated."; 1980 list certificate { 1981 key "name"; 1982 description 1983 "A certificate for this asymmetric key."; 1984 leaf name { 1985 type string; 1986 description 1987 "An arbitrary name for the certificate. If the name 1988 matches the name of a certificate that exists 1989 independently in (i.e., an IDevID), 1990 then the 'cert' node MUST NOT be configured."; 1991 } 1992 uses end-entity-cert-grouping { 1993 refine cert-data { 1994 mandatory true; 1995 } 1996 } 1997 } 1998 } 1999 uses generate-csr-grouping; 2000 } // asymmetric-key-pair-with-certs-grouping 2002 } 2004 2006 3. Security Considerations 2008 3.1. No Support for CRMF 2010 This document uses PKCS #10 [RFC2986] for the "generate-certificate- 2011 signing-request" action. The use of Certificate Request Message 2012 Format (CRMF) [RFC4211] was considered, but is was unclear if there 2013 was market demand for it. If it is desired to support CRMF in the 2014 future, a backwards compatible solution can be defined at that time. 2016 3.2. No Support for Key Generation 2018 Early revisions of this document included "rpc" statements for 2019 generating symmetric and asymmetric keys. There statements were 2020 removed due to an inability to obtain consensus for how to identify 2021 the key-algorithm to use. Thusly, the solution presented in this 2022 document only supports keys to be configured via an external client, 2023 which does not support Security best practice. 2025 3.3. Strength of Keys Configured 2027 When configuring key values, implementations SHOULD ensure that the 2028 strength of the key being configured is not greater than the strength 2029 of the underlying secure transport connection over which it is 2030 communicated. Implementations SHOULD fail the write-request if ever 2031 the strength of the private key is greater then the strength of the 2032 underlying transport. 2034 3.4. Deletion of Cleartext Key Values 2036 This module defines storage for cleartext key values that SHOULD be 2037 zeroized when deleted, so as to prevent the remnants of their 2038 persisted storage locations from being analyzed in any meaningful 2039 way. 2041 The cleartext key values are the "cleartext-key" node defined in the 2042 "symmetric-key-grouping" grouping (Section 2.1.4.3) and the 2043 "cleartext-private-key" node defined in the "asymmetric-key-pair- 2044 grouping" grouping ("Section 2.1.4.5). 2046 3.5. The "ietf-crypto-types" YANG Module 2048 The YANG module in this document defines "grouping" statements that 2049 are designed to be accessed via YANG based management protocols, such 2050 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2051 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2052 with mutual authentication. 2054 The NETCONF access control model (NACM) [RFC8341] provides the means 2055 to restrict access for particular users to a pre-configured subset of 2056 all available protocol operations and content. 2058 Since the module in this document only define groupings, these 2059 considerations are primarily for the designers of other modules that 2060 use these groupings. 2062 Some of the readable data nodes defined in this YANG module may be 2063 considered sensitive or vulnerable in some network environments. It 2064 is thus important to control read access (e.g., via get, get-config, 2065 or notification) to these data nodes. These are the subtrees and 2066 data nodes and their sensitivity/vulnerability: 2068 * The "cleartext-key" node: 2070 The "cleartext-key" node defined in the "symmetric-key- 2071 grouping" grouping is additionally sensitive to read operations 2072 such that, in normal use cases, it should never be returned to 2073 a client. For this reason, the NACM extension "default-deny- 2074 all" has been applied to it. 2076 * The "cleartext-private-key" node: 2078 The "cleartext-private-key" node defined in the "asymmetric- 2079 key-pair-grouping" grouping is additionally sensitive to read 2080 operations such that, in normal use cases, it should never be 2081 returned to a client. For this reason, the NACM extension 2082 "default-deny-all" has been applied. 2084 All of the writable data nodes defined by all the groupings defined 2085 in this module may be considered sensitive or vulnerable in some 2086 network environments. For instance, even the modification of a 2087 public key or a certificate can dramatically alter the implemented 2088 security policy. For this reason, the NACM extension "default-deny- 2089 write" has been applied to all the data nodes defined in the module. 2091 Some of the operations in this YANG module may be considered 2092 sensitive or vulnerable in some network environments. It is thus 2093 important to control access to these operations. These are the 2094 operations and their sensitivity/vulnerability: 2096 * generate-certificate-signing-request: 2098 This "action" statement SHOULD only be executed by authorized 2099 users. For this reason, the NACM extension "default-deny-all" 2100 has been applied. Note that NACM uses "default-deny-all" to 2101 protect "RPC" and "action" statements; it does not define, 2102 e.g., an extension called "default-deny-execute". 2104 For this action, it is RECOMMENDED that implementations assert 2105 channel binding [RFC5056], so as to ensure that the application 2106 layer that sent the request is the same as the device 2107 authenticated when the secure transport layer was established. 2109 4. IANA Considerations 2111 4.1. The "IETF XML" Registry 2113 This document registers one URI in the "ns" subregistry of the "IETF 2114 XML" registry [RFC3688]. Following the format in [RFC3688], the 2115 following registration is requested: 2117 URI: urn:ietf:params:xml:ns:yang:ietf-crypto-types 2118 Registrant Contact: The NETCONF WG of the IETF. 2119 XML: N/A, the requested URI is an XML namespace. 2121 4.2. The "YANG Module Names" Registry 2123 This document registers one YANG module in the "YANG Module Names" 2124 registry [RFC6020]. Following the format in [RFC6020], the following 2125 registration is requested: 2127 name: ietf-crypto-types 2128 namespace: urn:ietf:params:xml:ns:yang:ietf-crypto-types 2129 prefix: ct 2130 reference: RFC AAAA 2132 5. References 2134 5.1. Normative References 2136 [ITU.X680.2015] 2137 International Telecommunication Union, "Information 2138 technology - Abstract Syntax Notation One (ASN.1): 2139 Specification of basic notation", ITU-T Recommendation 2140 X.680, ISO/IEC 8824-1:2015, August 2015, 2141 . 2143 [ITU.X690.2015] 2144 International Telecommunication Union, "Information 2145 Technology - ASN.1 encoding rules: Specification of Basic 2146 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2147 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2148 X.690, ISO/IEC 8825-1:2015, August 2015, 2149 . 2151 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2152 Requirement Levels", BCP 14, RFC 2119, 2153 DOI 10.17487/RFC2119, March 1997, 2154 . 2156 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2157 Standards (PKCS) #1: RSA Cryptography Specifications 2158 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 2159 2003, . 2161 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 2162 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 2163 January 2006, . 2165 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2166 Housley, R., and W. Polk, "Internet X.509 Public Key 2167 Infrastructure Certificate and Certificate Revocation List 2168 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2169 . 2171 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2172 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2173 . 2175 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, 2176 DOI 10.17487/RFC5958, August 2010, 2177 . 2179 [RFC6031] Turner, S. and R. Housley, "Cryptographic Message Syntax 2180 (CMS) Symmetric Key Package Content Type", RFC 6031, 2181 DOI 10.17487/RFC6031, December 2010, 2182 . 2184 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2185 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2186 . 2188 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2189 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2190 . 2192 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2193 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2194 May 2017, . 2196 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2197 Access Control Model", STD 91, RFC 8341, 2198 DOI 10.17487/RFC8341, March 2018, 2199 . 2201 5.2. Informative References 2203 [I-D.ietf-netconf-crypto-types] 2204 Watsen, K., "YANG Data Types and Groupings for 2205 Cryptography", Work in Progress, Internet-Draft, draft- 2206 ietf-netconf-crypto-types-17, 10 July 2020, 2207 . 2210 [I-D.ietf-netconf-http-client-server] 2211 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2212 Servers", Work in Progress, Internet-Draft, draft-ietf- 2213 netconf-http-client-server-04, 8 July 2020, 2214 . 2217 [I-D.ietf-netconf-keystore] 2218 Watsen, K., "A YANG Data Model for a Keystore", Work in 2219 Progress, Internet-Draft, draft-ietf-netconf-keystore-19, 2220 10 July 2020, . 2223 [I-D.ietf-netconf-netconf-client-server] 2224 Watsen, K., "NETCONF Client and Server Models", Work in 2225 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2226 client-server-20, 8 July 2020, 2227 . 2230 [I-D.ietf-netconf-restconf-client-server] 2231 Watsen, K., "RESTCONF Client and Server Models", Work in 2232 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2233 client-server-20, 8 July 2020, 2234 . 2237 [I-D.ietf-netconf-ssh-client-server] 2238 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2239 SSH Servers", Work in Progress, Internet-Draft, draft- 2240 ietf-netconf-ssh-client-server-21, 10 July 2020, 2241 . 2244 [I-D.ietf-netconf-tcp-client-server] 2245 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2246 and TCP Servers", Work in Progress, Internet-Draft, draft- 2247 ietf-netconf-tcp-client-server-07, 8 July 2020, 2248 . 2251 [I-D.ietf-netconf-tls-client-server] 2252 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2253 TLS Servers", Work in Progress, Internet-Draft, draft- 2254 ietf-netconf-tls-client-server-21, 10 July 2020, 2255 . 2258 [I-D.ietf-netconf-trust-anchors] 2259 Watsen, K., "A YANG Data Model for a Truststore", Work in 2260 Progress, Internet-Draft, draft-ietf-netconf-trust- 2261 anchors-12, 10 July 2020, . 2264 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 2265 Request Syntax Specification Version 1.7", RFC 2986, 2266 DOI 10.17487/RFC2986, November 2000, 2267 . 2269 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2270 DOI 10.17487/RFC3688, January 2004, 2271 . 2273 [RFC4211] Schaad, J., "Internet X.509 Public Key Infrastructure 2274 Certificate Request Message Format (CRMF)", RFC 4211, 2275 DOI 10.17487/RFC4211, September 2005, 2276 . 2278 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 2279 Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, 2280 . 2282 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 2283 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 2284 . 2286 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2287 the Network Configuration Protocol (NETCONF)", RFC 6020, 2288 DOI 10.17487/RFC6020, October 2010, 2289 . 2291 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2292 Verification of Domain-Based Application Service Identity 2293 within Internet Public Key Infrastructure Using X.509 2294 (PKIX) Certificates in the Context of Transport Layer 2295 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2296 2011, . 2298 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2299 and A. Bierman, Ed., "Network Configuration Protocol 2300 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2301 . 2303 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2304 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2305 . 2307 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2308 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2309 . 2311 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2312 and R. Wilton, "Network Management Datastore Architecture 2313 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2314 . 2316 Appendix A. Change Log 2318 This section is to be removed before publishing as an RFC. 2320 A.1. I-D to 00 2322 * Removed groupings and notifications. 2324 * Added typedefs for identityrefs. 2326 * Added typedefs for other RFC 5280 structures. 2328 * Added typedefs for other RFC 5652 structures. 2330 * Added convenience typedefs for RFC 4253, RFC 5280, and RFC 5652. 2332 A.2. 00 to 01 2334 * Moved groupings from the draft-ietf-netconf-keystore here. 2336 A.3. 01 to 02 2338 * Removed unwanted "mandatory" and "must" statements. 2340 * Added many new crypto algorithms (thanks Haiguang!) 2342 * Clarified in asymmetric-key-pair-with-certs-grouping, in 2343 certificates/certificate/name/description, that if the name MUST 2344 NOT match the name of a certificate that exists independently in 2345 , enabling certs installed by the manufacturer (e.g., 2346 an IDevID). 2348 A.4. 02 to 03 2350 * renamed base identity 'asymmetric-key-encryption-algorithm' to 2351 'asymmetric-key-algorithm'. 2353 * added new 'asymmetric-key-algorithm' identities for secp192r1, 2354 secp224r1, secp256r1, secp384r1, and secp521r1. 2356 * removed 'mac-algorithm' identities for mac-aes-128-ccm, mac-aes- 2357 192-ccm, mac-aes-256-ccm, mac-aes-128-gcm, mac-aes-192-gcm, mac- 2358 aes-256-gcm, and mac-chacha20-poly1305. 2360 * for all -cbc and -ctr identities, renamed base identity 2361 'symmetric-key-encryption-algorithm' to 'encryption-algorithm'. 2363 * for all -ccm and -gcm identities, renamed base identity 2364 'symmetric-key-encryption-algorithm' to 'encryption-and-mac- 2365 algorithm' and renamed the identity to remove the "enc-" prefix. 2367 * for all the 'signature-algorithm' based identities, renamed from 2368 'rsa-*' to 'rsassa-*'. 2370 * removed all of the "x509v3-" prefixed 'signature-algorithm' based 2371 identities. 2373 * added 'key-exchange-algorithm' based identities for 'rsaes-oaep' 2374 and 'rsaes-pkcs1-v1_5'. 2376 * renamed typedef 'symmetric-key-encryption-algorithm-ref' to 2377 'symmetric-key-algorithm-ref'. 2379 * renamed typedef 'asymmetric-key-encryption-algorithm-ref' to 2380 'asymmetric-key-algorithm-ref'. 2382 * added typedef 'encryption-and-mac-algorithm-ref'. 2384 * Updated copyright date, boilerplate template, affiliation, and 2385 folding algorithm. 2387 A.5. 03 to 04 2389 * ran YANG module through formatter. 2391 A.6. 04 to 05 2393 * fixed broken symlink causing reformatted YANG module to not show. 2395 A.7. 05 to 06 2397 * Added NACM annotations. 2399 * Updated Security Considerations section. 2401 * Added 'asymmetric-key-pair-with-cert-grouping' grouping. 2403 * Removed text from 'permanently-hidden' enum regarding such keys 2404 not being backed up or restored. 2406 * Updated the boilerplate text in module-level "description" 2407 statement to match copyeditor convention. 2409 * Added an explanation to the 'public-key-grouping' and 'asymmetric- 2410 key-pair-grouping' statements as for why the nodes are not 2411 mandatory (e.g., because they may exist only in . 2413 * Added 'must' expressions to the 'public-key-grouping' and 2414 'asymmetric-key-pair-grouping' statements ensuring sibling nodes 2415 are either all exist or do not all exist. 2417 * Added an explanation to the 'permanently-hidden' that the value 2418 cannot be configured directly by clients and servers MUST fail any 2419 attempt to do so. 2421 * Added 'trust-anchor-certs-grouping' and 'end-entity-certs- 2422 grouping' (the plural form of existing groupings). 2424 * Now states that keys created in by the *-hidden-key 2425 actions are bound to the lifetime of the parent 'config true' 2426 node, and that subsequent invocations of either action results in 2427 a failure. 2429 A.8. 06 to 07 2431 * Added clarifications that implementations SHOULD assert that 2432 configured certificates contain the matching public key. 2434 * Replaced the 'generate-hidden-key' and 'install-hidden-key' 2435 actions with special 'crypt-hash' -like input/output values. 2437 A.9. 07 to 08 2439 * Removed the 'generate-key and 'hidden-key' features. 2441 * Added grouping symmetric-key-grouping 2443 * Modified 'asymmetric-key-pair-grouping' to have a 'choice' 2444 statement for the keystone module to augment into, as well as 2445 replacing the 'union' with leafs (having different NACM settings. 2447 A.10. 08 to 09 2449 * Converting algorithm from identities to enumerations. 2451 A.11. 09 to 10 2453 * All of the below changes are to the algorithm enumerations defined 2454 in ietf-crypto-types. 2456 * Add in support for key exchange over x.25519 and x.448 based on 2457 RFC 8418. 2459 * Add in SHAKE-128, SHAKE-224, SHAKE-256, SHAKE-384 and SHAKE 512 2461 * Revise/add in enum of signature algorithm for x25519 and x448 2463 * Add in des3-cbc-sha1 for IPSec 2465 * Add in sha1-des3-kd for IPSec 2467 * Add in definit for rc4-hmac and rc4-hmac-exp. These two 2468 algorithms have been deprecated in RFC 8429. But some existing 2469 draft in i2nsf may still want to use them. 2471 * Add x25519 and x448 curve for asymmetric algorithms 2473 * Add signature algorithms ed25519, ed25519-cts, ed25519ph 2475 * add signature algorithms ed448, ed448ph 2477 * Add in rsa-sha2-256 and rsa-sha2-512 for SSH protocols (rfc8332) 2479 A.12. 10 to 11 2481 * Added a "key-format" identity. 2483 * Added symmetric keys to the example in Section 2.2. 2485 A.13. 11 to 12 2487 * Removed all non-essential (to NC/RC) algorithm types. 2489 * Moved remaining algorithm types each into its own module. 2491 * Added a 'config false' "algorithms-supported" list to each of the 2492 algorithm-type modules. 2494 A.14. 12 to 13 2496 * Added the four features: "[encrypted-]one-[a]symmetric-key- 2497 format", each protecting a 'key-format' identity of the same name. 2499 * Added 'must' expressions asserting that the 'key-format' leaf 2500 exists whenever a non-hidden key is specified. 2502 * Improved the 'description' statements and added 'reference' 2503 statements for the 'key-format' identities. 2505 * Added a questionable forward reference to "encrypted-*" leafs in a 2506 couple 'when' expressions. 2508 * Did NOT move "config false" alg-supported lists to SSH/TLS drafts. 2510 A.15. 13 to 14 2512 * Resolved the "FIXME: forward ref" issue by modulating 'must', 2513 'when', and 'mandatory' expressions. 2515 * Moved the 'generatesymmetric-key' and 'generate-asymmetric-key' 2516 actions from ietf-keystore to ietf-crypto-types, now as RPCs. 2518 * Cleaned up various description statements and removed lingering 2519 FIXMEs. 2521 * Converted the "iana--algs" YANG modules to IANA 2522 registries with instructions for how to generate modules from the 2523 registries, whenever they may be updated. 2525 A.16. 14 to 15 2527 * Removed the IANA-maintained registries for symmetric, asymmetric, 2528 and hash algorithms. 2530 * Removed the "generate-symmetric-key" and "generate-asymmetric-key" 2531 RPCs. 2533 * Removed the "algorithm" node in the various symmetric and 2534 asymmetric key groupings. 2536 * Added 'typedef csr' and 'feature certificate-signing-request- 2537 generation'. 2539 * Refined a usage of "end-entity-cert-grouping" to make the "cert" 2540 node mandatory true. 2542 * Added a "Note to Reviewers" note to first page. 2544 A.17. 15 to 16 2546 * Updated draft title (refer to "Groupings" too). 2548 * Removed 'end-entity-certs-grouping' as it wasn't being used 2549 anywhere. 2551 * Removed 'trust-anchor-certs-grouping' as it was no longer being 2552 used after modifying 'local-or-truststore-certs-grouping' to use 2553 lists (not leaf-lists). 2555 * Renamed "cert" to "cert-data" in trust-anchor-cert-grouping. 2557 * Added "csr-info" typedef, to complement the existing "csr" 2558 typedef. 2560 * Added "ocsp-request" and "ocsp-response" typedefs, to complement 2561 the existing "crl" typedef. 2563 * Added "encrypted" cases to both symmetric-key-grouping and 2564 asymmetric-key-pair-grouping (Moved from Keystore draft). 2566 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2567 diagrams]. 2569 * Updated the Security Considerations section. 2571 A.18. 16 to 17 2573 * [Re]-added a "Strength of Keys Configured" Security Consideration 2575 * Prefixed "cleartext-" in the "key" and "private-key" node names. 2577 A.19. 17 to 18 2579 * Fixed issues found by the SecDir review of the "keystore" draft. 2581 * Added "password-grouping", discussed during the IETF 108 session. 2583 Acknowledgements 2585 The authors would like to thank for following for lively discussions 2586 on list and in the halls (ordered by first name): Balazs Kovacs, Eric 2587 Voit, Juergen Schoenwaelder, Liang Xia, Martin Bjorklund, Nick 2588 Hancock, Rich Salz, Rob Wilton, Sandra Murphy, Tom Petch, and Wang 2589 Haiguang. 2591 Author's Address 2593 Kent Watsen 2594 Watsen Networks 2596 Email: kent+ietf@watsen.net