idnits 2.17.1 draft-josefsson-pkix-textual-06.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 (September 15, 2014) is 3503 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 normative reference: RFC 5208 (Obsoleted by RFC 5958) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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: March 19, 2015 Penango, Inc. 6 September 15, 2014 8 Text Encodings of PKIX and CMS Structures 9 draft-josefsson-pkix-textual-06 11 Abstract 13 This document describes and discusses the text encodings of the 14 Public-Key Infrastructure X.509 (PKIX), Public-Key Cryptography 15 Standards (PKCS), and Cryptographic Message Syntax (CMS), The text 16 encodings are well-known, are implemented by several applications and 17 libraries, and are widely deployed. This document is intended to 18 articulate the de-facto rules that existing implementations operate 19 by, and to give recommendations that will promote interoperability 20 going forward. 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 March 19, 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. Text Encoding of Certificates . . . . . . . . . . . . . . . . 7 61 5.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 7 62 5.2. Explanatory Text . . . . . . . . . . . . . . . . . . . . 8 63 5.3. File Extension . . . . . . . . . . . . . . . . . . . . . 9 64 6. Text Encoding of Certificate Revocation Lists . . . . . . . . 9 65 7. Text Encoding of PKCS #10 Certification Request Syntax . . . 10 66 8. Text Encoding of PKCS #7 Cryptographic Message Syntax . . . . 11 67 9. Text Encoding of Cryptographic Message Syntax . . . . . . . . 11 68 10. Text Encoding of PKCS #8 Private Key Info, and One Asymmetric 69 Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 11. Text Encoding of PKCS #8 Encrypted Private Key Info . . . . . 12 71 12. Text Encoding of Attribute Certificates . . . . . . . . . . . 12 72 13. Text Encoding of Subject Public Key Info . . . . . . . . . . 13 73 14. Security Considerations . . . . . . . . . . . . . . . . . . . 13 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 . . . . . . . . . . . . . . 15 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 text 89 encodings of these 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 text encoding (or something 110 like it) 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 encodings is that they are easy to modify 121 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 and CMS libraries implement a text encoding 135 that is similar to--but not identical with--PEM encoding. This 136 document specifies the "PKIX text encoding" format, articulates the 137 de-facto rules that most implementations operate by, and provides 138 recommendations that will promote interoperability going forward. 139 This document also provides common nomenclature for syntax elements, 140 reflecting the evolution of this de-facto standard format. Peter 141 Gutmann's X.509 Style Guide [X.509SG] contains a section "base64 142 Encoding" that describes the formats and contains suggestions similar 143 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 PKIX text 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 [RFC4648] data. Data 155 before the "-----BEGIN " and after the "-----END " encapsulation 156 boundaries are permitted and MUST NOT cause parsers to malfunction. 157 Furthermore, parsers MUST ignore whitespace and other non-base64 158 characters and MUST handle different newline conventions. 160 The type of data encoded is labeled depending on the type label in 161 the "-----BEGIN " line (pre-encapsulation boundary). For example, 162 the line may be "-----BEGIN CERTIFICATE-----" to indicate that the 163 content is a PKIX certificate (see further below). Generators MUST 164 put the same label on the "-----END " line (post-encapsulation 165 boundary) as the corresponding "-----BEGIN " line. Parsers MAY 166 disregard the label on the "-----END " line instead of signaling an 167 error if there is a label mismatch. There is exactly one space 168 character (SP) separating the "BEGIN" or "END" from the label. There 169 are exactly five hyphen-minus (or dash) characters ("-") on both ends 170 of the encapsulation boundaries, no more, no less. 172 The label type implies that the encoded data follows the specified 173 syntax. Parsers MUST handle non-conforming data gracefully. 174 However, not all parsers or generators prior to this Internet-Draft 175 behave consistently. A conforming parser MAY interpret the contents 176 as another label type, but ought to be aware of the security 177 implications discussed in the Security Considerations section. 178 Consistent with algorithm agility, the labels described in this 179 document are not specific to any particular cryptographic algorithm. 181 Unlike legacy PEM encoding [RFC1421], OpenPGP ASCII armor, and the 182 OpenSSH key file format, PKIX text encoding does *not* define or 183 permit attributes to be encoded alongside the PKIX or CMS data. 184 Whitespace MAY appear between the pre-encapsulation boundary and the 185 base64, but generators SHOULD NOT emit such whitespace. 187 Files MAY contain multiple PKIX text encoding instances. This is 188 used, for example, when a file contains several certificates. 189 Whether the instances are ordered or unordered depends on the 190 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 of the PKIX text 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 This specification RECOMMENDS that new implementations emit the 251 strict format (Figure 2) specified above. 253 4. Guide 255 For convenience, this table summarizes the structures, encodings, and 256 references in the following sections: 258 Sec. Label ASN.1 Type Reference Module 259 ----+----------------------+-----------------------+---------+---------- 260 5 CERTIFICATE Certificate [RFC5280] id-pkix1-e 261 6 X.509 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 ASN.1 Module Object Identifier Value Assignments 272 ----------------------------------------------------------------------- 273 id-pkixmod OBJECT IDENTIFIER ::= {iso(1) identified-organization(3) 274 dod(6) internet(1) security(5) mechanisms(5) pkix(7) mod(0)} 275 id-pkix1-e OBJECT IDENTIFIER ::= {id-pkixmod pkix1-explicit(18)} 276 id-acv2 OBJECT IDENTIFIER ::= {id-pkixmod mod-attribute-cert-v2(61)} 277 id-pkcs OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 278 rsadsi(113549) pkcs(1)} 279 id-pkcs10 OBJECT IDENTIFIER ::= {id-pkcs 10 modules(1) pkcs-10(1)} 280 id-pkcs7 OBJECT IDENTIFIER ::= {id-pkcs 7 modules(0) pkcs-7(1)} 281 id-pkcs8 OBJECT IDENTIFIER ::= {id-pkcs 8 modules(1) pkcs-8(1)} 282 id-sm-mod OBJECT IDENTIFIER ::= {id-pkcs 9 smime(16) modules(0)} 283 id-aKPV1 OBJECT IDENTIFIER ::= {id-sm-mod mod-asymmetricKeyPkgV1(50)} 284 id-cms2004 OBJECT IDENTIFIER ::= {id-sm-mod cms-2004(24)} 286 *This OID does not actually appear in PKCS #7 v1.5 [RFC2315]. It was 287 defined in the ASN.1 module to PKCS #7 v1.6 [P7v1.6], and has been 288 carried forward through PKCS #12 [RFC7292]. 290 Figure 3: Convenience Guide 292 5. Text Encoding of Certificates 294 5.1. Encoding 296 Certificates are encoded using the "CERTIFICATE" label. The encoded 297 data MUST be a BER (DER strongly preferred) encoded ASN.1 298 "Certificate" structure as described in section 4 of [RFC5280]. 300 -----BEGIN CERTIFICATE----- 301 MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G 302 A1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2VydGlmaWNhdGUgYXV0aG9y 303 aXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdudVRMUyBjZXJ0aWZpY2F0 304 ZSBhdXRob3JpdHkwHhcNMTEwNTIzMjAzODIxWhcNMTIxMjIyMDc0MTUxWjB9MQsw 305 CQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2Vy 306 dGlmaWNhdGUgYXV0aG9yaXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdu 307 dVRMUyBjZXJ0aWZpY2F0ZSBhdXRob3JpdHkwWTATBgcqhkjOPQIBBggqhkjOPQMB 308 BwNCAARS2I0jiuNn14Y2sSALCX3IybqiIJUvxUpj+oNfzngvj/Niyv2394BWnW4X 309 uQ4RTEiywK87WRcWMGgJB5kX/t2no0MwQTAPBgNVHRMBAf8EBTADAQH/MA8GA1Ud 310 DwEB/wQFAwMHBgAwHQYDVR0OBBYEFPC0gf6YEr+1KLlkQAPLzB9mTigDMAoGCCqG 311 SM49BAMCA0gAMEUCIDGuwD1KPyG+hRf88MeyMQcqOFZD0TbVleF+UsAGQ4enAiEA 312 l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= 313 -----END CERTIFICATE----- 315 Figure 4: Certificate Example 317 Historically the label "X509 CERTIFICATE" and also less commonly 318 "X.509 CERTIFICATE" have been used. Generators conforming to this 319 document MUST generate "CERTIFICATE" labels and MUST NOT generate 320 "X509 CERTIFICATE" or "X.509 CERTIFICATE" labels. Parsers are NOT 321 RECOMMENDED to treat "X509 CERTIFICATE" or "X.509 CERTIFICATE" as 322 equivalent to "CERTIFICATE", but a valid exception may be for 323 backwards compatibility (potentially together with a warning). 325 5.2. Explanatory Text 327 Many tools are known to emit explanatory text before the BEGIN and 328 after the END lines for PKIX certificates, more than any other type. 329 If emitted, such text SHOULD be related to the certificate, such as 330 providing a textual representation of key data elements in the 331 certificate. 333 Subject: CN=Atlantis 334 Issuer: CN=Atlantis 335 Validity: from 7/9/2012 3:10:38 AM UTC to 7/9/2013 3:10:37 AM UTC 336 -----BEGIN CERTIFICATE----- 337 MIIBmTCCAUegAwIBAgIBKjAJBgUrDgMCHQUAMBMxETAPBgNVBAMTCEF0bGFudGlz 338 MB4XDTEyMDcwOTAzMTAzOFoXDTEzMDcwOTAzMTAzN1owEzERMA8GA1UEAxMIQXRs 339 YW50aXMwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAu+BXo+miabDIHHx+yquqzqNh 340 Ryn/XtkJIIHVcYtHvIX+S1x5ErgMoHehycpoxbErZmVR4GCq1S2diNmRFZCRtQID 341 AQABo4GJMIGGMAwGA1UdEwEB/wQCMAAwIAYDVR0EAQH/BBYwFDAOMAwGCisGAQQB 342 gjcCARUDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDAzA1BgNVHQEE 343 LjAsgBA0jOnSSuIHYmnVryHAdywMoRUwEzERMA8GA1UEAxMIQXRsYW50aXOCASow 344 CQYFKw4DAh0FAANBAKi6HRBaNEL5R0n56nvfclQNaXiDT174uf+lojzA4lhVInc0 345 ILwpnZ1izL4MlI9eCSHhVQBHEp2uQdXJB+d5Byg= 346 -----END CERTIFICATE----- 348 Figure 5: Certificate Example with Explanatory Text 350 5.3. File Extension 352 Although text encodings of PKIX structures can occur anywhere, many 353 tools are known to offer an option to encode PKIX structures in this 354 text encoding. To promote interoperability and to separate DER 355 encodings from text encodings, This Internet-Draft RECOMMENDS that 356 the extension ".crt" be used for this text encoding. Implementations 357 should be aware that in spite of this recommendation, many tools 358 still default to encode certificates in this text encoding with the 359 extension ".cer". 361 6. Text Encoding of Certificate Revocation Lists 363 Certificate Revocation Lists (CRLs) are encoded using the "X509 CRL" 364 label. The encoded data MUST be a BER (DER strongly preferred) 365 encoded ASN.1 "CertificateList" structure as described in Section 5 366 of [RFC5280]. 368 -----BEGIN X509 CRL----- 369 MIIB9DCCAV8CAQEwCwYJKoZIhvcNAQEFMIIBCDEXMBUGA1UEChMOVmVyaVNpZ24s 370 IEluYy4xHzAdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdvcmsxRjBEBgNVBAsT 371 PXd3dy52ZXJpc2lnbi5jb20vcmVwb3NpdG9yeS9SUEEgSW5jb3JwLiBieSBSZWYu 372 LExJQUIuTFREKGMpOTgxHjAcBgNVBAsTFVBlcnNvbmEgTm90IFZhbGlkYXRlZDEm 373 MCQGA1UECxMdRGlnaXRhbCBJRCBDbGFzcyAxIC0gTmV0c2NhcGUxGDAWBgNVBAMU 374 D1NpbW9uIEpvc2Vmc3NvbjEiMCAGCSqGSIb3DQEJARYTc2ltb25Aam9zZWZzc29u 375 Lm9yZxcNMDYxMjI3MDgwMjM0WhcNMDcwMjA3MDgwMjM1WjAjMCECEC4QNwPfRoWd 376 elUNpllhhTgXDTA2MTIyNzA4MDIzNFowCwYJKoZIhvcNAQEFA4GBAD0zX+J2hkcc 377 Nbrq1Dn5IKL8nXLgPGcHv1I/le1MNo9t1ohGQxB5HnFUkRPAY82fR6Epor4aHgVy 378 b+5y+neKN9Kn2mPF4iiun+a4o26CjJ0pArojCL1p8T0yyi9Xxvyc/ezaZ98HiIyP 379 c3DGMNR+oUmSjKZ0jIhAYmeLxaPHfQwR 380 -----END X509 CRL----- 382 Figure 6: CRL Example 384 Historically the label "CRL" has rarely been used. Today it is not 385 common and many popular tools do not understand the label. 386 Therefore, this document standardizes "X509 CRL" in order to promote 387 interoperability and backwards-compatibility. Generators conforming 388 to this document MUST generate "X509 CRL" labels and MUST NOT 389 generate "CRL" labels. Parsers are NOT RECOMMENDED to treat "CRL" as 390 equivalent to "X509 CRL". 392 7. Text Encoding of PKCS #10 Certification Request Syntax 394 PKCS #10 Certification Requests are encoded using the 395 "CERTIFICATE REQUEST" label. The encoded data MUST be a BER (DER 396 strongly preferred) encoded ASN.1 "CertificationRequest" structure as 397 described in [RFC2986]. 399 -----BEGIN CERTIFICATE REQUEST----- 400 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 401 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 402 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 403 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 404 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 405 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 406 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 407 dEQc8B8jAcnuOrfU 408 -----END CERTIFICATE REQUEST----- 410 Figure 7: PKCS #10 Example 412 The label "NEW CERTIFICATE REQUEST" is also in wide use. Generators 413 conforming to this document MUST generate "CERTIFICATE REQUEST" 414 labels. Parsers MAY treat "NEW CERTIFICATE REQUEST" as equivalent to 415 "CERTIFICATE REQUEST". 417 8. Text Encoding of PKCS #7 Cryptographic Message Syntax 419 PKCS #7 Cryptographic Message Syntax structures are encoded using the 420 "PKCS7" label. The encoded data MUST be a BER encoded ASN.1 421 "ContentInfo" structure as described in [RFC2315]. 423 -----BEGIN PKCS7----- 424 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 425 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 426 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 427 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 428 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 429 -----END PKCS7----- 431 Figure 8: PKCS #7 Example 433 The label "CERTIFICATE CHAIN" has been in use to denote a 434 degenerative PKCS #7 structure that contains only a list of 435 certificates. Several modern tools do not support this label. 436 Generators MUST NOT generate the "CERTIFICATE CHAIN" label. Parsers 437 are NOT RECOMMENDED to treat "CERTIFICATE CHAIN" as equivalent to 438 "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. Text 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 9: 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. Text Encoding of PKCS #8 Private Key Info, and One Asymmetric Key 465 Unencrypted PKCS #8 Private Key Information Syntax structures 466 (PrivateKeyInfo), renamed to Asymmetric Key Packages 467 (OneAsymmetricKey), are encoded using the "PRIVATE KEY" label. The 468 encoded data MUST be a BER (DER preferred) encoded ASN.1 469 "PrivateKeyInfo" structure as described in PKCS #8, or a 470 "OneAsymmetricKey" structure as described in [RFC5958]. The two are 471 semantically identical, and can be distinguished by version number. 473 -----BEGIN PRIVATE KEY----- 474 MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf 475 jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK 476 H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ 477 -----END PRIVATE KEY----- 479 Figure 10: PKCS #8 PrivateKeyInfo Example 481 11. Text Encoding of PKCS #8 Encrypted Private Key Info 483 Encrypted PKCS #8 Private Key Information Syntax structures 484 (EncryptedPrivateKeyInfo), called the same in [RFC5958], are encoded 485 using the "ENCRYPTED PRIVATE KEY" label. The encoded data MUST be a 486 BER (DER preferred) encoded ASN.1 "EncryptedPrivateKeyInfo" structure 487 as described in PKCS #8 and [RFC5958]. 489 -----BEGIN ENCRYPTED PRIVATE KEY----- 490 MIHNMEAGCSqGSIb3DQEFDTAzMBsGCSqGSIb3DQEFDDAOBAghhICA6T/51QICCAAw 491 FAYIKoZIhvcNAwcECBCxDgvI59i9BIGIY3CAqlMNBgaSI5QiiWVNJ3IpfLnEiEsW 492 Z0JIoHyRmKK/+cr9QPLnzxImm0TR9s4JrG3CilzTWvb0jIvbG3hu0zyFPraoMkap 493 8eRzWsIvC5SVel+CSjoS2mVS87cyjlD+txrmrXOVYDE+eTgMLbrLmsWh3QkCTRtF 494 QC7k0NNzUHTV9yGDwfqMbw== 495 -----END ENCRYPTED PRIVATE KEY----- 497 Figure 11: PKCS #8 EncryptedPrivateKeyInfo Example 499 12. Text Encoding of Attribute Certificates 501 Attribute certificates are encoded using the "ATTRIBUTE CERTIFICATE" 502 label. The encoded data MUST be a BER (DER strongly preferred) 503 encoded ASN.1 "AttributeCertificate" structure as described in 504 [RFC5755]. 506 -----BEGIN ATTRIBUTE CERTIFICATE----- 507 MIICKzCCAZQCAQEwgZeggZQwgYmkgYYwgYMxCzAJBgNVBAYTAlVTMREwDwYDVQQI 508 DAhOZXcgWW9yazEUMBIGA1UEBwwLU3RvbnkgQnJvb2sxDzANBgNVBAoMBkNTRTU5 509 MjE6MDgGA1UEAwwxU2NvdHQgU3RhbGxlci9lbWFpbEFkZHJlc3M9c3N0YWxsZXJA 510 aWMuc3VueXNiLmVkdQIGARWrgUUSoIGMMIGJpIGGMIGDMQswCQYDVQQGEwJVUzER 511 MA8GA1UECAwITmV3IFlvcmsxFDASBgNVBAcMC1N0b255IEJyb29rMQ8wDQYDVQQK 512 DAZDU0U1OTIxOjA4BgNVBAMMMVNjb3R0IFN0YWxsZXIvZW1haWxBZGRyZXNzPXNz 513 dGFsbGVyQGljLnN1bnlzYi5lZHUwDQYJKoZIhvcNAQEFBQACBgEVq4FFSjAiGA8z 514 OTA3MDIwMTA1MDAwMFoYDzM5MTEwMTMxMDUwMDAwWjArMCkGA1UYSDEiMCCGHmh0 515 dHA6Ly9pZGVyYXNobi5vcmcvaW5kZXguaHRtbDANBgkqhkiG9w0BAQUFAAOBgQAV 516 M9axFPXXozEFcer06bj9MCBBCQLtAM7ZXcZjcxyva7xCBDmtZXPYUluHf5OcWPJz 517 5XPus/xS9wBgtlM3fldIKNyNO8RsMp6Ocx+PGlICc7zpZiGmCYLl64lAEGPO/bsw 518 Smluak1aZIttePeTAHeJJs8izNJ5aR3Wcd3A5gLztQ== 519 -----END ATTRIBUTE CERTIFICATE----- 521 Figure 12: Attribute Certificate Example 523 13. Text Encoding of Subject Public Key Info 525 Public keys are encoded using the "PUBLIC KEY" label. The encoded 526 data MUST be a BER (DER preferred) encoded ASN.1 527 "SubjectPublicKeyInfo" structure as described in Section 4.1.2.7 of 528 [RFC5280]. 530 -----BEGIN PUBLIC KEY----- 531 MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEn1LlwLN/KBYQRVH6HfIMTzfEqJOVztLe 532 kLchp2hi78cCaMY81FBlYs8J9l7krc+M4aBeCGYFjba+hiXttJWPL7ydlE+5UG4U 533 Nkn3Eos8EiZByi9DVsyfy9eejh+8AXgp 534 -----END PUBLIC KEY----- 536 Figure 13: Subject Public Key Info Example 538 14. Security Considerations 540 Data in this format often originates from untrusted sources, thus 541 parsers must be prepared to handle unexpected data without causing 542 security vulnerabilities. 544 Implementers building implementations that rely on canonical 545 representation or the ability to fingerprint a particular data object 546 need to understand that this Internet-Draft does not define canonical 547 encodings. The first ambiguity is introduced by permitting the text- 548 encoded representation instead of the binary BER or DER encodings, 549 but further ambiguities arise when multiple labels are treated as 550 similar. Variations of whitespace and non-base64 alphabetic 551 characters can create further ambiguities. Data encoding ambiguities 552 also create opportunities for side channels. If canonical encodings 553 are desired, the encoded structure must be decoded and processed into 554 a canonical form (namely, DER encoding). 556 15. IANA Considerations 558 This document implies no IANA Considerations. 560 16. Acknowledgements 562 Peter Gutmann suggested to document labels for Attribute Certificates 563 and PKCS #7 messages, and to add examples for the non-standard 564 variants. Dr. Stephen Henson suggested distinguishing when BER 565 versus DER are appropriate or necessary. 567 17. References 569 17.1. Normative References 571 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 572 Requirement Levels", BCP 14, RFC 2119, March 1997. 574 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 575 Version 1.5", RFC 2315, March 1998. 577 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 578 Request Syntax Specification Version 1.7", RFC 2986, 579 November 2000. 581 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 582 Encodings", RFC 4648, October 2006. 584 [RFC5208] Kaliski, B., "Public-Key Cryptography Standards (PKCS) #8: 585 Private-Key Information Syntax Specification Version 1.2", 586 RFC 5208, May 2008. 588 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 589 Housley, R., and W. Polk, "Internet X.509 Public Key 590 Infrastructure Certificate and Certificate Revocation List 591 (CRL) Profile", RFC 5280, May 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 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 625 M. Scott, "PKCS #12: Personal Information Exchange Syntax 626 v1.1", RFC 7292, July 2014. 628 [P7v1.6] Kaliski, B. and K. Kingdon, "Extensions and Revisions to 629 PKCS #7 (Version 1.6 Bulletin)", May 1997, 630 . 634 [X.509SG] Gutmann, P., "X.509 Style Guide", October 2000, 635 . 638 Appendix A. Non-Conforming Examples 640 This section contains examples for the non-recommended label variants 641 described earlier in this document. As discussed earlier, supporting 642 these are not required and sometimes discouraged. Still, they can be 643 useful for interoperability testing and for easy reference. 645 -----BEGIN X509 CERTIFICATE----- 646 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 647 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 648 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 649 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 650 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 651 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 652 -----END X509 CERTIFICATE----- 654 Figure 14: Non-standard 'X509' Certificate Example 656 -----BEGIN X.509 CERTIFICATE----- 657 MIIBHDCBxaADAgECAgIcxzAJBgcqhkjOPQQBMBAxDjAMBgNVBAMUBVBLSVghMB4X 658 DTE0MDkxNDA2MTU1MFoXDTI0MDkxNDA2MTU1MFowEDEOMAwGA1UEAxQFUEtJWCEw 659 WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwoQSr863QrR0PoRIYQ96H7WykDePH 660 Wa0eVAE24bth43wCNc+U5aZ761dhGhSSJkVWRgVH5+prLIr+nzfIq+X4oxAwDjAM 661 BgNVHRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIfMdKS5F63lMnWVhi7uaKJzKCs 662 NnY/OKgBex6MIEAv2AIhAI2GdvfL+mGvhyPZE+JxRxWChmggb5/9eHdUcmW/jkOH 663 -----END X.509 CERTIFICATE----- 665 Figure 15: Non-standard 'X.509' Certificate Example 667 -----BEGIN NEW CERTIFICATE REQUEST----- 668 MIIBWDCCAQcCAQAwTjELMAkGA1UEBhMCU0UxJzAlBgNVBAoTHlNpbW9uIEpvc2Vm 669 c3NvbiBEYXRha29uc3VsdCBBQjEWMBQGA1UEAxMNam9zZWZzc29uLm9yZzBOMBAG 670 ByqGSM49AgEGBSuBBAAhAzoABLLPSkuXY0l66MbxVJ3Mot5FCFuqQfn6dTs+9/CM 671 EOlSwVej77tj56kj9R/j9Q+LfysX8FO9I5p3oGIwYAYJKoZIhvcNAQkOMVMwUTAY 672 BgNVHREEETAPgg1qb3NlZnNzb24ub3JnMAwGA1UdEwEB/wQCMAAwDwYDVR0PAQH/ 673 BAUDAwegADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDATAKBggqhkjOPQQDAgM/ADA8 674 AhxBvfhxPFfbBbsE1NoFmCUczOFApEuQVUw3ZP69AhwWXk3dgSUsKnuwL5g/ftAY 675 dEQc8B8jAcnuOrfU 676 -----END NEW CERTIFICATE REQUEST----- 678 Figure 16: Non-standard 'NEW' PKCS #10 Example 680 -----BEGIN CERTIFICATE CHAIN----- 681 MIHjBgsqhkiG9w0BCRABF6CB0zCB0AIBADFho18CAQCgGwYJKoZIhvcNAQUMMA4E 682 CLfrI6dr0gUWAgITiDAjBgsqhkiG9w0BCRADCTAUBggqhkiG9w0DBwQIZpECRWtz 683 u5kEGDCjerXY8odQ7EEEromZJvAurk/j81IrozBSBgkqhkiG9w0BBwEwMwYLKoZI 684 hvcNAQkQAw8wJDAUBggqhkiG9w0DBwQI0tCBcU09nxEwDAYIKwYBBQUIAQIFAIAQ 685 OsYGYUFdAH0RNc1p4VbKEAQUM2Xo8PMHBoYdqEcsbTodlCFAZH4= 686 -----END CERTIFICATE CHAIN----- 688 Figure 17: Non-standard 'CERTIFICATE CHAIN' Example 690 Appendix B. DER Expectations 692 This appendix is informative. Consult the respective standards for 693 the normative rules. 695 DER is a restricted profile of BER [X.690]; thus all DER encodings of 696 data values are BER encodings, but just one of the BER encodings is 697 the DER encoding for a data value. Canonical encoding matters when 698 performing cryptographic operations; additionally, canonical encoding 699 has certain efficiency advantages for parsers. There are three 700 principal reasons to do encode with DER: 702 1. A digital signature is (supposed to be) computed over the DER 703 encoding of the semantic content, so providing anything other 704 than the DER encoding is senseless. (In practice, an implementer 705 might choose to have an implementation parse and digest the data 706 as-is, but this practice amounts to guesswork.) 708 2. In practice, cryptographic hashes are computed over the DER 709 encoding for identification. 711 3. In practice, the content is small. DER always encodes data 712 values in definite length form (where the length is stated at the 713 beginning of the encoding); thus, a parser can anticipate memory 714 or resource usage up-front. 716 Figure 18 matches the structures in this document with the particular 717 reasons for DER encoding: 719 Sec. Label Reasons 720 ----+----------------------+------- 721 5 CERTIFICATE 1 2 ~3 722 6 X.509 CRL 1 723 7 CERTIFICATE REQUEST 1 ~3 724 8 PKCS7 * 725 9 CMS * 726 10 PRIVATE KEY 3 727 11 ENCRYPTED PRIVATE KEY 3 728 12 ATTRIBUTE CERTIFICATE 1 ~3 729 13 PUBLIC KEY 2 3 731 *Cryptographic Message Syntax is designed for content of any length; 732 indefinite length encoding enables one-pass processing (streaming) 733 when generating the encoding. Only certain parts, namely signed and 734 authenticated attributes, need to be DER encoded. 735 ~Although not always "small", these encoded structures should not be 736 particularly "large" (e.g., more than 16 kilobytes). The parser 737 ought to be informed of large things up-front in any event, which is 738 yet another reason to DER encode these things in the first place. 740 Figure 18: Guide for DER Encoding 742 Authors' Addresses 744 Simon Josefsson 745 SJD AB 746 Johan Olof Wallins Vaeg 13 747 Solna 171 64 748 SE 750 Email: simon@josefsson.org 751 URI: http://josefsson.org/ 753 Sean Leonard 754 Penango, Inc. 755 5900 Wilshire Boulevard 756 21st Floor 757 Los Angeles, CA 90036 758 USA 760 Email: dev+ietf@seantek.com 761 URI: http://www.penango.com/