idnits 2.17.1 draft-josefsson-pkix-textual-09.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 13, 2014) is 3419 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: June 16, 2015 Penango, Inc. 6 December 13, 2014 8 Textual Encodings of PKIX, PKCS, and CMS Structures 9 draft-josefsson-pkix-textual-09 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 is intended to articulate the de-facto rules that existing 19 implementations operate by, and to give recommendations that will 20 promote interoperability. 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 June 16, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 5. Textual Encoding of Certificates . . . . . . . . . . . . . . 7 61 5.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 7 62 5.2. Explanatory Text . . . . . . . . . . . . . . . . . . . . 8 63 5.3. File Extension . . . . . . . . . . . . . . . . . . . . . 8 64 6. Textual Encoding of Certificate Revocation Lists . . . . . . 8 65 7. Textual Encoding of PKCS #10 Certification Request Syntax . . 9 66 8. Textual Encoding of PKCS #7 Cryptographic Message Syntax . . 10 67 9. Textual Encoding of Cryptographic Message Syntax . . . . . . 10 68 10. Textual Encoding of PKCS #8 Private Key Info, and One 69 Asymmetric Key . . . . . . . . . . . . . . . . . . . . . . . 11 70 11. Textual Encoding of PKCS #8 Encrypted Private Key Info . . . 11 71 12. Textual Encoding of Attribute Certificates . . . . . . . . . 11 72 13. Textual Encoding of Subject Public Key Info . . . . . . . . . 12 73 14. Security Considerations . . . . . . . . . . . . . . . . . . . 12 74 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 75 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 76 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 17.1. Normative References . . . . . . . . . . . . . . . . . . 13 78 17.2. Informative References . . . . . . . . . . . . . . . . . 14 79 Appendix A. Non-Conforming Examples . . . . . . . . . . . . . . 14 80 Appendix B. DER Expectations . . . . . . . . . . . . . . . . . . 16 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 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 Although other formats exist that use the encodings (or something 110 like them) described in this document, the included formats share a 111 common property: algorithm agility. "Algorithm agility" means that 112 different algorithms to achieve the same purposes--such as content 113 encryption or integrity protection--can be used in different 114 instances of the same format because the instance data identifies the 115 algorithms and associated parameters. Weakness in an algorithm does 116 not destroy the utility of the format. 118 A disadvantage of a binary data format is that it cannot be 119 interchanged in textual transports, such as e-mail or text documents. 120 One advantage with text-based encodings is that they are easy to 121 modify using common text editors; for example, a user may concatenate 122 several certificates to form a certificate chain with copy-and-paste 123 operations. 125 The tradition within the RFC series can be traced back to PEM 126 [RFC1421], based on a proposal by M. Rose in Message Encapsulation 127 [RFC0934]. Originally called "PEM encapsulation mechanism", 128 "encapsulated PEM message", or (arguably) "PEM printable encoding", 129 today the format is sometimes referred to as "PEM encoding". 130 Variations include OpenPGP ASCII Armor [RFC2015] and OpenSSH Key File 131 Format [RFC4716]. 133 For reasons that basically boil down to non-coordination or 134 inattention, many PKIX, PKCS, and CMS libraries implement a text- 135 based encoding that is similar to--but not identical with--PEM 136 encoding. This document specifies the _textual encoding_ format, 137 articulates the de-facto rules that most implementations operate by, 138 and provides recommendations that will promote interoperability going 139 forward. This document also provides common nomenclature for syntax 140 elements, reflecting the evolution of this de-facto standard format. 141 Peter Gutmann's X.509 Style Guide [X.509SG] contains a section 142 "base64 Encoding" that describes the formats and contains suggestions 143 similar to what is in this document. 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in RFC 148 2119 [RFC2119]. 150 2. General Considerations 152 Textual encoding begins with a line starting with "-----BEGIN " and 153 ends with a line starting with "-----END ". Between these lines, or 154 "encapsulation boundaries", are base64-encoded data according to 155 Section 4 of [RFC4648]. Data before the "-----BEGIN " and after the 156 "-----END " encapsulation boundaries are permitted and parsers MUST 157 NOT malfunction when processing such data. Furthermore, parsers MUST 158 ignore whitespace and other non-base64 characters and MUST handle 159 different newline conventions. 161 The type of data encoded is labeled depending on the type label in 162 the "-----BEGIN " line (pre-encapsulation boundary). For example, 163 the line may be "-----BEGIN CERTIFICATE-----" to indicate that the 164 content is a PKIX certificate (see further below). Generators MUST 165 put the same label on the "-----END " line (post-encapsulation 166 boundary) as the corresponding "-----BEGIN " line. Parsers MAY 167 disregard the label on the "-----END " line instead of signaling an 168 error if there is a label mismatch. There is exactly one space 169 character (SP) separating the "BEGIN" or "END" from the label. There 170 are exactly five hyphen-minus (or dash) characters ("-") on both ends 171 of the encapsulation 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. 179 Consistent with algorithm agility, the labels described in this 180 document are not specific to any particular cryptographic algorithm. 182 Unlike legacy PEM encoding [RFC1421], OpenPGP ASCII armor, and the 183 OpenSSH key file format, textual encoding does *not* define or permit 184 attributes to be encoded alongside the PKIX or CMS data. Whitespace 185 MAY appear between the pre-encapsulation boundary and the base64, but 186 generators SHOULD NOT emit such whitespace. 188 Files MAY contain multiple textual encoding instances. This is used, 189 for example, when a file contains several certificates. Whether the 190 instances are ordered or unordered depends on the context. 192 Generators MUST wrap the base64 encoded lines so that each line 193 consists of exactly 64 characters except for the final line which 194 will encode the remainder of the data (within the 64 character line 195 boundary). Parsers MAY handle other line sizes. These requirements 196 are consistent with PEM [RFC1421]. 198 3. ABNF 200 The ABNF [RFC5234] of the textual encoding is: 202 pkixmsg = preeb 203 *eolWSP 204 base64text 205 posteb 207 preeb = "-----BEGIN " label "-----" eol 209 posteb = "-----END " label "-----" eol 211 base64char = ALPHA / DIGIT / "+" / "/" 213 base64pad = "=" 215 base64line = 1*base64char eol 217 base64finl = *base64char (base64pad eol base64pad / 218 *2base64pad) eol 219 ; ...AB= = is not good, but is valid 221 base64text = *base64line base64finl 222 ; we could also use from RFC 1421, which requires 223 ; 16 groups of 4 chars, which means exactly 64 chars per 224 ; line, except the final line, but this is more accurate 226 labelchar = %x21-2C / %x2E-%7E ; any printable character, 227 ; except hyphen 229 label = labelchar *(labelchar / labelchar "-" / SP) labelchar 231 eol = CRLF / CR / LF 233 eolWSP = WSP / CR / LF ; compare with LWSP 235 Figure 1: ABNF 237 pkixmsgstrict = preeb 238 strictbase64text 239 posteb 241 strictbase64finl = *15(4base64char) (4base64char / 3base64char 242 base64pad / 2base64char 2base64pad) eol 244 base64fullline = 64base64char eol 246 strictbase64text = *base64fullline strictbase64finl 248 Figure 2: ABNF (Strict) 250 New implementations SHOULD emit the strict format (Figure 2) 251 specified above. 253 4. Guide 255 For convenience, these figures summarize the structures, encodings, 256 and references in the following sections: 258 Sec. Label ASN.1 Type Reference Module 259 ----+----------------------+-----------------------+---------+---------- 260 5 CERTIFICATE Certificate [RFC5280] id-pkix1-e 261 6 X509 CRL CertificateList [RFC5280] id-pkix1-e 262 7 CERTIFICATE REQUEST CertificationRequest [RFC2986] id-pkcs10 263 8 PKCS7 ContentInfo [RFC2315] id-pkcs7* 264 9 CMS ContentInfo [RFC5652] id-cms2004 265 10 PRIVATE KEY PrivateKeyInfo ::= [RFC5208] id-pkcs8 266 OneAsymmetricKey [RFC5958] id-aKPV1 267 11 ENCRYPTED PRIVATE KEY EncryptedPrivateKeyInfo [RFC5958] id-aKPV1 268 12 ATTRIBUTE CERTIFICATE AttributeCertificate [RFC5755] id-acv2 269 13 PUBLIC KEY SubjectPublicKeyInfo [RFC5280] id-pkix1-e 271 Figure 3: Convenience Guide 273 ----------------------------------------------------------------------- 274 id-pkixmod OBJECT IDENTIFIER ::= {iso(1) identified-organization(3) 275 dod(6) internet(1) security(5) mechanisms(5) pkix(7) mod(0)} 276 id-pkix1-e OBJECT IDENTIFIER ::= {id-pkixmod pkix1-explicit(18)} 277 id-acv2 OBJECT IDENTIFIER ::= {id-pkixmod mod-attribute-cert-v2(61)} 278 id-pkcs OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 279 rsadsi(113549) pkcs(1)} 280 id-pkcs10 OBJECT IDENTIFIER ::= {id-pkcs 10 modules(1) pkcs-10(1)} 281 id-pkcs7 OBJECT IDENTIFIER ::= {id-pkcs 7 modules(0) pkcs-7(1)} 282 id-pkcs8 OBJECT IDENTIFIER ::= {id-pkcs 8 modules(1) pkcs-8(1)} 283 id-sm-mod OBJECT IDENTIFIER ::= {id-pkcs 9 smime(16) modules(0)} 284 id-aKPV1 OBJECT IDENTIFIER ::= {id-sm-mod mod-asymmetricKeyPkgV1(50)} 285 id-cms2004 OBJECT IDENTIFIER ::= {id-sm-mod cms-2004(24)} 287 *This OID does not actually appear in PKCS #7 v1.5 [RFC2315]. It was 288 defined in the ASN.1 module to PKCS #7 v1.6 [P7v1.6], and has been 289 carried forward through PKCS #12 [RFC7292]. 291 Figure 4: ASN.1 Module Object Identifier Value Assignments 293 5. Textual Encoding of Certificates 295 5.1. Encoding 297 Public-key certificates are encoded using the "CERTIFICATE" label. 298 The encoded data MUST be a BER (DER strongly preferred) encoded ASN.1 299 "Certificate" structure as described in section 4 of [RFC5280]. 301 -----BEGIN CERTIFICATE----- 302 MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G 303 A1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2VydGlmaWNhdGUgYXV0aG9y 304 aXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdudVRMUyBjZXJ0aWZpY2F0 305 ZSBhdXRob3JpdHkwHhcNMTEwNTIzMjAzODIxWhcNMTIxMjIyMDc0MTUxWjB9MQsw 306 CQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2Vy 307 dGlmaWNhdGUgYXV0aG9yaXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdu 308 dVRMUyBjZXJ0aWZpY2F0ZSBhdXRob3JpdHkwWTATBgcqhkjOPQIBBggqhkjOPQMB 309 BwNCAARS2I0jiuNn14Y2sSALCX3IybqiIJUvxUpj+oNfzngvj/Niyv2394BWnW4X 310 uQ4RTEiywK87WRcWMGgJB5kX/t2no0MwQTAPBgNVHRMBAf8EBTADAQH/MA8GA1Ud 311 DwEB/wQFAwMHBgAwHQYDVR0OBBYEFPC0gf6YEr+1KLlkQAPLzB9mTigDMAoGCCqG 312 SM49BAMCA0gAMEUCIDGuwD1KPyG+hRf88MeyMQcqOFZD0TbVleF+UsAGQ4enAiEA 313 l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= 314 -----END CERTIFICATE----- 316 Figure 5: Certificate Example 318 Historically the label "X509 CERTIFICATE" and also less commonly 319 "X.509 CERTIFICATE" have been used. Generators conforming to this 320 document MUST generate "CERTIFICATE" labels and MUST NOT generate 321 "X509 CERTIFICATE" or "X.509 CERTIFICATE" labels. Parsers are NOT 322 RECOMMENDED to treat "X509 CERTIFICATE" or "X.509 CERTIFICATE" as 323 equivalent to "CERTIFICATE", but a valid exception may be for 324 backwards compatibility (potentially together with a warning). 326 5.2. Explanatory Text 328 Many tools are known to emit explanatory text before the BEGIN and 329 after the END lines for PKIX certificates, more than any other type. 330 If emitted, such text SHOULD be related to the certificate, such as 331 providing a textual representation of key data elements in the 332 certificate. 334 Subject: CN=Atlantis 335 Issuer: CN=Atlantis 336 Validity: from 7/9/2012 3:10:38 AM UTC to 7/9/2013 3:10:37 AM UTC 337 -----BEGIN CERTIFICATE----- 338 MIIBmTCCAUegAwIBAgIBKjAJBgUrDgMCHQUAMBMxETAPBgNVBAMTCEF0bGFudGlz 339 MB4XDTEyMDcwOTAzMTAzOFoXDTEzMDcwOTAzMTAzN1owEzERMA8GA1UEAxMIQXRs 340 YW50aXMwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAu+BXo+miabDIHHx+yquqzqNh 341 Ryn/XtkJIIHVcYtHvIX+S1x5ErgMoHehycpoxbErZmVR4GCq1S2diNmRFZCRtQID 342 AQABo4GJMIGGMAwGA1UdEwEB/wQCMAAwIAYDVR0EAQH/BBYwFDAOMAwGCisGAQQB 343 gjcCARUDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDAzA1BgNVHQEE 344 LjAsgBA0jOnSSuIHYmnVryHAdywMoRUwEzERMA8GA1UEAxMIQXRsYW50aXOCASow 345 CQYFKw4DAh0FAANBAKi6HRBaNEL5R0n56nvfclQNaXiDT174uf+lojzA4lhVInc0 346 ILwpnZ1izL4MlI9eCSHhVQBHEp2uQdXJB+d5Byg= 347 -----END CERTIFICATE----- 349 Figure 6: Certificate Example with Explanatory Text 351 5.3. File Extension 353 Although textual encodings of PKIX structures can occur anywhere, 354 many tools are known to offer an option to output this encoding when 355 serializing PKIX structures. To promote interoperability and to 356 separate DER encodings from textual encodings, the extension ".crt" 357 SHOULD be used for the textual encoding of a certificate. 358 Implementations should be aware that in spite of this recommendation, 359 many tools still default to encode certificates in this textual 360 encoding with the extension ".cer". 362 6. Textual Encoding of Certificate Revocation Lists 364 Certificate Revocation Lists (CRLs) are encoded using the "X509 CRL" 365 label. The encoded data MUST be a BER (DER strongly preferred) 366 encoded ASN.1 "CertificateList" structure as described in Section 5 367 of [RFC5280]. 369 -----BEGIN X509 CRL----- 370 MIIB9DCCAV8CAQEwCwYJKoZIhvcNAQEFMIIBCDEXMBUGA1UEChMOVmVyaVNpZ24s 371 IEluYy4xHzAdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdvcmsxRjBEBgNVBAsT 372 PXd3dy52ZXJpc2lnbi5jb20vcmVwb3NpdG9yeS9SUEEgSW5jb3JwLiBieSBSZWYu 373 LExJQUIuTFREKGMpOTgxHjAcBgNVBAsTFVBlcnNvbmEgTm90IFZhbGlkYXRlZDEm 374 MCQGA1UECxMdRGlnaXRhbCBJRCBDbGFzcyAxIC0gTmV0c2NhcGUxGDAWBgNVBAMU 375 D1NpbW9uIEpvc2Vmc3NvbjEiMCAGCSqGSIb3DQEJARYTc2ltb25Aam9zZWZzc29u 376 Lm9yZxcNMDYxMjI3MDgwMjM0WhcNMDcwMjA3MDgwMjM1WjAjMCECEC4QNwPfRoWd 377 elUNpllhhTgXDTA2MTIyNzA4MDIzNFowCwYJKoZIhvcNAQEFA4GBAD0zX+J2hkcc 378 Nbrq1Dn5IKL8nXLgPGcHv1I/le1MNo9t1ohGQxB5HnFUkRPAY82fR6Epor4aHgVy 379 b+5y+neKN9Kn2mPF4iiun+a4o26CjJ0pArojCL1p8T0yyi9Xxvyc/ezaZ98HiIyP 380 c3DGMNR+oUmSjKZ0jIhAYmeLxaPHfQwR 381 -----END X509 CRL----- 383 Figure 7: CRL Example 385 Historically the label "CRL" has rarely been used. Today it is not 386 common and many popular tools do not understand the label. 387 Therefore, this document standardizes "X509 CRL" in order to promote 388 interoperability and backwards-compatibility. Generators conforming 389 to this document MUST generate "X509 CRL" labels and MUST NOT 390 generate "CRL" labels. Parsers SHOULD NOT treat "CRL" as equivalent 391 to "X509 CRL". 393 7. Textual Encoding of PKCS #10 Certification Request Syntax 395 PKCS #10 Certification Requests are encoded using the "CERTIFICATE 396 REQUEST" label. The encoded data MUST be a BER (DER strongly 397 preferred) encoded ASN.1 "CertificationRequest" structure as 398 described in [RFC2986]. 400 -----BEGIN CERTIFICATE REQUEST----- 401 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 402 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 403 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 404 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 405 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 406 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 407 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 408 dEQc8B8jAcnuOrfU 409 -----END CERTIFICATE REQUEST----- 411 Figure 8: PKCS #10 Example 413 The label "NEW CERTIFICATE REQUEST" is also in wide use. Generators 414 conforming to this document MUST generate "CERTIFICATE REQUEST" 415 labels. Parsers MAY treat "NEW CERTIFICATE REQUEST" as equivalent to 416 "CERTIFICATE REQUEST". 418 8. Textual Encoding of PKCS #7 Cryptographic Message Syntax 420 PKCS #7 Cryptographic Message Syntax structures are encoded using the 421 "PKCS7" label. The encoded data MUST be a BER encoded ASN.1 422 "ContentInfo" structure as described in [RFC2315]. 424 -----BEGIN PKCS7----- 425 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 426 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 427 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 428 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 429 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 430 -----END PKCS7----- 432 Figure 9: PKCS #7 Example 434 The label "CERTIFICATE CHAIN" has been in use to denote a 435 degenerative PKCS #7 structure that contains only a list of 436 certificates. Several modern tools do not support this label. 437 Generators MUST NOT generate the "CERTIFICATE CHAIN" label. Parsers 438 SHOULD NOT treat "CERTIFICATE CHAIN" as equivalent to "PKCS7". 440 PKCS #7 is an old standard that has long been superseded by CMS. 441 Implementations SHOULD NOT generate PKCS #7 when CMS is an 442 alternative. 444 9. Textual Encoding of Cryptographic Message Syntax 446 Cryptographic Message Syntax structures are encoded using the "CMS" 447 label. The encoded data MUST be a BER encoded ASN.1 "ContentInfo" 448 structure as described in [RFC5652]. 450 -----BEGIN CMS----- 451 MIGDBgsqhkiG9w0BCRABCaB0MHICAQAwDQYLKoZIhvcNAQkQAwgwXgYJKoZIhvcN 452 AQcBoFEET3icc87PK0nNK9ENqSxItVIoSa0o0S/ISczMs1ZIzkgsKk4tsQ0N1nUM 453 dvb05OXi5XLPLEtViMwvLVLwSE0sKlFIVHAqSk3MBkkBAJv0Fx0= 454 -----END CMS----- 456 Figure 10: CMS Example 458 CMS is the IETF successor to PKCS #7. Section 1.1.1 of [RFC5652] 459 describes the changes since PKCS #7 v1.5. Implementations SHOULD 460 generate CMS when it is an alternative, promoting interoperability 461 and forwards-compatibility. 463 10. Textual Encoding of PKCS #8 Private Key Info, and One Asymmetric 464 Key 466 Unencrypted PKCS #8 Private Key Information Syntax structures 467 (PrivateKeyInfo), renamed to Asymmetric Key Packages 468 (OneAsymmetricKey), are encoded using the "PRIVATE KEY" label. The 469 encoded data MUST be a BER (DER preferred) encoded ASN.1 470 "PrivateKeyInfo" structure as described in PKCS #8, or a 471 "OneAsymmetricKey" structure as described in [RFC5958]. The two are 472 semantically identical, and can be distinguished by version number. 474 -----BEGIN PRIVATE KEY----- 475 MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf 476 jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK 477 H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ 478 -----END PRIVATE KEY----- 480 Figure 11: PKCS #8 PrivateKeyInfo (OneAsymmetricKey) Example 482 11. Textual Encoding of PKCS #8 Encrypted Private Key Info 484 Encrypted PKCS #8 Private Key Information Syntax structures 485 (EncryptedPrivateKeyInfo), called the same in [RFC5958], are encoded 486 using the "ENCRYPTED PRIVATE KEY" label. The encoded data MUST be a 487 BER (DER preferred) encoded ASN.1 "EncryptedPrivateKeyInfo" structure 488 as described in PKCS #8 and [RFC5958]. 490 -----BEGIN ENCRYPTED PRIVATE KEY----- 491 MIHNMEAGCSqGSIb3DQEFDTAzMBsGCSqGSIb3DQEFDDAOBAghhICA6T/51QICCAAw 492 FAYIKoZIhvcNAwcECBCxDgvI59i9BIGIY3CAqlMNBgaSI5QiiWVNJ3IpfLnEiEsW 493 Z0JIoHyRmKK/+cr9QPLnzxImm0TR9s4JrG3CilzTWvb0jIvbG3hu0zyFPraoMkap 494 8eRzWsIvC5SVel+CSjoS2mVS87cyjlD+txrmrXOVYDE+eTgMLbrLmsWh3QkCTRtF 495 QC7k0NNzUHTV9yGDwfqMbw== 496 -----END ENCRYPTED PRIVATE KEY----- 498 Figure 12: PKCS #8 EncryptedPrivateKeyInfo Example 500 12. Textual Encoding of Attribute Certificates 502 Attribute certificates are encoded using the "ATTRIBUTE CERTIFICATE" 503 label. The encoded data MUST be a BER (DER strongly preferred) 504 encoded ASN.1 "AttributeCertificate" structure as described in 505 [RFC5755]. 507 -----BEGIN ATTRIBUTE CERTIFICATE----- 508 MIICKzCCAZQCAQEwgZeggZQwgYmkgYYwgYMxCzAJBgNVBAYTAlVTMREwDwYDVQQI 509 DAhOZXcgWW9yazEUMBIGA1UEBwwLU3RvbnkgQnJvb2sxDzANBgNVBAoMBkNTRTU5 510 MjE6MDgGA1UEAwwxU2NvdHQgU3RhbGxlci9lbWFpbEFkZHJlc3M9c3N0YWxsZXJA 511 aWMuc3VueXNiLmVkdQIGARWrgUUSoIGMMIGJpIGGMIGDMQswCQYDVQQGEwJVUzER 512 MA8GA1UECAwITmV3IFlvcmsxFDASBgNVBAcMC1N0b255IEJyb29rMQ8wDQYDVQQK 513 DAZDU0U1OTIxOjA4BgNVBAMMMVNjb3R0IFN0YWxsZXIvZW1haWxBZGRyZXNzPXNz 514 dGFsbGVyQGljLnN1bnlzYi5lZHUwDQYJKoZIhvcNAQEFBQACBgEVq4FFSjAiGA8z 515 OTA3MDIwMTA1MDAwMFoYDzM5MTEwMTMxMDUwMDAwWjArMCkGA1UYSDEiMCCGHmh0 516 dHA6Ly9pZGVyYXNobi5vcmcvaW5kZXguaHRtbDANBgkqhkiG9w0BAQUFAAOBgQAV 517 M9axFPXXozEFcer06bj9MCBBCQLtAM7ZXcZjcxyva7xCBDmtZXPYUluHf5OcWPJz 518 5XPus/xS9wBgtlM3fldIKNyNO8RsMp6Ocx+PGlICc7zpZiGmCYLl64lAEGPO/bsw 519 Smluak1aZIttePeTAHeJJs8izNJ5aR3Wcd3A5gLztQ== 520 -----END ATTRIBUTE CERTIFICATE----- 522 Figure 13: Attribute Certificate Example 524 13. Textual Encoding of Subject Public Key Info 526 Public keys are encoded using the "PUBLIC KEY" label. The encoded 527 data MUST be a BER (DER preferred) encoded ASN.1 528 "SubjectPublicKeyInfo" structure as described in Section 4.1.2.7 of 529 [RFC5280]. 531 -----BEGIN PUBLIC KEY----- 532 MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEn1LlwLN/KBYQRVH6HfIMTzfEqJOVztLe 533 kLchp2hi78cCaMY81FBlYs8J9l7krc+M4aBeCGYFjba+hiXttJWPL7ydlE+5UG4U 534 Nkn3Eos8EiZByi9DVsyfy9eejh+8AXgp 535 -----END PUBLIC KEY----- 537 Figure 14: Subject Public Key Info Example 539 14. Security Considerations 541 Data in this format often originates from untrusted sources, thus 542 parsers must be prepared to handle unexpected data without causing 543 security vulnerabilities. 545 Implementers building implementations that rely on canonical 546 representation or the ability to fingerprint a particular data object 547 need to understand that this Internet-Draft does not define canonical 548 encodings. The first ambiguity is introduced by permitting the text- 549 encoded representation instead of the binary BER or DER encodings, 550 but further ambiguities arise when multiple labels are treated as 551 similar. Variations of whitespace and non-base64 alphabetic 552 characters can create further ambiguities. Data encoding ambiguities 553 also create opportunities for side channels. If canonical encodings 554 are desired, the encoded structure must be decoded and processed into 555 a canonical form (namely, DER encoding). 557 15. IANA Considerations 559 This document implies no IANA Considerations. 561 16. Acknowledgements 563 Peter Gutmann suggested to document labels for Attribute Certificates 564 and PKCS #7 messages, and to add examples for the non-standard 565 variants. Dr. Stephen Henson suggested distinguishing when BER 566 versus DER are appropriate or necessary. 568 17. References 570 17.1. Normative References 572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 573 Requirement Levels", BCP 14, RFC 2119, March 1997. 575 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 576 Version 1.5", RFC 2315, March 1998. 578 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 579 Request Syntax Specification Version 1.7", RFC 2986, 580 November 2000. 582 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 583 Encodings", RFC 4648, October 2006. 585 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 586 Housley, R., and W. Polk, "Internet X.509 Public Key 587 Infrastructure Certificate and Certificate Revocation List 588 (CRL) Profile", RFC 5280, May 2008. 590 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 591 Specifications: ABNF", STD 68, RFC 5234, January 2008. 593 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 594 RFC 5652, September 2009. 596 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 597 Attribute Certificate Profile for Authorization", RFC 598 5755, January 2010. 600 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August 601 2010. 603 [X.690] International Telecommunications Union, "Information 604 Technology - ASN.1 encoding rules: Specification of Basic 605 Encoding Rules (BER), Canonical Encoding Rules (CER) and 606 Distinguished Encoding Rules (DER)", ITU-T Recommendation 607 X.690, ISO/IEC 8825-1:2008, November 2008. 609 17.2. Informative References 611 [RFC0934] Rose, M. and E. Stefferud, "Proposed standard for message 612 encapsulation", RFC 934, January 1985. 614 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 615 Mail: Part I: Message Encryption and Authentication 616 Procedures", RFC 1421, February 1993. 618 [RFC2015] Elkins, M., "MIME Security with Pretty Good Privacy 619 (PGP)", RFC 2015, October 1996. 621 [RFC4716] Galbraith, J. and R. Thayer, "The Secure Shell (SSH) 622 Public Key File Format", RFC 4716, November 2006. 624 [RFC5208] Kaliski, B., "Public-Key Cryptography Standards (PKCS) #8: 625 Private-Key Information Syntax Specification Version 1.2", 626 RFC 5208, May 2008. 628 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 629 M. Scott, "PKCS #12: Personal Information Exchange Syntax 630 v1.1", RFC 7292, July 2014. 632 [P7v1.6] Kaliski, B. and K. Kingdon, "Extensions and Revisions to 633 PKCS #7 (Version 1.6 Bulletin)", May 1997, 634 . 638 [X.509SG] Gutmann, P., "X.509 Style Guide", October 2000, 639 . 642 Appendix A. Non-Conforming Examples 644 This section contains examples for the non-recommended label variants 645 described earlier in this document. As discussed earlier, supporting 646 these are not required and sometimes discouraged. Still, they can be 647 useful for interoperability testing and for easy reference. 649 -----BEGIN X509 CERTIFICATE----- 650 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 651 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 652 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 653 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 654 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 655 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 656 -----END X509 CERTIFICATE----- 658 Figure 15: Non-standard 'X509' Certificate Example 660 -----BEGIN X.509 CERTIFICATE----- 661 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 662 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 663 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 664 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 665 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 666 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 667 -----END X.509 CERTIFICATE----- 669 Figure 16: Non-standard 'X.509' Certificate Example 671 -----BEGIN NEW CERTIFICATE REQUEST----- 672 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 673 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 674 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 675 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 676 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 677 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 678 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 679 dEQc8B8jAcnuOrfU 680 -----END NEW CERTIFICATE REQUEST----- 682 Figure 17: Non-standard 'NEW' PKCS #10 Example 684 -----BEGIN CERTIFICATE CHAIN----- 685 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 686 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 687 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 688 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 689 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 690 -----END CERTIFICATE CHAIN----- 692 Figure 18: Non-standard 'CERTIFICATE CHAIN' Example 694 Appendix B. DER Expectations 696 This appendix is informative. Consult the respective standards for 697 the normative rules. 699 DER is a restricted profile of BER [X.690]; thus all DER encodings of 700 data values are BER encodings, but just one of the BER encodings is 701 the DER encoding for a data value. Canonical encoding matters when 702 performing cryptographic operations; additionally, canonical encoding 703 has certain efficiency advantages for parsers. There are three 704 principal reasons to do encode with DER: 706 1. A digital signature is (supposed to be) computed over the DER 707 encoding of the semantic content, so providing anything other 708 than the DER encoding is senseless. (In practice, an implementer 709 might choose to have an implementation parse and digest the data 710 as-is, but this practice amounts to guesswork.) 712 2. In practice, cryptographic hashes are computed over the DER 713 encoding for identification. 715 3. In practice, the content is small. DER always encodes data 716 values in definite length form (where the length is stated at the 717 beginning of the encoding); thus, a parser can anticipate memory 718 or resource usage up-front. 720 Figure 19 matches the structures in this document with the particular 721 reasons for DER encoding: 723 Sec. Label Reasons 724 ----+----------------------+------- 725 5 CERTIFICATE 1 2 ~3 726 6 X509 CRL 1 727 7 CERTIFICATE REQUEST 1 ~3 728 8 PKCS7 * 729 9 CMS * 730 10 PRIVATE KEY 3 731 11 ENCRYPTED PRIVATE KEY 3 732 12 ATTRIBUTE CERTIFICATE 1 ~3 733 13 PUBLIC KEY 2 3 735 *Cryptographic Message Syntax is designed for content of any length; 736 indefinite length encoding enables one-pass processing (streaming) 737 when generating the encoding. Only certain parts, namely signed and 738 authenticated attributes, need to be DER encoded. 739 ~Although not always "small", these encoded structures should not be 740 particularly "large" (e.g., more than 16 kilobytes). The parser 741 ought to be informed of large things up-front in any event, which is 742 yet another reason to DER encode these things in the first place. 744 Figure 19: Guide for DER Encoding 746 Authors' Addresses 748 Simon Josefsson 749 SJD AB 750 Johan Olof Wallins Vaeg 13 751 Solna 171 64 752 SE 754 Email: simon@josefsson.org 755 URI: http://josefsson.org/ 757 Sean Leonard 758 Penango, Inc. 759 5900 Wilshire Boulevard 760 21st Floor 761 Los Angeles, CA 90036 762 USA 764 Email: dev+ietf@seantek.com 765 URI: http://www.penango.com/