idnits 2.17.1 draft-ietf-netconf-crypto-types-01.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 120 has weird spacing: '...gorithm ct:...' == Line 135 has weird spacing: '...gorithm ct:...' == Line 152 has weird spacing: '...request bin...' == Line 158 has weird spacing: '...-- cert ct:...' == Line 485 has weird spacing: '... string cer...' -- The document date (September 20, 2018) is 2016 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.X690.2015' -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track September 20, 2018 5 Expires: March 24, 2019 7 Common YANG Data Types for Cryptography 8 draft-ietf-netconf-crypto-types-01 10 Abstract 12 This document defines YANG identities and typedefs useful for 13 cryptographic applications. 15 Editorial Note (To be removed by RFC Editor) 17 This draft contains many placeholder values that need to be replaced 18 with finalized values at the time of publication. This note 19 summarizes all of the substitutions that are needed. No other RFC 20 Editor instructions are specified elsewhere in this document. 22 Artwork in this document contains shorthand references to drafts in 23 progress. Please apply the following replacements: 25 o "XXXX" --> the assigned RFC value for this draft 27 Artwork in this document contains placeholder values for the date of 28 publication of this draft. Please apply the following replacement: 30 o "2018-09-20" --> the publication date of this draft 32 The following Appendix section is to be removed prior to publication: 34 o Appendix A. Change Log 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on March 24, 2019. 53 Copyright Notice 55 Copyright (c) 2018 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 2. The Crypto Types Module . . . . . . . . . . . . . . . . . . . 3 72 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 73 2.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 5 74 3. Security Considerations . . . . . . . . . . . . . . . . . . . 19 75 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 76 4.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 19 77 4.2. The YANG Module Names Registry . . . . . . . . . . . . . 20 78 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 79 5.1. Normative References . . . . . . . . . . . . . . . . . . 20 80 5.2. Informative References . . . . . . . . . . . . . . . . . 21 81 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 23 82 A.1. The "asymmetric-key-pair-with-certs-grouping" Grouping . 23 83 A.2. The "generate-hidden-key" Action . . . . . . . . . . . . 25 84 A.3. The "install-hidden-key" Action . . . . . . . . . . . . . 26 85 A.4. The "generate-certificate-signing-request" Action . . . . 26 86 A.5. The "certificate-expiration" Notification . . . . . . . . 27 87 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 28 88 B.1. I-D to 00 . . . . . . . . . . . . . . . . . . . . . . . . 28 89 B.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 28 90 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 28 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29 93 1. Introduction 95 This document defines a YANG 1.1 [RFC7950] module specifying 96 identities and typedefs useful for cryptography. 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in BCP 101 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 2. The Crypto Types Module 106 2.1. Tree Diagram 108 This section provides a tree diagrams [RFC8340] for the "ietf-crypto- 109 types" module that, in addition to typedefs and identities, also 110 presents groupings intended for external usage. 112 module: ietf-crypto-types 114 grouping asymmetric-key-pair-grouping 115 +-- algorithm? ct:key-algorithm-ref 116 +-- public-key? binary 117 +-- private-key? union 118 +---x generate-hidden-key 119 | +---w input 120 | +---w algorithm ct:key-algorithm-ref 121 +---x install-hidden-key 122 +---w input 123 +---w algorithm ct:key-algorithm-ref 124 +---w public-key? binary 125 +---w private-key? binary 126 grouping public-key-grouping 127 +-- algorithm? ct:key-algorithm-ref 128 +-- public-key? binary 129 grouping asymmetric-key-pair-with-certs-grouping 130 +-- algorithm? ct:key-algorithm-ref 131 +-- public-key? binary 132 +-- private-key? union 133 +---x generate-hidden-key 134 | +---w input 135 | +---w algorithm ct:key-algorithm-ref 136 +---x install-hidden-key 137 | +---w input 138 | +---w algorithm ct:key-algorithm-ref 139 | +---w public-key? binary 140 | +---w private-key? binary 141 +-- certificates 142 | +-- certificate* [name] 143 | +-- name? string 144 | +-- cert ct:end-entity-cert-cms 145 | +---n certificate-expiration 146 | +-- expiration-date? yang:date-and-time 147 +---x generate-certificate-signing-request 148 +---w input 149 | +---w subject binary 150 | +---w attributes? binary 151 +--ro output 152 +--ro certificate-signing-request binary 153 grouping end-entity-cert-grouping 154 +-- cert ct:end-entity-cert-cms 155 +---n certificate-expiration 156 +-- expiration-date? yang:date-and-time 157 grouping trust-anchor-cert-grouping 158 +-- cert ct:trust-anchor-cert-cms 160 2.2. YANG Module 162 This module has normative references to [RFC4253], [RFC5280], 163 [RFC5480], [RFC5652], [RFC6991], [RFC8341] and [ITU.X690.2015]. 165 This module has informational references to [RFC2986], [RFC5915], 166 [RFC6125], [RFC6234], and [RFC8017] 168 file "ietf-crypto-types@2018-09-20.yang" 169 module ietf-crypto-types { 170 yang-version 1.1; 172 namespace "urn:ietf:params:xml:ns:yang:ietf-crypto-types"; 173 prefix "ct"; 175 import ietf-yang-types { 176 prefix yang; 177 reference 178 "RFC 6991: Common YANG Data Types"; 179 } 181 import ietf-netconf-acm { 182 prefix nacm; 183 reference 184 "RFC 8341: Network Configuration Access Control Model"; 185 } 187 organization 188 "IETF NETCONF (Network Configuration) Working Group"; 190 contact 191 "WG Web: 192 WG List: 194 Author: Kent Watsen 195 "; 197 description 198 "This module defines common YANG types for cryptographic 199 applications. 201 Copyright (c) 2018 IETF Trust and the persons identified 202 as authors of the code. All rights reserved. 204 Redistribution and use in source and binary forms, with 205 or without modification, is permitted pursuant to, and 206 subject to the license terms contained in, the Simplified 207 BSD License set forth in Section 4.c of the IETF Trust's 208 Legal Provisions Relating to IETF Documents 209 (http://trustee.ietf.org/license-info). 211 This version of this YANG module is part of RFC XXXX; see 212 the RFC itself for full legal notices."; 214 revision "2018-09-20" { 215 description 216 "Initial version"; 217 reference 218 "RFC XXXX: Common YANG Data Types for Cryptography"; 219 } 221 /*****************************************/ 222 /* Identities for Hashing Algorithms */ 223 /*****************************************/ 225 identity hash-algorithm { 226 description 227 "A base identity for hash algorithm verification."; 228 } 230 identity sha-256 { 231 base "hash-algorithm"; 232 description "The SHA-256 algorithm."; 233 reference "RFC 6234: US Secure Hash Algorithms."; 234 } 236 /*************************************/ 237 /* Identities for Key Algorithms */ 238 /*************************************/ 240 identity key-algorithm { 241 description 242 "Base identity from which all key-algorithms are derived."; 243 } 245 identity rsa1024 { 246 base key-algorithm; 247 description 248 "The RSA algorithm using a 1024-bit key."; 249 reference 250 "RFC 8017: 251 PKCS #1: RSA Cryptography Specifications Version 2.2."; 252 } 254 identity rsa2048 { 255 base key-algorithm; 256 description 257 "The RSA algorithm using a 2048-bit key."; 258 reference 259 "RFC 8017: 260 PKCS #1: RSA Cryptography Specifications Version 2.2."; 261 } 263 identity rsa3072 { 264 base key-algorithm; 265 description 266 "The RSA algorithm using a 3072-bit key."; 267 reference 268 "RFC 8017: 269 PKCS #1: RSA Cryptography Specifications Version 2.2."; 270 } 272 identity rsa4096 { 273 base key-algorithm; 274 description 275 "The RSA algorithm using a 4096-bit key."; 276 reference 277 "RFC 8017: 278 PKCS #1: RSA Cryptography Specifications Version 2.2."; 279 } 281 identity rsa7680 { 282 base key-algorithm; 283 description 284 "The RSA algorithm using a 7680-bit key."; 285 reference 286 "RFC 8017: 287 PKCS #1: RSA Cryptography Specifications Version 2.2."; 288 } 290 identity rsa15360 { 291 base key-algorithm; 292 description 293 "The RSA algorithm using a 15360-bit key."; 294 reference 295 "RFC 8017: 296 PKCS #1: RSA Cryptography Specifications Version 2.2."; 297 } 299 identity secp192r1 { 300 base key-algorithm; 301 description 302 "The secp192r1 algorithm."; 304 reference 305 "RFC 5480: Elliptic Curve Cryptography Subject Public 306 Key Information."; 307 } 309 identity secp256r1 { 310 base key-algorithm; 311 description 312 "The secp256r1 algorithm."; 313 reference 314 "RFC 5480: Elliptic Curve Cryptography Subject Public 315 Key Information."; 316 } 318 identity secp384r1 { 319 base key-algorithm; 320 description 321 "The secp384r1 algorithm."; 322 reference 323 "RFC 5480: Elliptic Curve Cryptography Subject Public 324 Key Information."; 325 } 327 identity secp521r1 { 328 base key-algorithm; 329 description 330 "The secp521r1 algorithm."; 331 reference 332 "RFC 5480: Elliptic Curve Cryptography Subject Public 333 Key Information."; 334 } 336 /*********************************************************/ 337 /* Typedefs for identityrefs to above base identites */ 338 /*********************************************************/ 340 typedef hash-algorithm-ref { 341 type identityref { 342 base "hash-algorithm"; 343 } 344 description 345 "This typedef enables importing modules to easily define an 346 identityref to the 'hash-algorithm' base identity."; 347 } 349 typedef key-algorithm-ref { 350 type identityref { 351 base "key-algorithm"; 352 } 353 description 354 "This typedef enables importing modules to easily define an 355 identityref to the 'key-algorithm' base identity."; 356 } 358 /***************************************************/ 359 /* Typedefs for ASN.1 structures from RFC 5280 */ 360 /***************************************************/ 362 typedef x509 { 363 type binary; 364 description 365 "A Certificate structure, as specified in RFC 5280, 366 encoded using ASN.1 distinguished encoding rules (DER), 367 as specified in ITU-T X.690."; 368 reference 369 "RFC 5280: 370 Internet X.509 Public Key Infrastructure Certificate 371 and Certificate Revocation List (CRL) Profile 372 ITU-T X.690: 373 Information technology - ASN.1 encoding rules: 374 Specification of Basic Encoding Rules (BER), 375 Canonical Encoding Rules (CER) and Distinguished 376 Encoding Rules (DER)."; 377 } 379 typedef crl { 380 type binary; 381 description 382 "A CertificateList structure, as specified in RFC 5280, 383 encoded using ASN.1 distinguished encoding rules (DER), 384 as specified in ITU-T X.690."; 385 reference 386 "RFC 5280: 387 Internet X.509 Public Key Infrastructure Certificate 388 and Certificate Revocation List (CRL) Profile 389 ITU-T X.690: 390 Information technology - ASN.1 encoding rules: 391 Specification of Basic Encoding Rules (BER), 392 Canonical Encoding Rules (CER) and Distinguished 393 Encoding Rules (DER)."; 394 } 396 /***********************************************/ 397 /* Typedefs for ASN.1 structures from 5652 */ 398 /***********************************************/ 400 typedef cms { 401 type binary; 402 description 403 "A ContentInfo structure, as specified in RFC 5652, 404 encoded using ASN.1 distinguished encoding rules (DER), 405 as specified in ITU-T X.690."; 406 reference 407 "RFC 5652: 408 Cryptographic Message Syntax (CMS) 409 ITU-T X.690: 410 Information technology - ASN.1 encoding rules: 411 Specification of Basic Encoding Rules (BER), 412 Canonical Encoding Rules (CER) and Distinguished 413 Encoding Rules (DER)."; 414 } 416 typedef data-content-cms { 417 type cms; 418 description 419 "A CMS structure whose top-most content type MUST be the 420 data content type, as described by Section 4 in RFC 5652."; 421 reference 422 "RFC 5652: Cryptographic Message Syntax (CMS)"; 423 } 425 typedef signed-data-cms { 426 type cms; 427 description 428 "A CMS structure whose top-most content type MUST be the 429 signed-data content type, as described by Section 5 in 430 RFC 5652."; 431 reference 432 "RFC 5652: Cryptographic Message Syntax (CMS)"; 433 } 435 typedef enveloped-data-cms { 436 type cms; 437 description 438 "A CMS structure whose top-most content type MUST be the 439 enveloped-data content type, as described by Section 6 440 in RFC 5652."; 441 reference 442 "RFC 5652: Cryptographic Message Syntax (CMS)"; 443 } 445 typedef digested-data-cms { 446 type cms; 447 description 448 "A CMS structure whose top-most content type MUST be the 449 digested-data content type, as described by Section 7 450 in RFC 5652."; 451 reference 452 "RFC 5652: Cryptographic Message Syntax (CMS)"; 453 } 455 typedef encrypted-data-cms { 456 type cms; 457 description 458 "A CMS structure whose top-most content type MUST be the 459 encrypted-data content type, as described by Section 8 460 in RFC 5652."; 461 reference 462 "RFC 5652: Cryptographic Message Syntax (CMS)"; 463 } 465 typedef authenticated-data-cms { 466 type cms; 467 description 468 "A CMS structure whose top-most content type MUST be the 469 authenticated-data content type, as described by Section 9 470 in RFC 5652."; 471 reference 472 "RFC 5652: Cryptographic Message Syntax (CMS)"; 473 } 475 /***************************************************/ 476 /* Typedefs for structures related to RFC 4253 */ 477 /***************************************************/ 479 typedef ssh-host-key { 480 type binary; 481 description 482 "The binary public key data for this SSH key, as 483 specified by RFC 4253, Section 6.6, i.e.: 485 string certificate or public key format 486 identifier 487 byte[n] key/certificate data."; 488 reference 489 "RFC 4253: The Secure Shell (SSH) Transport Layer 490 Protocol"; 491 } 493 /*********************************************************/ 494 /* Typedefs for ASN.1 structures related to RFC 5280 */ 495 /*********************************************************/ 497 typedef trust-anchor-cert-x509 { 498 type x509; 499 description 500 "A Certificate structure that MUST encode a self-signed 501 root certificate."; 502 } 504 typedef end-entity-cert-x509 { 505 type x509; 506 description 507 "A Certificate structure that MUST encode a certificate 508 that is neither self-signed nor having Basic constraint 509 CA true."; 510 } 512 /*********************************************************/ 513 /* Typedefs for ASN.1 structures related to RFC 5652 */ 514 /*********************************************************/ 516 typedef trust-anchor-cert-cms { 517 type signed-data-cms; 518 description 519 "A CMS SignedData structure that MUST contain the chain of 520 X.509 certificates needed to authenticate the certificate 521 presented by a client or end-entity. 523 The CMS MUST contain only a single chain of certificates. 524 The client or end-entity certificate MUST only authenticate 525 to last intermediate CA certificate listed in the chain. 527 In all cases, the chain MUST include a self-signed root 528 certificate. In the case where the root certificate is 529 itself the issuer of the client or end-entity certificate, 530 only one certificate is present. 532 This CMS structure MAY (as applicable where this type is 533 used) also contain suitably fresh (as defined by local 534 policy) revocation objects with which the device can 535 verify the revocation status of the certificates. 537 This CMS encodes the degenerate form of the SignedData 538 structure that is commonly used to disseminate X.509 539 certificates and revocation objects (RFC 5280)."; 540 reference 541 "RFC 5280: 543 Internet X.509 Public Key Infrastructure Certificate 544 and Certificate Revocation List (CRL) Profile."; 545 } 547 typedef end-entity-cert-cms { 548 type signed-data-cms; 549 description 550 "A CMS SignedData structure that MUST contain the end 551 entity certificate itself, and MAY contain any number 552 of intermediate certificates leading up to a trust 553 anchor certificate. The trust anchor certificate 554 MAY be included as well. 556 The CMS MUST contain a single end entity certificate. 557 The CMS MUST NOT contain any spurious certificates. 559 This CMS structure MAY (as applicable where this type is 560 used) also contain suitably fresh (as defined by local 561 policy) revocation objects with which the device can 562 verify the revocation status of the certificates. 564 This CMS encodes the degenerate form of the SignedData 565 structure that is commonly used to disseminate X.509 566 certificates and revocation objects (RFC 5280)."; 567 reference 568 "RFC 5280: 569 Internet X.509 Public Key Infrastructure Certificate 570 and Certificate Revocation List (CRL) Profile."; 571 } 573 /**********************************************/ 574 /* Groupings for keys and/or certificates */ 575 /**********************************************/ 577 grouping public-key-grouping { 578 description 579 "A public key."; 580 leaf algorithm { 581 type ct:key-algorithm-ref; 582 description 583 "Identifies the key's algorithm. More specifically, 584 this leaf specifies how the 'public-key' binary leaf 585 is encoded."; 586 reference 587 "RFC CCCC: Common YANG Data Types for Cryptography"; 588 } 589 leaf public-key { 590 type binary; 591 description 592 "A binary that contains the value of the public key. The 593 interpretation of the content is defined by the key 594 algorithm. For example, a DSA key is an integer, an RSA 595 key is represented as RSAPublicKey as defined in 596 RFC 8017, and an Elliptic Curve Cryptography (ECC) key 597 is represented using the 'publicKey' described in 598 RFC 5915."; 599 reference 600 "RFC 8017: Public-Key Cryptography Standards (PKCS) #1: 601 RSA Cryptography Specifications Version 2.2. 602 RFC 5915: Elliptic Curve Private Key Structure."; 603 } 604 } // end public-key-grouping 606 grouping asymmetric-key-pair-grouping { 607 description 608 "A private/public key pair."; 609 uses public-key-grouping; 610 leaf private-key { 611 nacm:default-deny-all; 612 type union { 613 type binary; 614 type enumeration { 615 enum "permanently-hidden" { 616 description 617 "The private key is inaccessible due to being 618 protected by the system (e.g., a cryptographic 619 hardware module). It is not possible to 620 configure a permanently hidden key, as a real 621 private key value must be set. Permanently 622 hidden keys cannot be archived or backed up."; 623 } 624 } 625 } 626 description 627 "A binary that contains the value of the private key. The 628 interpretation of the content is defined by the key 629 algorithm. For example, a DSA key is an integer, an RSA 630 key is represented as RSAPrivateKey as defined in 631 RFC 8017, and an Elliptic Curve Cryptography (ECC) key 632 is represented as ECPrivateKey as defined in RFC 5915."; 633 reference 634 "RFC 8017: Public-Key Cryptography Standards (PKCS) #1: 635 RSA Cryptography Specifications Version 2.2. 636 RFC 5915: Elliptic Curve Private Key Structure."; 638 } 639 action generate-hidden-key { 640 description 641 "Requests the device to generate a hidden key using the 642 specified asymmetric key algorithm. This action is 643 used to request the system the generate a key that 644 is 'permanently-hidden', perhaps protected by a 645 cryptographic hardware module. The resulting 646 asymmetric key values are considered operational 647 state and hence present only in ."; 648 input { 649 leaf algorithm { 650 type ct:key-algorithm-ref; 651 mandatory true; 652 description 653 "The algorithm to be used when generating the 654 asymmetric key."; 655 reference 656 "RFC CCCC: Common YANG Data Types for Cryptography"; 657 } 658 } 659 } // end generate-hidden-key 660 action install-hidden-key { 661 description 662 "Requests the device to load the specified values into 663 a hidden key. The resulting asymmetric key values are 664 considered operational state and hence present only in 665 ."; 666 input { 667 leaf algorithm { 668 type ct:key-algorithm-ref; 669 mandatory true; 670 description 671 "The algorithm to be used when generating the 672 asymmetric key."; 673 reference 674 "RFC CCCC: Common YANG Data Types for Cryptography"; 675 } 676 leaf public-key { 677 type binary; 678 description 679 "A binary that contains the value of the public key. 680 The interpretation of the content is defined by the key 681 algorithm. For example, a DSA key is an integer, an 682 RSA key is represented as RSAPublicKey as defined in 683 RFC 8017, and an Elliptic Curve Cryptography (ECC) key 684 is represented using the 'publicKey' described in 685 RFC 5915."; 687 reference 688 "RFC 8017: Public-Key Cryptography Standards (PKCS) #1: 689 RSA Cryptography Specifications Version 2.2. 690 RFC 5915: Elliptic Curve Private Key Structure."; 691 } 692 leaf private-key { 693 type binary; 694 description 695 "A binary that contains the value of the private key. 696 The interpretation of the content is defined by the key 697 algorithm. For example, a DSA key is an integer, an RSA 698 key is represented as RSAPrivateKey as defined in 699 RFC 8017, and an Elliptic Curve Cryptography (ECC) key 700 is represented as ECPrivateKey as defined in RFC 5915."; 701 reference 702 "RFC 8017: Public-Key Cryptography Standards (PKCS) #1: 703 RSA Cryptography Specifications Version 2.2. 704 RFC 5915: Elliptic Curve Private Key Structure."; 705 } 706 } 707 } // end install-hidden-key 708 } // end asymmetric-key-pair-grouping 710 grouping trust-anchor-cert-grouping { 711 description 712 "A certificate, and a notification for when it might expire."; 713 leaf cert { 714 type ct:trust-anchor-cert-cms; 715 mandatory true; 716 description 717 "The binary certificate data for this certificate."; 718 reference 719 "RFC YYYY: Common YANG Data Types for Cryptography"; 720 } 721 } // end trust-anchor-cert-grouping 723 grouping end-entity-cert-grouping { 724 description 725 "A certificate, and a notification for when it might expire."; 726 leaf cert { 727 type ct:end-entity-cert-cms; 728 mandatory true; 729 description 730 "The binary certificate data for this certificate."; 731 reference 732 "RFC YYYY: Common YANG Data Types for Cryptography"; 734 } 735 notification certificate-expiration { 736 description 737 "A notification indicating that the configured certificate 738 is either about to expire or has already expired. When to 739 send notifications is an implementation specific decision, 740 but it is RECOMMENDED that a notification be sent once a 741 month for 3 months, then once a week for four weeks, and 742 then once a day thereafter until the issue is resolved."; 743 leaf expiration-date { 744 type yang:date-and-time; 745 //mandatory true; 746 description 747 "Identifies the expiration date on the certificate."; 748 } 749 } 750 } // end end-entity-cert-grouping 752 grouping asymmetric-key-pair-with-certs-grouping { 753 description 754 "A private/public key pair and associated certificates."; 755 uses asymmetric-key-pair-grouping; 756 container certificates { 757 description 758 "Certificates associated with this asymmetric key. 759 More than one certificate supports, for instance, 760 a TPM-protected asymmetric key that has both IDevID 761 and LDevID certificates associated."; 762 list certificate { 763 must "../../algorithm 764 and ../../public-key 765 and ../../private-key"; 766 key name; 767 description 768 "A certificate for this asymmetric key."; 769 leaf name { 770 type string; 771 description 772 "An arbitrary name for the certificate."; 773 } 774 uses end-entity-cert-grouping; 775 } // end certificate 776 } // end certificates 777 action generate-certificate-signing-request { 778 description 779 "Generates a certificate signing request structure for 780 the associated asymmetric key using the passed subject 781 and attribute values. The specified assertions need 782 to be appropriate for the certificate's use. For 783 example, an entity certificate for a TLS server 784 SHOULD have values that enable clients to satisfy 785 RFC 6125 processing."; 786 input { 787 leaf subject { 788 type binary; 789 mandatory true; 790 description 791 "The 'subject' field per the CertificationRequestInfo 792 structure as specified by RFC 2986, Section 4.1 793 encoded using the ASN.1 distinguished encoding 794 rules (DER), as specified in ITU-T X.690."; 795 reference 796 "RFC 2986: 797 PKCS #10: Certification Request Syntaxi 798 Specification Version 1.7. 799 ITU-T X.690: 800 Information technology - ASN.1 encoding rules: 801 Specification of Basic Encoding Rules (BER), 802 Canonical Encoding Rules (CER) and Distinguished 803 Encoding Rules (DER)."; 804 } 805 leaf attributes { 806 type binary; 807 description 808 "The 'attributes' field from the structure 809 CertificationRequestInfo as specified by RFC 2986, 810 Section 4.1 encoded using the ASN.1 distinguished 811 encoding rules (DER), as specified in ITU-T X.690."; 812 reference 813 "RFC 2986: 814 PKCS #10: Certification Request Syntax 815 Specification Version 1.7. 816 ITU-T X.690: 817 Information technology - ASN.1 encoding rules: 818 Specification of Basic Encoding Rules (BER), 819 Canonical Encoding Rules (CER) and Distinguished 820 Encoding Rules (DER)."; 821 } 822 } 823 output { 824 leaf certificate-signing-request { 825 type binary; 826 mandatory true; 827 description 828 "A CertificationRequest structure as specified by 829 RFC 2986, Section 4.2 encoded using the ASN.1 830 distinguished encoding rules (DER), as specified 831 in ITU-T X.690."; 832 reference 833 "RFC 2986: 834 PKCS #10: Certification Request Syntax 835 Specification Version 1.7. 836 ITU-T X.690: 837 Information technology - ASN.1 encoding rules: 838 Specification of Basic Encoding Rules (BER), 839 Canonical Encoding Rules (CER) and Distinguished 840 Encoding Rules (DER)."; 842 } 843 } 844 } // end generate-certificate-signing-request 845 } // end asymmetric-key-pair-with-certs-grouping 847 } 848 850 3. Security Considerations 852 In order to use YANG identities for algorithm identifiers, only the 853 most commonly used RSA key lengths are supported for the RSA 854 algorithm. Additional key lengths can be defined in another module 855 or added into a future version of this document. 857 This document limits the number of elliptical curves supported. This 858 was done to match industry trends and IETF best practice (e.g., 859 matching work being done in TLS 1.3). If additional algorithms are 860 needed, they can be defined by another module or added into a future 861 version of this document. 863 The YANG module defined in this document specifies only typedefs and 864 identities, and hence there are no YANG-specific security 865 considerations that need to be addressed. 867 4. IANA Considerations 869 4.1. The IETF XML Registry 871 This document registers one URI in the "ns" subregistry of the IETF 872 XML Registry [RFC3688]. Following the format in [RFC3688], the 873 following registration is requested: 875 URI: urn:ietf:params:xml:ns:yang:ietf-crypto-types 876 Registrant Contact: The NETCONF WG of the IETF. 877 XML: N/A, the requested URI is an XML namespace. 879 4.2. The YANG Module Names Registry 881 This document registers one YANG module in the YANG Module Names 882 registry [RFC6020]. Following the format in [RFC6020], the the 883 following registration is requested: 885 name: ietf-crypto-types 886 namespace: urn:ietf:params:xml:ns:yang:ietf-crypto-types 887 prefix: ct 888 reference: RFC XXXX 890 5. References 892 5.1. Normative References 894 [ITU.X690.2015] 895 International Telecommunication Union, "Information 896 Technology - ASN.1 encoding rules: Specification of Basic 897 Encoding Rules (BER), Canonical Encoding Rules (CER) and 898 Distinguished Encoding Rules (DER)", ITU-T Recommendation 899 X.690, ISO/IEC 8825-1, August 2015, 900 . 902 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 903 Requirement Levels", BCP 14, RFC 2119, 904 DOI 10.17487/RFC2119, March 1997, 905 . 907 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 908 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 909 January 2006, . 911 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 912 Housley, R., and W. Polk, "Internet X.509 Public Key 913 Infrastructure Certificate and Certificate Revocation List 914 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 915 . 917 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 918 "Elliptic Curve Cryptography Subject Public Key 919 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 920 . 922 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 923 RFC 5652, DOI 10.17487/RFC5652, September 2009, 924 . 926 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 927 RFC 6991, DOI 10.17487/RFC6991, July 2013, 928 . 930 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 931 RFC 7950, DOI 10.17487/RFC7950, August 2016, 932 . 934 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 935 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 936 May 2017, . 938 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 939 Access Control Model", STD 91, RFC 8341, 940 DOI 10.17487/RFC8341, March 2018, 941 . 943 5.2. Informative References 945 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 946 Request Syntax Specification Version 1.7", RFC 2986, 947 DOI 10.17487/RFC2986, November 2000, 948 . 950 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 951 DOI 10.17487/RFC3688, January 2004, 952 . 954 [RFC5915] Turner, S. and D. Brown, "Elliptic Curve Private Key 955 Structure", RFC 5915, DOI 10.17487/RFC5915, June 2010, 956 . 958 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 959 the Network Configuration Protocol (NETCONF)", RFC 6020, 960 DOI 10.17487/RFC6020, October 2010, 961 . 963 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 964 Verification of Domain-Based Application Service Identity 965 within Internet Public Key Infrastructure Using X.509 966 (PKIX) Certificates in the Context of Transport Layer 967 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 968 2011, . 970 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 971 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 972 DOI 10.17487/RFC6234, May 2011, 973 . 975 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 976 "PKCS #1: RSA Cryptography Specifications Version 2.2", 977 RFC 8017, DOI 10.17487/RFC8017, November 2016, 978 . 980 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 981 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 982 . 984 Appendix A. Examples 986 A.1. The "asymmetric-key-pair-with-certs-grouping" Grouping 988 The following example module has been constructed to illustrate use 989 of the "asymmetric-key-pair-with-certs-grouping" grouping defined in 990 the "ietf-crypto-types" module. 992 Note that the "asymmetric-key-pair-with-certs-grouping" grouping uses 993 both the "asymmetric-key-pair-grouping" and "end-entity-cert- 994 grouping" groupings, and that the "asymmetric-key-pair-grouping" 995 grouping uses the "public-key-grouping" grouping. Thus, a total of 996 four of the five groupings defined in the "ietf-crypto-types" module 997 are illustrated through the use of this one grouping. The only 998 grouping not represented is the "trust-anchor-cert-grouping" 999 grouping. 1001 module ex-crypto-types-usage { 1002 yang-version 1.1; 1004 namespace "http://example.com/ns/example-crypto-types-usage"; 1005 prefix "ectu"; 1007 import ietf-crypto-types { 1008 prefix ct; 1009 reference 1010 "RFC XXXX: Common YANG Data Types for Cryptography"; 1011 } 1013 organization 1014 "Example Corporation"; 1016 contact 1017 "Author: YANG Designer "; 1019 description 1020 "This module illustrates the grouping 1021 defined in the crypto-types draft called 1022 'asymmetric-key-pair-with-certs-grouping'."; 1024 revision "1001-01-01" { 1025 description 1026 "Initial version"; 1027 reference 1028 "RFC ????: Usage Example for RFC XXXX"; 1029 } 1031 container keys { 1032 description 1033 "A container of keys."; 1034 list key { 1035 key name; 1036 leaf name { 1037 type string; 1038 description 1039 "An arbitrary name for this key."; 1040 } 1041 uses ct:asymmetric-key-pair-with-certs-grouping; 1042 description 1043 "An asymmetric key pair with associated certificates."; 1044 } 1045 } 1046 } 1047 Given the above example usage module, the following example 1048 illustrates some configured keys. 1050 1051 1052 locally-defined key 1053 1055 ct:secp521r1 1056 1057 base64encodedvalue== 1058 base64encodedvalue== 1059 1060 1062 A.2. The "generate-hidden-key" Action 1064 The following example illustrates the "generate-hidden-key" action in 1065 use with the NETCONF protocol. 1067 REQUEST 1068 ------- 1069 1071 1072 1073 1074 empty-key 1075 1076 1078 ct:secp521r1 1079 1080 1081 1082 1083 1084 1086 RESPONSE 1087 -------- 1088 1090 1091 1093 A.3. The "install-hidden-key" Action 1095 The following example illustrates the "install-hidden-key" action in 1096 use with the NETCONF protocol. 1098 REQUEST 1099 ------- 1100 1102 1103 1104 1105 empty-key 1106 1107 1109 ct:secp521r1 1110 1111 base64encodedvalue== 1112 base64encodedvalue== 1113 1114 1115 1116 1117 1119 RESPONSE 1120 -------- 1121 1123 1124 1126 A.4. The "generate-certificate-signing-request" Action 1128 The following example illustrates the "generate-certificate-signing- 1129 request" action in use with the NETCONF protocol. 1131 REQUEST 1132 ------- 1133 1135 1136 1137 1138 ex-key-sect571r1 1139 1140 base64encodedvalue== 1141 base64encodedvalue== 1142 1143 1144 1145 1146 1148 RESPONSE 1149 -------- 1150 1152 1154 base64encodedvalue== 1155 1156 1158 A.5. The "certificate-expiration" Notification 1160 The following example illustrates the "certificate-expiration" 1161 notification in use with the NETCONF protocol. 1163 1165 2018-05-25T00:01:00Z 1166 1167 1168 locally-defined key 1169 1170 1171 my-cert 1172 1173 1174 2018-08-05T14:18:53-05:00 1175 1176 1177 1178 1179 1180 1181 1183 Appendix B. Change Log 1185 B.1. I-D to 00 1187 o Removed groupings and notifications. 1189 o Added typedefs for identityrefs. 1191 o Added typedefs for other RFC 5280 structures. 1193 o Added typedefs for other RFC 5652 structures. 1195 o Added convenience typedefs for RFC 4253, RFC 5280, and RFC 5652. 1197 B.2. 00 to 01 1199 o Moved groupings from the draft-ietf-netconf-keystore here. 1201 Acknowledgements 1203 The authors would like to thank for following for lively discussions 1204 on list and in the halls (ordered by last name): Martin Bjorklund, 1205 Balazs Kovacs, Eric Voit, and Liang Xia. 1207 Author's Address 1209 Kent Watsen 1210 Juniper Networks 1212 EMail: kwatsen@juniper.net