idnits 2.17.1 draft-seantek-certspec-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == 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 (September 23, 2016) is 2771 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 714, but not defined == Unused Reference: 'RFC2119' is defined on line 1400, 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' == Outdated reference: A later version (-22) exists of draft-ietf-urnbis-rfc2141bis-urn-17 -- 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 (~~), 8 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 September 23, 2016 5 Expires: March 27, 2017 7 Textual Specification for Certificates and Attributes 8 draft-seantek-certspec-09 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 March 27, 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 . . . . . . . . . . . . . . . . . . . . 6 59 4. certstring Syntax . . . . . . . . . . . . . . . . . . . . . . 6 60 5. certspec Syntax . . . . . . . . . . . . . . . . . . . . . . . 7 61 5.1. certspec Type and Value . . . . . . . . . . . . . . . . . 9 62 6. Standard Certificate Specifications . . . . . . . . . . . . . 9 63 6.1. Cryptographic Hash-Based Specifications . . . . . . . . . 10 64 6.2. Content-Based Specifications . . . . . . . . . . . . . . 11 65 6.3. Element-Based Specifications . . . . . . . . . . . . . . 11 66 6.4. Path-Based Specifications . . . . . . . . . . . . . . . . 15 67 6.5. Algorithm for Distinguishing ASN.1 PDUs . . . . . . . . . 18 68 7. Other Certificate Specifications . . . . . . . . . . . . . . 20 69 7.1. DBKEY (Reserved) . . . . . . . . . . . . . . . . . . . . 20 70 7.2. SELECT (Reserved) . . . . . . . . . . . . . . . . . . . . 20 71 8. Multiple certspecs (multispec) . . . . . . . . . . . . . . . 20 72 9. Attributes (pkcsattrs) . . . . . . . . . . . . . . . . . . . 21 73 9.1. ABNF . . . . . . . . . . . . . . . . . . . . . . . . . . 23 74 9.2. Mandatory Attribute Support . . . . . . . . . . . . . . . 24 75 9.3. Canonicalization . . . . . . . . . . . . . . . . . . . . 25 76 10. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . . 25 77 11. Guidelines for Extending certspec . . . . . . . . . . . . . . 26 78 12. Use of certspec in Systems . . . . . . . . . . . . . . . . . 27 79 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 80 14. Security Considerations . . . . . . . . . . . . . . . . . . . 29 81 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 82 15.1. Normative References . . . . . . . . . . . . . . . . . . 30 83 15.2. Informative References . . . . . . . . . . . . . . . . . 32 84 Appendix A. [[Omitted]] . . . . . . . . . . . . . . . . . . . . 33 85 Appendix B. Mandatory Attribute Descriptors for Distinguished 86 Names . . . . . . . . . . . . . . . . . . . . . . . 33 87 Appendix C. Recommended Attribute Descriptors for issuersn 88 certspec . . . . . . . . . . . . . . . . . . . . . . 35 89 Appendix D. Suggested Algorithm for Distinguishing Textual Data 35 90 Appendix E. Binary Formats for Conveying Certificates with 91 Attributes . . . . . . . . . . . . . . . . . . . . . 36 92 E.1. PKCS #12 certs-only Profile . . . . . . . . . . . . . . . 36 93 E.2. CMS SafeContents contentType . . . . . . . . . . . . . . 37 94 E.3. SafeContents-to-PKCS#12 BER Adapter . . . . . . . . . . . 38 95 Appendix F. Textual Encoding of Attributes . . . . . . . . . . . 39 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 98 1. Introduction 100 Digital certificates [RFC5280] are used in many systems and protocols 101 to identify and authenticate parties. Security considerations 102 frequently require that the certificate must be identified with 103 certainty, because selecting the wrong certificate will lead to 104 validation errors (resulting in denial of service), or in improper 105 credential selection (resulting in unwanted disclosure or 106 substitution attacks). The goal of this document is to provide a 107 uniform syntax for identifying certificates with precision and speed 108 without re-encoding in a variety of protocol slots. 110 Using this syntax, any protocol or system that refers to a 111 certificate in a textual format can unambiguously identify that 112 certificate by value or reference. Implementations that parse these 113 strings can resolve them into actual certificates. Examples include: 115 SHA-1:3ea3f070773971539b9dbf1b98c54be3a4f0f3c8 116 ISSUERSN:cn=AcmeIssuingCompany,st=California,c=US;0134F1 117 BASE64:MIIBHDCBxaADAgECAgIAmTAJBgcqhkjOPQQBMBAxDjAMBgNVBAMT 118 BVNtYWxsMB4XDTEzMTEwNTE5MjUzM1oXDTE2MDgwMjE5MjUzM1ow 119 EDEOMAwGA1UEAxMFU21hbGwwWTATBgcqhkjOPQIBBggqhkjOPQMB 120 BwNCAAS2kwRQ1thNMBMUq5d/SFdFr1uDidntNjXQrc3D/QpzYWkE 121 WDsxeY8xcbl2m0TBO4TJ/2CevdoOX0OMIOaqJ/TNoxAwDjAMBgNV 122 HRMBAf8EAjAAMAkGByqGSM49BAEDRwAwRAIgPyF8ok6h2NxMQ4uJ 123 OcGcXYcvZ1ua0kB+rIv0omHcfNECICKwpTp3LDIwhlHTQ/DulQDD 124 eYn+lnYQVc2Gm1WKAuxp 125 /etc/myserver.cer|friendlyName=fluffy the Tomcat 126 URI:https://certificates.example.com/acme/BAADF00D.cer 128 1.1. Requirements Language 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in RFC 2119. 134 1.2. Definitions 136 The term "certificate" means either a certificate [RFC5280] or an 137 attribute certificate [RFC5755]. When a certificate [RFC5280] alone 138 is to be distinguished, this specification may use the term "public 139 key certificate". 141 The term "whitespace" means HT, VT, FF, LF, CR, and SP, when 142 referring to the ASCII range. An implementation SHOULD also consider 143 whitespace beyond the ASCII range, if the implementation supports it, 144 e.g., the characters that have the White_Space character property in 145 [UNICODE].) 146 The term "entity" means a MIME entity [RFC2045], namely, a fixed 147 sequence of octets (i.e., data) with an Internet media type and 148 optional parameters. 150 2. Motivation and Purpose 152 Although certificates [RFC5280] have diverse applications, there has 153 been no uniform way to refer to a certificate in text. De-facto 154 standards such as PEM [RFC1421] and PKIX text encoding [RFC7468] are 155 used to include whole certificates in textual formats, but this 156 practice is impractical for a variety of use cases. Certificates 157 that identify long public keys (e.g., 2048-bit RSA keys) and that 158 contain required and recommended PKIX extensions can easily exceed 159 many kilobytes in length. 161 The purpose of this document is to provide a uniform textual format 162 for identifying individual certificates, with human usability as a 163 design goal. Certificate specifications, or "certspecs", are not 164 designed or intended to provide a search tool or query language to 165 match multiple certificates. The goal is to replace data elements 166 that would otherwise have to include whole certificates, or that 167 employ proprietary reference schemes. For example, certspecs fit 168 easily into XML/SGML data, YAML, JSON, and config files and databases 169 (e.g., .properties, .ini, and Windows Registry) with minimal required 170 escaping. 172 To be usable by humans, certspecs are supposed to be amenable to 173 copy-and-paste operations. The structure of a certspec is also 174 supposed to be plainly visible, do that someone glancing at a 175 certspec can ascertain the data types that it comprises. This 176 specification addresses the "speed" goal by incorporating identifiers 177 that implementations typically use as indexes to certificate 178 databases. For instance, many implementations index certificates by 179 issuer and serial number, or by SHA-1 hash, regardless of how 180 collision resistant those pieces of data are at present. 182 2.1. Static Identification 184 Identifying a specific certificate by reference or value allows 185 diverse applications to have a common syntax. For example, 186 applications can store certspecs as local or shared preferences, so 187 that users can edit them without resorting to application-specific 188 storage formats or relying on the availability of particular 189 protocols represented by URIs (such as http:, ldap: [RFC4516], file: 190 [RFC1738], or ni: schemes). When conveyed in protocol, a certspec 191 can identify a specific certificate to a client or server using text- 192 based formats such as YAML, XML, JSON, and others. The format 193 described in this document is intended to be readily reproducible by 194 users using common certificate processing tools, so that users can 195 easily create, recognize, compare, and reproduce them at a glance. 196 For example, the hash-based identifications use hexadecimal encoding 197 so that a user can easily compose or compare an URN with a simple 198 copy-and-paste operation. 200 2.2. Relationship with Other Specifications 202 Previous versions of this draft attempted to define certspecs as a 203 URN namespace, and then as a family of URI schemes. Certspecs were 204 found to be incompatible with these approaches for several 205 engineering reasons. 207 The definition of URN [I-D.ietf-urnbis-rfc2141bis-urn] changed during 208 the course of this draft's development, and as of this publication, 209 remains unclear. Overall, URNs are meant to be assigned durably and 210 persistently by namespace authorities. An algorithm that identifies 211 a datum with high but not absolute precision does not satisfy this 212 requirement, because the pigeonhole principle shows that there will 213 always be collisions for unbounded data sets, even though finding 214 particular collisions may be computationally infeasible. (The other 215 specification types are even less precise.) 217 URI schemes were also pursued and rejected. URIs have dereferencing 218 semantics, which could have significant security implications. When 219 a URI is dereferenced, an access mechanism is determined and an 220 action is performed on the URI's resource (see Section 1.2.2 of 221 [RFC3986]). When the URI scheme identifies an information retrieval 222 protocol, such as HTTP, the access mechanisms usually involve 223 performing actions on the resource (most commonly, retrieving the 224 resource). However, a wide variety of standardized and proprietary 225 URI schemes do not correspond to information retrieval protocols; 226 instead, these URI schemes serve to launch applications associated 227 with the scheme names. The practical effect of dereferencing a 228 mailto: URI [RFC6068], for example, is to launch a preferred e-mail 229 client from a user agent (e.g., a web browser), so that the user can 230 easily send e-mail to a recipient with certain fields pre-populated 231 by the contents of a URI. The practical effect of the ymsgr: URI 232 [PROVURI] is much more application and vendor-specific: dereferencing 233 such a URI is supposed to launch Yahoo! Messenger to send an instant 234 message to a designated Yahoo! screen name. The launching semantics 235 of URIs are exploited in modern consumer desktop and mobile operating 236 systems as a convenient methodology to launch an application from 237 another application, as well as to communicate application-specific 238 data between applications that otherwise have no privileged 239 relationship. 241 The arbitrary, misdirected, or outright malicious launching of 242 applications to handle certificates has grave security implications. 243 These risks are mitigated by avoiding URI schemes for certspecs. 245 URI schemes such as ni: [RFC6920] and data: identify resources in a 246 similar way as (for example) the hash and data-based spec types, 247 although they were not as usable for copy-and-paste operations. 248 Resistance was encountered when new URI scheme names were proposed 249 that did similar things as ni: and data:, but with better usability 250 for this use case. 252 Nevertheless, this draft allows for specifying a certificate by URI, 253 recognizing that an implementation might categorically decline to 254 retrieve URI certspecs on security or other grounds. 256 To distinguish this syntax from URI syntax, this Internet-Draft 257 capitalizes the "introducer characters" of the various certspec types 258 and does not require that they be delimited with a colon, even though 259 these productions (mostly) are case-insensitive and (mostly) end with 260 a colon. OpenSSL's x509v3_config format inspired this aspect of the 261 syntax. 263 3. Basic Syntax and ABNF 265 The bulk of this document defines textual formats for interchange. 266 While textual strings in this document can be in any character 267 encoding, the delimiter characters in this document are drawn from 268 ASCII. Unicode [UNICODE] support at some level (e.g., in attribute 269 values that are in LDAP string form) is inevitable, but the general 270 premise is that an implementation can convert the production (or 271 appropriate parts of the production) to Unicode when it is needed. 272 The ABNF in this document is normative, and is drawn from [RFC5234], 273 [RFC7405], [I-D.seantek-abnf-more-core-rules], and 274 [I-D.seantek-unicode-in-abnf]. The ABNF reuses certain definitions 275 from [RFC4512] and [RFC4514], but does not formally reference those 276 rules due to notating Unicode characters beyond the ASCII range in a 277 more modern way. 279 4. certstring Syntax 281 A certificate string ("certstring") is a string with a single 282 certspec (see Section 5) or multiple certspecs (a "multispec", see 283 Section 8), followed by an optional set of attributes ("pkcsattrs", 284 see Section 9). The string has the ABNF: 286 certstring = (certspec / multispec) [ "|" pkcsattrs ] 288 Figure 1: certstring ABNF 290 5. certspec Syntax 292 A certspec is a string that is intended to identify a single 293 certificate. A certspec has introducer characters followed by value 294 characters; these introducer characters MAY be part of the "value" of 295 the identifier. The ABNF is: 297 certspec = certspec-hash / certspec-content / certspec-el / 298 certspec-path 300 certspec-hash = "SHA-1" ":" 40HEXDIG / 301 "SHA-256" ":" 64HEXDIG / 302 "SHA-384" ":" 96HEXDIG / 303 "SHA-512" ":" 128HEXDIG 305 ; Proposal: Hash Function Textual Name registry hereby limited 306 ; to RFC 3986 scheme characters 308 certspec-content = ("HEX" / "BASE16") ":" 1*(2HEXDIG) / 309 "BASE64" ":" base64string 311 base64char = ALPHA / DIGIT / "+" / "/" 312 base64string = 1*(4base64char) 313 [ 3base64char "=" / 2base64char "==" ] 315 ; based on [RFC4512][RFC4514] 316 distinguishedName = [ relativeDistinguishedName 317 *( "," relativeDistinguishedName ) ] 318 relativeDistinguishedName = attributeTypeAndValue 319 *( "+" attributeTypeAndValue ) 320 attributeTypeAndValue = attributeType "=" attributeValue 321 attributeType = descr / numericoid 323 num = "0" / %x31-39 *DIGIT 324 descr = ALPHA *(ALPHA / DIGIT / "-") 325 numericoid = ("0" / "1" / "2") 1*("." num) 327 attributeValue = string / hexstring 328 string = [ ( leadchar / pair ) [ *( stringchar / pair ) 329 ( trailchar / pair ) ] ] 330 ; excl SP " # + , ; < > \ 331 leadchar = %x01-1F / %x21 / %x24-2A / %x2D-3A / 332 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 333 ; excl SP " + , ; < > \ 334 trailchar = %x01-1F / %x21 / %x23-2A / %x2D-3A / 335 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 336 ; excl " + , ; < > \ 337 stringchar = %x01-21 / %x23-2A / %x2D-3A / 338 %x3D / %x3F-5B / %x5D-7F / BEYONDASCII 340 pair = "\" (" " / %x22-23 / %x2B-2C / %x3B-3E / "\" / 2HEXDIG) 341 hexstring = "#" 2HEXDIG 343 certspec-el = "ISSUERSN" ":" distinguishedName ";" serialNumber / 344 "SUBJECTEXP" ":" distinguishedName ";" certtime / 345 "HOLDEREXP" ":" holder ";" certtime / 346 "SKI" ":" 1*(2HEXDIG) 348 serialNumber = 1*(2HEXDIG) 350 holder = distinguishedName ";" serialNumber ["+" certspec-hash] / 351 ("SPKI" / "CERT" / numericoid ) "/" certspec-hash / 352 hexstring 354 ; see RFC 7405 for case-sensitive string support 355 certtime = date-fullyear date-month date-mday 356 time-hour time-minute time-second %s"Z" / 357 date-time-nosecfrac 359 ; see draft-seantek-abnf-more-core-rules 360 full-date = full-date@[RFC3339] 361 time-hour = time-hour@[RFC3339] 362 time-minute = time-minute@[RFC3339] 363 time-second = time-second@[RFC3339] 364 time-offset = time-offset@[RFC3339] 366 date-time-nosecfrac = full-date "T" time-hour ":" time-minute ":" 367 time-second time-offset 369 certspec-path = certspec-uri / certspec-file / certspec-reg 371 ; from RFC3986; RFC 6570 372 URI-reference = URI-reference@[RFC3986] 373 URI-Template = URI-Template@[RFC6570] 375 certspec-uri = "URI:" URI-reference / URI-Template 377 ; see POSIX, etc. 378 certspec-file = ("/" / "\" / [A-Z] ":" / 379 ("." / "..") ("/" / "\") / "~" / "%" / "$") 380 *filepathchar 382 ; BEYONDASCII is from draft-seantek-more-core-rules 383 filepathchar = %x01-29 / %x2B-3B / "=" / %x40-5B / 384 %x5D-7B / %x7D-7F / quoted-fpc / BEYONDASCII 386 quoted-fpc = "\" ("*" / "<" / ">" / "?" / "\" / "|") 388 ; TODO: validate Windows file path characters 390 certspec-reg = reg-hive 1*("\" reg-key) 391 ["\\" reg-value-name] 393 reg-hive = reg-local-hive / reg-remote-hive 394 reg-local-hive = "HKEY_LOCAL_MACHINE" / "HKEY_CURRENT_USER" / 395 "HKEY_CLASSES_ROOT" / "HKEY_USERS" / 396 "HKEY_CURRENT_CONFIG" / 397 "HKLM:" / "HKCU:" / "HKCR:" / 398 "HKU:" / "HKCC:" 399 ; TODO: better specify computer name; it could be a NETBIOS name...? 400 reg-remote-hive = "\\" reg-name@[RFC3986] "\" ("HKLM" / "HKU") ":" 402 ; escape < > |. Need to figure out if 7F is ok, also C0, C1, etc. 403 reg-key = 1*(%x20-3B / %x3D / %x3F-5B %x5D-7B / %x7D.7E / 404 "\<" / "\>" / "\|" / BEYONDASCII) 405 ; reg-value-name can be empty 406 reg-value-name = *(%x20-3B / %x3D / %x3F-7B / %x7D.7E / 407 "\<" / "\>" / "\|" / BEYONDASCII) 409 Figure 2: certspec ABNF 411 5.1. certspec Type and Value 413 Semantically, a certspec is comprised of its type and value. The 414 value is always provided, but the type is either explicitly declared, 415 or is inferred from the initial (introducer) characters in the type. 416 When types are explicitly provided, they are compared case- 417 insensitively. The certspec-value identifies the certificate 418 specification value. 420 Several certspecs use hexadecimal encodings of octets. Generally: if 421 the hex octets are malformed (whether in the source material, such as 422 the corresponding certificate element, or in the hex text), the 423 certspec is invalid. 425 6. Standard Certificate Specifications 427 Standard certificate specifications are intended for interchange as 428 intuitive (to users and developers) identifiers for individual 429 certificates. This section provides four cryptographic hash-based 430 certspecs, two content-based certspecs, three element-based 431 certspecs, and two path-based certspecs. 433 A standard algorithm 435 6.1. Cryptographic Hash-Based Specifications 437 A cryptographic hash or "fingerprint" of a certificate uniquely 438 identifies that certificate. For hash-based certspecs, the hash is 439 computed over the octets of the DER encoding of the certificate, 440 namely, the Certificate type in Section 4.1 of [RFC5280] and the 441 AttributeCertificate type in Section 4.1 of [RFC5755]. The certspec- 442 value is the hexadecimal encoding of the hash value octets. For 443 example, a 256-bit SHA-256 hash is represented by exactly 32 hex 444 octets, or 64 hex characters. The hexadecimal encoding is not case 445 sensitive. 447 A conforming generator SHALL emit only hexadecimal encoded data, 448 i.e., the characters A-F (case-insensitive) and 0-9. 450 A conforming parser SHALL accept value productions that contain the 451 following non-hex digits: whitespace, hyphen, and colon. A 452 conforming parser MAY accept values that contain other characters. 454 Conforming implementations to this Internet-Draft MUST process these 455 hash-based certspecs, unless security considerations dictate 456 otherwise. Acceptable reasons for refusing to process a certspec 457 include a) the local policy prohibits use of the hash, or b) the hash 458 has known cryptographic weaknesses, such as a preimage attacks, which 459 weaken the cryptographic uniqueness guarantees of the hash. 461 6.1.1. SHA-1 463 The introducer production is "SHA-1:". The hash is computed using 464 SHA-1 [SHS]. 466 6.1.2. SHA-256 468 The introducer production is "SHA-256:". The hash is computed using 469 SHA-256 [SHS]. 471 6.1.3. SHA-384 473 The introducer production is "SHA-384:". The hash is computed using 474 SHA-384 [SHS]. 476 6.1.4. SHA-512 478 The introducer production is "SHA-512:". The hash is computed using 479 SHA-512 [SHS]. 481 6.2. Content-Based Specifications 483 Content-based certspecs identify certificates by their constituent 484 octets. For small-to-medium certificates, identifying the 485 certificate by embedding it in the certspec will be computationally 486 efficient and resistant to denial-of-service attacks (by always being 487 available). A conforming implementation MUST implement base64 and 488 hex specs. 490 The octets of a certificate are the octets of the DER encoding of the 491 certificate, namely, the Certificate type in Section 4.1 of [RFC5280] 492 and the AttributeCertificate type in Section 4.1 of [RFC5755]. The 493 DER encoding includes tag and length octets, so it always starts with 494 30h (the tag for SEQUENCE) followed by any octet other than 80h (the 495 marker for indefinite length encoding). See also Section 6.5. 497 Because users may end up copying and pasting base64 or hex-encoded 498 certificates into certspecs, and because these certspecs will 499 routinely exceed 72 characters, a production might contain embedded 500 whitespace. A conforming generator SHALL emit no whitespace, or 501 SHALL emit a hanging indent, between semantically significant 502 characters. 504 6.2.1. BASE64 506 The introducer production is "BASE64:". The value production is the 507 BASE64 encoding of the certificate octets (Section 4 of [RFC4648]). 509 6.2.2. HEX and BASE16 511 The introducer production is "HEX:" or "BASE16:". Generators MUST 512 generate "HEX:"; parsers MUST accept "HEX:" and "BASE16:". The value 513 production is the hexadecimal encoding of the certificate octets. 515 6.3. Element-Based Specifications 517 A certificate may be identified by certain data elements contained 518 within it. The following certspecs reflect the traditional reliance 519 of PKIX [RFC5280] and CMS [RFC5652] on a certificate's issuer 520 distinguished name and serial number, a certificate's subject 521 distinguished name and expiration, or a certificate's subject key 522 identifier. 524 Note that distinguished names can contain "|" in attribute value 525 strings, but this production is unambiguous with the pkcsattrs 526 delimiter because distinguished names are always terminated by ";". 528 6.3.1. ISSUERSN: Issuer Name and Serial Number 530 The introducer production is "ISSUERSN:". 532 6.3.1.1. Issuer 534 The distinguishedName production encodes the certificate's issuer 535 distinguished name (DN) field in LDAP string format [RFC4514]. 536 [RFC4514] no longer separates relative distinguished names (RDNs) by 537 semicolons, as required by its predecessor, [RFC2253]. Accordingly, 538 ";" is used to separate the issuer's DN from the subject's serial 539 number. 541 6.3.1.2. Serial Number 543 The serialNumber production is the hexadecimal encoding the DER- 544 encoded contents octets of the CertificateSerialNumber (INTEGER, 545 i.e., not the type or length octets) as specified in Section 4.1.2.2 546 of [RFC5280]. 548 6.3.1.3. Conformance 550 A conforming implementation SHALL implement the ISSUERSN certspec. 551 An implementation MUST process serial numbers up to the same length 552 as required by Section 4.1.2.2 of [RFC5280] (20 octets), and MUST 553 process distinguished name strings as required by [RFC4514], 554 including the table of minimum AttributeType name strings that MUST 555 be recognized. Additionally, implementations MUST process attribute 556 descriptors specified in [RFC5280] (MUST or SHOULD), and [RFC5750] 557 (specifically: E, email, emailAddress). For reference, a complete 558 list of required attribute descriptors is provided in Appendix B. 559 Implementations are encouraged to recognize additional attribute 560 descriptors where possible. A sample list of such attribute 561 descriptors is provided in Appendix C. Conforming implementations 562 MUST be able to parse all distinguished name attribute types that are 563 encoded in OID dotted decimal form, as well as all distinguished name 564 attribute values that are encoded in "#" hexadecimal form. 566 6.3.2. SUBJECTEXP: Subject and Expiration 568 The SUBJECTEXP certspec only identifies certificates [RFC5280], not 569 attribute certificates [RFC5755]. The introducer production is 570 "SUBJECTEXP:". 572 6.3.2.1. Subject 574 The distinguishedName production encodes the certificate's subject 575 distinguished name (DN) field in LDAP string format [RFC4514]. 576 [RFC4514] no longer separates relative distinguished names (RDNs) by 577 semicolons, as required by its predecessor, [RFC2253]. Accordingly, 578 ";" is used to separate the subject's DN from the subject's 579 expiration (notAfter) date and time. 581 6.3.2.2. Expiration (notAfter) 583 The certificate's expiration is the notAfter value of the certificate 584 validity period (Section 4.1.2.5 of [RFC5280]). The production in 585 this certspec can be in one of two formats: GeneralizedTime or 586 [RFC3339] date-time. These forms are syntactically distinct. 588 The GeneralizedTime format from Clause 46 of [X.680] SHALL be with 589 four-digit years, no fractional seconds, and "Z" time (UTC or Zulu 590 time, with no time zone offset) in accordance with Section 4.1.2.5.2 591 of [RFC5280]. (The "Z" is case-sensitive, Clause 46.3 of [X.680].) 593 The [RFC3339] date-time format from [RFC3339] SHALL be with no 594 fractional seconds (time-secfrac omitted). 596 6.3.2.3. Conformance 598 A conforming implementation SHALL parse and generate distinguished 599 name productions with the same adherence as stated above in 600 Section 6.3.1.3. 602 A conforming implementation SHALL parse and generate all expiration 603 productions, including all four-digit years, and (for [RFC3339] only) 604 all time zone offsets. Time zone offsets in date-time productions 605 MUST be supported on usability grounds. Time zone offsets are not 606 permitted in GeneralizedTime because the flexible syntax is only 607 meant to support copy-and-paste operations with the underlying data 608 in the public key certificate [RFC5280]. 610 6.3.3. HOLDEREXP: Holder and Expiration 612 The HOLDEREXP certspec only identifies attribute certificates 613 [RFC5755], not certificates [RFC5280]. The introducer production is 614 "HOLDEREXP:". 616 6.3.3.1. Holder 618 The holder production encodes the attribute certificate's Holder 619 field [RFC5755]. Unfortunately, this field can get a bit complex. 621 The entire DER encoding of the Holder structure (including the tag 622 and length octets) can be encoded in LDAP hexadecimal form [RFC4514], 623 with "#" prepended. This amounts to a cop-out, but covers all cases. 625 When the Holder field identifies a public key certificate solely by 626 one issuer distinguished name, a serial number, and no issuerUID 627 (issuerUID is ABSENT), then the holder production SHALL be the 628 distinguished name in LDAP string form [RFC4514], a semicolon, and 629 the serial number in hexadecimal form. 631 When the Holder field identifies a holder solely by its object 632 digest, the digest algorithm does not include additional parameters, 633 and the objectDigest comprises an integral number of octets, then the 634 holder production SHALL be the digested object type, "/", the 635 algorithm identifier from the Hash Function Textual Names registry, 636 ":", and the hexadecimal encoding of the hash value (objectDigest) 637 octets. The case-insensitive digested object type can be "SPKI", 638 "CERT", or the dotted decimal representation of the 639 otherObjectTypeID. 641 [[NB: do we really need this? RFC 5755 says only one thing.]] When 642 the Holder field identifies a public key certificate by both of the 643 aforementioned sets of data (one issuer distinguished name, a serial 644 number, no issuerUID, and the public key certificate's fingerprint 645 with digestedObjectType set to publicKeyCert), then the Holder 646 production SHALL be first production, "+", the algorithm identifier, 647 and the hexadecimal encoding of the hash value (objectDigest) octets. 649 [[NB: Shall we include a string format for GeneralName, and then 650 GeneralNames?]] 652 6.3.3.2. Expiration (notAfter) 654 The attribute certificate's expiration is the notAfter value of the 655 attribute certificate validity period (Section 4.2.6 of [RFC5755]). 656 The production in this certspec is the same as Section 6.3.2.2. 658 6.3.3.3. Conformance 660 A conforming implementation SHALL parse and generate distinguished 661 name productions with the same adherence as stated above in 662 Section 6.3.1.3. 664 A conforming implementation SHALL parse and generate all expiration 665 productions, including all four-digit years, and (for [RFC3339] only) 666 all time zone offsets. Time zone offsets in date-time productions 667 MUST be supported on usability grounds. Time zone offsets are not 668 permitted in GeneralizedTime because the flexible syntax is only 669 meant to support copy-and-paste operations with the underlying data 670 in the attribute certificate [RFC5755]. 672 6.3.4. ski: Subject Key Identifier 674 The introducer production is "SKI:". The value production is the 675 hexadecimal encoding of the certificate's subject key identifier, 676 which is recorded in the certificate's Subject Key Identifier 677 extension (Section 4.2.1.2 of [RFC5280]). The octets are the DER- 678 encoded contents octets of the SubjectKeyIdentifier (OCTET STRING) 679 extension value. For a certificate that lacks a subject key 680 identifier, an underlying implementation MAY operatively associate a 681 subject key identifier with the certificate. 683 A conforming generator SHALL emit only hexadecimal encoded data, 684 i.e., the characters A-F (case-insensitive) and 0-9. 686 A conforming parser SHALL accept value productions that contain the 687 following non-hex digits: whitespace (HT, VT, SP, FF, CR, LF), 688 hyphen, and colon. A conforming parser MAY accept values that 689 contain other characters. 691 6.4. Path-Based Specifications 693 A certificate may be identified by a path to data. A conforming 694 parser MUST recognize file path, Registry, and URI specs, although 695 conforming implementations merely MAY process them. 697 Two common themes among path-based certspecs are that they may refer 698 to weakly typed or untyped data, and they have a higher probability 699 of referring to data that contains multiple certificates. Therefore, 700 a greater degree of content-sniffing is required for interoperability 701 than the certspecs above. An implementation that implements these 702 path-based certspecs SHALL support the ASN.1 Certificate PDU when 703 public key certificates are being retrieved, and the ASN.1 704 AttributeCertificate PDU when attribute certificates are being 705 retrieved. Additionally, a conforming implementation SHALL support 706 the ASN.1 ContentInfo (PKCS #7/CMS SignedData) PDU. 708 Untyped binary data may be encoded in a [X.690] transfer syntax, 709 which may be BER, CER, or DER; for purposes of this section, these 710 are all called "BER-encoded". 712 6.4.1. File Path 714 File paths are identified by their introducer productions / \ [A-Z]: 715 ./ ../ .\ ..\ ~ % and $. The characters that follow MUST be valid 716 path characters for the system on which the files are being accessed. 717 Since the starting character sequences for file paths are fixed and 718 determinable, prefixing the file path with a type identifier is 719 (thought to be) unnecessary. 721 A relative file path begins with "." or "..", and is relative to a 722 "current directory". Determining an appropriate "current directory" 723 is outside the scope of this specification. 725 When the file is read, implementations MUST accept the following, 726 regardless of the filename, which SHOULD NOT be the conclusive 727 determinant of the type: 729 1. Typed data (reported only by a minority of file systems), which 730 is treated conclusively as the type 732 2. Data that is determined to be textual, which is analyzed 733 according to [RFC7468] 735 3. Data that is determined to be BER-encoded 737 The manner of determining whether data is textual or BER-encoded data 738 is not fixed by this specification, but see, e.g., Appendix D. 740 File paths may have unexpanded environment variables, such as 741 %USERNAME% or ${LOGNAME}; implementations MUST parse these 742 environment variable syntaxes, but merely MAY perform environment 743 variable substitution as environment, capability, and security 744 concerns dictate. 746 Note that Unix-oriented file paths can contain "|" in the production 747 "\|", but this production is unambiguous with the pkcsattrs 748 delimiter. 750 6.4.2. Registry 752 Certificates can be identified on Windows machines with Registry keys 753 and values. The introducer productions for local Registry entries 754 are "HKEY_LOCAL_MACHINE\", "HKEY_CURRENT_USER\", 755 "HKEY_CLASSES_ROOT\", "HKEY_USERS\", "HKEY_CURRENT_CONFIG\", 756 "HKLM:\", "HKCU:\", "HKCR:\", "HKU:\", and "HKCC:\". The introducer 757 productions for remote Registry entries are "\\", followed by a 758 computer name, followed by either "\HKLM:\" or "\HKU:\". 760 Registry key names include any printable character except backslash 761 "\"; each key includes what amounts to an associative array of 762 values, which are name/type/data tuples. A value name can include 763 any printable character, including "<", ">", and "|"; additionally, 764 every key has a default value, which has a zero-length name. This 765 layout presents a couple of parsing challenges. 767 A Registry production is comprised of a key path followed by a value. 768 The key path's key names are delimited by "\". In each key name, 769 "<", ">", and "|" SHALL be escaped with a preceding "\". The value 770 name is delimited from the key name with two backslashes "\\". "<", 771 ">", "|", and "\" in the value SHALL be escaped with a preceding "\". 772 The default value MAY be identified with or without the two final 773 backslashes. Unlike file paths, Registry productions do not 774 recognize or substitute unexpanded environment variables. 776 Registry values have a type and some data. When the type is REG_SZ 777 or REG_EXPAND_SZ, an implementation is to treat the text as a 778 recursive certspec or multispec. If it is not a certspec or 779 multispec, then an implementation is to analyze the text according to 780 [RFC7468]. Text in REG_EXPAND_SZ is subject to environment variable 781 substitution. When the type is REG_BINARY, an implementation is to 782 determine if the data is BER-encoded, and if so, to analyze it for 783 supported ASN.1 PDUs. When the type is REG_LINK, an implementation 784 is to follow the symbolic link. 786 6.4.3. URI 788 The introducer production is "URI:". The value is a [RFC3986] 789 conforming URI-reference or [RFC6570] conforming URI-Template. 791 In the context of URIs, a relative reference conforms to the 792 relative-ref production of [RFC3986] and the usage described in 793 Section 4.2 of [RFC3986], it is relative to a "base URI". 794 Determining an appropriate "base URI" is outside the scope of this 795 specification. 797 When the URI is dereferenced, implementations MUST accept the 798 following, regardless of the path or query productions: 800 1. representations that are conclusively public key certificates or 801 attribute certificates, such as LDAP URIs [RFC4516] that point to 802 or contain userCertificate attributes (2.5.4.36, for public key 803 certificates) or attributeCertificate attributes (2.5.4.58, for 804 attribute certificates) 806 2. application/pkix-cert and application/pkix-attr-cert entities, 807 which are conclusively public key certificates or attribute 808 certificates, respectively 810 3. application/pkcs7-mime and application/cms entities, when the 811 body represents a ContentInfo/SignedData containing certificates 812 (regardless of the smime-type or encapsulatingContent parameters, 813 and regardless of whether or not the SignedData is in a 814 degenerate, certs-only format) 816 4. text/plain entities, which are analyzed according to [RFC7468] 818 5. Arbitrary data and application/octet-stream entities are treated 819 as untyped; they are are analyzed for textual or binary [X.690] 820 data 822 6. Arbitrary text, which is analyzed according to [RFC7468] 824 7. Arbitrary BER-encoded data, which is analyzed for supported ASN.1 825 PDUs 827 The URI certspec can include a fragment identifier. Implementations 828 MUST parse fragment identifiers, but merely MAY perform "secondary 829 resource" isolation and processing as environment, capability, and 830 security concerns dictate. 832 The URI certspec can be a URI Template [RFC6570]. Implementations 833 MUST parse URI templates, but merely MAY expand them in accordance 834 with [RFC6570] as environment, capability, and security concerns 835 dictate. 837 Note that URI templates can contain "|" in the production "{|".."}", 838 but this production is unambiguous with the pkcsattrs delimiter. 840 6.5. Algorithm for Distinguishing ASN.1 PDUs 842 A certspec can identify a public key certificate ("PKC") or an 843 attribute certificate ("AC"). When the type of certificate is 844 specified unambiguously in the source data, an implementation SHALL 845 follow the specifier in the source data. However, of the certspecs 846 listed in this document, only a subset of URIs are capable of 847 unambiguous specification (e.g., via Internet media type designation 848 of application/pkix-cert or application/pkix-attr-cert). Most other 849 certspecs will return a blob of bytes or characters. Therefore, an 850 implementation needs to perform some content-sniffing to figure out 851 what the data represents. There are two (not entirely orthogonal) 852 decisions: is the data textual [RFC7468] or not, and does the data 853 represent a PKC or AC? (Note: The content-based certspecs BASE64 and 854 HEX always represent one certificate; the encodings MUST NOT encode a 855 textual blob or a PKCS #7/CMS PDU.) 857 This section is normative, as it is based on standardized formats. 858 An implementation MAY use any algorithm it chooses, as long as it 859 produces the same results. 861 A suggested algorithm for distinguishing textual data is in 862 Appendix D; that algorithm is merely informative. 864 An implementation can use the following algorithm to choose between 865 the supported PDU types when encountering BER-encoded data: 867 1. Ensure that the first octet is SEQUENCE 30h. 869 2. Ensure that the length covers the length of the data, minus the 870 tag and length octets. (If the length is indefinite, a check 871 that the end of the data has the end-of-contents octets would be 872 appropriate.) Extraneous data SHALL be considered erroneous. 874 3. If there are 2 elements -> confirm that the first element is 875 OBJECT IDENTIFIER 1.2.840.113549.1.7.2 and the second element is 876 explicitly tagged (APPLICATION 0, A0). Analyze the PDU as a 877 ContentInfo containing SignedData. 879 4. Otherwise, ensure that there are 3 elements, and that the first 880 element is a SEQUENCE 30h (either AttributeCertificateInfo or 881 TBSCertificate). 883 5. this SEQUENCE has: 6, 7, or 7+ elements 885 6. if 6 elements -> Analyze the PDU as a Certificate (public key 886 certificate) with version v1 (ABSENT). 888 7. if 7+ elements -> 890 1. look at version field (first element) 892 2. if INTEGER (UNIVERSAL 2) -> Analyze the PDU as an 893 AttributeCertificate (attribute certificate) 895 3. if explicitly tagged (APPLICATION 0, A0) and the contents are 896 INTEGER (UNIVERSAL 2) -> Analyze the PDU as a Certificate 897 (public key certificate). 899 7. Other Certificate Specifications 901 The additional certificate specifications in this section are 902 provided for applications to use as local identifiers that are 903 useful, intuitive, or supportive of legacy systems or overriding 904 design goals. These certspecs SHOULD NOT be used for interchange. 906 7.1. DBKEY (Reserved) 908 The introducer production is "DBKEY:". The DBKEY certspec is meant 909 for an opaque string that serves as the unique key to a certificate 910 in an implementation's certificate database. This document reserves 911 this introducer sequence for future use. 913 7.2. SELECT (Reserved) 915 The introducer production is "SELECT" (without a colon). The SELECT 916 certspec is meant for a valid SQL statement (suitably escaped) that 917 retrieves a row representing a certificate. This document reserves 918 this introducer sequence for future use. 920 8. Multiple certspecs (multispec) 922 A multispec is a string that contains multiple certspecs, each of 923 which is intended to identify the exact same certificate. If 924 multiple certificates match a single spec, a single certificate can 925 be returned by the access operation, so long as the intersection of 926 certificates identified by all of the certspecs in the multispec is 927 one. The purpose of multispec is to provide multiple access and 928 verification methods. For example, a hash algorithm may have known 929 weaknesses, but may be the most efficient way to identify a 930 certificate (e.g., because it is the index method). Providing 931 additional certspecs (i.e., strong hash algorithms) would increase 932 the certainty that the correct certificate is accessed. 934 As the certspecs above make use of almost all other characters in the 935 ASCII range, < and > have been chosen to delimit certspecs between 936 each other. (Whitespace can also appear between each < and > 937 delimited certspec.) The ABNF of multispec is: 939 multispec = 1*("<" certspec ">") 941 Figure 3: multispec ABNF 943 9. Attributes (pkcsattrs) 945 This specification defines a textual format for PKCS attributes. 946 This format is not limited to certificates: it can be used with other 947 PKCS-related data. The syntax is intended primarily to convey 948 certificate-related attributes found in PKCS #9 [RFC2985], PKCS #11 949 [PKCS11], PKCS #12 [RFC7292], and particular implementations of 950 cryptographic libraries. These attributes are syntactically 951 identical to, but semantically disjoint from, Directory (X.500/LDAP) 952 attributes. 954 When pkcsattrs is used with a certspec or multispec, the intent is to 955 associate arbitrary metadata with a certificate--metadata that is not 956 intrinsic to that certificate. For example, the additional 957 attributes may represent preferences. Attributes in this context are 958 semantically equivalent to PKCS #12 "bagAttributes", drawn from the 959 "PKCS12AttrSet" [RFC7292]. 961 pkcsattrs are delimited from a certspec or multispec production with 962 "|". Each pkcsattr SHALL have a corresponding ASN.1 definition. The 963 textual syntax of pkcsattrs is very similar to (in fact, a superset 964 of) [RFC4514]: the pkcsattrs production represents the PKCS 965 Attributes family of types, which are repeatedly defined in those 966 standards, and standards that derive from them, as 967 SET SIZE (1..MAX) OF Attribute. E.g., CMS (from PKCS #7) [RFC5652], 968 private keys (from PKCS #8) [RFC5958], and PKCS #12 [RFC7292]. 969 Attributes are semantically unordered. Multiple attributes are 970 separated with ",". 972 Each attribute has a single attrType (canonically defined as OBJECT 973 IDENTIFIER in [RFC5652]), and a SET OF attrValues. The attrType is 974 encoded as the string representation of AttributeType (that is, 975 either a registered short name (descriptor) [RFC4520], or the dotted- 976 decimal encoding, of the OBJECT IDENTIFIER [RFC4512]). 978 When an attribute has at least one value, the attrType is followed by 979 "=" and the encoding of the attrValues (empty strings are possible). 980 Multiple attrValues are separated by "+". When the attribute has no 981 values, the attrType MUST NOT be followed by "=". 983 An attrValue can have one of several encodings: 985 hex: The attrValue can always be represented by "#" followed by the 986 hexadecimal encoding of each of the octets of the BER encoding of 987 the attrValue, following paragraph 1 of Section 2.4 of [RFC4514]. 988 Implementations MUST support this encoding. 990 string: If the attrValue has a LDAP-specific string encoding, that 991 encoding can be used as the string representation of the value, 992 with characters suitably escaped according to paragraph 2 and 993 onward of Section 2.4 of [RFC4514]. Implementations SHOULD 994 support this encoding for attributes of interest to it. 996 XER: The attrValue can be represented by its BASIC-XER encoding 997 [X.693] (Clause 8). When in BASIC-XER encoding, the string MUST 998 be a complete XML fragment comprising one element, i.e., there 999 SHALL NOT be an XML prolog. XER encoding is self-delimiting 1000 because it has balanced elements; this string always begins with 1001 "<" and ends with ">". Processing is simplified compared to 1002 arbitrary XML in that XML processing instructions, XML comments, 1003 and CDATA sections are prohibited. Implementations MUST support 1004 parsing through this encoding, but merely MAY support this 1005 encoding (encoding and decoding between [X.690]) for attributes of 1006 interest to it. 1008 ASN.1 value: The attrValue can be represented by its ASN.1 value 1009 notation [X.680], surrounded by exactly one space (SP) on each 1010 end. The syntax is precisely defined in Figure 4 so that the 1011 value itself never begins or ends with ASN.1 "white-space", 1012 although "white-space" can occur within the value. ASN.1 value 1013 notation requires a bit of finesse in that <"> can appear inside 1014 to delimit "cstring" lexical items (see Clause 12.14 and Clause 41 1015 of [X.680]). A "cstring" starts and ends with <">, and can 1016 represent <"> internally with a pair of consecutive <">. 1017 Therefore, <"> is balanced because it always occurs in multiples 1018 of two. If the value is just a cstring, then the representation 1019 will have exactly two <"> at the beginning, and two <"> at the 1020 end, with evenly-balanced <"> pairs inside. Other values that are 1021 not lists (enclosed with "{" and "}") do not have <"> occur within 1022 them. Otherwise, the representation must have at least one "{" 1023 "}" balanced pair at either end, hemming in <"> occurrences to 1024 within the balanced pairs of "{" and "}". Implementations MUST 1025 support parsing through this encoding, but merely MAY support this 1026 encoding (encoding and decoding between [X.690]) for attributes of 1027 interest to it. 1029 Of the attrValue encodings listed above, only "hex" can reliably 1030 transfer the underlying BER representation without an implementation 1031 maintaining specific knowledge of every attribute. Therefore, "hex" 1032 is RECOMMENDED for open interchange of pkcsattrs. The other 1033 representations are really meant for human production and 1034 consumption. 1036 9.1. ABNF 1038 The collective ABNF of pkcsattrs is: 1040 pkcsattrs = pkcsattr ["," pkcsattrs] 1041 pkcsattr = pkcsattrType ["=" pkcsattrValues] 1042 pkcsattrType = descr / numericoid 1043 pkcsattrValues = pkcsattrValue ["+" pkcsAttrValues] 1044 pkcsattrValue = hexstring / string / 1045 basic-xer-string / asn1-value-string 1047 basic-xer-string = xer-element 1049 ; limited by [X.680][X.693] 1050 xer-Name = ALPHA *(ALPHA / DIGIT / "_" / "-" / ".") 1052 ; limited by XML to these four chars 1053 xW = *(HT / LF / CR / SP) 1055 xer-element = xer-EmptyElemTag / xer-STag xer-content xer-ETag 1057 xer-EmptyElemTag = "<" xer-Name xW "/>" 1059 xer-STag = "<" xer-Name xW ">" 1061 xer-content = *xer-CharData *((xer-element / xer-Reference) 1062 *xer-CharData) 1064 xer-ETag = "" 1066 xer-CharData = HT / LF / CR / %x20-25 / %x27-3B / "=" / %x3F-D7FF / 1067 %xE000-%xFFFD / %x10000-10FFFF 1069 xer-Reference = xer-EntityRef / xer-CharRef 1071 xer-EntityRef = "&" (%s"amp" / %s"lt" / %s"gt") ";" 1073 xer-CharRef = "&#" (1*DIGIT / %s"x" 1*HEXDIG) ";" 1075 ; TODO: may want another delimiter--think about it 1076 ; uses num from above for non-negative integers 1077 asn1-value-string = SP aValue aW 1079 ; identifier, Clause 12.3 of [X.680] 1080 aid = %x61-7A *(["-"] (ALPHA / DIGIT)) 1082 ; "newline", Clause 12.1.6 of [X.680] 1083 ; (NEL LS PS omitted) 1084 aNL = %d10-13 1085 ; single "white-space" (comment considered matching, 1086 ; because delimits lexical items), Clause 12.1.6 of [X.680] 1087 aS = %d9-13 / SP / NBSP / acomment 1088 aW = *aS 1090 acomment = "--" *(["-"] ( UWSP / %x21-2C / %x2E-7E / 1091 UVCHARBEYONDASCII / PUACHAR ) ) 1092 (aNL / "-" (aNL / "-")) 1094 ; space in unicode: 85 A0 1680 2000-200A 202F 205F 3000 1095 ; related not-unicode-White_Space-but-whitespace 1096 ; 180E 200B-200D 2060 FEFF 1098 ; uses "white-space" above, but "comment" not relevant 1099 acstring = %x22 *(UWSP / aNL / %x21 / %x22.x22 / %x23-7E / 1100 UVCHARBEYONDASCII) %x22 1102 aValue = %s"TRUE" / %s"FALSE" / %s"NULL" / %s"PLUS-INFINITY" / 1103 %s"MINUS-INFINITY" / %s"NOT-A-NUMBER" / 1104 "'" *("0" / "1" / aW) "'B" / "'" *(HEXDIG / aW) "'H" / 1105 %s"CONTAINING" 1*aS aValue / 1106 aid [aW ":" aW aValue] / 1107 aNumericRealValue / acstring / "{" aW alist "}" 1109 ; ObjIdComponents [X.680] 1110 ; aOIDC 1111 aObjIdComponents = (num / aid) [aW "(" aW (num/aid) aW ")"] 1113 ; NumericRealValue [X.680] 1114 ; TODO: integer part could be 1*DIGIT or num 1115 aNumericRealValue = ["-" aW] 1*DIGIT ["."] *DIGIT ["e" ["-"] num] 1117 ; *List values [X.680] 1118 alist = aValue aW *("," aW aValue aW) / 1119 aid 1*aS aValue aW *("," aW aid 1*aS aValue aW) / 1120 ; aOIDC *(1*aS aOIDC) aW 1121 aObjIdComponents *(1*aS aObjIdComponents) aW 1123 Figure 4: pkcsattrs ABNF 1125 9.2. Mandatory Attribute Support 1127 9.2.1. In General 1129 Attributes related to certificate objects are in the domain of PKCS 1130 attributes, not Directory name attributes. [I-D.seantek-ldap-pkcs9] 1131 discusses the problem and registers attributes that are specifically 1132 designated for PKCS use, rather than Directory use. 1134 A conforming implementation is expected to recognize the short names 1135 (descriptors) recorded in the LDAP Parameters: Object Identifier 1136 Descriptors registry [LDAPDESC] that are designated for PKCS use if 1137 the implementation processes that attribute. Not all attributes are 1138 needed by all implementations. For example, a CMS processing 1139 application that supports pkcsattrs needs to recognize contentType 1140 and messageDigest, but not extendedCertificateAttributes. 1142 9.2.2. For Certificate Applications 1144 A conforming implementation that supports pkcsattrs for certificates 1145 SHALL process the following attributes from PKCS #9 [RFC2985], 1146 including recognizing the following short names (descriptors) and 1147 associated LDAP-specific string encodings. 1149 friendlyName (1.2.840.113549.1.9.20) 1151 localKeyId (1.2.840.113549.1.9.21) 1153 signingDescription (1.2.840.113549.1.9.13) 1155 smimeCapabilities (1.2.840.113549.1.9.15) 1156 [[NB: smimeCapabilities does not have a SYNTAX with an LDAP- 1157 specific encoding. ASN.1 value notation is probably the most 1158 readable alternative, but support for ASN.1 value notation remains 1159 OPTIONAL.]] 1161 9.3. Canonicalization 1163 The pkcsattrs production is a textual encoding of the ASN.1 1164 SET SIZE (1..MAX) OF Attribute. The textual format in this section 1165 is not intended to be used as any kind of canonical form. The 1166 canonical form is the DER encoding of the corresponding 1167 SET SIZE (1..MAX) OF Attribute. 1169 10. Whitespace 1171 This specification is intended for textual data that may be visible 1172 to or edited by humans. Whitespace is a key factor in usability, so 1173 this specification permits whitespace in certain productions. 1175 The certspec, multispec, pkcsattrs, and certstring productions are 1176 ideally emitted as one (long) line. The overall intent is that a 1177 bare line break (without leading or trailing horizontal space) is 1178 supposed to delimit these productions from each other. 1180 If it is desirable to break one of these productions across multiple 1181 lines, a hanging indent SHALL be used at syntactically appropriate 1182 places. A hanging indent means a newline production (LF, CRLF, or 1183 other characters appropriate to the character set, e.g., [[UNICODE]]) 1184 followed by one or more horizontal space characters. The preferred 1185 horizontal space production is a single SP character. 1187 Generally, where whitespace is permitted, the whitespace either has 1188 no semantic meaning and therefore can be collapsed to a zero-length 1189 substring, i.e., skipped, or can be folded into a single whitespace 1190 character, i.e., a single SP. 1192 Productions that represent the hexadecimal (or base64) encodings of 1193 octets MAY have arbitrary whitespace interspersed between the 1194 hexadecimal (or base64) characters. The whitespace has no semantic 1195 meaning, and can be collapsed. Certspec and pkcsattrs parsers that 1196 parse "#" delimited attribute values in distinguished names and 1197 certificate attributes MAY accept and collapse whitespace; however, 1198 such whitespace is not permitted by [RFC4514]. Note that the 1199 attribute value MUST begin with "#"; there MUST NOT be leading 1200 whitespace. 1202 A parser MAY accept whitespace preceding the pkcsattrType production 1203 in pkcsattrs. 1205 A parser MAY accept whitespace between each angle-bracket-delimited 1206 certspec in the multispec production. 1208 A parser MAY accept whitespace preceding the attributeType production 1209 in distinguishedName. 1211 Generally, whitespace characters in values are otherwise considered 1212 to be semantically meaningful. A generator SHOULD encode such 1213 characters (e.g., with hexpair [RFC4514]) to avoid ambiguity or 1214 corruption. 1216 11. Guidelines for Extending certspec 1218 The certspec definition presented in this document is intended to be 1219 fairly comprehensive. Nevertheless, there are several points of 1220 extension for implementors who may want to identify a certificate 1221 with more than what is presented in this document. 1223 Firstly, certspec is naturally extended by supporting additional hash 1224 algorithms. The hash introducer characters are tied to the Hash 1225 Function Textual Names Registry; adding a new hash algorithm to that 1226 registry is necessary for certificates to get identified with that 1227 hash algorithm under this specification. However, for security 1228 reasons, the introducers "MD2" and "MD5" SHALL NOT be generated or 1229 parsed. 1231 Secondly, certspec allows for the full range of "local" identifiers 1232 (i.e., file paths, which may not actually be local) and "network" 1233 identifiers (i.e., URIs, which may not actually need the network). A 1234 certspec implementation that can make use of these facilities can 1235 naturally be extended by extending the path (e.g., with pipes and 1236 mount points) or the URI topology (e.g., with novel URI schemes). 1238 The ISSUERSN, SUBJECTEXP, and HOLDEREXP certspecs provide 1239 opportunities to identify the issuer, subject, or holder using 1240 multiple methods. An implementation MAY support other productions 1241 that equate to issuer certificates, subject identifiers, or holder 1242 sub-fields. 1244 Implementations MAY recognize other types of certspecs. However, new 1245 types intended for open interchange require an update to this 1246 document. 1248 A new certspec SHALL satisfy the following criteria: 1250 1. The type is identified by a keyword, followed by ":", or, the 1251 type is identified by very short sequences of characters that 1252 unambiguously signal the type of the certspec value (as file 1253 paths and Registry keys and values currently do). The 1254 specification MUST state whether the introducer characters are 1255 case-sensitive. 1257 2. The characters "<", ">", and "|" need to be distinguishable from 1258 their uses in multispec and pkcsattrs (certstring) using a 1259 context-free grammar, e.g., ABNF. 1261 3. [[TODO: further elaborate, or remove.]] If internal whitespace 1262 (including line-breaking) is permitted, the internal whitespace 1263 is consistent with this specification. 1265 12. Use of certspec in Systems 1267 certspec is useful wherever a system may need to include or refer to 1268 a certificate. Some systems may wish to refer to a certificate 1269 without enabling all of the expressive power (and security 1270 considerations) of all strings in this specification. Accordingly, 1271 those systems and specifications SHOULD develop profiles of this 1272 specification. 1274 This document guarantees that the introducer characters "URN:" and 1275 "CERT:" are RESERVED and will never be used. Implementors MUST take 1276 note that a raw certspec is not a valid URI: certspec-types are not 1277 registered URI schemes, have a broader character repertoire than 1278 permitted by [RFC3986], and do not have the same semantics as URIs. 1280 13. IANA Considerations 1282 Appendix E proposes modifications to the application/pkcs12 media 1283 type to support labeling a degenerate syntax that only contains 1284 certificates and certificate revocation lists. IANA is asked to 1285 update the fields of the application/pkcs12 registration as follows: 1287 Optional parameters: 1288 profile: A profile of PKCS #12 for particular applications. 1289 When this parameter has value "certs-only", then it conforms 1290 to the profile in Appendix E of [[RFC Ed: this document]]. 1291 If a filename is supplied, the file extension is to be .p12c; 1292 appropriate description strings (in US-English) might be 1293 "PKCS #12 Certificate Store" or 1294 "PKCS #12 Certificate Data with Attributes", among others. 1295 It would be inappropriate to imply that such content 1296 contains keys or other secret materials. 1298 This parameter is case sensitive. 1300 Published specification: 1301 PKCS #12 v1.0, June 1999; PKCS #12 v1.1 (RFC 7292), July 2014 1302 [[RFC Ed: add reference to this document.]] 1304 Additional information: 1306 Deprecated alias names for this type: N/A 1307 Magic number(s): None. 1308 File extension(s): .p12 or .pfx; .p12c (in profile=certs-only case) 1309 Macintosh file type code(s): N/A 1311 Figure 5: application/pkcs12 Media Type Registration 1313 Appendix E proposes modifications to the application/cms media type 1314 to support SafeContents as a CMS inner content type. IANA is asked 1315 to update the CMS Inner Content Types sub-registry by adding an 1316 identifier "safeContents" with the object identifier listed in 1317 Appendix E. IANA is further asked to update the application/cms 1318 media type registration template accordingly. 1320 14. Security Considerations 1322 Digital certificates are important building blocks for 1323 authentication, integrity, authorization, and (occasionally) 1324 confidentiality services. Accordingly, identifying digital 1325 certificates incorrectly can have significant security ramifications. 1327 When using hash-based certspecs, the cryptographic hash algorithm 1328 MUST be implemented properly and SHOULD have no known attack vectors. 1329 For this reason, algorithms that are considered "broken" as of the 1330 date of this Internet-Draft, such as MD5 [RFC6151], are precluded 1331 from being valid certspecs. The registration of a particular 1332 algorithm spec in this namespace does NOT mean that it is acceptable 1333 or safe for every usage, even though this Internet-Draft requires 1334 that a conforming implementation MUST implement certain specs. 1336 When using content-based certspecs, the implementation MUST be 1337 prepared to process strings of arbitrary length. As of this writing, 1338 useful certificates rarely exceed 10KB, and most implementations are 1339 concerned with keeping certificate sizes down. However, a 1340 pathological or malicious certificate could easily exceed these 1341 metrics. 1343 When using element-based certspecs, the implementation MUST be 1344 prepared to deal with multiple found certificates that contain the 1345 same certificate data, but are not the same certificate. In such a 1346 case, the implementation MUST segregate these certificates so that 1347 the implementation only continues with certificates that it considers 1348 valid or trustworthy (as discussed further below). If, despite this 1349 segregation, multiple valid or trustworthy certificates match the 1350 certspec, the certspec (not in a multispec) MUST be rejected, because 1351 a certspec is meant to identify exactly one certificate (not a family 1352 of certificates). 1354 Certificates identified by certspecs should only be used with an 1355 analysis of their validity, such as by computing the Certification 1356 Path Validation Algorithm (Section 6 of [RFC5280]) or by other means. 1357 For example, if a certificate database contains a set of certificates 1358 that it considers inherently trustworthy, then the inclusion of a 1359 certificate in that set makes it trustworthy, regardless of the 1360 results of the Certification Path Validation Algorithm. Such a 1361 database is frequently used for "Root CA" lists. 1363 Conveying PKCS attributes with certificates will likely have security 1364 effects. For example, some implementations display the friendlyName 1365 attribute to a user on par with or in lieu of data derived from the 1366 certificate itself. Other implementations allow certificates to be 1367 identified by this friendlyName attribute. Therefore, blind 1368 acceptance of PKCS attributes without considering the source or 1369 content can result in security compromises. 1371 15. References 1373 15.1. Normative References 1375 [I-D.seantek-abnf-more-core-rules] 1376 Leonard, S., "Comprehensive Core Rules and References for 1377 ABNF", draft-seantek-abnf-more-core-rules-06 (work in 1378 progress), September 2016. 1380 [I-D.seantek-ldap-pkcs9] 1381 Leonard, S., "Lightweight Directory Access Protocol (LDAP) 1382 Registrations for PKCS #9", draft-seantek-ldap-pkcs9-05 1383 (work in progress), June 2016. 1385 [I-D.seantek-unicode-in-abnf] 1386 Leonard, S. and P. Kyzivat, "Unicode in ABNF", draft- 1387 seantek-unicode-in-abnf-00 (work in progress), September 1388 2016. 1390 [LDAPDESC] 1391 IANA, "LDAP Parameters: Object Identifier Descriptors", 1392 . 1395 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1396 Extensions (MIME) Part One: Format of Internet Message 1397 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1398 . 1400 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1401 Requirement Levels", BCP 14, RFC 2119, March 1997. 1403 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1404 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1405 . 1407 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1408 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1409 3986, January 2005. 1411 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 1412 (LDAP): Directory Information Models", RFC 4512, June 1413 2006. 1415 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 1416 (LDAP): String Representation of Distinguished Names", RFC 1417 4514, June 2006. 1419 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 1420 Considerations for the Lightweight Directory Access 1421 Protocol (LDAP)", BCP 64, RFC 4520, DOI 10.17487/RFC4520, 1422 June 2006, . 1424 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1425 Encodings", RFC 4648, October 2006. 1427 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1428 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1430 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1431 Housley, R., and W. Polk, "Internet X.509 Public Key 1432 Infrastructure Certificate and Certificate Revocation List 1433 (CRL) Profile", RFC 5280, May 2008. 1435 [RFC5750] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 1436 Mail Extensions (S/MIME) Version 3.2 Certificate 1437 Handling", RFC 5750, January 2010. 1439 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 1440 Attribute Certificate Profile for Authorization", RFC 1441 5755, January 2010. 1443 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1444 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 1445 RFC6570, March 2012, 1446 . 1448 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 1449 7405, DOI 10.17487/RFC7405, December 2014, 1450 . 1452 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 1453 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 1454 April 2015, . 1456 [SHS] National Institute of Standards and Technology, "Secure 1457 Hash Standard", Federal Information Processing Standard 1458 (FIPS) 180-4, March 2012, 1459 . 1462 15.2. Informative References 1464 [I-D.ietf-urnbis-rfc2141bis-urn] 1465 Saint-Andre, P. and J. Klensin, "Uniform Resource Names 1466 (URNs)", draft-ietf-urnbis-rfc2141bis-urn-17 (work in 1467 progress), June 2016. 1469 [PKCS11] RSA Laboratories, "PKCS #11 v2.30: Cryptographic Token 1470 Interface Standard", PKCS 11, April 2009. 1472 [PROVURI] IANA, "Uniform Resource Identifier (URI) Schemes: 1473 Provisional URI Schemes", 1474 . 1477 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1478 Mail: Part I: Message Encryption and Authentication 1479 Procedures", RFC 1421, February 1993. 1481 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 1482 Resource Locators (URL)", RFC 1738, December 1994. 1484 [RFC2253] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory 1485 Access Protocol (v3): UTF-8 String Representation of 1486 Distinguished Names", RFC 2253, December 1997. 1488 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1489 Classes and Attribute Types Version 2.0", RFC 2985, 1490 November 2000. 1492 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 1493 Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 1494 2006. 1496 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1497 RFC 5652, September 2009. 1499 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August 1500 2010. 1502 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 1503 URI Scheme", RFC 6068, October 2010. 1505 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1506 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1507 RFC 6151, March 2011. 1509 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1510 Keranen, A., and P. Hallam-Baker, "Naming Things with 1511 Hashes", RFC 6920, April 2013. 1513 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 1514 M. Scott, "PKCS #12: Personal Information Exchange Syntax 1515 v1.1", RFC 7292, July 2014. 1517 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 1518 8.0.0", ISBN 978-1-936213-10-8, August 2015. 1520 Mountain View, CA: The Unicode Consortium. 1522 [X.501] International Telecommunication Union, "Information 1523 technology - Open Systems Interconnection - The Directory: 1524 Models", ITU-T Recommendation X.501, ISO/IEC 9594-2, 1525 October 2012, . 1527 [X.680] International Telecommunication Union, "Information 1528 technology - Abstract Syntax Notation One (ASN.1): 1529 Specification of basic notation", ITU-T Recommendation 1530 X.680, ISO/IEC 8824-1, August 2015, . 1533 [X.690] International Telecommunication Union, "Information 1534 technology - ASN.1 encoding rules: Specification of Basic 1535 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1536 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1537 X.690, ISO/IEC 8825-1, August 2015, . 1540 [X.693] International Telecommunication Union, "Information 1541 technology - ASN.1 encoding rules: XML Encoding Rules 1542 (XER)", ITU-T Recommendation X.693, ISO/IEC 8825-4, August 1543 2015, . 1545 Appendix A. [[Omitted]] 1547 [[Omitted in this draft.]] 1549 Appendix B. Mandatory Attribute Descriptors for Distinguished Names 1551 As per [RFC4514], attribute descriptors case-insensitive. A 1552 conformant implementation MUST recognize the attributes in the table 1553 below when parsing certspecs containing distinguished names, both by 1554 the OIDs and by the names recorded in the LDAP Parameters: Object 1555 Identifier Descriptors registry [LDAPDESC]. A conforming generator 1556 SHOULD emit these attribute descriptors in lieu of their dotted 1557 decimal representations. 1559 +----------------------------+-------------------------------+------+ 1560 | OID | Names | RFC | 1561 +----------------------------+-------------------------------+------+ 1562 | 2.5.4.3 | cn (CN) | 4514 | 1563 | | commonName | | 1564 | 2.5.4.7 | l (L) | 4514 | 1565 | | localityName | | 1566 | 2.5.4.8 | st (ST) | 4514 | 1567 | | (S)* | | 1568 | | stateOrProvinceName | | 1569 | 2.5.4.10 | o (O) | 4514 | 1570 | | organizationName | | 1571 | 2.5.4.11 | ou (OU) | 4514 | 1572 | | organizationalUnitName | | 1573 | 2.5.4.6 | c (C) | 4514 | 1574 | | countryName | | 1575 | 2.5.4.9 | street (STREET) | 4514 | 1576 | | streetAddress | | 1577 | 0.9.2342.19200300.100.1.25 | dc (DC) | 4514 | 1578 | | domainComponent | | 1579 | 0.9.2342.19200300.100.1.1 | uid (UID) | 4514 | 1580 | | userId | | 1581 | 2.5.4.5 | serialNumber (SERIALNUMBER) | 5280 | 1582 | 2.5.4.46 | dnQualifier (DNQUALIFIER) | 5280 | 1583 | 2.5.4.4 | sn (SN) | 5280 | 1584 | | surname | | 1585 | 2.5.4.42 | gn (GN)** | 5280 | 1586 | | givenName | | 1587 | 2.5.4.12 | (T)* | 5280 | 1588 | | title | | 1589 | 2.5.4.43 | (I)* | 5280 | 1590 | | initials | | 1591 | 2.5.4.44 | (GENQUALIFIER)* | 5280 | 1592 | | generationQualifier | | 1593 | | (GENERATIONQUALIFIER) | | 1594 | 2.5.4.65 | (PNYM)* | 5280 | 1595 | | pseudonym (PSEUDONYM) | | 1596 | 1.2.840.113549.1.9.1 | (E)* | 5750 | 1597 | | emailAddress | | 1598 | | email | | 1599 +----------------------------+-------------------------------+------+ 1601 Names in parentheses are variations that are not assigned as such in 1602 [LDAPDESC]. Implementations MAY parse these names, but SHOULD NOT 1603 generate them. 1605 Names in ALL-CAPS may be emitted by some certificate-processing 1606 applications; these names are compatible with lowercase or mixed-case 1607 variations due to case-insensitivity. 1608 * Name may appear in some implementations, but is not in [LDAPDESC]. 1609 ** Name commonly appears in implementations, but is RESERVED in 1610 [LDAPDESC]. Conforming implementations MAY generate this name from 1611 2.5.4.42 and MUST parse this name as 2.5.4.42, despite its RESERVED 1612 status. 1614 Table 1: Attribute Descriptors 1616 Appendix C. Recommended Attribute Descriptors for issuersn certspec 1618 As per [RFC4514], attribute descriptors are case-insensitive. 1619 [[TODO: complete. Probably date of birth, place of birth, gender, 1620 etc. are already defined elsewhere.]] 1622 Appendix D. Suggested Algorithm for Distinguishing Textual Data 1624 This appendix provides an informative algorithm that implementations 1625 MAY use to content-sniff textual data. 1627 Some certspecs will return arbitrary data, which might be textual in 1628 nature. This is especially true of the file path and URI specs. 1629 There are historical reasons for this, mostly boiling down to "DER" 1630 vs. "PEM" output options in popular cryptographic software packages, 1631 without clear guidance on file extensions. 1633 The only BER-encoded PDUs that are mandated by this spec are 1634 Certificate [RFC5280], AttributeCertificate [RFC5755], and 1635 ContentInfo (containing SignedData) [RFC5652]. Before trying to do 1636 charset-sniffing, it is reasonable to probe for BER decoding first to 1637 see what happens. The (normative) algorithm in Section 6.5 is a 1638 sufficient test. At the very least, an implementation ought to check 1639 for the presence of the SEQUENCE octet (30h), a valid length that 1640 covers the length of the data, minus the tag and length octets, and 1641 two or three validly-encoded tag-length-value elements (Clause 8.1.1 1642 of [X.690]) inside the SEQUENCE. 1644 Although an implementation can ingest arbitrary text containing 1645 certificates, this specification only requires [RFC7468], which 1646 requires the presence of encapsulation boundaries. An implementation 1647 ought to look for Unicode byte order marks first; failing that, it 1648 ought to consider ASCII, basically ignoring invalid byte sequences 1649 that do not appear in [RFC7468] productions. Regardless of the 1650 charset(s) chosen, an implementation can hunt for the minimum string 1651 "-----BEGIN " followed somewhere by "-----END ", since those strings 1652 are required for [RFC7468] conformance. 1654 Appendix E. Binary Formats for Conveying Certificates with Attributes 1656 During the development of this document, the author noted that there 1657 is a lack of standardization around conveying attributes with 1658 certificates. The bulk of this specification can be used to convey 1659 such attributes in text; however, a binary format is also desirable. 1660 Because the attributes in Section 9 are semantically equivalent to 1661 PKCS #12 "bagAttributes", it makes sense to reuse this structure of 1662 PKCS #12, if possible. 1664 E.1. PKCS #12 certs-only Profile 1666 Predecessors to PKCS #12 have been criticized for being too obtuse 1667 and cumbersome to implement. This section proposes a profile of PKCS 1668 #12 for a degenerate case of the syntax that only conveys 1669 certificates and certificate revocation lists. It is analogous to 1670 the degenerate case of SignedData in CMS [RFC5652]. The overall 1671 usability goal is to convey certificates with attributes without 1672 requiring user input of secret or private material (i.e., a password 1673 or private key) to receive the data. The data MAY be signed for 1674 integrity protection, so long as verifying the signature does not 1675 require user input of secret or private material. 1677 To compose the degenerate case, the following structures in the "PFX" 1678 structure are limited: 1680 1. authSafe has contentType id-data or id-signedData (if signed), 1681 containing an AuthenticatedSafe. 1683 2. The AuthenticatedSafe SHALL contain exactly one ContentInfo, 1684 which has contentType id-data, containing a SafeContents. 1686 3. The SafeContents can contain any number of SafeBags. 1688 4. Each SafeBag can only contain a certificate (via certBag) or a 1689 certificate revocation list (via crlBag). 1691 5. macData SHALL be "ABSENT". 1693 [RFC7292] does not have an identifier for attribute certificates in 1694 the CertBag. The ASN.1 module is hereby modified to support 1695 attribute certificates: 1697 attributeCertificate BAG-TYPE ::= 1698 {OCTET STRING IDENTIFIED BY {certTypes 3}} -- 3 is TBD 1699 -- DER-encoded attribute certificate stored in OCTET STRING 1701 CertTypes BAG-TYPE ::= { 1702 x509Certificate | 1703 sdsiCertificate, 1704 ..., 1705 attributeCertificate, 1706 ... } 1708 Figure 6: PKCS #12 ASN.1 Module Modification 1710 Implementations MUST parse through certBag elements containing 1711 attribute certificates (MUST NOT fail parsing), but actually 1712 processing attribute certificates is OPTIONAL if an implementation 1713 has no need for them. (The same remarks apply to certificate 1714 revocation lists.) Because this profile does not use encryption or 1715 key derivation functions, conforming implementations do not need to 1716 support such algorithms, which should greatly simplify 1717 implementations. 1719 It is desirable to convey this degenerate PKCS #12 data in MIME 1720 entities and files. Since this format has very different usability 1721 properties from full-featured PKCS #12, it is not to be labeled as 1722 standard PKCS #12. A new "profile" optional parameter with value 1723 "certs-only" is proposed for the application/pkcs12 media type, as 1724 well as a new file extension .p12c. See Section 13 for the modified 1725 registration template. 1727 E.2. CMS SafeContents contentType 1729 Some applications will not want to bother with the PFX PDU of PKCS 1730 #12 at all. For those applications, it is possible to transmit 1731 SafeContents directly as CMS (PKCS #7) content. 1733 The CMS (TBD: or PKCS #12?) ASN.1 module is hereby enhanced to 1734 include an object identifier for SafeContents as a content type: 1736 IMPORTS 1737 SafeContents, bagtypes 1738 FROM PKCS-12 {1 2 840 113549 1 pkcs-12(12) modules(0) pkcs-12(1)} 1740 ContentSet CONTENT-TYPE ::= { 1741 -- Define the set of content types to be recognized. 1742 ct-Data | ct-SignedData | ct-EncryptedData | ct-EnvelopedData | 1743 ct-AuthenticatedData | ct-DigestedData | ct-SafeContents, ... } 1745 ct-SafeContents CONTENT-TYPE ::= 1746 { SafeContents IDENTIFIED BY id-safeContents } 1748 -- could be 1.2.840.113549.1.12.10.1.6 existing safeContentsBag OID, 1749 -- or a new 1.2.840.113549.1.12.10.2, 1750 -- or a new 1.2.840.113549.7.9 from PKCS #7, 1751 -- or a new 1.2.840.113549.1.9.16.1.37 from pkcs-9 smime ct 1752 id-safeContents OBJECT IDENTIFIER ::= {bagtypes 6} 1754 Figure 7: CMS ASN.1 Module Modification 1756 SafeContents is registered as a CMS Inner Content Type (ICT) with the 1757 identifier "safeContents". See Section 13 for the relevant 1758 registration and application/cms modification. 1760 Using this technique allows SafeContents directly in CMS content. 1761 Any kind of SafeBag is permitted inside; unlike Appendix E.1, this 1762 format is not further profiled. 1764 E.3. SafeContents-to-PKCS#12 BER Adapter 1766 An application that processes a SafeContents PDU directly may find it 1767 expedient to adapt it to a PFX PDU for ingestion into legacy code 1768 that only processes PKCS #12 data. The following adapter can be used 1769 for that purpose. Octets are listed in hexadecimal. Place the BER 1770 encoding of SafeContents in the position marked "(SafeContents)". 1771 The placeholders "LEN-" are [X.690] length octets, which are to be 1772 computed as follows: 1774 LEN-SC: The length in octets of the SafeContents. 1776 LEN-2: LEN-SC plus the length in octets of LEN-SC itself, plus 1. 1778 LEN-3: LEN-2 plus the length in octets of LEN-2 itself, plus 20. 1780 LEN-4: LEN-3 plus the length in octets of LEN-3 itself, plus 1. 1782 30 80 02 01 03 30 80 06092A864886F70D010701 A0 LEN-4 04 LEN-3 1783 30 80 30 80 06092A864886F70D010701 A0 LEN-2 04 LEN-SC 1784 (SafeContents) 1785 0000 0000 0000 0000 1787 Figure 8: BER Adapter 1789 Appendix F. Textual Encoding of Attributes 1791 From time to time, it is desirable to convey attributes independently 1792 of other PKIX, PKCS, or CMS structures. This appendix defines a 1793 textual encoding [RFC7468] format for attributes. 1795 Attributes are encoded using the "ATTRIBUTES" label. The encoded 1796 data MUST be a BER (DER strongly preferred; see Appendix B of 1797 [RFC7468]) encoded ASN.1 "SET OF Attribute", or, in rare cases, 1798 "SEQUENCE OF Attribute" structure as described throughout Directory, 1799 PKIX, PKCS, and CMS standards. Unless the collection is specifically 1800 ordered, emitting the "SET OF Attribute" variant is RECOMMENDED. 1802 No IETF document formally discusses what an attribute is (although 1803 [RFC4512] comes close). Workable definitions can be gleaned from 1804 [X.501] and [RFC4512]: 1806 Each attribute [in the Directory] provides a piece of information 1807 about, or describes a particular characteristic of, the object to 1808 which the entry corresponds. --Clause 8.2 of [X.501] 1810 An attribute consists of an _attribute type_, which identifies the 1811 class of information given by an attribute, and the corresponding 1812 _attribute values_, which are the particular instances of that 1813 class of information appearing in the attribute within the entry. 1814 --Clause 8.2 of [X.501] 1816 An entry [in the Directory] consists of a set of attributes that 1817 hold information about the object that the entry represents. 1818 --Section 2.2 of [RFC4512] 1820 An attribute is an attribute description (a type and zero or more 1821 options) with one or more associated values. An attribute is 1822 often referred to by its attribute description. --Section 2.2 of 1823 [RFC4512] 1825 An attribute is comprised of a type and a SET OF values. The 1826 collection of values is always unordered. Collections of attributes 1827 are almost always unordered, and are almost always stored in a 1828 "SET OF Attribute". A few protocols store attributes in a 1829 "SEQUENCE OF Attribute", but for nearly all cases, the ordering is 1830 stated to be irrelevant by the relevant standard document. 1832 The attribute type is a widely shared protocol element in LDAP/ 1833 Directory, PKIX, PKCS, and CMS standards. However, the collections 1834 of relevant attributes to particular occurrences of the structure (as 1835 represented by a table constraint on an occurence) are largely 1836 disjoint from one another. CMS attribute collections (e.g., 1837 "SignedAttributes", "UnsignedAttributes", "UnprotectedAttributes") 1838 share no common semantics with Directory attributes, for instance. 1839 The textual encoding provided in this section is appropriate for any 1840 collection of attributes, but only context can determine what kinds 1841 of attributes are appropriate, as well as the identity of the 1842 corresponding object. Figure 9 provides an example of the textual 1843 encoding, along with its corresponding Section 9 format. 1845 localKeyId=#0402534C,friendlyName=Chubby\F0\9F\90\B0 1846 -----BEGIN ATTRIBUTES----- 1847 MTQwEQYJKoZIhvcNAQkVMQQEAlNMMB8GCSqGSIb3DQEJFDESHhAAQwBoAHUAYgBi 1848 AHnYPdww 1849 -----END ATTRIBUTES----- 1851 Figure 9: Attributes Example 1853 Author's Address 1855 Sean Leonard 1856 Penango, Inc. 1857 5900 Wilshire Boulevard 1858 21st Floor 1859 Los Angeles, CA 90036 1860 USA 1862 Email: dev+ietf@seantek.com 1863 URI: http://www.penango.com/