idnits 2.17.1 draft-seantek-certspec-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 : ---------------------------------------------------------------------------- == There are 16 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 30, 2016) is 2732 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'A-Z' is mentioned on line 540, but not defined == Unused Reference: 'RFC2119' is defined on line 1231, but no explicit reference was found in the text == Outdated reference: A later version (-08) exists of draft-seantek-abnf-more-core-rules-06 == Outdated reference: A later version (-08) exists of draft-seantek-ldap-pkcs9-05 ** Downref: Normative reference to an Informational draft: draft-seantek-ldap-pkcs9 (ref. 'I-D.seantek-ldap-pkcs9') == Outdated reference: A later version (-03) exists of draft-seantek-unicode-in-abnf-00 ** Downref: Normative reference to an Experimental draft: draft-seantek-unicode-in-abnf (ref. 'I-D.seantek-unicode-in-abnf') -- Possible downref: Non-RFC (?) normative reference: ref. 'LDAPDESC' ** Obsolete normative reference: RFC 5750 (Obsoleted by RFC 8550) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Obsolete informational reference (is this intentional?): RFC 1738 (Obsoleted by RFC 4248, RFC 4266) -- Obsolete informational reference (is this intentional?): RFC 2253 (Obsoleted by RFC 4510, RFC 4514) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Leonard 3 Internet-Draft Penango, Inc. 4 Intended status: Standards Track October 30, 2016 5 Expires: May 3, 2017 7 Textual Specification for Certificates and Attributes 8 draft-seantek-certspec-10 10 Abstract 12 Digital certificates are used in many systems and protocols to 13 identify and authenticate parties. This document describes a string 14 format that identifies certificates, along with optional attributes. 15 This string format has been engineered to work without re-encoding in 16 a variety of protocol slots. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 3, 2017. 35 Copyright Notice 37 Copyright (c) 2016 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 54 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Motivation and Purpose . . . . . . . . . . . . . . . . . . . 4 56 2.1. Static Identification . . . . . . . . . . . . . . . . . . 4 57 2.2. Relationship with Other Specifications . . . . . . . . . 5 58 3. Basic Syntax and ABNF . . . . . . . . . . . . . . . . . . . . 5 59 4. certstring Syntax . . . . . . . . . . . . . . . . . . . . . . 5 60 5. certspec Syntax . . . . . . . . . . . . . . . . . . . . . . . 6 61 5.1. certspec Type and Value . . . . . . . . . . . . . . . . . 8 62 6. Standard Certificate Specifications . . . . . . . . . . . . . 8 63 6.1. Cryptographic Hash-Based Specifications . . . . . . . . . 8 64 6.2. Content-Based Specifications . . . . . . . . . . . . . . 9 65 6.3. Element-Based Specifications . . . . . . . . . . . . . . 10 66 6.4. Path-Based Specifications . . . . . . . . . . . . . . . . 11 67 6.5. Algorithm for Distinguishing ASN.1 PDUs . . . . . . . . . 14 68 7. Other Certificate Specifications . . . . . . . . . . . . . . 16 69 7.1. DBKEY (Reserved) . . . . . . . . . . . . . . . . . . . . 16 70 7.2. SELECT (Reserved) . . . . . . . . . . . . . . . . . . . . 16 71 8. Multiple certspecs (multispec) . . . . . . . . . . . . . . . 16 72 9. Attributes (pkcsattrs) . . . . . . . . . . . . . . . . . . . 17 73 9.1. ABNF . . . . . . . . . . . . . . . . . . . . . . . . . . 19 74 9.2. Mandatory Attribute Support . . . . . . . . . . . . . . . 20 75 9.3. Canonicalization . . . . . . . . . . . . . . . . . . . . 21 76 10. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . . 21 77 11. Guidelines for Extending certspec . . . . . . . . . . . . . . 22 78 12. Use of certspec in Systems . . . . . . . . . . . . . . . . . 23 79 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 80 14. Security Considerations . . . . . . . . . . . . . . . . . . . 25 81 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 82 15.1. Normative References . . . . . . . . . . . . . . . . . . 26 83 15.2. Informative References . . . . . . . . . . . . . . . . . 27 84 Appendix A. Mandatory Attribute Descriptors for Distinguished 85 Names . . . . . . . . . . . . . . . . . . . . . . . 29 86 Appendix B. Recommended Attribute Descriptors for issuersn 87 certspec . . . . . . . . . . . . . . . . . . . . . . 30 88 Appendix C. Suggested Algorithm for Distinguishing Textual Data 30 89 Appendix D. Binary Formats for Conveying Certificates with 90 Attributes . . . . . . . . . . . . . . . . . . . . . 31 91 D.1. PKCS #12 certs-only Profile . . . . . . . . . . . . . . . 31 92 D.2. CMS SafeContents contentType . . . . . . . . . . . . . . 33 93 D.3. SafeContents-to-PKCS#12 BER Adapter . . . . . . . . . . . 33 94 Appendix E. Textual Encoding of Attributes . . . . . . . . . . . 34 95 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 35 97 1. Introduction 99 Digital certificates [RFC5280] are used in many systems and protocols 100 to identify and authenticate parties. Security considerations 101 frequently require that the certificate must be identified with 102 certainty, because selecting the wrong certificate will lead to 103 validation errors (resulting in denial of service), or in improper 104 credential selection (resulting in unwanted disclosure or 105 substitution attacks). The goal of this document is to provide a 106 uniform syntax for identifying certificates with precision and speed 107 without re-encoding in a variety of protocol slots. 109 Using this syntax, any protocol or system that refers to a 110 certificate in a textual format can unambiguously identify that 111 certificate by value or reference. Implementations that parse these 112 strings can resolve them into actual certificates. Examples include: 114 SHA-1:3ea3f070773971539b9dbf1b98c54be3a4f0f3c8 115 ISSUERSN:cn=AcmeIssuingCompany,st=California,c=US;0134F1 116 BASE64:MIIBHDCBxaADAgECAgIAmTAJBgcqhkjOPQQBMBAxDjAMBgNVBAMT 117 BVNtYWxsMB4XDTEzMTEwNTE5MjUzM1oXDTE2MDgwMjE5MjUzM1ow 118 EDEOMAwGA1UEAxMFU21hbGwwWTATBgcqhkjOPQIBBggqhkjOPQMB 119 BwNCAAS2kwRQ1thNMBMUq5d/SFdFr1uDidntNjXQrc3D/QpzYWkE 120 WDsxeY8xcbl2m0TBO4TJ/2CevdoOX0OMIOaqJ/TNoxAwDjAMBgNV 121 HRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIgPyF8ok6h2NxMQ4uJ 122 OcGcXYcvZ1ua0kB+rIv0omHcfNECICKwpTp3LDIwhlHTQ/DulQDD 123 eYn+lnYQVc2Gm1WKAuxp 124 /etc/myserver.cer|friendlyName=fluffy the Tomcat 125 URI:https://certificates.example.com/acme/BAADF00D.cer 127 1.1. Requirements Language 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in RFC 2119. 133 1.2. Definitions 135 The term "certificate" means either a certificate containing a public 136 key [RFC5280] or an attribute certificate [RFC5755]. When a 137 certificate [RFC5280] alone is to be distinguished, this 138 specification may use the term "public key certificate". 140 The term "whitespace" means HT, VT, FF, LF, CR, and SP, when 141 referring to the ASCII range. An implementation SHOULD also consider 142 whitespace beyond the ASCII range, if the implementation supports it, 143 e.g., the characters that have the White_Space character property in 144 [UNICODE].) 145 The term "entity" means a MIME entity [RFC2045], namely, a fixed 146 sequence of octets (i.e., data) with an Internet media type and 147 optional parameters. 149 2. Motivation and Purpose 151 Although certificates [RFC5280] have diverse applications, there has 152 been no uniform way to refer to a certificate in text. De-facto 153 standards such as PEM [RFC1421] and PKIX text encoding [RFC7468] are 154 used to include whole certificates in textual formats, but this 155 practice is impractical for a variety of use cases. Certificates 156 that identify long public keys (e.g., 2048-bit RSA keys) and that 157 contain required and recommended PKIX extensions can easily exceed 158 many kilobytes in length. 160 The purpose of this document is to provide a uniform textual format 161 for identifying individual certificates, with human usability as a 162 design goal. Certificate specifications, or "certspecs", are not 163 designed or intended to provide a search tool or query language to 164 match multiple certificates. The goal is to replace data elements 165 that would otherwise have to include whole certificates, or that 166 employ proprietary reference schemes. For example, certspecs fit 167 easily into XML/SGML data, YAML, JSON, and config files and databases 168 (e.g., .properties, .ini, and Windows Registry) with minimal required 169 escaping. 171 To be usable by humans, certspecs are supposed to be amenable to 172 copy-and-paste operations. The structure of a certspec is also 173 supposed to be plainly visible so that someone glancing at a certspec 174 can ascertain the data types that it comprises. This specification 175 addresses the "speed" goal by incorporating identifiers that 176 implementations typically use as indexes to certificate databases. 177 For instance, many implementations index certificates by issuer and 178 serial number, or by SHA-1 hash, regardless of how collision 179 resistant those pieces of data are at present. 181 2.1. Static Identification 183 Identifying a specific certificate by reference or value allows 184 diverse applications to have a common syntax. For example, 185 applications can store certspecs as local or shared preferences, so 186 that users can edit them without resorting to application-specific 187 storage formats or relying on the availability of particular 188 protocols represented by URIs (such as http:, ldap: [RFC4516], file: 189 [RFC1738], or ni: schemes). When conveyed in protocol, a certspec 190 can identify a specific certificate to a client or server using text- 191 based formats such as YAML, XML, JSON, and others. The format 192 described in this document is intended to be readily reproducible by 193 users using common certificate processing tools, so that users can 194 easily create, recognize, compare, and reproduce them at a glance. 195 For example, the hash-based identifications use hexadecimal encoding 196 so that a user can easily compose or compare an URN with a simple 197 copy-and-paste operation. 199 2.2. Relationship with Other Specifications 201 Certspecs and their attendant elements are textual strings, and are 202 intended for use with textual protocols. Where possible, certspecs 203 are just identifiers from other protocols with minimal syntactic 204 sugar to distinguish one type of certspec from another. Several 205 certspec productions look like URIs, but are not. To distinguish 206 certspec syntax from URI syntax, this Internet-Draft capitalizes the 207 "introducer characters" of the various certspec types and does not 208 require that they be delimited with a colon, even though these 209 productions (mostly) are case-insensitive and (mostly) end with a 210 colon. OpenSSL's x509v3_config format inspired this aspect of the 211 syntax. 213 3. Basic Syntax and ABNF 215 The bulk of this document defines textual formats for interchange. 216 While textual strings in this document can be in any character 217 encoding, the delimiter characters in this document are drawn from 218 ASCII. Unicode [UNICODE] support at some level (e.g., in attribute 219 values that are in LDAP string form) is inevitable, but the general 220 premise is that an implementation can convert the production (or 221 appropriate parts of the production) to Unicode when it is needed. 222 The ABNF in this document is normative, and is drawn from [RFC5234], 223 [RFC7405], [I-D.seantek-abnf-more-core-rules], and 224 [I-D.seantek-unicode-in-abnf]. The ABNF reuses certain definitions 225 from [RFC4512] and [RFC4514], but does not formally reference those 226 rules due to notating Unicode characters beyond the ASCII range in a 227 more modern way. 229 4. certstring Syntax 231 A certificate string ("certstring") is a string with a single 232 certspec (see Section 5) or multiple certspecs (a "multispec", see 233 Section 8), followed by an optional set of attributes ("pkcsattrs", 234 see Section 9). A multispec is a discriminator for a single 235 certificate. In contrast, pkcsattrs are optional attributes 236 associated with a single certificate. These attributes do not 237 participate in selecting a certificate, but might be used to identify 238 other things, such as the token on which associated private keying 239 material resides. The string has the ABNF: 241 certstring = (certspec / multispec) [ "|" pkcsattrs ] 243 Figure 1: certstring ABNF 245 5. certspec Syntax 247 A certspec is a string that is intended to identify a single 248 certificate. A certspec has introducer characters followed by value 249 characters; these introducer characters MAY be part of the "value" of 250 the identifier. The ABNF is: 252 certspec = certspec-hash / certspec-content / certspec-el / 253 certspec-path 255 certspec-hash = "SHA-1" ":" 40HEXDIG / 256 "SHA-256" ":" 64HEXDIG / 257 "SHA-384" ":" 96HEXDIG / 258 "SHA-512" ":" 128HEXDIG 260 ; Proposal: Hash Function Textual Name registry hereby limited 261 ; to RFC 3986 scheme characters 263 certspec-content = ("HEX" / "BASE16") ":" 1*(2HEXDIG) / 264 "BASE64" ":" base64string 266 base64char = ALPHA / DIGIT / "+" / "/" 267 base64string = 1*(4base64char) 268 [ 3base64char "=" / 2base64char "==" ] 270 ; based on [RFC4512][RFC4514] 271 distinguishedName = [ relativeDistinguishedName 272 *( "," relativeDistinguishedName ) ] 273 relativeDistinguishedName = attributeTypeAndValue 274 *( "+" attributeTypeAndValue ) 275 attributeTypeAndValue = attributeType "=" attributeValue 276 attributeType = descr / numericoid 278 num = "0" / %x31-39 *DIGIT 279 descr = ALPHA *(ALPHA / DIGIT / "-") 280 numericoid = ("0" / "1" / "2") 1*("." num) 282 attributeValue = string / hexstring 283 string = [ ( leadchar / pair ) [ *( stringchar / pair ) 284 ( trailchar / pair ) ] ] 285 ; excl SP " # + , ; < > \ 286 leadchar = %x01-1F / %x21 / %x24-2A / %x2D-3A / 287 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 288 ; excl SP " + , ; < > \ 289 trailchar = %x01-1F / %x21 / %x23-2A / %x2D-3A / 290 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 291 ; excl " + , ; < > \ 292 stringchar = %x01-21 / %x23-2A / %x2D-3A / 293 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 295 pair = "\" (" " / %x22-23 / %x2B-2C / %x3B-3E / "\" / 2HEXDIG) 296 hexstring = "#" 2HEXDIG 298 certspec-el = "ISSUERSN" ":" distinguishedName ";" serialNumber / 299 "SKI" ":" 1*(2HEXDIG) 301 serialNumber = 1*(2HEXDIG) 303 certspec-path = certspec-uri / certspec-file / certspec-reg 305 ; from RFC3986; RFC 6570 306 ; superfluous: URI-reference = URI-reference@[RFC3986] 307 URI-Template = URI-Template@[RFC6570] 309 certspec-uri = "URI:" URI-Template 311 ; see POSIX, etc. 312 certspec-file = ("/" / "\" / [A-Z] ":" / 313 ("." / "..") ("/" / "\") / "~" / "%" / "$") 314 *filepathchar 316 ; BEYONDASCII is from draft-seantek-more-core-rules 317 filepathchar = %x01-29 / %x2B-3B / "=" / %x40-5B / 318 %x5D-7B / %x7D-7F / quoted-fpc / BEYONDASCII 320 quoted-fpc = "\" ("*" / "<" / ">" / "?" / "\" / "|") 322 ; TODO: validate Windows file path characters 324 certspec-reg = reg-hive 1*("\" reg-key) 325 ["\\" reg-value-name] 327 reg-hive = reg-local-hive / reg-remote-hive 328 reg-local-hive = "HKEY_LOCAL_MACHINE" / "HKEY_CURRENT_USER" / 329 "HKEY_CLASSES_ROOT" / "HKEY_USERS" / 330 "HKEY_CURRENT_CONFIG" / 331 "HKLM:" / "HKCU:" / "HKCR:" / 332 "HKU:" / "HKCC:" 333 ; TODO: better specify computer name; it could be a NETBIOS name...? 334 reg-remote-hive = "\\" reg-name@[RFC3986] "\" ("HKLM" / "HKU") ":" 336 ; escape < > |. Need to figure out if 7F is ok, also C0, C1, etc. 338 reg-key = 1*(%x20-3B / %x3D / %x3F-5B %x5D-7B / %x7D.7E / 339 "\<" / "\>" / "\|" / BEYONDASCII) 340 ; reg-value-name can be empty 341 reg-value-name = *(%x20-3B / %x3D / %x3F-7B / %x7D.7E / 342 "\<" / "\>" / "\|" / BEYONDASCII) 344 Figure 2: certspec ABNF 346 5.1. certspec Type and Value 348 Semantically, a certspec is comprised of its type and value. The 349 value is always provided, but the type is either explicitly declared, 350 or is inferred from the initial (introducer) characters in the type. 351 When types are explicitly provided, they are compared case- 352 insensitively. The certspec-value identifies the certificate 353 specification value. 355 Several certspecs use hexadecimal encodings of octets. Generally: if 356 the hex octets are malformed (whether in the source material, such as 357 the corresponding certificate element, or in the hex text), the 358 certspec is invalid. 360 6. Standard Certificate Specifications 362 Standard certificate specifications are intended for interchange as 363 user- and developer-friendly identifiers for individual certificates. 364 This section provides four cryptographic hash-based certspecs, two 365 content-based certspecs, two element-based certspecs, and three path- 366 based certspecs. 368 6.1. Cryptographic Hash-Based Specifications 370 A cryptographic hash or "fingerprint" of a certificate uniquely 371 identifies that certificate. For hash-based certspecs, the hash is 372 computed over the octets of the DER encoding of the certificate, 373 namely, the Certificate type in Section 4.1 of [RFC5280] and the 374 AttributeCertificate type in Section 4.1 of [RFC5755]. The certspec- 375 value is the hexadecimal encoding of the hash value octets. For 376 example, a 256-bit SHA-256 hash is represented by exactly 32 hex 377 octets, or 64 hex characters. The hexadecimal encoding is not case 378 sensitive. 380 A conforming generator SHALL emit only hexadecimal encoded data, 381 i.e., the characters A-F (case-insensitive) and 0-9. 383 A conforming parser SHALL accept value productions that contain the 384 following non-hex digits: whitespace, hyphen, and colon. A 385 conforming parser MAY accept values that contain other characters. 387 Conforming implementations to this Internet-Draft MUST process these 388 hash-based certspecs, unless security considerations dictate 389 otherwise. Acceptable reasons for refusing to process a certspec 390 include a) the local policy prohibits use of the hash, or b) the hash 391 has known cryptographic weaknesses, such as a preimage attacks, which 392 weaken the cryptographic uniqueness guarantees of the hash. 394 6.1.1. SHA-1 396 The introducer production is "SHA-1:". The hash is computed using 397 SHA-1 [SHS]. 399 6.1.2. SHA-256 401 The introducer production is "SHA-256:". The hash is computed using 402 SHA-256 [SHS]. 404 6.1.3. SHA-384 406 The introducer production is "SHA-384:". The hash is computed using 407 SHA-384 [SHS]. 409 6.1.4. SHA-512 411 The introducer production is "SHA-512:". The hash is computed using 412 SHA-512 [SHS]. 414 6.2. Content-Based Specifications 416 Content-based certspecs identify certificates by their constituent 417 octets. For small-to-medium certificates, identifying the 418 certificate by embedding it in the certspec will be computationally 419 efficient and resistant to denial-of-service attacks (by always being 420 available). A conforming implementation MUST implement base64 and 421 hex specs. 423 The octets of a certificate are the octets of the DER encoding of the 424 certificate, namely, the Certificate type in Section 4.1 of [RFC5280] 425 and the AttributeCertificate type in Section 4.1 of [RFC5755]. The 426 DER encoding includes tag and length octets, so it always starts with 427 30h (the tag for SEQUENCE) followed by any octet other than 80h (the 428 marker for indefinite length encoding). See also Section 6.5. 430 Because users may end up copying and pasting base64 or hex-encoded 431 certificates into certspecs, and because these certspecs will 432 routinely exceed 72 characters, a production might contain embedded 433 whitespace. A conforming generator SHALL emit no whitespace, or 434 SHALL emit a hanging indent, between semantically significant 435 characters. 437 6.2.1. BASE64 439 The introducer production is "BASE64:". The value production is the 440 BASE64 encoding of the certificate octets (Section 4 of [RFC4648]). 442 6.2.2. HEX and BASE16 444 The introducer production is "HEX:" or "BASE16:". Generators MUST 445 generate "HEX:"; parsers MUST accept "HEX:" and "BASE16:". The value 446 production is the hexadecimal encoding of the certificate octets. 448 6.3. Element-Based Specifications 450 A certificate may be identified by certain data elements contained 451 within it. The following certspecs reflect the traditional reliance 452 of PKIX [RFC5280] and CMS [RFC5652] on a certificate's issuer 453 distinguished name and serial number, or a certificate's subject key 454 identifier. 456 Note that distinguished names can contain "|" in attribute value 457 strings, but this production is unambiguous with the pkcsattrs 458 delimiter because distinguished names are always terminated by ";". 460 6.3.1. ISSUERSN: Issuer Name and Serial Number 462 The introducer production is "ISSUERSN:". 464 6.3.1.1. Issuer 466 The distinguishedName production encodes the certificate's issuer 467 distinguished name (DN) field in LDAP string format [RFC4514]. 468 [RFC4514] no longer separates relative distinguished names (RDNs) by 469 semicolons, as required by its predecessor, [RFC2253]. Accordingly, 470 ";" is used to separate the issuer's DN from the subject's serial 471 number. 473 6.3.1.2. Serial Number 475 The serialNumber production is the hexadecimal encoding the DER- 476 encoded contents octets of the CertificateSerialNumber (INTEGER, 477 i.e., not the type or length octets) as specified in Section 4.1.2.2 478 of [RFC5280]. 480 6.3.1.3. Conformance 482 A conforming implementation SHALL implement the ISSUERSN certspec. 483 An implementation MUST process serial numbers up to the same length 484 as required by Section 4.1.2.2 of [RFC5280] (20 octets), and MUST 485 process distinguished name strings as required by [RFC4514], 486 including the table of minimum AttributeType name strings that MUST 487 be recognized. Additionally, implementations MUST process attribute 488 descriptors specified in [RFC5280] (MUST or SHOULD), and [RFC5750] 489 (specifically: E, email, emailAddress). For reference, a complete 490 list of required attribute descriptors is provided in Appendix A. 491 Implementations are encouraged to recognize additional attribute 492 descriptors where possible. A sample list of such attribute 493 descriptors is provided in Appendix B. Conforming implementations 494 MUST be able to parse all distinguished name attribute types that are 495 encoded in OID dotted decimal form, as well as all distinguished name 496 attribute values that are encoded in "#" hexadecimal form. 498 6.3.2. ski: Subject Key Identifier 500 The introducer production is "SKI:". The value production is the 501 hexadecimal encoding of the certificate's subject key identifier, 502 which is recorded in the certificate's Subject Key Identifier 503 extension (Section 4.2.1.2 of [RFC5280]). The octets are the DER- 504 encoded contents octets of the SubjectKeyIdentifier (OCTET STRING) 505 extension value. For a certificate that lacks a subject key 506 identifier, an underlying implementation MAY operatively associate a 507 subject key identifier with the certificate. 509 A conforming generator SHALL emit only hexadecimal encoded data, 510 i.e., the characters A-F (case-insensitive) and 0-9. 512 A conforming parser SHALL accept value productions that contain the 513 following non-hex digits: whitespace (HT, VT, SP, FF, CR, LF), 514 hyphen, and colon. A conforming parser MAY accept values that 515 contain other characters. 517 6.4. Path-Based Specifications 519 A certificate may be identified by a path to data. A conforming 520 parser MUST recognize file path, Registry, and URI specs, although 521 conforming implementations merely MAY process them. 523 Two common themes among path-based certspecs are that they may refer 524 to weakly typed or untyped data, and they have a higher probability 525 of referring to data that contains multiple certificates. Therefore, 526 a greater degree of content-sniffing is required for interoperability 527 than the certspecs above. An implementation that implements these 528 path-based certspecs SHALL support the ASN.1 Certificate PDU when 529 public key certificates are being retrieved, and the ASN.1 530 AttributeCertificate PDU when attribute certificates are being 531 retrieved. Additionally, a conforming implementation SHALL support 532 the ASN.1 ContentInfo (PKCS #7/CMS SignedData) PDU. 534 Untyped binary data may be encoded in a [X.690] transfer syntax, 535 which may be BER, CER, or DER; for purposes of this section, these 536 are all called "BER-encoded". 538 6.4.1. File Path 540 File paths are identified by their introducer productions / \ [A-Z]: 541 ./ ../ .\ ..\ ~ % and $. The characters that follow MUST be valid 542 path characters for the system on which the files are being accessed. 543 Since the starting character sequences for file paths are fixed and 544 determinable, prefixing the file path with a type identifier is 545 (thought to be) unnecessary. 547 A relative file path begins with "." or "..", and is relative to a 548 "current directory". Determining an appropriate "current directory" 549 is outside the scope of this specification. 551 When the file is read, implementations MUST accept the following, 552 regardless of the filename, which SHOULD NOT be the conclusive 553 determinant of the type: 555 1. Typed data (reported only by a minority of file systems), which 556 is treated conclusively as the type 558 2. Data that is determined to be textual, which is analyzed 559 according to [RFC7468] 561 3. Data that is determined to be BER-encoded 563 The manner of determining whether data is textual or BER-encoded data 564 is not fixed by this specification, but see, e.g., Appendix C. 566 File paths may have unexpanded environment variables, such as 567 %USERNAME% or ${LOGNAME}; implementations MUST parse these 568 environment variable syntaxes, but merely MAY perform environment 569 variable substitution as environment, capability, and security 570 concerns dictate. 572 Note that Unix-oriented file paths can contain "|" in the production 573 "\|", but this production is unambiguous with the pkcsattrs 574 delimiter. Windows-oriented file paths cannot contain "|". 576 6.4.2. Registry 578 Certificates can be identified on Windows machines with Registry keys 579 and values. The introducer productions for local Registry entries 580 are "HKEY_LOCAL_MACHINE\", "HKEY_CURRENT_USER\", 581 "HKEY_CLASSES_ROOT\", "HKEY_USERS\", "HKEY_CURRENT_CONFIG\", 582 "HKLM:\", "HKCU:\", "HKCR:\", "HKU:\", and "HKCC:\". The introducer 583 productions for remote Registry entries are "\\", followed by a 584 computer name, followed by either "\HKLM:\" or "\HKU:\". 586 Registry key names include any printable character except backslash 587 "\"; each key includes what amounts to an associative array of 588 values, which are name/type/data tuples. A value name can include 589 any printable character, including "<", ">", and "|"; additionally, 590 every key has a default value, which has a zero-length name. This 591 layout presents a couple of parsing challenges. 593 A Registry production is comprised of a key path followed by a value. 594 The key path's key names are delimited by "\". In each key name, 595 "<", ">", and "|" SHALL be escaped with a preceding "\". The value 596 name is delimited from the key name with two backslashes "\\". "<", 597 ">", "|", and "\" in the value SHALL be escaped with a preceding "\". 598 The default value MAY be identified with or without the two final 599 backslashes. Unlike file paths, Registry productions do not 600 recognize or substitute unexpanded environment variables. 602 Registry values have a type and some data. When the type is REG_SZ 603 or REG_EXPAND_SZ, an implementation is to treat the text firstly as a 604 recursive certspec or multispec. If it is not a certspec or 605 multispec, then an implementation is to analyze the text according to 606 [RFC7468]. Text in REG_EXPAND_SZ is subject to environment variable 607 substitution. When the type is REG_BINARY, an implementation is to 608 determine if the data is BER-encoded, and if so, to analyze it for 609 supported ASN.1 PDUs. When the type is REG_LINK, an implementation 610 is to follow the symbolic link. 612 6.4.3. URI 614 The introducer production is "URI:". The value is a URI-Template 615 production [RFC6570], which is to produce a [RFC3986] conforming URI- 616 reference production. 618 In the context of URIs, a relative reference conforms to the 619 relative-ref production of [RFC3986] and the usage described in 620 Section 4.2 of [RFC3986]; it is relative to a "base URI". 621 Determining an appropriate "base URI" is outside the scope of this 622 specification. 624 When the URI is dereferenced, implementations MUST accept the 625 following, regardless of the path or query productions: 627 1. representations that are conclusively public key certificates or 628 attribute certificates, such as LDAP URIs [RFC4516] that point to 629 or contain userCertificate attributes (2.5.4.36, for public key 630 certificates) or attributeCertificate attributes (2.5.4.58, for 631 attribute certificates) 633 2. application/pkix-cert and application/pkix-attr-cert entities, 634 which are conclusively public key certificates or attribute 635 certificates, respectively 637 3. application/pkcs7-mime and application/cms entities, when the 638 body represents a ContentInfo/SignedData containing certificates 639 (regardless of the smime-type or encapsulatingContent parameters, 640 and regardless of whether or not the SignedData is in a 641 degenerate, certs-only format) 643 4. text/plain entities, which are analyzed according to [RFC7468] 645 5. Arbitrary data and application/octet-stream entities are treated 646 as untyped; they are are analyzed for textual or binary [X.690] 647 data 649 6. Arbitrary text, which is analyzed according to [RFC7468] 651 7. Arbitrary BER-encoded data, which is analyzed for supported ASN.1 652 PDUs 654 The URI certspec can include a fragment identifier. Implementations 655 MUST parse fragment identifiers, but merely MAY perform "secondary 656 resource" isolation and processing as environment, capability, and 657 security concerns dictate. 659 The URI certspec can be a URI Template [RFC6570]. Implementations 660 MUST parse URI templates, but merely MAY expand them in accordance 661 with [RFC6570] as environment, capability, and security concerns 662 dictate. 664 Note that URI templates can contain "|" in the production "{|".."}", 665 but this production is unambiguous with the pkcsattrs delimiter. 667 6.5. Algorithm for Distinguishing ASN.1 PDUs 669 A certspec can identify a public key certificate ("PKC") or an 670 attribute certificate ("AC"). When the type of certificate is 671 specified unambiguously in the source data, an implementation SHALL 672 follow the specifier in the source data. However, of the certspecs 673 listed in this document, only a subset of URIs are capable of 674 unambiguous specification (e.g., via Internet media type designation 675 of application/pkix-cert or application/pkix-attr-cert). Most other 676 certspecs will return a blob of bytes or characters. Therefore, an 677 implementation needs to perform some content-sniffing to figure out 678 what the data represents. There are two (not entirely orthogonal) 679 decisions: is the data textual [RFC7468] or not, and does the data 680 represent a PKC or AC? (Note: The content-based certspecs BASE64 and 681 HEX always represent one certificate; the encodings MUST NOT encode a 682 textual blob or a PKCS #7/CMS PDU.) 684 This normative section addresses distinguishing PDU types when 685 applications encounter BER-encoded data that is not further typed. 686 An implementation MAY use any algorithm it chooses, as long as it 687 produces the same results. A suggested algorithm for distinguishing 688 textual data is in Appendix C; that algorithm is merely informative. 690 The algorithm for distinguishing ASN.1 PDUs is: 692 1. Ensure that the first octet is SEQUENCE 30h. 694 2. Ensure that the length covers the length of the data, minus the 695 tag and length octets. (If the length is indefinite, a check 696 that the end of the data has the end-of-contents octets would be 697 appropriate.) Extraneous data SHALL be considered erroneous. 699 3. If there are 2 elements -> confirm that the first element is 700 OBJECT IDENTIFIER 1.2.840.113549.1.7.2 and the second element is 701 explicitly tagged (APPLICATION 0, A0). Analyze the PDU as a 702 ContentInfo containing SignedData. 704 4. Otherwise, ensure that there are 3 elements, and that the first 705 element is a SEQUENCE 30h (either AttributeCertificateInfo or 706 TBSCertificate). 708 5. this SEQUENCE has: 6, 7, or 7+ elements 710 6. if 6 elements -> Analyze the PDU as a Certificate (public key 711 certificate) with version v1 (ABSENT). 713 7. if 7+ elements -> 715 1. look at version field (first element) 717 2. if INTEGER (UNIVERSAL 2) -> Analyze the PDU as an 718 AttributeCertificate (attribute certificate) 720 3. if explicitly tagged (APPLICATION 0, A0) and the contents are 721 INTEGER (UNIVERSAL 2) -> Analyze the PDU as a Certificate 722 (public key certificate). 724 7. Other Certificate Specifications 726 The additional certificate specifications in this section are 727 provided for applications to use as local identifiers that are 728 useful, intuitive, or supportive of legacy systems or overriding 729 design goals. These certspecs SHOULD NOT be used for interchange. 731 7.1. DBKEY (Reserved) 733 The introducer production is "DBKEY:". The DBKEY certspec is meant 734 for an opaque string that serves as the unique key to a certificate 735 in an implementation's certificate database. This document reserves 736 this introducer sequence for future use. 738 7.2. SELECT (Reserved) 740 The introducer production is "SELECT" (without a colon). The SELECT 741 certspec is meant for a valid SQL statement (suitably escaped) that 742 retrieves a row representing a certificate. This document reserves 743 this introducer sequence for future use. 745 8. Multiple certspecs (multispec) 747 A multispec is a string that contains multiple certspecs, each of 748 which is intended to identify the exact same certificate. If 749 multiple certificates match a single spec, a single certificate can 750 be returned by the multispec access operation, so long as the 751 intersection of certificates identified by all of the certspecs in 752 the multispec is one. The purpose of multispec is to provide 753 multiple access and verification methods. For example, a hash 754 algorithm may have known weaknesses, but may be the most efficient 755 way to identify a certificate (e.g., because it is the index method). 756 Providing additional certspecs (i.e., strong hash algorithms) would 757 increase the certainty that the correct certificate is accessed. 759 Another example is to provide two URIs for a certificate: one that 760 works inside an organizational firewall, and one that works outside 761 an organizational firewall. Conforming applications MAY ignore 762 individual certspec lookup failures (where the certspec fails to 763 return any certificate due to error conditions) as environment, 764 capability, and security concerns dictate. 766 As the certspecs above make use of almost all other characters in the 767 ASCII range, < and > have been chosen to delimit certspecs between 768 each other. (Whitespace can also appear between each < and > 769 delimited certspec.) The ABNF of multispec is: 771 multispec = 1*("<" certspec ">") 773 Figure 3: multispec ABNF 775 9. Attributes (pkcsattrs) 777 This specification defines a textual format for PKCS attributes. 778 This format is not limited to certificates: it can be used with other 779 PKCS-related data. The syntax is intended primarily to convey 780 certificate-related attributes found in PKCS #9 [RFC2985], PKCS #11 781 [PKCS11], PKCS #12 [RFC7292], and particular implementations of 782 cryptographic libraries. These attributes are syntactically 783 identical to, but semantically disjoint from, Directory (X.500/LDAP) 784 attributes. 786 When pkcsattrs is used with a certspec or multispec, the intent is to 787 associate arbitrary metadata with a certificate--metadata that is not 788 intrinsic to that certificate. For example, the additional 789 attributes may represent preferences. Attributes in this context are 790 semantically equivalent to PKCS #12 "bagAttributes", drawn from the 791 "PKCS12AttrSet" [RFC7292]. 793 pkcsattrs are delimited from a certspec or multispec production with 794 "|". Each pkcsattr SHALL have a corresponding ASN.1 definition. The 795 textual syntax of pkcsattrs is very similar to (in fact, a superset 796 of) [RFC4514]: the pkcsattrs production represents the PKCS 797 Attributes family of types, which are repeatedly defined in those 798 standards, and standards that derive from them, as 799 SET SIZE (1..MAX) OF Attribute. E.g., CMS (from PKCS #7) [RFC5652], 800 private keys (from PKCS #8) [RFC5958], and PKCS #12 [RFC7292]. 801 Attributes are semantically unordered. Multiple attributes are 802 separated with ",". 804 Each attribute has a single attrType (canonically defined as OBJECT 805 IDENTIFIER in [RFC5652]), and a SET OF attrValues. The attrType is 806 encoded as the string representation of AttributeType (that is, 807 either a registered short name (descriptor) [RFC4520], or the dotted- 808 decimal encoding, of the OBJECT IDENTIFIER [RFC4512]). 810 When an attribute has at least one value, the attrType is followed by 811 "=" and the encoding of the attrValues (empty strings are possible). 812 Multiple attrValues are separated by "+". When the attribute has no 813 values, the attrType MUST NOT be followed by "=". 815 An attrValue can have one of several encodings: 817 hex: The attrValue can always be represented by "#" followed by the 818 hexadecimal encoding of each of the octets of the BER encoding of 819 the attrValue, following paragraph 1 of Section 2.4 of [RFC4514]. 820 Implementations MUST support this encoding. 822 string: If the attrValue has a LDAP-specific string encoding, that 823 encoding can be used as the string representation of the value, 824 with characters suitably escaped according to paragraph 2 and 825 onward of Section 2.4 of [RFC4514]. Implementations SHOULD 826 support this encoding for attributes of interest to it. 828 XER: The attrValue can be represented by its BASIC-XER encoding 829 [X.693] (Clause 8). When in BASIC-XER encoding, the string MUST 830 be a complete XML fragment comprising one element, i.e., there 831 SHALL NOT be an XML prolog. XER encoding is self-delimiting 832 because it has balanced elements; this string always begins with 833 "<" and ends with ">". Processing is simplified compared to 834 arbitrary XML in that XML processing instructions, XML comments, 835 and CDATA sections are prohibited. Implementations MUST support 836 parsing through this encoding, but merely MAY support this 837 encoding (encoding and decoding between [X.690]) for attributes of 838 interest to it. 840 ASN.1 value: The attrValue can be represented by its ASN.1 value 841 notation [X.680], surrounded by exactly one space (SP) on each 842 end. The syntax is precisely defined in Figure 4 so that the 843 value itself never begins or ends with ASN.1 "white-space", 844 although "white-space" can occur within the value. ASN.1 value 845 notation requires a bit of finesse in that <"> can appear inside 846 to delimit "cstring" lexical items (see Clause 12.14 and Clause 41 847 of [X.680]). A "cstring" starts and ends with <">, and can 848 represent <"> internally with a pair of consecutive <">. 849 Therefore, <"> is balanced because it always occurs in multiples 850 of two. If the value is just a cstring, then the representation 851 will have exactly two <"> at the beginning, and two <"> at the 852 end, with evenly-balanced <"> pairs inside. Other values that are 853 not lists (enclosed with "{" and "}") do not have <"> occur within 854 them. Otherwise, the representation must have at least one "{" 855 "}" balanced pair at either end, hemming in <"> occurrences to 856 within the balanced pairs of "{" and "}". Implementations MUST 857 support parsing through this encoding, but merely MAY support this 858 encoding (encoding and decoding between [X.690]) for attributes of 859 interest to it. 861 Of the attrValue encodings listed above, only "hex" can reliably 862 transfer the underlying BER representation without an implementation 863 maintaining specific knowledge of every attribute. Therefore, "hex" 864 is RECOMMENDED for open interchange of pkcsattrs. The other 865 representations are really meant for human production and 866 consumption. 868 9.1. ABNF 870 The collective ABNF of pkcsattrs is: 872 pkcsattrs = pkcsattr ["," pkcsattrs] 873 pkcsattr = pkcsattrType ["=" pkcsattrValues] 874 pkcsattrType = descr / numericoid 875 pkcsattrValues = pkcsattrValue ["+" pkcsAttrValues] 876 pkcsattrValue = hexstring / string / 877 basic-xer-string / asn1-value-string 879 basic-xer-string = xer-element 881 ; limited by [X.680][X.693] 882 xer-Name = ALPHA *(ALPHA / DIGIT / "_" / "-" / ".") 884 ; limited by XML to these four chars 885 xW = *(HT / LF / CR / SP) 887 xer-element = xer-EmptyElemTag / xer-STag xer-content xer-ETag 889 xer-EmptyElemTag = "<" xer-Name xW "/>" 891 xer-STag = "<" xer-Name xW ">" 893 xer-content = *xer-CharData *((xer-element / xer-Reference) 894 *xer-CharData) 896 xer-ETag = "" 898 xer-CharData = HT / LF / CR / %x20-25 / %x27-3B / "=" / %x3F-D7FF / 899 %xE000-%xFFFD / %x10000-10FFFF 901 xer-Reference = xer-EntityRef / xer-CharRef 903 xer-EntityRef = "&" (%s"amp" / %s"lt" / %s"gt") ";" 905 xer-CharRef = "&#" (1*DIGIT / %s"x" 1*HEXDIG) ";" 907 ; TODO: may want another delimiter--think about it 908 ; uses num from above for non-negative integers 909 asn1-value-string = SP aValue aW 911 ; identifier, Clause 12.3 of [X.680] 912 aid = %x61-7A *(["-"] (ALPHA / DIGIT)) 913 ; "newline", Clause 12.1.6 of [X.680] 914 ; (NEL LS PS omitted) 915 aNL = %d10-13 916 ; single "white-space" (comment considered matching, 917 ; because delimits lexical items), Clause 12.1.6 of [X.680] 918 aS = %d9-13 / SP / NBSP / acomment 919 aW = *aS 921 acomment = "--" *(["-"] ( UWSP / %x21-2C / %x2E-7E / 922 UVCHARBEYONDASCII / PUACHAR ) ) 923 (aNL / "-" (aNL / "-")) 925 ; space in unicode: 85 A0 1680 2000-200A 202F 205F 3000 926 ; related not-unicode-White_Space-but-whitespace 927 ; 180E 200B-200D 2060 FEFF 929 ; uses "white-space" above, but "comment" not relevant 930 acstring = %x22 *(UWSP / aNL / %x21 / %x22.x22 / %x23-7E / 931 UVCHARBEYONDASCII) %x22 933 aValue = %s"TRUE" / %s"FALSE" / %s"NULL" / %s"PLUS-INFINITY" / 934 %s"MINUS-INFINITY" / %s"NOT-A-NUMBER" / 935 "'" *("0" / "1" / aW) "'B" / "'" *(HEXDIG / aW) "'H" / 936 %s"CONTAINING" 1*aS aValue / 937 aid [aW ":" aW aValue] / 938 aNumericRealValue / acstring / "{" aW alist "}" 940 ; ObjIdComponents [X.680] 941 ; aOIDC 942 aObjIdComponents = (num / aid) [aW "(" aW (num/aid) aW ")"] 944 ; NumericRealValue [X.680] 945 ; TODO: integer part could be 1*DIGIT or num 946 aNumericRealValue = ["-" aW] 1*DIGIT ["."] *DIGIT ["e" ["-"] num] 948 ; *List values [X.680] 949 alist = aValue aW *("," aW aValue aW) / 950 aid 1*aS aValue aW *("," aW aid 1*aS aValue aW) / 951 ; aOIDC *(1*aS aOIDC) aW 952 aObjIdComponents *(1*aS aObjIdComponents) aW 954 Figure 4: pkcsattrs ABNF 956 9.2. Mandatory Attribute Support 957 9.2.1. In General 959 Attributes related to certificate objects are in the domain of PKCS 960 attributes, not Directory name attributes. [I-D.seantek-ldap-pkcs9] 961 discusses the problem and registers attributes that are specifically 962 designated for PKCS use, rather than Directory use. 964 A conforming implementation is expected to recognize the short names 965 (descriptors) recorded in the LDAP Parameters: Object Identifier 966 Descriptors registry [LDAPDESC] that are designated for PKCS use if 967 the implementation processes that attribute. Not all attributes are 968 needed by all implementations. For example, a CMS processing 969 application that supports pkcsattrs needs to recognize contentType 970 and messageDigest, but not extendedCertificateAttributes. 972 9.2.2. For Certificate Applications 974 A conforming implementation that supports pkcsattrs for certificates 975 SHALL process the following attributes from PKCS #9 [RFC2985], 976 including recognizing the following short names (descriptors) and 977 associated LDAP-specific string encodings. 979 friendlyName (1.2.840.113549.1.9.20) 981 localKeyId (1.2.840.113549.1.9.21) 983 signingDescription (1.2.840.113549.1.9.13) 985 smimeCapabilities (1.2.840.113549.1.9.15) 986 [[NB: smimeCapabilities does not have a SYNTAX with an LDAP- 987 specific encoding. ASN.1 value notation is probably the most 988 readable alternative, but support for ASN.1 value notation remains 989 OPTIONAL.]] 991 9.3. Canonicalization 993 The pkcsattrs production is a textual encoding of the ASN.1 994 SET SIZE (1..MAX) OF Attribute. The textual format in this section 995 is not intended to be used as any kind of canonical form. The 996 canonical form is the DER encoding of the corresponding 997 SET SIZE (1..MAX) OF Attribute. 999 10. Whitespace 1001 This specification is intended for textual data that may be visible 1002 to or edited by humans. Whitespace is a key factor in usability, so 1003 this specification permits whitespace in certain productions. 1005 The certspec, multispec, pkcsattrs, and certstring productions are 1006 ideally emitted as one (long) line. The overall intent is that a 1007 bare line break (without leading or trailing horizontal space) is 1008 supposed to delimit these productions from each other. 1010 If it is desirable to break one of these productions across multiple 1011 lines, a hanging indent SHALL be used at syntactically appropriate 1012 places. A hanging indent means a newline production (LF, CRLF, or 1013 other characters appropriate to the character set, e.g., [[UNICODE]]) 1014 followed by one or more horizontal space characters. The preferred 1015 horizontal space production is a single SP character. 1017 Generally, where whitespace is permitted, the whitespace either has 1018 no semantic meaning and therefore can be collapsed to a zero-length 1019 substring, i.e., skipped, or can be folded into a single whitespace 1020 character, i.e., a single SP. 1022 Productions that represent the hexadecimal (or base64) encodings of 1023 octets MAY have arbitrary whitespace interspersed between the 1024 hexadecimal (or base64) characters. The whitespace has no semantic 1025 meaning, and can be collapsed. Certspec and pkcsattrs parsers that 1026 parse "#" delimited attribute values in distinguished names and 1027 certificate attributes MAY accept and collapse whitespace; however, 1028 such whitespace is not permitted by [RFC4514]. Note that the 1029 attribute value MUST begin with "#"; there MUST NOT be leading 1030 whitespace. 1032 A parser MAY accept whitespace preceding the pkcsattrType production 1033 in pkcsattrs. 1035 A parser MAY accept whitespace between each angle-bracket-delimited 1036 certspec in the multispec production. 1038 A parser MAY accept whitespace preceding the attributeType production 1039 in distinguishedName. 1041 Generally, whitespace characters in values are otherwise considered 1042 to be semantically meaningful. A generator SHOULD encode such 1043 characters (e.g., with hexpair [RFC4514]) to avoid ambiguity or 1044 corruption. 1046 11. Guidelines for Extending certspec 1048 The certspec definition presented in this document is intended to be 1049 fairly comprehensive. Nevertheless, there are several points of 1050 extension for implementors who may want to identify a certificate 1051 with more than what is presented in this document. 1053 Firstly, certspec is naturally extended by supporting additional hash 1054 algorithms. The hash introducer characters are tied to the Hash 1055 Function Textual Names Registry; adding a new hash algorithm to that 1056 registry is necessary for certificates to get identified with that 1057 hash algorithm under this specification. For security reasons, the 1058 introducers "MD2" and "MD5" SHALL NOT be generated or parsed. See 1059 [RFC6149] and [RFC6151]. 1061 Secondly, certspec allows for the full range of "local" identifiers 1062 (i.e., file paths, which may not actually be local) and "network" 1063 identifiers (i.e., URIs, which may not actually need the network). A 1064 certspec implementation that can make use of these facilities can 1065 naturally be extended by extending the path (e.g., with pipes and 1066 mount points) or the URI topology (e.g., with novel URI schemes). 1068 The ISSUERSN, SUBJECTEXP, and HOLDEREXP certspecs provide 1069 opportunities to identify the issuer, subject, or holder using 1070 multiple methods. An implementation MAY support other productions 1071 that equate to issuer certificates, subject identifiers, or holder 1072 sub-fields. 1074 Implementations MAY recognize other types of certspecs. However, new 1075 types intended for open interchange require an update to this 1076 document. 1078 A new certspec SHALL satisfy the following criteria: 1080 1. The type is identified by a keyword, followed by ":", or, the 1081 type is identified by very short sequences of characters that 1082 unambiguously signal the type of the certspec value (as file 1083 paths and Registry keys and values currently do). The 1084 specification MUST state whether the introducer characters are 1085 case-sensitive. 1087 2. The characters "<", ">", and "|" need to be distinguishable from 1088 their uses in multispec and pkcsattrs (certstring) using a 1089 context-free grammar, e.g., ABNF. 1091 3. [[TODO: further elaborate, or remove.]] If internal whitespace 1092 (including line-breaking) is permitted, the internal whitespace 1093 is consistent with this specification. 1095 12. Use of certspec in Systems 1097 certspec is useful wherever a system may need to include or refer to 1098 a certificate. Some systems may wish to refer to a certificate 1099 without enabling all of the expressive power (and security 1100 considerations) of all strings in this specification. Accordingly, 1101 those systems and specifications SHOULD develop profiles of this 1102 specification. 1104 This document guarantees that the introducer characters "URN:" and 1105 "CERT:" are RESERVED and will never be used. Implementors MUST take 1106 note that a raw certspec is not a valid URI: certspec-types are not 1107 registered URI schemes, have a broader character repertoire than 1108 permitted by [RFC3986], and do not have the same semantics as URIs. 1110 13. IANA Considerations 1112 Appendix D proposes modifications to the application/pkcs12 media 1113 type to support labeling a degenerate syntax that only contains 1114 certificates and certificate revocation lists. IANA is asked to 1115 update the fields of the application/pkcs12 registration as follows: 1117 Optional parameters: 1118 profile: A profile of PKCS #12 for particular applications. 1119 When this parameter has value "certs-only", then it conforms 1120 to the profile in Appendix E of [[RFC Ed: this document]]. 1121 If a filename is supplied, the file extension is to be .p12c; 1122 appropriate description strings (in US-English) might be 1123 "PKCS #12 Certificate Store" or 1124 "PKCS #12 Certificate Data with Attributes", among others. 1125 It would be inappropriate to imply that such content 1126 contains keys or other secret materials. 1128 This parameter is case sensitive. 1130 Published specification: 1131 PKCS #12 v1.0, June 1999; PKCS #12 v1.1 (RFC 7292), July 2014 1132 [[RFC Ed: add reference to this document.]] 1134 Additional information: 1136 Deprecated alias names for this type: N/A 1137 Magic number(s): None. 1138 File extension(s): .p12 or .pfx; .p12c (in profile=certs-only case) 1139 Macintosh file type code(s): N/A 1141 Figure 5: application/pkcs12 Media Type Registration 1143 Appendix D proposes modifications to the application/cms media type 1144 to support SafeContents as a CMS inner content type. IANA is asked 1145 to update the CMS Inner Content Types sub-registry by adding an 1146 identifier "safeContents" with the object identifier listed in 1147 Appendix D. IANA is further asked to update the application/cms 1148 media type registration template accordingly. 1150 14. Security Considerations 1152 Digital certificates are important building blocks for 1153 authentication, integrity, authorization, and (occasionally) 1154 confidentiality services. Accordingly, identifying digital 1155 certificates incorrectly can have significant security ramifications. 1157 When using hash-based certspecs, the cryptographic hash algorithm 1158 MUST be implemented properly and SHOULD have no known attack vectors. 1159 For this reason, algorithms that are considered "broken" as of the 1160 date of this Internet-Draft, such as MD2 [RFC6149] and MD5 [RFC6151], 1161 are precluded from being valid certspecs. The registration of a 1162 particular algorithm spec in this namespace does NOT mean that it is 1163 acceptable or safe for every usage, even though this Internet-Draft 1164 requires that a conforming implementation MUST implement certain 1165 specs. 1167 When using content-based certspecs, the implementation MUST be 1168 prepared to process strings of arbitrary length. As of this writing, 1169 useful certificates rarely exceed 10KB, and most implementations are 1170 concerned with keeping certificate sizes down. However, a 1171 pathological or malicious certificate could easily exceed these 1172 metrics. 1174 When using element-based certspecs, the implementation MUST be 1175 prepared to deal with multiple found certificates that contain the 1176 same certificate data, but are not the same certificate. In such a 1177 case, the implementation MUST segregate these certificates so that 1178 the implementation only continues with certificates that it considers 1179 valid or trustworthy (as discussed further below). If, despite this 1180 segregation, multiple valid or trustworthy certificates match the 1181 certspec, the certspec (not in a multispec) MUST be rejected, because 1182 a certspec is meant to identify exactly one certificate (not a family 1183 of certificates). 1185 Certificates identified by certspecs should only be used with an 1186 analysis of their validity, such as by computing the Certification 1187 Path Validation Algorithm (Section 6 of [RFC5280]) or by other means. 1188 For example, if a certificate database contains a set of certificates 1189 that it considers inherently trustworthy, then the inclusion of a 1190 certificate in that set makes it trustworthy, regardless of the 1191 results of the Certification Path Validation Algorithm. Such a 1192 database is frequently used for "Root CA" lists. 1194 Conveying PKCS attributes with certificates will likely have security 1195 effects. For example, some implementations display the friendlyName 1196 attribute to a user on par with or in lieu of data derived from the 1197 certificate itself. Other implementations allow certificates to be 1198 identified by this friendlyName attribute. Therefore, blind 1199 acceptance of PKCS attributes without considering the source or 1200 content can result in security compromises. 1202 15. References 1204 15.1. Normative References 1206 [I-D.seantek-abnf-more-core-rules] 1207 Leonard, S., "Comprehensive Core Rules and References for 1208 ABNF", draft-seantek-abnf-more-core-rules-06 (work in 1209 progress), September 2016. 1211 [I-D.seantek-ldap-pkcs9] 1212 Leonard, S., "Lightweight Directory Access Protocol (LDAP) 1213 Registrations for PKCS #9", draft-seantek-ldap-pkcs9-05 1214 (work in progress), June 2016. 1216 [I-D.seantek-unicode-in-abnf] 1217 Leonard, S. and P. Kyzivat, "Unicode in ABNF", draft- 1218 seantek-unicode-in-abnf-00 (work in progress), September 1219 2016. 1221 [LDAPDESC] 1222 IANA, "LDAP Parameters: Object Identifier Descriptors", 1223 . 1226 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1227 Extensions (MIME) Part One: Format of Internet Message 1228 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1229 . 1231 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1232 Requirement Levels", BCP 14, RFC 2119, March 1997. 1234 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1235 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1236 3986, January 2005. 1238 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 1239 (LDAP): Directory Information Models", RFC 4512, June 1240 2006. 1242 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 1243 (LDAP): String Representation of Distinguished Names", RFC 1244 4514, June 2006. 1246 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 1247 Considerations for the Lightweight Directory Access 1248 Protocol (LDAP)", BCP 64, RFC 4520, DOI 10.17487/RFC4520, 1249 June 2006, . 1251 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1252 Encodings", RFC 4648, October 2006. 1254 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1255 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1257 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1258 Housley, R., and W. Polk, "Internet X.509 Public Key 1259 Infrastructure Certificate and Certificate Revocation List 1260 (CRL) Profile", RFC 5280, May 2008. 1262 [RFC5750] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 1263 Mail Extensions (S/MIME) Version 3.2 Certificate 1264 Handling", RFC 5750, January 2010. 1266 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 1267 Attribute Certificate Profile for Authorization", RFC 1268 5755, January 2010. 1270 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1271 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 1272 RFC6570, March 2012, 1273 . 1275 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 1276 7405, DOI 10.17487/RFC7405, December 2014, 1277 . 1279 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 1280 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 1281 April 2015, . 1283 [SHS] National Institute of Standards and Technology, "Secure 1284 Hash Standard", Federal Information Processing Standard 1285 (FIPS) 180-4, March 2012, 1286 . 1289 15.2. Informative References 1291 [PKCS11] RSA Laboratories, "PKCS #11 v2.30: Cryptographic Token 1292 Interface Standard", PKCS 11, April 2009. 1294 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1295 Mail: Part I: Message Encryption and Authentication 1296 Procedures", RFC 1421, February 1993. 1298 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 1299 Resource Locators (URL)", RFC 1738, December 1994. 1301 [RFC2253] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory 1302 Access Protocol (v3): UTF-8 String Representation of 1303 Distinguished Names", RFC 2253, December 1997. 1305 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1306 Classes and Attribute Types Version 2.0", RFC 2985, 1307 November 2000. 1309 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 1310 Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 1311 2006. 1313 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1314 RFC 5652, September 2009. 1316 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August 1317 2010. 1319 [RFC6149] Turner, S. and L. Chen, "MD2 to Historic Status", RFC 1320 6149, DOI 10.17487/RFC6149, March 2011, 1321 . 1323 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1324 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1325 RFC 6151, March 2011. 1327 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 1328 M. Scott, "PKCS #12: Personal Information Exchange Syntax 1329 v1.1", RFC 7292, July 2014. 1331 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 1332 8.0.0", ISBN 978-1-936213-10-8, August 2015. 1334 Mountain View, CA: The Unicode Consortium. 1336 [X.501] International Telecommunication Union, "Information 1337 technology - Open Systems Interconnection - The Directory: 1338 Models", ITU-T Recommendation X.501, ISO/IEC 9594-2, 1339 October 2012, . 1341 [X.680] International Telecommunication Union, "Information 1342 technology - Abstract Syntax Notation One (ASN.1): 1343 Specification of basic notation", ITU-T Recommendation 1344 X.680, ISO/IEC 8824-1, August 2015, . 1347 [X.690] International Telecommunication Union, "Information 1348 technology - ASN.1 encoding rules: Specification of Basic 1349 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1350 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1351 X.690, ISO/IEC 8825-1, August 2015, . 1354 [X.693] International Telecommunication Union, "Information 1355 technology - ASN.1 encoding rules: XML Encoding Rules 1356 (XER)", ITU-T Recommendation X.693, ISO/IEC 8825-4, August 1357 2015, . 1359 Appendix A. Mandatory Attribute Descriptors for Distinguished Names 1361 As per [RFC4514], attribute descriptors case-insensitive. A 1362 conformant implementation MUST recognize the attributes in the table 1363 below when parsing certspecs containing distinguished names, both by 1364 the OIDs and by the names recorded in the LDAP Parameters: Object 1365 Identifier Descriptors registry [LDAPDESC]. A conforming generator 1366 SHOULD emit these attribute descriptors in lieu of their dotted 1367 decimal representations. 1369 +----------------------------+-------------------------------+------+ 1370 | OID | Names | RFC | 1371 +----------------------------+-------------------------------+------+ 1372 | 2.5.4.3 | cn (CN) | 4514 | 1373 | | commonName | | 1374 | 2.5.4.7 | l (L) | 4514 | 1375 | | localityName | | 1376 | 2.5.4.8 | st (ST) | 4514 | 1377 | | (S)* | | 1378 | | stateOrProvinceName | | 1379 | 2.5.4.10 | o (O) | 4514 | 1380 | | organizationName | | 1381 | 2.5.4.11 | ou (OU) | 4514 | 1382 | | organizationalUnitName | | 1383 | 2.5.4.6 | c (C) | 4514 | 1384 | | countryName | | 1385 | 2.5.4.9 | street (STREET) | 4514 | 1386 | | streetAddress | | 1387 | 0.9.2342.19200300.100.1.25 | dc (DC) | 4514 | 1388 | | domainComponent | | 1389 | 0.9.2342.19200300.100.1.1 | uid (UID) | 4514 | 1390 | | userId | | 1391 | 2.5.4.5 | serialNumber (SERIALNUMBER) | 5280 | 1392 | 2.5.4.46 | dnQualifier (DNQUALIFIER) | 5280 | 1393 | 2.5.4.4 | sn (SN) | 5280 | 1394 | | surname | | 1395 | 2.5.4.42 | gn (GN)** | 5280 | 1396 | | givenName | | 1397 | 2.5.4.12 | (T)* | 5280 | 1398 | | title | | 1399 | 2.5.4.43 | (I)* | 5280 | 1400 | | initials | | 1401 | 2.5.4.44 | (GENQUALIFIER)* | 5280 | 1402 | | generationQualifier | | 1403 | | (GENERATIONQUALIFIER) | | 1404 | 2.5.4.65 | (PNYM)* | 5280 | 1405 | | pseudonym (PSEUDONYM) | | 1406 | 1.2.840.113549.1.9.1 | (E)* | 5750 | 1407 | | emailAddress | | 1408 | | email | | 1409 +----------------------------+-------------------------------+------+ 1411 Names in parentheses are variations that are not assigned as such in 1412 [LDAPDESC]. Implementations MAY parse these names, but SHOULD NOT 1413 generate them. 1414 Names in ALL-CAPS may be emitted by some certificate-processing 1415 applications; these names are compatible with lowercase or mixed-case 1416 variations due to case-insensitivity. 1417 * Name may appear in some implementations, but is not in [LDAPDESC]. 1418 ** Name commonly appears in implementations, but is RESERVED in 1419 [LDAPDESC]. Conforming implementations MAY generate this name from 1420 2.5.4.42 and MUST parse this name as 2.5.4.42, despite its RESERVED 1421 status. 1423 Table 1: Attribute Descriptors 1425 Appendix B. Recommended Attribute Descriptors for issuersn certspec 1427 As per [RFC4514], attribute descriptors are case-insensitive. 1428 [[TODO: complete. Probably date of birth, place of birth, gender, 1429 etc. are already defined elsewhere. Also jurisdictionLocalityName, 1430 etc. from CABForum.]] 1432 Appendix C. Suggested Algorithm for Distinguishing Textual Data 1434 This appendix provides an informative algorithm that implementations 1435 MAY use to content-sniff textual data. This appendix is a companion 1436 to Section 6.5. 1438 Some certspecs will return arbitrary data, which might be textual in 1439 nature. This is especially true of the file path and URI specs. 1440 There are historical reasons for this, mostly boiling down to "DER" 1441 vs. "PEM" output options in popular cryptographic software packages, 1442 without clear guidance on file extensions. 1444 The only BER-encoded PDUs that are mandated by this spec are 1445 Certificate [RFC5280], AttributeCertificate [RFC5755], and 1446 ContentInfo (containing SignedData) [RFC5652]. Before trying to do 1447 charset-sniffing, it is reasonable to probe for BER decoding first to 1448 see what happens. The (normative) algorithm in Section 6.5 is a 1449 sufficient test. At the very least, an implementation ought to check 1450 for the presence of the SEQUENCE octet (30h), a valid length that 1451 covers the length of the data, minus the tag and length octets, and 1452 two or three validly-encoded tag-length-value elements (Clause 8.1.1 1453 of [X.690]) inside the SEQUENCE. 1455 Although an implementation can ingest arbitrary text containing 1456 certificates, this specification only requires [RFC7468], which 1457 requires the presence of encapsulation boundaries. An implementation 1458 ought to look for Unicode byte order marks first; failing that, it 1459 ought to consider ASCII, basically ignoring invalid byte sequences 1460 that do not appear in [RFC7468] productions. Regardless of the 1461 charset(s) chosen, an implementation can hunt for the minimum string 1462 "-----BEGIN " followed somewhere by "-----END ", since those strings 1463 are required for [RFC7468] conformance. 1465 Appendix D. Binary Formats for Conveying Certificates with Attributes 1467 During the development of this document, the author noted that there 1468 is a lack of standardization around conveying attributes with 1469 certificates. The bulk of this specification can be used to convey 1470 such attributes in text; however, a binary format is also desirable. 1471 Because the attributes in Section 9 are semantically equivalent to 1472 PKCS #12 "bagAttributes", it makes sense to reuse this structure of 1473 PKCS #12, if possible. 1475 D.1. PKCS #12 certs-only Profile 1477 Predecessors to PKCS #12 have been criticized for being too obtuse 1478 and cumbersome to implement. This section proposes a profile of PKCS 1479 #12 for a degenerate case of the syntax that only conveys 1480 certificates and certificate revocation lists. It is analogous to 1481 the degenerate case of SignedData in CMS [RFC5652]. The overall 1482 usability goal is to convey certificates with attributes without 1483 requiring user input of secret or private material (i.e., a password 1484 or private key) to receive the data. The data MAY be signed for 1485 integrity protection, so long as verifying the signature does not 1486 require user input of secret or private material. 1488 To compose the degenerate case, the following structures in the "PFX" 1489 structure are limited: 1491 1. authSafe has contentType id-data or id-signedData (if signed), 1492 containing an AuthenticatedSafe. 1494 2. The AuthenticatedSafe SHALL contain exactly one ContentInfo, 1495 which has contentType id-data, containing a SafeContents. 1497 3. The SafeContents can contain any number of SafeBags. 1499 4. Each SafeBag can only contain a certificate (via certBag) or a 1500 certificate revocation list (via crlBag). 1502 5. macData SHALL be "ABSENT". 1504 [RFC7292] does not have an identifier for attribute certificates in 1505 the CertBag. The ASN.1 module is hereby modified to support 1506 attribute certificates: 1508 attributeCertificate BAG-TYPE ::= 1509 {OCTET STRING IDENTIFIED BY {certTypes 3}} -- 3 is TBD 1510 -- DER-encoded attribute certificate stored in OCTET STRING 1512 CertTypes BAG-TYPE ::= { 1513 x509Certificate | 1514 sdsiCertificate, 1515 ..., 1516 attributeCertificate, 1517 ... } 1519 Figure 6: PKCS #12 ASN.1 Module Modification 1521 Implementations MUST parse through certBag elements containing 1522 attribute certificates (MUST NOT fail parsing), but actually 1523 processing attribute certificates is OPTIONAL if an implementation 1524 has no need for them. (The same remarks apply to certificate 1525 revocation lists.) Because this profile does not use encryption or 1526 key derivation functions, conforming implementations do not need to 1527 support such algorithms, which should greatly simplify 1528 implementations. 1530 It is desirable to convey this degenerate PKCS #12 data in MIME 1531 entities and files. Since this format has very different usability 1532 properties from full-featured PKCS #12, it is not to be labeled as 1533 standard PKCS #12. A new "profile" optional parameter with value 1534 "certs-only" is proposed for the application/pkcs12 media type, as 1535 well as a new file extension .p12c. See Section 13 for the modified 1536 registration template. 1538 D.2. CMS SafeContents contentType 1540 Some applications will not want to bother with the PFX PDU of PKCS 1541 #12 at all. For those applications, it is possible to transmit 1542 SafeContents directly as CMS (PKCS #7) content. 1544 The CMS (TBD: or PKCS #12?) ASN.1 module is hereby enhanced to 1545 include an object identifier for SafeContents as a content type: 1547 IMPORTS 1548 SafeContents, bagtypes 1549 FROM PKCS-12 {1 2 840 113549 1 pkcs-12(12) modules(0) pkcs-12(1)} 1551 ContentSet CONTENT-TYPE ::= { 1552 -- Define the set of content types to be recognized. 1553 ct-Data | ct-SignedData | ct-EncryptedData | ct-EnvelopedData | 1554 ct-AuthenticatedData | ct-DigestedData | ct-SafeContents, ... } 1556 ct-SafeContents CONTENT-TYPE ::= 1557 { SafeContents IDENTIFIED BY id-safeContents } 1559 -- could be 1.2.840.113549.1.12.10.1.6 existing safeContentsBag OID, 1560 -- or a new 1.2.840.113549.1.12.10.2, 1561 -- or a new 1.2.840.113549.7.9 from PKCS #7, 1562 -- or a new 1.2.840.113549.1.9.16.1.37 from pkcs-9 smime ct 1563 id-safeContents OBJECT IDENTIFIER ::= {bagtypes 6} 1565 Figure 7: CMS ASN.1 Module Modification 1567 SafeContents is registered as a CMS Inner Content Type (ICT) with the 1568 identifier "safeContents". See Section 13 for the relevant 1569 registration and application/cms modification. 1571 Using this technique allows SafeContents directly in CMS content. 1572 Any kind of SafeBag is permitted inside; unlike Appendix D.1, this 1573 format is not further profiled. 1575 D.3. SafeContents-to-PKCS#12 BER Adapter 1577 An application that processes a SafeContents PDU directly may find it 1578 expedient to adapt it to a PFX PDU for ingestion into legacy code 1579 that only processes PKCS #12 data. The following adapter can be used 1580 for that purpose. Octets are listed in hexadecimal. Place the BER 1581 encoding of SafeContents in the position marked "(SafeContents)". 1582 The placeholders "LEN-" are [X.690] length octets, which are to be 1583 computed as follows: 1585 LEN-SC: The length in octets of the SafeContents. 1587 LEN-2: LEN-SC plus the length in octets of LEN-SC itself, plus 1. 1589 LEN-3: LEN-2 plus the length in octets of LEN-2 itself, plus 20. 1591 LEN-4: LEN-3 plus the length in octets of LEN-3 itself, plus 1. 1593 30 80 02 01 03 30 80 06092A864886F70D010701 A0 LEN-4 04 LEN-3 1594 30 80 30 80 06092A864886F70D010701 A0 LEN-2 04 LEN-SC 1595 (SafeContents) 1596 0000 0000 0000 0000 1598 Figure 8: BER Adapter 1600 Appendix E. Textual Encoding of Attributes 1602 [[TODO: Consider removing this appendix; Section 9 is clearer.]] 1604 From time to time, it is desirable to convey attributes independently 1605 of other PKIX, PKCS, or CMS structures. This appendix defines a 1606 textual encoding [RFC7468] format for attributes. 1608 Attributes are encoded using the "ATTRIBUTES" label. The encoded 1609 data MUST be a BER (DER strongly preferred; see Appendix B of 1610 [RFC7468]) encoded ASN.1 "SET OF Attribute", or, in rare cases, 1611 "SEQUENCE OF Attribute" structure as described throughout Directory, 1612 PKIX, PKCS, and CMS standards. Unless the collection is specifically 1613 ordered, emitting the "SET OF Attribute" variant is RECOMMENDED. 1615 No IETF document formally discusses what an attribute is (although 1616 [RFC4512] comes close). Workable definitions can be gleaned from 1617 [X.501] and [RFC4512]: 1619 Each attribute [in the Directory] provides a piece of information 1620 about, or describes a particular characteristic of, the object to 1621 which the entry corresponds. --Clause 8.2 of [X.501] 1623 An attribute consists of an _attribute type_, which identifies the 1624 class of information given by an attribute, and the corresponding 1625 _attribute values_, which are the particular instances of that 1626 class of information appearing in the attribute within the entry. 1627 --Clause 8.2 of [X.501] 1628 An entry [in the Directory] consists of a set of attributes that 1629 hold information about the object that the entry represents. 1630 --Section 2.2 of [RFC4512] 1632 An attribute is an attribute description (a type and zero or more 1633 options) with one or more associated values. An attribute is 1634 often referred to by its attribute description. --Section 2.2 of 1635 [RFC4512] 1637 An attribute is comprised of a type and a SET OF values. The 1638 collection of values is always unordered. Collections of attributes 1639 are almost always unordered, and are almost always stored in a 1640 "SET OF Attribute". A few protocols store attributes in a 1641 "SEQUENCE OF Attribute", but for nearly all cases, the ordering is 1642 stated to be irrelevant by the relevant standard document. 1644 The attribute type is a widely shared protocol element in LDAP/ 1645 Directory, PKIX, PKCS, and CMS standards. However, the collections 1646 of relevant attributes to particular occurrences of the structure (as 1647 represented by a table constraint on an occurence) are largely 1648 disjoint from one another. CMS attribute collections (e.g., 1649 "SignedAttributes", "UnsignedAttributes", "UnprotectedAttributes") 1650 share no common semantics with Directory attributes, for instance. 1651 The textual encoding provided in this section is appropriate for any 1652 collection of attributes, but only context can determine what kinds 1653 of attributes are appropriate, as well as the identity of the 1654 corresponding object. Figure 9 provides an example of the textual 1655 encoding, along with its corresponding Section 9 format. 1657 localKeyId=#0402534C,friendlyName=Chubby\F0\9F\90\B0 1658 -----BEGIN ATTRIBUTES----- 1659 MTQwEQYJKoZIhvcNAQkVMQQEAlNMMB8GCSqGSIb3DQEJFDESHhAAQwBoAHUAYgBi 1660 AHnYPdww 1661 -----END ATTRIBUTES----- 1663 Figure 9: Attributes Example 1665 Author's Address 1667 Sean Leonard 1668 Penango, Inc. 1669 5900 Wilshire Boulevard 1670 21st Floor 1671 Los Angeles, CA 90036 1672 USA 1674 Email: dev+ietf@seantek.com 1675 URI: http://www.penango.com/