idnits 2.17.1 draft-josefsson-pkix-textual-10.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 -- The document date (December 29, 2014) is 3399 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) ** Downref: Normative reference to an Informational RFC: RFC 2315 ** Downref: Normative reference to an Informational RFC: RFC 2986 -- Obsolete informational reference (is this intentional?): RFC 5208 (Obsoleted by RFC 5958) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Josefsson 3 Internet-Draft SJD AB 4 Intended status: Standards Track S. Leonard 5 Expires: July 2, 2015 Penango, Inc. 6 December 29, 2014 8 Textual Encodings of PKIX, PKCS, and CMS Structures 9 draft-josefsson-pkix-textual-10 11 Abstract 13 This document describes and discusses the textual encodings of the 14 Public-Key Infrastructure X.509 (PKIX), Public-Key Cryptography 15 Standards (PKCS), and Cryptographic Message Syntax (CMS). The 16 textual encodings are well-known, are implemented by several 17 applications and libraries, and are widely deployed. This document 18 articulates the de-facto rules by which existing implementations 19 operate, defines them so that future implementations can 20 interoperate. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 2, 2015. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. General Considerations . . . . . . . . . . . . . . . . . . . 4 58 3. ABNF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 4. Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 5. Textual Encoding of Certificates . . . . . . . . . . . . . . 8 61 5.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 8 62 5.2. Explanatory Text . . . . . . . . . . . . . . . . . . . . 9 63 5.3. File Extension . . . . . . . . . . . . . . . . . . . . . 9 64 6. Textual Encoding of Certificate Revocation Lists . . . . . . 10 65 7. Textual Encoding of PKCS #10 Certification Request Syntax . . 10 66 8. Textual Encoding of PKCS #7 Cryptographic Message Syntax . . 11 67 9. Textual Encoding of Cryptographic Message Syntax . . . . . . 12 68 10. Textual Encoding of PKCS #8 Private Key Info, and One 69 Asymmetric Key . . . . . . . . . . . . . . . . . . . . . . . 12 70 11. Textual Encoding of PKCS #8 Encrypted Private Key Info . . . 12 71 12. Textual Encoding of Attribute Certificates . . . . . . . . . 13 72 13. Textual Encoding of Subject Public Key Info . . . . . . . . . 13 73 14. Security Considerations . . . . . . . . . . . . . . . . . . . 14 74 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 75 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 76 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 17.1. Normative References . . . . . . . . . . . . . . . . . . 14 78 17.2. Informative References . . . . . . . . . . . . . . . . . 15 79 Appendix A. Non-Conforming Examples . . . . . . . . . . . . . . 16 80 Appendix B. DER Expectations . . . . . . . . . . . . . . . . . . 17 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 83 1. Introduction 85 Several security-related standards used on the Internet define ASN.1 86 data formats that are normally encoded using the Basic Encoding Rules 87 (BER) or Distinguished Encoding Rules (DER) [X.690], which are 88 binary, octet-oriented encodings. This document is about the textual 89 encodings of the following formats: 91 1. Certificates, Certificate Revocation Lists (CRLs), and Subject 92 Public Key Info structures in the Internet X.509 Public Key 93 Infrastructure Certificate and Certificate Revocation List (CRL) 94 Profile [RFC5280]. 96 2. PKCS #10: Certification Request Syntax [RFC2986]. 98 3. PKCS #7: Cryptographic Message Syntax [RFC2315]. 100 4. Cryptographic Message Syntax [RFC5652]. 102 5. PKCS #8: Private-Key Information Syntax [RFC5208], renamed to One 103 Asymmetric Key in Asymmetric Key Package [RFC5958], and Encrypted 104 Private-Key Information Syntax in the same standards. 106 6. Attribute Certificates in An Internet Attribute Certificate 107 Profile for Authorization [RFC5755]. 109 A disadvantage of a binary data format is that it cannot be 110 interchanged in textual transports, such as e-mail or text documents. 111 One advantage with text-based encodings is that they are easy to 112 modify using common text editors; for example, a user may concatenate 113 several certificates to form a certificate chain with copy-and-paste 114 operations. 116 The tradition within the RFC series can be traced back to PEM 117 [RFC1421], based on a proposal by Marshall Rose in Message 118 Encapsulation [RFC0934]. Originally called "PEM encapsulation 119 mechanism", "encapsulated PEM message", or (arguably) "PEM printable 120 encoding", today the format is sometimes referred to as "PEM 121 encoding". Variations include OpenPGP ASCII Armor [RFC2015] and 122 OpenSSH Key File Format [RFC4716]. 124 For reasons that basically boil down to non-coordination or 125 inattention, many PKIX, PKCS, and CMS libraries implement a text- 126 based encoding that is similar to--but not identical with--PEM 127 encoding. This document specifies the _textual encoding_ format, 128 articulates the de-facto rules that most implementations operate by, 129 and provides recommendations that will promote interoperability going 130 forward. This document also provides common nomenclature for syntax 131 elements, reflecting the evolution of this de-facto standard format. 132 Peter Gutmann's X.509 Style Guide [X.509SG] contains a section 133 "base64 Encoding" that describes the formats and contains suggestions 134 similar to what is in this document. All figures are real, 135 functional examples, with key lengths and inner contents chosen to be 136 as small as practicable. 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in RFC 141 2119 [RFC2119]. 143 2. General Considerations 145 Textual encoding begins with a line comprising "-----BEGIN ", a 146 label, and "-----", and ends with a line comprising "-----END ", a 147 label, and "-----". Between these lines, or "encapsulation 148 boundaries", are base64-encoded data according to Section 4 of 149 [RFC4648]. (PEM referred to this data as the "encapsulated text 150 portion".) Data before the encapsulation boundaries are permitted 151 and parsers MUST NOT malfunction when processing such data. 152 Furthermore, parsers SHOULD ignore whitespace and other non-base64 153 characters and MUST handle different newline conventions. 155 The type of data encoded is labeled depending on the type label in 156 the "-----BEGIN " line (pre-encapsulation boundary). For example, 157 the line may be "-----BEGIN CERTIFICATE-----" to indicate that the 158 content is a PKIX certificate (see further below). Generators MUST 159 put the same label on the "-----END " line (post-encapsulation 160 boundary) as the corresponding "-----BEGIN " line. Labels are 161 formally case-sensitive, uppercase, and comprised of zero or more 162 characters; they do not contain consecutive spaces or hyphen-minuses, 163 nor do they contain spaces or hyphen-minuses at either end. Parsers 164 MAY disregard the label in the post-encapsulation boundary instead of 165 signaling an error if there is a label mismatch: some extant 166 implementations require the labels to match; others do not. 168 There is exactly one space character (SP) separating the "BEGIN" or 169 "END" from the label. There are exactly five hyphen-minus (also 170 known as dash) characters ("-") on both ends of the encapsulation 171 boundaries, no more, no less. 173 The label type implies that the encoded data follows the specified 174 syntax. Parsers MUST handle non-conforming data gracefully. 175 However, not all parsers or generators prior to this Internet-Draft 176 behave consistently. A conforming parser MAY interpret the contents 177 as another label type, but ought to be aware of the security 178 implications discussed in the Security Considerations section. The 179 labels described in this document identify container formats that are 180 not specific to any particular cryptographic algorithm, a property 181 consistent with algorithm agility. These formats use the ASN.1 182 "AlgorithmIdentifier" structure as described in section 4.1.1.2 of 183 [RFC5280]. 185 Unlike legacy PEM encoding [RFC1421], OpenPGP ASCII armor, and the 186 OpenSSH key file format, textual encoding does *not* define or permit 187 headers to be encoded alongside the data. Empty space can appear 188 between the pre-encapsulation boundary and the base64, but generators 189 SHOULD NOT emit such any such spacing. (The provision for this empty 190 area is a throwback to PEM, which defined an "encapsulated header 191 portion".) 193 Implementers need to be aware that extant parsers diverge 194 considerably on the handling of whitespace. In this document, 195 "whitespace" means any character or series of characters that 196 represent horizontal or vertical space in typography. In US-ASCII, 197 whitespace means HT (0x09), VT (0x0B), FF (0x0C), SP (0x20), CR 198 (0x0D) and LF (0x0A); "blank" means HT and SP; lines are divided with 199 CRLF, CR, or LF. The common ABNF production WSP is congruent with 200 "blank"; a new production W is used for "whitespace". The ABNF in 201 Section 3 is specific to US-ASCII. As these textual encodings can be 202 used on many different systems as well as on long-term archival 203 storage media such as paper or engravings, an implementer ought to 204 use the spirit rather than the letter of the rules when generating or 205 parsing these formats in environments that are not strictly limited 206 to US-ASCII. 208 Most extant parsers ignore blanks at the ends of lines; blanks at the 209 beginnings of lines or in the middle of the base64-encoded data are 210 far less compatible. These observations are codified in Figure 1. 211 The most lax parser implementations are not line-oriented at all, and 212 will accept any mixture of whitespace outside of the encapsulation 213 boundaries (see Figure 2). Such lax parsing may run the risk of 214 accepting text that was not intended to be accepted in the first 215 place (e.g., because the text was a snippet or sample). 217 Generators MUST wrap the base64 encoded lines so that each line 218 consists of exactly 64 characters except for the final line which 219 will encode the remainder of the data (within the 64 character line 220 boundary), and MUST NOT emit extraneous whitespace. Parsers MAY 221 handle other line sizes. These requirements are consistent with PEM 222 [RFC1421]. 224 Files MAY contain multiple textual encoding instances. This is used, 225 for example, when a file contains several certificates. Whether the 226 instances are ordered or unordered depends on the context. 228 3. ABNF 230 The ABNF [RFC5234] of the textual encoding is: 232 textualmsg = preeb *WSP eol 233 *eolWSP 234 base64text 235 posteb *WSP [eol] 237 preeb = "-----BEGIN " label "-----" ; unlike [RFC1421] (A)BNF, 238 ; eol is not required (but 239 posteb = "-----END " label "-----" ; see [RFC1421] Section 4.4) 241 base64char = ALPHA / DIGIT / "+" / "/" 243 base64pad = "=" 245 base64line = 1*base64char *WSP eol 247 base64finl = *base64char (base64pad *WSP eol base64pad / 248 *2base64pad) *WSP eol 249 ; ...AB= = is not good, but is valid 251 base64text = *base64line base64finl 252 ; we could also use from RFC 1421, which requires 253 ; 16 groups of 4 chars, which means exactly 64 chars per 254 ; line, except the final line, but this is more accurate 256 labelchar = %x21-2C / %x2E-%7E ; any printable character, 257 ; except hyphen-minus 259 label = [ labelchar *( ["-" / SP] labelchar ) ] ; empty ok 261 eol = CRLF / CR / LF 263 eolWSP = WSP / CR / LF ; compare with LWSP 265 Figure 1: ABNF (Standard) 267 laxtextualmsg = *W preeb 268 laxbase64text 269 posteb *W 271 W = WSP / CR / LF / %x0B / %x0C ; whitespace 273 laxbase64text = *(W / base64char) [base64pad *W [base64pad *W]] 275 Figure 2: ABNF (Lax) 277 stricttextualmsg = preeb eol 278 strictbase64text 279 posteb eol 281 strictbase64finl = *15(4base64char) (4base64char / 3base64char 282 base64pad / 2base64char 2base64pad) eol 284 base64fullline = 64base64char eol 286 strictbase64text = *base64fullline strictbase64finl 288 Figure 3: ABNF (Strict) 290 New implementations SHOULD emit the strict format (Figure 3) 291 specified above. The choice of parsing strategy depends on the 292 context of use. 294 4. Guide 296 For convenience, these figures summarize the structures, encodings, 297 and references in the following sections: 299 Sec. Label ASN.1 Type Reference Module 300 ----+----------------------+-----------------------+---------+---------- 301 5 CERTIFICATE Certificate [RFC5280] id-pkix1-e 302 6 X509 CRL CertificateList [RFC5280] id-pkix1-e 303 7 CERTIFICATE REQUEST CertificationRequest [RFC2986] id-pkcs10 304 8 PKCS7 ContentInfo [RFC2315] id-pkcs7* 305 9 CMS ContentInfo [RFC5652] id-cms2004 306 10 PRIVATE KEY PrivateKeyInfo ::= [RFC5208] id-pkcs8 307 OneAsymmetricKey [RFC5958] id-aKPV1 308 11 ENCRYPTED PRIVATE KEY EncryptedPrivateKeyInfo [RFC5958] id-aKPV1 309 12 ATTRIBUTE CERTIFICATE AttributeCertificate [RFC5755] id-acv2 310 13 PUBLIC KEY SubjectPublicKeyInfo [RFC5280] id-pkix1-e 312 Figure 4: Convenience Guide 314 ----------------------------------------------------------------------- 315 id-pkixmod OBJECT IDENTIFIER ::= {iso(1) identified-organization(3) 316 dod(6) internet(1) security(5) mechanisms(5) pkix(7) mod(0)} 317 id-pkix1-e OBJECT IDENTIFIER ::= {id-pkixmod pkix1-explicit(18)} 318 id-acv2 OBJECT IDENTIFIER ::= {id-pkixmod mod-attribute-cert-v2(61)} 319 id-pkcs OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 320 rsadsi(113549) pkcs(1)} 321 id-pkcs10 OBJECT IDENTIFIER ::= {id-pkcs 10 modules(1) pkcs-10(1)} 322 id-pkcs7 OBJECT IDENTIFIER ::= {id-pkcs 7 modules(0) pkcs-7(1)} 323 id-pkcs8 OBJECT IDENTIFIER ::= {id-pkcs 8 modules(1) pkcs-8(1)} 324 id-sm-mod OBJECT IDENTIFIER ::= {id-pkcs 9 smime(16) modules(0)} 325 id-aKPV1 OBJECT IDENTIFIER ::= {id-sm-mod mod-asymmetricKeyPkgV1(50)} 326 id-cms2004 OBJECT IDENTIFIER ::= {id-sm-mod cms-2004(24)} 328 *This OID does not actually appear in PKCS #7 v1.5 [RFC2315]. It was 329 defined in the ASN.1 module to PKCS #7 v1.6 [P7v1.6], and has been 330 carried forward through PKCS #12 [RFC7292]. 332 Figure 5: ASN.1 Module Object Identifier Value Assignments 334 5. Textual Encoding of Certificates 336 5.1. Encoding 338 Public-key certificates are encoded using the "CERTIFICATE" label. 339 The encoded data MUST be a BER (DER strongly preferred; see 340 Appendix B) encoded ASN.1 "Certificate" structure as described in 341 section 4 of [RFC5280]. 343 -----BEGIN CERTIFICATE----- 344 MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G 345 A1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2VydGlmaWNhdGUgYXV0aG9y 346 aXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdudVRMUyBjZXJ0aWZpY2F0 347 ZSBhdXRob3JpdHkwHhcNMTEwNTIzMjAzODIxWhcNMTIxMjIyMDc0MTUxWjB9MQsw 348 CQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2Vy 349 dGlmaWNhdGUgYXV0aG9yaXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdu 350 dVRMUyBjZXJ0aWZpY2F0ZSBhdXRob3JpdHkwWTATBgcqhkjOPQIBBggqhkjOPQMB 351 BwNCAARS2I0jiuNn14Y2sSALCX3IybqiIJUvxUpj+oNfzngvj/Niyv2394BWnW4X 352 uQ4RTEiywK87WRcWMGgJB5kX/t2no0MwQTAPBgNVHRMBAf8EBTADAQH/MA8GA1Ud 353 DwEB/wQFAwMHBgAwHQYDVR0OBBYEFPC0gf6YEr+1KLlkQAPLzB9mTigDMAoGCCqG 354 SM49BAMCA0gAMEUCIDGuwD1KPyG+hRf88MeyMQcqOFZD0TbVleF+UsAGQ4enAiEA 355 l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= 356 -----END CERTIFICATE----- 358 Figure 6: Certificate Example 360 Historically the label "X509 CERTIFICATE" and also less commonly 361 "X.509 CERTIFICATE" have been used. Generators conforming to this 362 document MUST generate "CERTIFICATE" labels and MUST NOT generate 363 "X509 CERTIFICATE" or "X.509 CERTIFICATE" labels. Parsers SHOULD NOT 364 treat "X509 CERTIFICATE" or "X.509 CERTIFICATE" as equivalent to 365 "CERTIFICATE", but a valid exception may be for backwards 366 compatibility (potentially together with a warning). 368 5.2. Explanatory Text 370 Many tools are known to emit explanatory text before the BEGIN and 371 after the END lines for PKIX certificates, more than any other type. 372 If emitted, such text SHOULD be related to the certificate, such as 373 providing a textual representation of key data elements in the 374 certificate. 376 Subject: CN=Atlantis 377 Issuer: CN=Atlantis 378 Validity: from 7/9/2012 3:10:38 AM UTC to 7/9/2013 3:10:37 AM UTC 379 -----BEGIN CERTIFICATE----- 380 MIIBmTCCAUegAwIBAgIBKjAJBgUrDgMCHQUAMBMxETAPBgNVBAMTCEF0bGFudGlz 381 MB4XDTEyMDcwOTAzMTAzOFoXDTEzMDcwOTAzMTAzN1owEzERMA8GA1UEAxMIQXRs 382 YW50aXMwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAu+BXo+miabDIHHx+yquqzqNh 383 Ryn/XtkJIIHVcYtHvIX+S1x5ErgMoHehycpoxbErZmVR4GCq1S2diNmRFZCRtQID 384 AQABo4GJMIGGMAwGA1UdEwEB/wQCMAAwIAYDVR0EAQH/BBYwFDAOMAwGCisGAQQB 385 gjcCARUDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDAzA1BgNVHQEE 386 LjAsgBA0jOnSSuIHYmnVryHAdywMoRUwEzERMA8GA1UEAxMIQXRsYW50aXOCASow 387 CQYFKw4DAh0FAANBAKi6HRBaNEL5R0n56nvfclQNaXiDT174uf+lojzA4lhVInc0 388 ILwpnZ1izL4MlI9eCSHhVQBHEp2uQdXJB+d5Byg= 389 -----END CERTIFICATE----- 391 Figure 7: Certificate Example with Explanatory Text 393 5.3. File Extension 395 Although textual encodings of PKIX structures can occur anywhere, 396 many tools are known to offer an option to output this encoding when 397 serializing PKIX structures. To promote interoperability and to 398 separate DER encodings from textual encodings, the extension ".crt" 399 SHOULD be used for the textual encoding of a certificate. 400 Implementations should be aware that in spite of this recommendation, 401 many tools still default to encode certificates in this textual 402 encoding with the extension ".cer". 404 This section does not disturb the official application/pkix-cert 405 registration [RFC2585] in any way (which states that "each '.cer' 406 file contains exactly one certificate, encoded in DER format"), but 407 merely articulates a widespread, de-facto alternative. 409 6. Textual Encoding of Certificate Revocation Lists 411 Certificate Revocation Lists (CRLs) are encoded using the "X509 CRL" 412 label. The encoded data MUST be a BER (DER strongly preferred; see 413 Appendix B) encoded ASN.1 "CertificateList" structure as described in 414 Section 5 of [RFC5280]. 416 -----BEGIN X509 CRL----- 417 MIIB9DCCAV8CAQEwCwYJKoZIhvcNAQEFMIIBCDEXMBUGA1UEChMOVmVyaVNpZ24s 418 IEluYy4xHzAdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdvcmsxRjBEBgNVBAsT 419 PXd3dy52ZXJpc2lnbi5jb20vcmVwb3NpdG9yeS9SUEEgSW5jb3JwLiBieSBSZWYu 420 LExJQUIuTFREKGMpOTgxHjAcBgNVBAsTFVBlcnNvbmEgTm90IFZhbGlkYXRlZDEm 421 MCQGA1UECxMdRGlnaXRhbCBJRCBDbGFzcyAxIC0gTmV0c2NhcGUxGDAWBgNVBAMU 422 D1NpbW9uIEpvc2Vmc3NvbjEiMCAGCSqGSIb3DQEJARYTc2ltb25Aam9zZWZzc29u 423 Lm9yZxcNMDYxMjI3MDgwMjM0WhcNMDcwMjA3MDgwMjM1WjAjMCECEC4QNwPfRoWd 424 elUNpllhhTgXDTA2MTIyNzA4MDIzNFowCwYJKoZIhvcNAQEFA4GBAD0zX+J2hkcc 425 Nbrq1Dn5IKL8nXLgPGcHv1I/le1MNo9t1ohGQxB5HnFUkRPAY82fR6Epor4aHgVy 426 b+5y+neKN9Kn2mPF4iiun+a4o26CjJ0pArojCL1p8T0yyi9Xxvyc/ezaZ98HiIyP 427 c3DGMNR+oUmSjKZ0jIhAYmeLxaPHfQwR 428 -----END X509 CRL----- 430 Figure 8: CRL Example 432 Historically the label "CRL" has rarely been used. Today it is not 433 common and many popular tools do not understand the label. 434 Therefore, this document standardizes "X509 CRL" in order to promote 435 interoperability and backwards-compatibility. Generators conforming 436 to this document MUST generate "X509 CRL" labels and MUST NOT 437 generate "CRL" labels. Parsers SHOULD NOT treat "CRL" as equivalent 438 to "X509 CRL". 440 7. Textual Encoding of PKCS #10 Certification Request Syntax 442 PKCS #10 Certification Requests are encoded using the 443 "CERTIFICATE REQUEST" label. The encoded data MUST be a BER (DER 444 strongly preferred; see Appendix B) encoded ASN.1 445 "CertificationRequest" structure as described in [RFC2986]. 447 -----BEGIN CERTIFICATE REQUEST----- 448 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 449 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 450 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 451 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 452 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 453 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 454 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 455 dEQc8B8jAcnuOrfU 456 -----END CERTIFICATE REQUEST----- 458 Figure 9: PKCS #10 Example 460 The label "NEW CERTIFICATE REQUEST" is also in wide use. Generators 461 conforming to this document MUST generate "CERTIFICATE REQUEST" 462 labels. Parsers MAY treat "NEW CERTIFICATE REQUEST" as equivalent to 463 "CERTIFICATE REQUEST". 465 8. Textual Encoding of PKCS #7 Cryptographic Message Syntax 467 PKCS #7 Cryptographic Message Syntax structures are encoded using the 468 "PKCS7" label. The encoded data MUST be a BER encoded ASN.1 469 "ContentInfo" structure as described in [RFC2315]. 471 -----BEGIN PKCS7----- 472 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 473 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 474 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 475 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 476 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 477 -----END PKCS7----- 479 Figure 10: PKCS #7 Example 481 The label "CERTIFICATE CHAIN" has been in use to denote a degenerate 482 PKCS #7 structure that contains only a list of certificates (see 483 Section 9 of [RFC2315]). Several modern tools do not support this 484 label. Generators MUST NOT generate the "CERTIFICATE CHAIN" label. 485 Parsers SHOULD NOT treat "CERTIFICATE CHAIN" as equivalent to 486 "PKCS7". 488 PKCS #7 is an old standard that has long been superseded by CMS. 489 Implementations SHOULD NOT generate PKCS #7 when CMS is an 490 alternative. 492 9. Textual Encoding of Cryptographic Message Syntax 494 Cryptographic Message Syntax structures are encoded using the "CMS" 495 label. The encoded data MUST be a BER encoded ASN.1 "ContentInfo" 496 structure as described in [RFC5652]. 498 -----BEGIN CMS----- 499 MIGDBgsqhkiG9w0BCRABCaB0MHICAQAwDQYLKoZIhvcNAQkQAwgwXgYJKoZIhvcN 500 AQcBoFEET3icc87PK0nNK9ENqSxItVIoSa0o0S/ISczMs1ZIzkgsKk4tsQ0N1nUM 501 dvb05OXi5XLPLEtViMwvLVLwSE0sKlFIVHAqSk3MBkkBAJv0Fx0= 502 -----END CMS----- 504 Figure 11: CMS Example 506 CMS is the IETF successor to PKCS #7. Section 1.1.1 of [RFC5652] 507 describes the changes since PKCS #7 v1.5. Implementations SHOULD 508 generate CMS when it is an alternative, promoting interoperability 509 and forwards-compatibility. 511 10. Textual Encoding of PKCS #8 Private Key Info, and One Asymmetric 512 Key 514 Unencrypted PKCS #8 Private Key Information Syntax structures 515 (PrivateKeyInfo), renamed to Asymmetric Key Packages 516 (OneAsymmetricKey), are encoded using the "PRIVATE KEY" label. The 517 encoded data MUST be a BER (DER preferred; see Appendix B) encoded 518 ASN.1 "PrivateKeyInfo" structure as described in PKCS #8, or a 519 "OneAsymmetricKey" structure as described in [RFC5958]. The two are 520 semantically identical, and can be distinguished by version number. 522 -----BEGIN PRIVATE KEY----- 523 MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf 524 jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK 525 H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ 526 -----END PRIVATE KEY----- 528 Figure 12: PKCS #8 PrivateKeyInfo (OneAsymmetricKey) Example 530 11. Textual Encoding of PKCS #8 Encrypted Private Key Info 532 Encrypted PKCS #8 Private Key Information Syntax structures 533 (EncryptedPrivateKeyInfo), called the same in [RFC5958], are encoded 534 using the "ENCRYPTED PRIVATE KEY" label. The encoded data MUST be a 535 BER (DER preferred; see Appendix B) encoded ASN.1 536 "EncryptedPrivateKeyInfo" structure as described in PKCS #8 and 537 [RFC5958]. 539 -----BEGIN ENCRYPTED PRIVATE KEY----- 540 MIHNMEAGCSqGSIb3DQEFDTAzMBsGCSqGSIb3DQEFDDAOBAghhICA6T/51QICCAAw 541 FAYIKoZIhvcNAwcECBCxDgvI59i9BIGIY3CAqlMNBgaSI5QiiWVNJ3IpfLnEiEsW 542 Z0JIoHyRmKK/+cr9QPLnzxImm0TR9s4JrG3CilzTWvb0jIvbG3hu0zyFPraoMkap 543 8eRzWsIvC5SVel+CSjoS2mVS87cyjlD+txrmrXOVYDE+eTgMLbrLmsWh3QkCTRtF 544 QC7k0NNzUHTV9yGDwfqMbw== 545 -----END ENCRYPTED PRIVATE KEY----- 547 Figure 13: PKCS #8 EncryptedPrivateKeyInfo Example 549 12. Textual Encoding of Attribute Certificates 551 Attribute certificates are encoded using the "ATTRIBUTE CERTIFICATE" 552 label. The encoded data MUST be a BER (DER strongly preferred; see 553 Appendix B) encoded ASN.1 "AttributeCertificate" structure as 554 described in [RFC5755]. 556 -----BEGIN ATTRIBUTE CERTIFICATE----- 557 MIICKzCCAZQCAQEwgZeggZQwgYmkgYYwgYMxCzAJBgNVBAYTAlVTMREwDwYDVQQI 558 DAhOZXcgWW9yazEUMBIGA1UEBwwLU3RvbnkgQnJvb2sxDzANBgNVBAoMBkNTRTU5 559 MjE6MDgGA1UEAwwxU2NvdHQgU3RhbGxlci9lbWFpbEFkZHJlc3M9c3N0YWxsZXJA 560 aWMuc3VueXNiLmVkdQIGARWrgUUSoIGMMIGJpIGGMIGDMQswCQYDVQQGEwJVUzER 561 MA8GA1UECAwITmV3IFlvcmsxFDASBgNVBAcMC1N0b255IEJyb29rMQ8wDQYDVQQK 562 DAZDU0U1OTIxOjA4BgNVBAMMMVNjb3R0IFN0YWxsZXIvZW1haWxBZGRyZXNzPXNz 563 dGFsbGVyQGljLnN1bnlzYi5lZHUwDQYJKoZIhvcNAQEFBQACBgEVq4FFSjAiGA8z 564 OTA3MDIwMTA1MDAwMFoYDzM5MTEwMTMxMDUwMDAwWjArMCkGA1UYSDEiMCCGHmh0 565 dHA6Ly9pZGVyYXNobi5vcmcvaW5kZXguaHRtbDANBgkqhkiG9w0BAQUFAAOBgQAV 566 M9axFPXXozEFcer06bj9MCBBCQLtAM7ZXcZjcxyva7xCBDmtZXPYUluHf5OcWPJz 567 5XPus/xS9wBgtlM3fldIKNyNO8RsMp6Ocx+PGlICc7zpZiGmCYLl64lAEGPO/bsw 568 Smluak1aZIttePeTAHeJJs8izNJ5aR3Wcd3A5gLztQ== 569 -----END ATTRIBUTE CERTIFICATE----- 571 Figure 14: Attribute Certificate Example 573 13. Textual Encoding of Subject Public Key Info 575 Public keys are encoded using the "PUBLIC KEY" label. The encoded 576 data MUST be a BER (DER preferred; see Appendix B) encoded ASN.1 577 "SubjectPublicKeyInfo" structure as described in Section 4.1.2.7 of 578 [RFC5280]. 580 -----BEGIN PUBLIC KEY----- 581 MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEn1LlwLN/KBYQRVH6HfIMTzfEqJOVztLe 582 kLchp2hi78cCaMY81FBlYs8J9l7krc+M4aBeCGYFjba+hiXttJWPL7ydlE+5UG4U 583 Nkn3Eos8EiZByi9DVsyfy9eejh+8AXgp 584 -----END PUBLIC KEY----- 586 Figure 15: Subject Public Key Info Example 588 14. Security Considerations 590 Data in this format often originates from untrusted sources, thus 591 parsers must be prepared to handle unexpected data without causing 592 security vulnerabilities. 594 Implementers building implementations that rely on canonical 595 representation or the ability to fingerprint a particular data object 596 need to understand that this Internet-Draft does not define canonical 597 encodings. The first ambiguity is introduced by permitting the text- 598 encoded representation instead of the binary BER or DER encodings, 599 but further ambiguities arise when multiple labels are treated as 600 similar. Variations of whitespace and non-base64 alphabetic 601 characters can create further ambiguities. Data encoding ambiguities 602 also create opportunities for side channels. If canonical encodings 603 are desired, the encoded structure must be decoded and processed into 604 a canonical form (namely, DER encoding). 606 15. IANA Considerations 608 This document implies no IANA Considerations. 610 16. Acknowledgements 612 Peter Gutmann suggested to document labels for Attribute Certificates 613 and PKCS #7 messages, and to add examples for the non-standard 614 variants. Dr. Stephen Henson suggested distinguishing when BER 615 versus DER are appropriate or necessary. 617 17. References 619 17.1. Normative References 621 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 622 Requirement Levels", BCP 14, RFC 2119, March 1997. 624 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 625 Version 1.5", RFC 2315, March 1998. 627 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 628 Request Syntax Specification Version 1.7", RFC 2986, 629 November 2000. 631 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 632 Encodings", RFC 4648, October 2006. 634 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 635 Housley, R., and W. Polk, "Internet X.509 Public Key 636 Infrastructure Certificate and Certificate Revocation List 637 (CRL) Profile", RFC 5280, May 2008. 639 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 640 Specifications: ABNF", STD 68, RFC 5234, January 2008. 642 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 643 RFC 5652, September 2009. 645 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 646 Attribute Certificate Profile for Authorization", RFC 647 5755, January 2010. 649 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August 650 2010. 652 [X.690] International Telecommunications Union, "Information 653 Technology - ASN.1 encoding rules: Specification of Basic 654 Encoding Rules (BER), Canonical Encoding Rules (CER) and 655 Distinguished Encoding Rules (DER)", ITU-T Recommendation 656 X.690, ISO/IEC 8825-1:2008, November 2008. 658 17.2. Informative References 660 [RFC0934] Rose, M. and E. Stefferud, "Proposed standard for message 661 encapsulation", RFC 934, January 1985. 663 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 664 Mail: Part I: Message Encryption and Authentication 665 Procedures", RFC 1421, February 1993. 667 [RFC2015] Elkins, M., "MIME Security with Pretty Good Privacy 668 (PGP)", RFC 2015, October 1996. 670 [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key 671 Infrastructure Operational Protocols: FTP and HTTP", RFC 672 2585, May 1999. 674 [RFC4716] Galbraith, J. and R. Thayer, "The Secure Shell (SSH) 675 Public Key File Format", RFC 4716, November 2006. 677 [RFC5208] Kaliski, B., "Public-Key Cryptography Standards (PKCS) #8: 678 Private-Key Information Syntax Specification Version 1.2", 679 RFC 5208, May 2008. 681 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 682 M. Scott, "PKCS #12: Personal Information Exchange Syntax 683 v1.1", RFC 7292, July 2014. 685 [P7v1.6] Kaliski, B. and K. Kingdon, "Extensions and Revisions to 686 PKCS #7 (Version 1.6 Bulletin)", May 1997, 687 . 691 [X.509SG] Gutmann, P., "X.509 Style Guide", October 2000, 692 . 695 Appendix A. Non-Conforming Examples 697 This section contains examples for the non-recommended label variants 698 described earlier in this document. As discussed earlier, supporting 699 these are not required and sometimes discouraged. Still, they can be 700 useful for interoperability testing and for easy reference. 702 -----BEGIN X509 CERTIFICATE----- 703 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 704 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 705 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 706 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 707 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 708 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 709 -----END X509 CERTIFICATE----- 711 Figure 16: Non-standard 'X509' Certificate Example 713 -----BEGIN X.509 CERTIFICATE----- 714 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 715 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 716 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 717 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 718 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 719 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 720 -----END X.509 CERTIFICATE----- 722 Figure 17: Non-standard 'X.509' Certificate Example 724 -----BEGIN NEW CERTIFICATE REQUEST----- 725 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 726 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 727 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 728 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 729 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 730 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 731 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 732 dEQc8B8jAcnuOrfU 733 -----END NEW CERTIFICATE REQUEST----- 735 Figure 18: Non-standard 'NEW' PKCS #10 Example 737 -----BEGIN CERTIFICATE CHAIN----- 738 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 739 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 740 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 741 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 742 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 743 -----END CERTIFICATE CHAIN----- 745 Figure 19: Non-standard 'CERTIFICATE CHAIN' Example 747 Appendix B. DER Expectations 749 This appendix is informative. Consult the respective standards for 750 the normative rules. 752 DER is a restricted profile of BER [X.690]; thus all DER encodings of 753 data values are BER encodings, but just one of the BER encodings is 754 the DER encoding for a data value. Canonical encoding matters when 755 performing cryptographic operations; additionally, canonical encoding 756 has certain efficiency advantages for parsers. There are three 757 principal reasons to encode with DER: 759 1. A digital signature is (supposed to be) computed over the DER 760 encoding of the semantic content, so providing anything other 761 than the DER encoding is senseless. (In practice, an implementer 762 might choose to have an implementation parse and digest the data 763 as-is, but this practice amounts to guesswork.) 765 2. In practice, cryptographic hashes are computed over the DER 766 encoding for identification. 768 3. In practice, the content is small. DER always encodes data 769 values in definite length form (where the length is stated at the 770 beginning of the encoding); thus, a parser can anticipate memory 771 or resource usage up-front. 773 Figure 20 matches the structures in this document with the particular 774 reasons for DER encoding: 776 Sec. Label Reasons 777 ----+----------------------+------- 778 5 CERTIFICATE 1 2 ~3 779 6 X509 CRL 1 780 7 CERTIFICATE REQUEST 1 ~3 781 8 PKCS7 * 782 9 CMS * 783 10 PRIVATE KEY 3 784 11 ENCRYPTED PRIVATE KEY 3 785 12 ATTRIBUTE CERTIFICATE 1 ~3 786 13 PUBLIC KEY 2 3 788 *Cryptographic Message Syntax is designed for content of any length; 789 indefinite length encoding enables one-pass processing (streaming) 790 when generating the encoding. Only certain parts, namely signed and 791 authenticated attributes, need to be DER encoded. 792 ~Although not always "small", these encoded structures should not be 793 particularly "large" (e.g., more than 16 kilobytes). The parser 794 ought to be informed of large things up-front in any event, which is 795 yet another reason to DER encode these things in the first place. 797 Figure 20: Guide for DER Encoding 799 Authors' Addresses 801 Simon Josefsson 802 SJD AB 803 Johan Olof Wallins Vaeg 13 804 Solna 171 64 805 SE 807 Email: simon@josefsson.org 808 URI: http://josefsson.org/ 810 Sean Leonard 811 Penango, Inc. 812 5900 Wilshire Boulevard 813 21st Floor 814 Los Angeles, CA 90036 815 USA 817 Email: dev+ietf@seantek.com 818 URI: http://www.penango.com/