idnits 2.17.1 draft-seantek-certspec-08.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 (July 31, 2016) is 2825 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 692, but not defined == Unused Reference: 'RFC2119' is defined on line 1302, but no explicit reference was found in the text == Outdated reference: A later version (-08) exists of draft-seantek-abnf-more-core-rules-05 == 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') -- 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: 2 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 July 31, 2016 5 Expires: February 1, 2017 7 Textual Specification for Certificates and Attributes 8 draft-seantek-certspec-08 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 February 1, 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 . . . . . . . . . 9 64 6.2. Content-Based Specifications . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . 19 69 7.1. DBKEY (Reserved) . . . . . . . . . . . . . . . . . . . . 19 70 7.2. SELECT (Reserved) . . . . . . . . . . . . . . . . . . . . 19 71 8. Multiple certspecs (multispec) . . . . . . . . . . . . . . . 20 72 9. Attributes (pkcsattrs) . . . . . . . . . . . . . . . . . . . 20 73 9.1. ABNF . . . . . . . . . . . . . . . . . . . . . . . . . . 22 74 9.2. Mandatory Attribute Support . . . . . . . . . . . . . . . 22 75 9.3. Canonicalization . . . . . . . . . . . . . . . . . . . . 23 76 10. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . . 23 77 11. Guidelines for Extending certspec . . . . . . . . . . . . . . 24 78 12. Use of certspec in Systems . . . . . . . . . . . . . . . . . 25 79 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 80 14. Security Considerations . . . . . . . . . . . . . . . . . . . 26 81 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 82 15.1. Normative References . . . . . . . . . . . . . . . . . . 28 83 15.2. Informative References . . . . . . . . . . . . . . . . . 29 84 Appendix A. [[Omitted]] . . . . . . . . . . . . . . . . . . . . 31 85 Appendix B. Mandatory Attribute Descriptors for Distinguished 86 Names . . . . . . . . . . . . . . . . . . . . . . . 31 87 Appendix C. Recommended Attribute Descriptors for issuersn 88 certspec . . . . . . . . . . . . . . . . . . . . . . 33 89 Appendix D. Suggested Algorithm for Distinguishing Textual Data 33 90 Appendix E. Binary Formats for Conveying Certificates with 91 Attributes . . . . . . . . . . . . . . . . . . . . . 33 92 E.1. PKCS #12 certs-only Profile . . . . . . . . . . . . . . . 34 93 E.2. CMS SafeContents contentType . . . . . . . . . . . . . . 35 94 E.3. SafeContents-to-PKCS#12 BER Adapter . . . . . . . . . . . 36 95 Appendix F. Textual Encoding of Attributes . . . . . . . . . . . 36 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 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], and [I-D.seantek-abnf-more-core-rules]. 275 4. certstring Syntax 277 A certificate string ("certstring") is a string with a single 278 certspec (see Section 5) or multiple certspecs (a "multispec", see 279 Section 8), followed by an optional set of attributes ("pkcsattrs", 280 see Section 9). The string has the ABNF: 282 certstring = (certspec / multispec) [ "|" pkcsattrs ] 284 Figure 1: certstring ABNF 286 5. certspec Syntax 288 A certspec is a string that is intended to identify a single 289 certificate. A certspec has introducer characters followed by value 290 characters; these introducer characters MAY be part of the "value" of 291 the identifier. The ABNF is: 293 certspec = certspec-hash / certspec-content / certspec-el / 294 certspec-path 296 hexOctet = 2HEXDIG 298 certspec-hash = "SHA-1" ":" 20hexOctet / 299 "SHA-256" ":" 32hexOctet / 300 "SHA-384" ":" 48hexOctet / 301 "SHA-512" ":" 64hexOctet / 302 certspec-other-hash 304 certspec-other-hash = certspec-hash-type ":" certspec-hash-value 305 ; Proposal: Hash Function Textual Name registry hereby limited 306 ; to RFC 3986 scheme characters 307 certspec-hash-type = scheme 308 ; implication is that it must be at least 128 bits 309 certspec-hash-value = 16*hexOctet 311 certspec-content = ("HEX" / "BASE16") ":" 1*hexOctet / 312 "BASE64" ":" base64string 314 base64char = ALPHA / DIGIT / "+" / "/" 315 base64string = 1*(4base64char) 316 [ 3base64char "=" / 2base64char "==" ] 318 distinguishedName = distinguishedName@[RFC4514] 319 hexstring = hexstring@[RFC4514] 321 certspec-el = "ISSUERSN" ":" distinguishedName ";" serialNumber / 322 "SUBJECTEXP" ":" distinguishedName ";" certtime / 323 "HOLDEREXP" ":" holder ";" certtime / 324 "SKI" ":" 1*(hexOctet) 326 serialNumber = 1*hexOctet 328 holder = distinguishedName ";" serialNumber ["+" certspec-hash] / 329 ("SPKI" / "CERT" / numericoid ) "/" certspec-hash / 330 hexstring 332 ; see RFC 7405 for case-sensitive string support 333 certtime = date-fullyear date-month date-mday 334 time-hour time-minute time-second %s"Z" / 335 date-time-nosecfrac 337 ; see draft-seantek-abnf-more-core-rules 338 full-date = full-date@[RFC3339] 339 time-hour = time-hour@[RFC3339] 340 time-minute = time-minute@[RFC3339] 341 time-second = time-second@[RFC3339] 342 time-offset = time-offset@[RFC3339] 344 date-time-nosecfrac = full-date "T" time-hour ":" time-minute ":" 345 time-second time-offset 347 certspec-path = certspec-uri / certspec-file / certspec-reg 349 ; from RFC3986; RFC 6570 350 URI-reference = URI-reference@[RFC3986] 351 URI-Template = URI-Template@[RFC6570] 353 certspec-uri = "URI:" URI-reference / URI-Template 355 ; see POSIX, etc. 356 certspec-file = ("/" / "\" / [A-Z] ":" / 357 ("." / "..") ("/" / "\") / "~" / "%" / "$") 358 *filepathchar 360 ; BEYONDASCII is from draft-seantek-more-core-rules 361 filepathchar = %x01-29 / %x2B-3B / "=" / %x40-5B / 362 %x5D-7B / %x7D-7F / quoted-fpc / BEYONDASCII 364 quoted-fpc = "\" ("*" / "<" / ">" / "?" / "\" / "|") 366 ; TODO: validate Windows file path characters 368 certspec-reg = reg-hive 1*("\" reg-key) 369 ["\\" reg-value-name] 371 reg-hive = reg-local-hive / reg-remote-hive 372 reg-local-hive = "HKEY_LOCAL_MACHINE" / "HKEY_CURRENT_USER" / 373 "HKEY_CLASSES_ROOT" / "HKEY_USERS" / 374 "HKEY_CURRENT_CONFIG" / 375 "HKLM:" / "HKCU:" / "HKCR:" / 376 "HKU:" / "HKCC:" 377 ; TODO: better specify computer name; it could be a NETBIOS name...? 378 reg-remote-hive = "\\" reg-name@[RFC3986] "\" ("HKLM" / "HKU") ":" 380 ; escape < > |. Need to figure out if 7F is ok, also C0, C1, etc. 381 reg-key = 1*(%x20-3B / %x3D / %x3F-5B %x5D-7B / %x7D.7E / 382 "\<" / "\>" / "\|" / BEYONDASCII) 383 ; reg-value-name can be empty 384 reg-value-name = *(%x20-3B / %x3D / %x3F-7B / %x7D.7E / 385 "\<" / "\>" / "\|" / BEYONDASCII) 387 Figure 2: certspec ABNF 389 5.1. certspec Type and Value 391 Semantically, a certspec is comprised of its type and value. The 392 value is always provided, but the type is either explicitly declared, 393 or is inferred from the initial (introducer) characters in the type. 394 When types are explicitly provided, they are compared case- 395 insensitively. The certspec-value identifies the certificate 396 specification value. 398 Several certspecs use hexadecimal encodings of octets. Generally: if 399 the hex octets are malformed (whether in the source material, such as 400 the corresponding certificate element, or in the hex text), the 401 certspec is invalid. 403 6. Standard Certificate Specifications 405 Standard certificate specifications are intended for interchange as 406 intuitive (to users and developers) identifiers for individual 407 certificates. This section provides four cryptographic hash-based 408 certspecs, two content-based certspecs, three element-based 409 certspecs, and two path-based certspecs. 411 A standard algorithm 413 6.1. Cryptographic Hash-Based Specifications 415 A cryptographic hash or "fingerprint" of a certificate uniquely 416 identifies that certificate. For hash-based certspecs, the hash is 417 computed over the octets of the DER encoding of the certificate, 418 namely, the Certificate type in Section 4.1 of [RFC5280] and the 419 AttributeCertificate type in Section 4.1 of [RFC5755]. The certspec- 420 value is the hexadecimal encoding of the hash value octets. For 421 example, a 256-bit SHA-256 hash is represented by exactly 32 hex 422 octets, or 64 hex characters. The hexadecimal encoding is not case 423 sensitive. 425 A conforming generator SHALL emit only hexadecimal encoded data, 426 i.e., the characters A-F (case-insensitive) and 0-9. 428 A conforming parser SHALL accept value productions that contain the 429 following non-hex digits: whitespace, hyphen, and colon. A 430 conforming parser MAY accept values that contain other characters. 432 Conforming implementations to this Internet-Draft MUST process these 433 hash-based certspecs, unless security considerations dictate 434 otherwise. Acceptable reasons for refusing to process a certspec 435 include a) the local policy prohibits use of the hash, or b) the hash 436 has known cryptographic weaknesses, such as a preimage attacks, which 437 weaken the cryptographic uniqueness guarantees of the hash. 439 6.1.1. SHA-1 441 The introducer production is "SHA-1:". The hash is computed using 442 SHA-1 [SHS]. 444 6.1.2. SHA-256 446 The introducer production is "SHA-256:". The hash is computed using 447 SHA-256 [SHS]. 449 6.1.3. SHA-384 451 The introducer production is "SHA-384:". The hash is computed using 452 SHA-384 [SHS]. 454 6.1.4. SHA-512 456 The introducer production is "SHA-512:". The hash is computed using 457 SHA-512 [SHS]. 459 6.2. Content-Based Specifications 461 Content-based certspecs identify certificates by their constituent 462 octets. For small-to-medium certificates, identifying the 463 certificate by embedding it in the certspec will be computationally 464 efficient and resistant to denial-of-service attacks (by always being 465 available). A conforming implementation MUST implement base64 and 466 hex specs. 468 The octets of a certificate are the octets of the DER encoding of the 469 certificate, namely, the Certificate type in Section 4.1 of [RFC5280] 470 and the AttributeCertificate type in Section 4.1 of [RFC5755]. The 471 DER encoding includes tag and length octets, so it always starts with 472 30h (the tag for SEQUENCE) followed by any octet other than 80h (the 473 marker for indefinite length encoding). See also Section 6.5. 475 Because users may end up copying and pasting base64 or hex-encoded 476 certificates into certspecs, and because these certspecs will 477 routinely exceed 72 characters, a production might contain embedded 478 whitespace. A conforming generator SHALL emit no whitespace, or 479 SHALL emit a hanging indent, between semantically significant 480 characters. 482 6.2.1. BASE64 484 The introducer production is "BASE64:". The value production is the 485 BASE64 encoding of the certificate octets (Section 4 of [RFC4648]). 487 6.2.2. HEX and BASE16 489 The introducer production is "HEX:" or "BASE16:". Generators MUST 490 generate "HEX:"; parsers MUST accept "HEX:" and "BASE16:". The value 491 production is the hexadecimal encoding of the certificate octets. 493 6.3. Element-Based Specifications 495 A certificate may be identified by certain data elements contained 496 within it. The following certspecs reflect the traditional reliance 497 of PKIX [RFC5280] and CMS [RFC5652] on a certificate's issuer 498 distinguished name and serial number, a certificate's subject 499 distinguished name and expiration, or a certificate's subject key 500 identifier. 502 Note that distinguished names can contain "|" in attribute value 503 strings, but this production is unambiguous with the pkcsattrs 504 delimiter because distinguished names are always terminated by ";". 506 6.3.1. ISSUERSN: Issuer Name and Serial Number 508 The introducer production is "ISSUERSN:". 510 6.3.1.1. Issuer 512 The distinguishedName production encodes the certificate's issuer 513 distinguished name (DN) field in LDAP string format [RFC4514]. 514 [RFC4514] no longer separates relative distinguished names (RDNs) by 515 semicolons, as required by its predecessor, [RFC2253]. Accordingly, 516 ";" is used to separate the issuer's DN from the subject's serial 517 number. 519 6.3.1.2. Serial Number 521 The serialNumber production is the hexadecimal encoding the DER- 522 encoded contents octets of the CertificateSerialNumber (INTEGER, 523 i.e., not the type or length octets) as specified in Section 4.1.2.2 524 of [RFC5280]. 526 6.3.1.3. Conformance 528 A conforming implementation SHALL implement the ISSUERSN certspec. 529 An implementation MUST process serial numbers up to the same length 530 as required by Section 4.1.2.2 of [RFC5280] (20 octets), and MUST 531 process distinguished name strings as required by [RFC4514], 532 including the table of minimum AttributeType name strings that MUST 533 be recognized. Additionally, implementations MUST process attribute 534 descriptors specified in [RFC5280] (MUST or SHOULD), and [RFC5750] 535 (specifically: E, email, emailAddress). For reference, a complete 536 list of required attribute descriptors is provided in Appendix B. 537 Implementations are encouraged to recognize additional attribute 538 descriptors where possible. A sample list of such attribute 539 descriptors is provided in Appendix C. Conforming implementations 540 MUST be able to parse all distinguished name attribute types that are 541 encoded in OID dotted decimal form, as well as all distinguished name 542 attribute values that are encoded in "#" hexadecimal form. 544 6.3.2. SUBJECTEXP: Subject and Expiration 546 The SUBJECTEXP certspec only identifies certificates [RFC5280], not 547 attribute certificates [RFC5755]. The introducer production is 548 "SUBJECTEXP:". 550 6.3.2.1. Subject 552 The distinguishedName production encodes the certificate's subject 553 distinguished name (DN) field in LDAP string format [RFC4514]. 554 [RFC4514] no longer separates relative distinguished names (RDNs) by 555 semicolons, as required by its predecessor, [RFC2253]. Accordingly, 556 ";" is used to separate the subject's DN from the subject's 557 expiration (notAfter) date and time. 559 6.3.2.2. Expiration (notAfter) 561 The certificate's expiration is the notAfter value of the certificate 562 validity period (Section 4.1.2.5 of [RFC5280]). The production in 563 this certspec can be in one of two formats: GeneralizedTime or 564 [RFC3339] date-time. These forms are syntactically distinct. 566 The GeneralizedTime format from Clause 46 of [X.680] SHALL be with 567 four-digit years, no fractional seconds, and "Z" time (UTC or Zulu 568 time, with no time zone offset) in accordance with Section 4.1.2.5.2 569 of [RFC5280]. (The "Z" is case-sensitive, Clause 46.3 of [X.680].) 571 The [RFC3339] date-time format from [RFC3339] SHALL be with no 572 fractional seconds (time-secfrac omitted). 574 6.3.2.3. Conformance 576 A conforming implementation SHALL parse and generate distinguished 577 name productions with the same adherence as stated above in 578 Section 6.3.1.3. 580 A conforming implementation SHALL parse and generate all expiration 581 productions, including all four-digit years, and (for [RFC3339] only) 582 all time zone offsets. Time zone offsets in date-time productions 583 MUST be supported on usability grounds. Time zone offsets are not 584 permitted in GeneralizedTime because the flexible syntax is only 585 meant to support copy-and-paste operations with the underlying data 586 in the public key certificate [RFC5280]. 588 6.3.3. HOLDEREXP: Holder and Expiration 590 The HOLDEREXP certspec only identifies attribute certificates 591 [RFC5755], not certificates [RFC5280]. The introducer production is 592 "HOLDEREXP:". 594 6.3.3.1. Holder 596 The holder production encodes the attribute certificate's Holder 597 field [RFC5755]. Unfortunately, this field can get a bit complex. 599 The entire DER encoding of the Holder structure (including the tag 600 and length octets) can be encoded in LDAP hexadecimal form [RFC4514], 601 with "#" prepended. This amounts to a cop-out, but covers all cases. 603 When the Holder field identifies a public key certificate solely by 604 one issuer distinguished name, a serial number, and no issuerUID 605 (issuerUID is ABSENT), then the holder production SHALL be the 606 distinguished name in LDAP string form [RFC4514], a semicolon, and 607 the serial number in hexadecimal form. 609 When the Holder field identifies a holder solely by its object 610 digest, the digest algorithm does not include additional parameters, 611 and the objectDigest comprises an integral number of octets, then the 612 holder production SHALL be the digested object type, "/", the 613 algorithm identifier from the Hash Function Textual Names registry, 614 ":", and the hexadecimal encoding of the hash value (objectDigest) 615 octets. The case-insensitive digested object type can be "SPKI", 616 "CERT", or the dotted decimal representation of the 617 otherObjectTypeID. 619 [[NB: do we really need this? RFC 5755 says only one thing.]] When 620 the Holder field identifies a public key certificate by both of the 621 aforementioned sets of data (one issuer distinguished name, a serial 622 number, no issuerUID, and the public key certificate's fingerprint 623 with digestedObjectType set to publicKeyCert), then the Holder 624 production SHALL be first production, "+", the algorithm identifier, 625 and the hexadecimal encoding of the hash value (objectDigest) octets. 627 [[NB: Shall we include a string format for GeneralName, and then 628 GeneralNames?]] 630 6.3.3.2. Expiration (notAfter) 632 The attribute certificate's expiration is the notAfter value of the 633 attribute certificate validity period (Section 4.2.6 of [RFC5755]). 634 The production in this certspec is the same as Section 6.3.2.2. 636 6.3.3.3. Conformance 638 A conforming implementation SHALL parse and generate distinguished 639 name productions with the same adherence as stated above in 640 Section 6.3.1.3. 642 A conforming implementation SHALL parse and generate all expiration 643 productions, including all four-digit years, and (for [RFC3339] only) 644 all time zone offsets. Time zone offsets in date-time productions 645 MUST be supported on usability grounds. Time zone offsets are not 646 permitted in GeneralizedTime because the flexible syntax is only 647 meant to support copy-and-paste operations with the underlying data 648 in the attribute certificate [RFC5755]. 650 6.3.4. ski: Subject Key Identifier 652 The introducer production is "SKI:". The value production is the 653 hexadecimal encoding of the certificate's subject key identifier, 654 which is recorded in the certificate's Subject Key Identifier 655 extension (Section 4.2.1.2 of [RFC5280]). The octets are the DER- 656 encoded contents octets of the SubjectKeyIdentifier (OCTET STRING) 657 extension value. For a certificate that lacks a subject key 658 identifier, an underlying implementation MAY operatively associate a 659 subject key identifier with the certificate. 661 A conforming generator SHALL emit only hexadecimal encoded data, 662 i.e., the characters A-F (case-insensitive) and 0-9. 664 A conforming parser SHALL accept value productions that contain the 665 following non-hex digits: whitespace (HT, VT, SP, FF, CR, LF), 666 hyphen, and colon. A conforming parser MAY accept values that 667 contain other characters. 669 6.4. Path-Based Specifications 671 A certificate may be identified by a path to data. A conforming 672 parser MUST recognize file path, Registry, and URI specs, although 673 conforming implementations merely MAY process them. 675 Two common themes among path-based certspecs are that they may refer 676 to weakly typed or untyped data, and they have a higher probability 677 of referring to data that contains multiple certificates. Therefore, 678 a greater degree of content-sniffing is required for interoperability 679 than the certspecs above. An implementation that implements these 680 path-based certspecs SHALL support the ASN.1 Certificate PDU when 681 public key certificates are being retrieved, and the ASN.1 682 AttributeCertificate PDU when attribute certificates are being 683 retrieved. Additionally, a conforming implementation SHALL support 684 the ASN.1 ContentInfo (PKCS #7/CMS SignedData) PDU. 686 Untyped binary data may be encoded in a [X.690] transfer syntax, 687 which may be BER, CER, or DER; for purposes of this section, these 688 are all called "BER-encoded". 690 6.4.1. File Path 692 File paths are identified by their introducer productions / \ [A-Z]: 693 ./ ../ .\ ..\ ~ % and $. The characters that follow MUST be valid 694 path characters for the system on which the files are being accessed. 695 Since the starting character sequences for file paths are fixed and 696 determinable, prefixing the file path with a type identifier is 697 (thought to be) unnecessary. 699 A relative file path begins with "." or "..", and is relative to a 700 "current directory". Determining an appropriate "current directory" 701 is outside the scope of this specification. 703 When the file is read, implementations MUST accept the following, 704 regardless of the filename, which SHOULD NOT be the conclusive 705 determinant of the type: 707 1. Typed data (reported only by a minority of file systems), which 708 is treated conclusively as the type 710 2. Data that is determined to be textual, which is analyzed 711 according to [RFC7468] 713 3. Data that is determined to be BER-encoded 715 The manner of determining whether data is textual or BER-encoded data 716 is not fixed by this specification, but see, e.g., Appendix D. 718 File paths may have unexpanded environment variables, such as 719 %USERNAME% or ${LOGNAME}; implementations MUST parse these 720 environment variable syntaxes, but merely MAY perform environment 721 variable substitution as environment, capability, and security 722 concerns dictate. 724 Note that Unix-oriented file paths can contain "|" in the production 725 "\|", but this production is unambiguous with the pkcsattrs 726 delimiter. 728 6.4.2. Registry 730 Certificates can be identified on Windows machines with Registry keys 731 and values. The introducer productions for local Registry entries 732 are "HKEY_LOCAL_MACHINE\", "HKEY_CURRENT_USER\", 733 "HKEY_CLASSES_ROOT\", "HKEY_USERS\", "HKEY_CURRENT_CONFIG\", 734 "HKLM:\", "HKCU:\", "HKCR:\", "HKU:\", and "HKCC:\". The introducer 735 productions for remote Registry entries are "\\", followed by a 736 computer name, followed by either "\HKLM:\" or "\HKU:\". 738 Registry key names include any printable character except backslash 739 "\"; each key includes what amounts to an associative array of 740 values, which are name/type/data tuples. A value name can include 741 any printable character, including "<", ">", and "|"; additionally, 742 every key has a default value, which has a zero-length name. This 743 layout presents a couple of parsing challenges. 745 A Registry production is comprised of a key path followed by a value. 746 The key path's key names are delimited by "\". In each key name, 747 "<", ">", and "|" SHALL be escaped with a preceding "\". The value 748 name is delimited from the key name with two backslashes "\\". "<", 749 ">", "|", and "\" in the value SHALL be escaped with a preceding "\". 750 The default value MAY be identified with or without the two final 751 backslashes. Unlike file paths, Registry productions do not 752 recognize or substitute unexpanded environment variables. 754 Registry values have a type and some data. When the type is REG_SZ 755 or REG_EXPAND_SZ, an implementation is to treat the text as a 756 recursive certspec or multispec. If it is not a certspec or 757 multispec, then an implementation is to analyze the text according to 759 [RFC7468]. Text in REG_EXPAND_SZ is subject to environment variable 760 substitution. When the type is REG_BINARY, an implementation is to 761 determine if the data is BER-encoded, and if so, to analyze it for 762 supported ASN.1 PDUs. When the type is REG_LINK, an implementation 763 is to follow the symbolic link. 765 6.4.3. URI 767 The introducer production is "URI:". The value is a [RFC3986] 768 conforming URI-reference or [RFC6570] conforming URI-Template. 770 In the context of URIs, a relative reference conforms to the 771 relative-ref production of [RFC3986] and the usage described in 772 Section 4.2 of [RFC3986], it is relative to a "base URI". 773 Determining an appropriate "base URI" is outside the scope of this 774 specification. 776 When the URI is dereferenced, implementations MUST accept the 777 following, regardless of the path or query productions: 779 1. representations that are conclusively public key certificates or 780 attribute certificates, such as LDAP URIs [RFC4516] that point to 781 or contain userCertificate attributes (2.5.4.36, for public key 782 certificates) or attributeCertificate attributes (2.5.4.58, for 783 attribute certificates) 785 2. application/pkix-cert and application/pkix-attr-cert entities, 786 which are conclusively public key certificates or attribute 787 certificates, respectively 789 3. application/pkcs7-mime and application/cms entities, when the 790 body represents a ContentInfo/SignedData containing certificates 791 (regardless of the smime-type or encapsulatingContent parameters, 792 and regardless of whether or not the SignedData is in a 793 degenerate, certs-only format) 795 4. text/plain entities, which are analyzed according to [RFC7468] 797 5. Arbitrary data and application/octet-stream entities are treated 798 as untyped; they are are analyzed for textual or binary [X.690] 799 data 801 6. Arbitrary text, which is analyzed according to [RFC7468] 803 7. Arbitrary BER-encoded data, which is analyzed for supported ASN.1 804 PDUs 806 The URI certspec can include a fragment identifier. Implementations 807 MUST parse fragment identifiers, but merely MAY perform "secondary 808 resource" isolation and processing as environment, capability, and 809 security concerns dictate. 811 The URI certspec can be a URI Template [RFC6570]. Implementations 812 MUST parse URI templates, but merely MAY expand them in accordance 813 with [RFC6570] as environment, capability, and security concerns 814 dictate. 816 Note that URI templates can contain "|" in the production "{|".."}", 817 but this production is unambiguous with the pkcsattrs delimiter. 819 6.5. Algorithm for Distinguishing ASN.1 PDUs 821 A certspec can identify a public key certificate ("PKC") or an 822 attribute certificate ("AC"). When the type of certificate is 823 specified unambiguously in the source data, an implementation SHALL 824 follow the specifier in the source data. However, of the certspecs 825 listed in this document, only a subset of URIs are capable of 826 unambiguous specification (e.g., via Internet media type designation 827 of application/pkix-cert or application/pkix-attr-cert). Most other 828 certspecs will return a blob of bytes or characters. Therefore, an 829 implementation needs to perform some content-sniffing to figure out 830 what the data represents. There are two (not entirely orthogonal) 831 decisions: is the data textual [RFC7468] or not, and does the data 832 represent a PKC or AC? (Note: The content-based certspecs BASE64 and 833 HEX always represent one certificate; the encodings MUST NOT encode a 834 textual blob or a PKCS #7/CMS PDU.) 836 This section is normative, as it is based on standardized formats. 837 An implementation MAY use any algorithm it chooses, as long as it 838 produces the same results. 840 A suggested algorithm for distinguishing textual data is in 841 Appendix D; that algorithm is merely informative. 843 An implementation can use the following algorithm to choose between 844 the supported PDU types when encountering BER-encoded data: 846 1. Ensure that the first octet is SEQUENCE 30h. 848 2. Ensure that the length covers the length of the data, minus the 849 tag and length octets. (If the length is indefinite, a check 850 that the end of the data has the end-of-contents octets would be 851 appropriate.) Extraneous data SHALL be considered erroneous. 853 3. If there are 2 elements -> confirm that the first element is 854 OBJECT IDENTIFIER 1.2.840.113549.1.7.2 and the second element is 855 explicitly tagged (APPLICATION 0, A0). Analyze the PDU as a 856 ContentInfo containing SignedData. 858 4. Otherwise, ensure that there are 3 elements, and that the first 859 element is a SEQUENCE 30h (either AttributeCertificateInfo or 860 TBSCertificate). 862 5. this SEQUENCE has: 6, 7, or 7+ elements 864 6. if 6 elements -> Analyze the PDU as a Certificate (public key 865 certificate) with version v1 (ABSENT). 867 7. if 7+ elements -> 869 1. look at version field (first element) 871 2. if INTEGER (UNIVERSAL 2) -> Analyze the PDU as an 872 AttributeCertificate (attribute certificate) 874 3. if explicitly tagged (APPLICATION 0, A0) and the contents are 875 INTEGER (UNIVERSAL 2) -> Analyze the PDU as a Certificate 876 (public key certificate). 878 7. Other Certificate Specifications 880 The additional certificate specifications in this section are 881 provided for applications to use as local identifiers that are 882 useful, intuitive, or supportive of legacy systems or overriding 883 design goals. These certspecs SHOULD NOT be used for interchange. 885 7.1. DBKEY (Reserved) 887 The introducer production is "DBKEY:". The DBKEY certspec is meant 888 for an opaque string that serves as the unique key to a certificate 889 in an implementation's certificate database. This document reserves 890 this introducer sequence for future use. 892 7.2. SELECT (Reserved) 894 The introducer production is "SELECT" (without a colon). The SELECT 895 certspec is meant for a valid SQL statement (suitably escaped) that 896 retrieves a row representing a certificate. This document reserves 897 this introducer sequence for future use. 899 8. Multiple certspecs (multispec) 901 A multispec is a string that contains multiple certspecs, each of 902 which is intended to identify the exact same certificate. If 903 multiple certificates match a single spec, a single certificate can 904 be returned by the access operation, so long as the intersection of 905 certificates identified by all of the certspecs in the multispec is 906 one. The purpose of multispec is to provide multiple access and 907 verification methods. For example, a hash algorithm may have known 908 weaknesses, but may be the most efficient way to identify a 909 certificate (e.g., because it is the index method). Providing 910 additional certspecs (i.e., strong hash algorithms) would increase 911 the certainty that the correct certificate is accessed. 913 As the certspecs above make use of almost all other characters in the 914 ASCII range, < and > have been chosen to delimit certspecs between 915 each other. (Whitespace can also appear between each < and > 916 delimited certspec.) The ABNF of multispec is: 918 multispec = 1*("<" certspec ">") 920 Figure 3: multispec ABNF 922 9. Attributes (pkcsattrs) 924 This specification defines a textual format for PKCS attributes. 925 This format is not limited to certificates: it can be used with other 926 PKCS-related data. The syntax is intended primarily to convey 927 certificate-related attributes found in PKCS #9 [RFC2985], PKCS #11 928 [PKCS11], PKCS #12 [RFC7292], and particular implementations of 929 cryptographic libraries. These attributes are syntactically 930 identical to, but semantically disjoint from, Directory (X.500/LDAP) 931 attributes. 933 When pkcsattrs is used with a certspec or multispec, the intent is to 934 associate arbitrary metadata with a certificate--metadata that is not 935 intrinsic to that certificate. For example, the additional 936 attributes may represent preferences. Attributes in this context are 937 semantically equivalent to PKCS #12 "bagAttributes", drawn from the 938 "PKCS12AttrSet" [RFC7292]. 940 pkcsattrs are delimited from a certspec or multispec production with 941 "|". Each pkcsattr SHALL have a corresponding ASN.1 definition. The 942 textual syntax of pkcsattrs is very similar to (in fact, a superset 943 of) [RFC4514]: the pkcsattrs production represents the PKCS 944 Attributes family of types, which are repeatedly defined in those 945 standards, and standards that derive from them, as 946 SET SIZE (1..MAX) OF Attribute. E.g., CMS (from PKCS #7) [RFC5652], 947 private keys (from PKCS #8) [RFC5958], and PKCS #12 [RFC7292]. 948 Attributes are semantically unordered. Multiple attributes are 949 separated with ",". 951 Each attribute has a single attrType (canonically defined as OBJECT 952 IDENTIFIER in [RFC5652]), and a SET OF attrValues. The attrType is 953 encoded as the string representation of AttributeType (that is, 954 either a registered short name (descriptor) [RFC4520], or the dotted- 955 decimal encoding, of the OBJECT IDENTIFIER [RFC4512]). 957 When an attribute has at least one value, the attrType is followed by 958 "=" and the encoding of the attrValues (empty strings are possible). 959 Multiple attrValues are separated by "+". When the attribute has no 960 values, the attrType MUST NOT be followed by "=". 962 An attrValue can have one of several encodings: 964 hex: The attrValue can always be represented by "#" followed by the 965 hexadecimal encoding of each of the octets of the BER encoding of 966 the attrValue, following paragraph 1 of Section 2.4 of [RFC4514]. 967 Implementations MUST support this encoding. 969 string: If the attrValue has a LDAP-specific string encoding, that 970 encoding can be used as the string representation of the value, 971 with characters suitably escaped according to paragraph 2 and 972 onward of Section 2.4 of [RFC4514]. Implementations SHOULD 973 support this encoding for attributes of interest to it. 975 XER: The attrValue can be represented by its BASIC-XER encoding 976 [X.693] (Clause 8). When in BASIC-XER encoding, the string MUST 977 be a complete XML fragment comprising one element, i.e., there 978 SHALL NOT be an XML prolog. XER encoding is self-delimiting 979 because it has balanced elements; this string always begins with 980 "<" and ends with ">". Processing is simplified compared to 981 arbitrary XML in that XML processing instructions, XML comments, 982 and CDATA sections are prohibited. Implementations MUST support 983 parsing through this encoding, but merely MAY support this 984 encoding (encoding and decoding between [X.690]) for attributes of 985 interest to it. 987 ASN.1 value: The attrValue can be represented by its ASN.1 value 988 notation [X.680], enclosed in quotation marks <"> on both ends. 989 [[NB: per RFC 4514, a leading space might also be unambiguous.]] 990 ASN.1 value notation requires a bit of finesse in that <"> can 991 appear inside to delimit "cstring" lexical items (see Clause 12.14 992 and Clause 41 of [X.680]). A "cstring" starts and ends with <">, 993 and can represent <"> internally with a pair of consecutive <">. 994 Therefore, <"> is balanced because it always occurs in multiples 995 of two. If the value is just a cstring, then the representation 996 will have exactly two <"> at the beginning, and two <"> at the 997 end, with evenly-balanced <"> pairs inside. Other values that are 998 not composites (enclosed with "{" and "}") do not have <"> occur 999 within them. Otherwise, the representation must have at least one 1000 "{" "}" balanced pair at either end, hemming in <"> occurrences to 1001 within the balanced pairs of "{" and "}". Implementations MUST 1002 support parsing through this encoding, but merely MAY support this 1003 encoding (encoding and decoding between [X.690]) for attributes of 1004 interest to it. 1006 Of the attrValue encodings listed above, only "hex" can reliably 1007 transfer the underlying BER representation without an implementation 1008 maintaining specific knowledge of every attribute. Therefore, "hex" 1009 is RECOMMENDED for open interchange of pkcsattrs. The other 1010 representations are really meant for human production and 1011 consumption. 1013 9.1. ABNF 1015 The collective ABNF of pkcsattrs is: 1017 pkcsattrs = pkcsattr ["," pkcsattrs] 1018 pkcsattr = pkcsattrType ["=" pkcsattrValues] 1019 ; descr, numericoid from RFC 4512 1020 pkcsattrType = descr / numericoid 1021 pkcsattrValues = pkcsattrValue ["+" pkcsAttrValues] 1022 ; string, hexstring from RFC 4514 1023 pkcsattrValue = hexstring / string / 1024 basic-xer-string / asn1-value-string 1025 ; TODO: complete basic-xer-string, asn1-value-string 1026 basic-xer-string = "<" ">" 1027 ; TODO: may also distinguish with leading space " "--think about it 1028 asn1-value-string = %x22 %x22 1030 Figure 4: pkcsattrs ABNF 1032 9.2. Mandatory Attribute Support 1034 9.2.1. In General 1036 Attributes related to certificate objects are in the domain of PKCS 1037 attributes, not Directory name attributes. [I-D.seantek-ldap-pkcs9] 1038 discusses the problem and registers attributes that are specifically 1039 designated for PKCS use, rather than Directory use. 1041 A conforming implementation is expected to recognize the short names 1042 (descriptors) recorded in the LDAP Parameters: Object Identifier 1043 Descriptors registry [LDAPDESC] that are designated for PKCS use if 1044 the implementation processes that attribute. Not all attributes are 1045 needed by all implementations. For example, a CMS processing 1046 application that supports pkcsattrs needs to recognize contentType 1047 and messageDigest, but not extendedCertificateAttributes. 1049 9.2.2. For Certificate Applications 1051 A conforming implementation that supports pkcsattrs for certificates 1052 SHALL process the following attributes from PKCS #9 [RFC2985], 1053 including recognizing the following short names (descriptors) and 1054 associated LDAP-specific string encodings. 1056 friendlyName (1.2.840.113549.1.9.20) 1058 localKeyId (1.2.840.113549.1.9.21) 1060 signingDescription (1.2.840.113549.1.9.13) 1062 smimeCapabilities (1.2.840.113549.1.9.15) 1063 [[NB: smimeCapabilities does not have a SYNTAX with an LDAP- 1064 specific encoding. ASN.1 value notation is probably the most 1065 readable alternative, but support for ASN.1 value notation remains 1066 OPTIONAL.]] 1068 9.3. Canonicalization 1070 The pkcsattrs production is a textual encoding of the ASN.1 1071 SET SIZE (1..MAX) OF Attribute. The textual format in this section 1072 is not intended to be used as any kind of canonical form. The 1073 canonical form is the DER encoding of the corresponding 1074 SET SIZE (1..MAX) OF Attribute. 1076 10. Whitespace 1078 This specification is intended for textual data that may be visible 1079 to or edited by humans. Whitespace is a key factor in usability, so 1080 this specification permits whitespace in certain productions. 1082 The certspec, multispec, pkcsattrs, and certstring productions are 1083 ideally emitted as one (long) line. The overall intent is that a 1084 bare line break (without leading or trailing horizontal space) is 1085 supposed to delimit these productions from each other. 1087 If it is desirable to break one of these productions across multiple 1088 lines, a hanging indent SHALL be used at syntactically appropriate 1089 places. A hanging indent means a newline production (LF, CRLF, or 1090 other characters appropriate to the character set, e.g., [[UNICODE]]) 1091 followed by one or more horizontal space characters. The preferred 1092 horizontal space production is a single SP character. 1094 Generally, where whitespace is permitted, the whitespace either has 1095 no semantic meaning and therefore can be collapsed to a zero-length 1096 substring, i.e., skipped, or can be folded into a single whitespace 1097 character, i.e., a single SP. 1099 Productions that represent the hexadecimal (or base64) encodings of 1100 octets MAY have arbitrary whitespace interspersed between the 1101 hexadecimal (or base64) characters. The whitespace has no semantic 1102 meaning, and can be collapsed. Certspec and pkcsattrs parsers that 1103 parse "#" delimited attribute values in distinguished names and 1104 certificate attributes MAY accept and collapse whitespace; however, 1105 such whitespace is not permitted by [RFC4514]. Note that the 1106 attribute value MUST begin with "#"; there MUST NOT be leading 1107 whitespace. 1109 A parser MAY accept whitespace preceding the pkcsattrType production 1110 in pkcsattrs. 1112 A parser MAY accept whitespace between each angle-bracket-delimited 1113 certspec in the multispec production. 1115 A parser MAY accept whitespace preceding the attributeType production 1116 in distinguishedName. 1118 Generally, whitespace characters in values are otherwise considered 1119 to be semantically meaningful. A generator SHOULD encode such 1120 characters (e.g., with hexpair [RFC4514]) to avoid ambiguity or 1121 corruption. 1123 11. Guidelines for Extending certspec 1125 The certspec definition presented in this document is intended to be 1126 fairly comprehensive. Nevertheless, there are several points of 1127 extension for implementors who may want to identify a certificate 1128 with more than what is presented in this document. 1130 Firstly, certspec is naturally extended by supporting additional hash 1131 algorithms. The hash introducer characters are tied to the Hash 1132 Function Textual Names Registry; adding a new hash algorithm to that 1133 registry is necessary for certificates to get identified with that 1134 hash algorithm under this specification. However, for security 1135 reasons, the introducers "MD2" and "MD5" SHALL NOT be generated or 1136 parsed. 1138 Secondly, certspec allows for the full range of "local" identifiers 1139 (i.e., file paths, which may not actually be local) and "network" 1140 identifiers (i.e., URIs, which may not actually need the network). A 1141 certspec implementation that can make use of these facilities can 1142 naturally be extended by extending the path (e.g., with pipes and 1143 mount points) or the URI topology (e.g., with novel URI schemes). 1145 The ISSUERSN, SUBJECTEXP, and HOLDEREXP certspecs provide 1146 opportunities to identify the issuer, subject, or holder using 1147 multiple methods. An implementation MAY support other productions 1148 that equate to issuer certificates, subject identifiers, or holder 1149 sub-fields. 1151 Implementations MAY recognize other types of certspecs. However, new 1152 types intended for open interchange require an update to this 1153 document. 1155 A new certspec SHALL satisfy the following criteria: 1157 1. The type is identified by a keyword, followed by ":", or, the 1158 type is identified by very short sequences of characters that 1159 unambiguously signal the type of the certspec value (as file 1160 paths and Registry keys and values currently do). The 1161 specification MUST state whether the introducer characters are 1162 case-sensitive. 1164 2. The characters "<", ">", and "|" need to be distinguishable from 1165 their uses in multispec and pkcsattrs (certstring) using a 1166 context-free grammar, e.g., ABNF. 1168 3. [[TODO: further elaborate, or remove.]] If internal whitespace 1169 (including line-breaking) is permitted, the internal whitespace 1170 is consistent with this specification. 1172 12. Use of certspec in Systems 1174 certspec is useful wherever a system may need to include or refer to 1175 a certificate. Some systems may wish to refer to a certificate 1176 without enabling all of the expressive power (and security 1177 considerations) of all strings in this specification. Accordingly, 1178 those systems and specifications SHOULD develop profiles of this 1179 specification. 1181 This document guarantees that the introducer characters "URN:" and 1182 "CERT:" are RESERVED and will never be used. Implementors MUST take 1183 note that a raw certspec is not a valid URI: certspec-types are not 1184 registered URI schemes, have a broader character repertoire than 1185 permitted by [RFC3986], and do not have the same semantics as URIs. 1187 13. IANA Considerations 1189 Appendix E proposes modifications to the application/pkcs12 media 1190 type to support labeling a degenerate syntax that only contains 1191 certificates and certificate revocation lists. IANA is asked to 1192 update the fields of the application/pkcs12 registration as follows: 1194 Optional parameters: 1195 profile: A profile of PKCS #12 for particular applications. 1196 When this parameter has value "certs-only", then it conforms 1197 to the profile in Appendix E of [[RFC Ed: this document]]. 1198 If a filename is supplied, the file extension is to be .p12c; 1199 appropriate description strings (in US-English) might be 1200 "PKCS #12 Certificate Store" or 1201 "PKCS #12 Certificate Data with Attributes", among others. 1202 It would be inappropriate to imply that such content 1203 contains keys or other secret materials. 1205 This parameter is case sensitive. 1207 Published specification: 1208 PKCS #12 v1.0, June 1999; PKCS #12 v1.1 (RFC 7292), July 2014 1209 [[RFC Ed: add reference to this document.]] 1211 Additional information: 1213 Deprecated alias names for this type: N/A 1214 Magic number(s): None. 1215 File extension(s): .p12 or .pfx; .p12c (in profile=certs-only case) 1216 Macintosh file type code(s): N/A 1218 Figure 5: application/pkcs12 Media Type Registration 1220 Appendix E proposes modifications to the application/cms media type 1221 to support SafeContents as a CMS inner content type. IANA is asked 1222 to update the CMS Inner Content Types sub-registry by adding an 1223 identifier "safeContents" with the object identifier listed in 1224 Appendix E. IANA is further asked to update the application/cms 1225 media type registration template accordingly. 1227 14. Security Considerations 1229 Digital certificates are important building blocks for 1230 authentication, integrity, authorization, and (occasionally) 1231 confidentiality services. Accordingly, identifying digital 1232 certificates incorrectly can have significant security ramifications. 1234 When using hash-based certspecs, the cryptographic hash algorithm 1235 MUST be implemented properly and SHOULD have no known attack vectors. 1236 For this reason, algorithms that are considered "broken" as of the 1237 date of this Internet-Draft, such as MD5 [RFC6151], are precluded 1238 from being valid certspecs. The registration of a particular 1239 algorithm spec in this namespace does NOT mean that it is acceptable 1240 or safe for every usage, even though this Internet-Draft requires 1241 that a conforming implementation MUST implement certain specs. 1243 When using content-based certspecs, the implementation MUST be 1244 prepared to process strings of arbitrary length. As of this writing, 1245 useful certificates rarely exceed 10KB, and most implementations are 1246 concerned with keeping certificate sizes down. However, a 1247 pathological or malicious certificate could easily exceed these 1248 metrics. 1250 When using element-based certspecs, the implementation MUST be 1251 prepared to deal with multiple found certificates that contain the 1252 same certificate data, but are not the same certificate. In such a 1253 case, the implementation MUST segregate these certificates so that 1254 the implementation only continues with certificates that it considers 1255 valid or trustworthy (as discussed further below). If, despite this 1256 segregation, multiple valid or trustworthy certificates match the 1257 certspec, the certspec (not in a multispec) MUST be rejected, because 1258 a certspec is meant to identify exactly one certificate (not a family 1259 of certificates). 1261 Certificates identified by certspecs should only be used with an 1262 analysis of their validity, such as by computing the Certification 1263 Path Validation Algorithm (Section 6 of [RFC5280]) or by other means. 1264 For example, if a certificate database contains a set of certificates 1265 that it considers inherently trustworthy, then the inclusion of a 1266 certificate in that set makes it trustworthy, regardless of the 1267 results of the Certification Path Validation Algorithm. Such a 1268 database is frequently used for "Root CA" lists. 1270 Conveying PKCS attributes with certificates will likely have security 1271 effects. For example, some implementations display the friendlyName 1272 attribute to a user on par with or in lieu of data derived from the 1273 certificate itself. Other implementations allow certificates to be 1274 identified by this friendlyName attribute. Therefore, blind 1275 acceptance of PKCS attributes without considering the source or 1276 content can result in security compromises. 1278 15. References 1280 15.1. Normative References 1282 [I-D.seantek-abnf-more-core-rules] 1283 Leonard, S., "Comprehensive Core Rules and References for 1284 ABNF", draft-seantek-abnf-more-core-rules-05 (work in 1285 progress), March 2016. 1287 [I-D.seantek-ldap-pkcs9] 1288 Leonard, S., "Lightweight Directory Access Protocol (LDAP) 1289 Registrations for PKCS #9", draft-seantek-ldap-pkcs9-05 1290 (work in progress), June 2016. 1292 [LDAPDESC] 1293 IANA, "LDAP Parameters: Object Identifier Descriptors", 1294 . 1297 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1298 Extensions (MIME) Part One: Format of Internet Message 1299 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1300 . 1302 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1303 Requirement Levels", BCP 14, RFC 2119, March 1997. 1305 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1306 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1307 . 1309 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1310 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1311 3986, January 2005. 1313 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 1314 (LDAP): Directory Information Models", RFC 4512, June 1315 2006. 1317 [RFC4514] Zeilenga, K., "Lightweight Directory Access Protocol 1318 (LDAP): String Representation of Distinguished Names", RFC 1319 4514, June 2006. 1321 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 1322 Considerations for the Lightweight Directory Access 1323 Protocol (LDAP)", BCP 64, RFC 4520, DOI 10.17487/RFC4520, 1324 June 2006, . 1326 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1327 Encodings", RFC 4648, October 2006. 1329 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1330 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1332 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1333 Housley, R., and W. Polk, "Internet X.509 Public Key 1334 Infrastructure Certificate and Certificate Revocation List 1335 (CRL) Profile", RFC 5280, May 2008. 1337 [RFC5750] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 1338 Mail Extensions (S/MIME) Version 3.2 Certificate 1339 Handling", RFC 5750, January 2010. 1341 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 1342 Attribute Certificate Profile for Authorization", RFC 1343 5755, January 2010. 1345 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1346 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 1347 RFC6570, March 2012, 1348 . 1350 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 1351 7405, DOI 10.17487/RFC7405, December 2014, 1352 . 1354 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 1355 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 1356 April 2015, . 1358 [SHS] National Institute of Standards and Technology, "Secure 1359 Hash Standard", Federal Information Processing Standard 1360 (FIPS) 180-4, March 2012, 1361 . 1364 15.2. Informative References 1366 [I-D.ietf-urnbis-rfc2141bis-urn] 1367 Saint-Andre, P. and J. Klensin, "Uniform Resource Names 1368 (URNs)", draft-ietf-urnbis-rfc2141bis-urn-17 (work in 1369 progress), June 2016. 1371 [PKCS11] RSA Laboratories, "PKCS #11 v2.30: Cryptographic Token 1372 Interface Standard", PKCS 11, April 2009. 1374 [PROVURI] IANA, "Uniform Resource Identifier (URI) Schemes: 1375 Provisional URI Schemes", 1376 . 1379 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1380 Mail: Part I: Message Encryption and Authentication 1381 Procedures", RFC 1421, February 1993. 1383 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 1384 Resource Locators (URL)", RFC 1738, December 1994. 1386 [RFC2253] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory 1387 Access Protocol (v3): UTF-8 String Representation of 1388 Distinguished Names", RFC 2253, December 1997. 1390 [RFC2985] Nystrom, M. and B. Kaliski, "PKCS #9: Selected Object 1391 Classes and Attribute Types Version 2.0", RFC 2985, 1392 November 2000. 1394 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 1395 Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 1396 2006. 1398 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1399 RFC 5652, September 2009. 1401 [RFC5958] Turner, S., "Asymmetric Key Packages", RFC 5958, August 1402 2010. 1404 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 1405 URI Scheme", RFC 6068, October 2010. 1407 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1408 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1409 RFC 6151, March 2011. 1411 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 1412 Keranen, A., and P. Hallam-Baker, "Naming Things with 1413 Hashes", RFC 6920, April 2013. 1415 [RFC7292] Moriarty, K., Nystrom, M., Parkinson, S., Rusch, A., and 1416 M. Scott, "PKCS #12: Personal Information Exchange Syntax 1417 v1.1", RFC 7292, July 2014. 1419 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 1420 8.0.0", ISBN 978-1-936213-10-8, August 2015. 1422 Mountain View, CA: The Unicode Consortium. 1424 [X.501] International Telecommunication Union, "Information 1425 technology - Open Systems Interconnection - The Directory: 1426 Models", ITU-T Recommendation X.501, ISO/IEC 9594-2, 1427 October 2012, . 1429 [X.680] International Telecommunication Union, "Information 1430 technology - Abstract Syntax Notation One (ASN.1): 1431 Specification of basic notation", ITU-T Recommendation 1432 X.680, ISO/IEC 8824-1, August 2015, . 1435 [X.690] International Telecommunication Union, "Information 1436 technology - ASN.1 encoding rules: Specification of Basic 1437 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1438 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1439 X.690, ISO/IEC 8825-1, August 2015, . 1442 [X.693] International Telecommunication Union, "Information 1443 technology - ASN.1 encoding rules: XML Encoding Rules 1444 (XER)", ITU-T Recommendation X.693, ISO/IEC 8825-4, August 1445 2015, . 1447 Appendix A. [[Omitted]] 1449 [[Omitted in this draft.]] 1451 Appendix B. Mandatory Attribute Descriptors for Distinguished Names 1453 As per [RFC4514], attribute descriptors case-insensitive. A 1454 conformant implementation MUST recognize the attributes in the table 1455 below when parsing certspecs containing distinguished names, both by 1456 the OIDs and by the names recorded in the LDAP Parameters: Object 1457 Identifier Descriptors registry [LDAPDESC]. A conforming generator 1458 SHOULD emit these attribute descriptors in lieu of their dotted 1459 decimal representations. 1461 +----------------------------+-------------------------------+------+ 1462 | OID | Names | RFC | 1463 +----------------------------+-------------------------------+------+ 1464 | 2.5.4.3 | cn (CN) | 4514 | 1465 | | commonName | | 1466 | 2.5.4.7 | l (L) | 4514 | 1467 | | localityName | | 1468 | 2.5.4.8 | st (ST) | 4514 | 1469 | | (S)* | | 1470 | | stateOrProvinceName | | 1471 | 2.5.4.10 | o (O) | 4514 | 1472 | | organizationName | | 1473 | 2.5.4.11 | ou (OU) | 4514 | 1474 | | organizationalUnitName | | 1475 | 2.5.4.6 | c (C) | 4514 | 1476 | | countryName | | 1477 | 2.5.4.9 | street (STREET) | 4514 | 1478 | | streetAddress | | 1479 | 0.9.2342.19200300.100.1.25 | dc (DC) | 4514 | 1480 | | domainComponent | | 1481 | 0.9.2342.19200300.100.1.1 | uid (UID) | 4514 | 1482 | | userId | | 1483 | 2.5.4.5 | serialNumber (SERIALNUMBER) | 5280 | 1484 | 2.5.4.46 | dnQualifier (DNQUALIFIER) | 5280 | 1485 | 2.5.4.4 | sn (SN) | 5280 | 1486 | | surname | | 1487 | 2.5.4.42 | gn (GN)** | 5280 | 1488 | | givenName | | 1489 | 2.5.4.12 | (T)* | 5280 | 1490 | | title | | 1491 | 2.5.4.43 | (I)* | 5280 | 1492 | | initials | | 1493 | 2.5.4.44 | (GENQUALIFIER)* | 5280 | 1494 | | generationQualifier | | 1495 | | (GENERATIONQUALIFIER) | | 1496 | 2.5.4.65 | (PNYM)* | 5280 | 1497 | | pseudonym (PSEUDONYM) | | 1498 | 1.2.840.113549.1.9.1 | (E)* | 5750 | 1499 | | emailAddress | | 1500 | | email | | 1501 +----------------------------+-------------------------------+------+ 1503 Names in parentheses are variations that are not assigned as such in 1504 [LDAPDESC]. Implementations MAY parse these names, but SHOULD NOT 1505 generate them. 1506 Names in ALL-CAPS may be emitted by some certificate-processing 1507 applications; these names are compatible with lowercase or mixed-case 1508 variations due to case-insensitivity. 1509 * Name may appear in some implementations, but is not in [LDAPDESC]. 1510 ** Name commonly appears in implementations, but is RESERVED in 1511 [LDAPDESC]. Conforming implementations MAY generate this name from 1512 2.5.4.42 and MUST parse this name as 2.5.4.42, despite its RESERVED 1513 status. 1515 Table 1: Attribute Descriptors 1517 Appendix C. Recommended Attribute Descriptors for issuersn certspec 1519 As per [RFC4514], attribute descriptors are case-insensitive. 1520 [[TODO: complete. Probably date of birth, place of birth, gender, 1521 etc. are already defined elsewhere.]] 1523 Appendix D. Suggested Algorithm for Distinguishing Textual Data 1525 This appendix provides an informative algorithm that implementations 1526 MAY use to content-sniff textual data. 1528 Some certspecs will return arbitrary data, which might be textual in 1529 nature. This is especially true of the file path and URI specs. 1530 There are historical reasons for this, mostly boiling down to "DER" 1531 vs. "PEM" output options in popular cryptographic software packages, 1532 without clear guidance on file extensions. 1534 The only BER-encoded PDUs that are mandated by this spec are 1535 Certificate [RFC5280], AttributeCertificate [RFC5755], and 1536 ContentInfo (containing SignedData) [RFC5652]. Before trying to do 1537 charset-sniffing, it is reasonable to probe for BER decoding first to 1538 see what happens. The (normative) algorithm in Section 6.5 is a 1539 sufficient test. At the very least, an implementation ought to check 1540 for the presence of the SEQUENCE octet (30h), a valid length that 1541 covers the length of the data, minus the tag and length octets, and 1542 two or three validly-encoded tag-length-value elements (Clause 8.1.1 1543 of [X.690]) inside the SEQUENCE. 1545 Although an implementation can ingest arbitrary text containing 1546 certificates, this specification only requires [RFC7468], which 1547 requires the presence of encapsulation boundaries. An implementation 1548 ought to look for Unicode byte order marks first; failing that, it 1549 ought to consider ASCII, basically ignoring invalid byte sequences 1550 that do not appear in [RFC7468] productions. Regardless of the 1551 charset(s) chosen, an implementation can hunt for the minimum string 1552 "-----BEGIN " followed somewhere by "-----END ", since those strings 1553 are required for [RFC7468] conformance. 1555 Appendix E. Binary Formats for Conveying Certificates with Attributes 1557 During the development of this document, the author noted that there 1558 is a lack of standardization around conveying attributes with 1559 certificates. The bulk of this specification can be used to convey 1560 such attributes in text; however, a binary format is also desirable. 1561 Because the attributes in Section 9 are semantically equivalent to 1562 PKCS #12 "bagAttributes", it makes sense to reuse this structure of 1563 PKCS #12, if possible. 1565 E.1. PKCS #12 certs-only Profile 1567 Predecessors to PKCS #12 have been criticized for being too obtuse 1568 and cumbersome to implement. This section proposes a profile of PKCS 1569 #12 for a degenerate case of the syntax that only conveys 1570 certificates and certificate revocation lists. It is analogous to 1571 the degenerate case of SignedData in CMS [RFC5652]. The overall 1572 usability goal is to convey certificates with attributes without 1573 requiring user input of secret or private material (i.e., a password 1574 or private key) to receive the data. The data MAY be signed for 1575 integrity protection, so long as verifying the signature does not 1576 require user input of secret or private material. 1578 To compose the degenerate case, the following structures in the "PFX" 1579 structure are limited: 1581 1. authSafe has contentType id-data or id-signedData (if signed), 1582 containing an AuthenticatedSafe. 1584 2. The AuthenticatedSafe SHALL contain exactly one ContentInfo, 1585 which has contentType id-data, containing a SafeContents. 1587 3. The SafeContents can contain any number of SafeBags. 1589 4. Each SafeBag can only contain a certificate (via certBag) or a 1590 certificate revocation list (via crlBag). 1592 5. macData SHALL be "ABSENT". 1594 [RFC7292] does not have an identifier for attribute certificates in 1595 the CertBag. The ASN.1 module is hereby modified to support 1596 attribute certificates: 1598 attributeCertificate BAG-TYPE ::= 1599 {OCTET STRING IDENTIFIED BY {certTypes 3}} -- 3 is TBD 1600 -- DER-encoded attribute certificate stored in OCTET STRING 1602 CertTypes BAG-TYPE ::= { 1603 x509Certificate | 1604 sdsiCertificate, 1605 ..., 1606 attributeCertificate, 1607 ... } 1609 Figure 6: PKCS #12 ASN.1 Module Modification 1611 Implementations MUST parse through certBag elements containing 1612 attribute certificates (MUST NOT fail parsing), but actually 1613 processing attribute certificates is OPTIONAL if an implementation 1614 has no need for them. (The same remarks apply to certificate 1615 revocation lists.) Because this profile does not use encryption or 1616 key derivation functions, conforming implementations do not need to 1617 support such algorithms, which should greatly simplify 1618 implementations. 1620 It is desirable to convey this degenerate PKCS #12 data in MIME 1621 entities and files. Since this format has very different usability 1622 properties from full-featured PKCS #12, it is not to be labeled as 1623 standard PKCS #12. A new "profile" optional parameter with value 1624 "certs-only" is proposed for the application/pkcs12 media type, as 1625 well as a new file extension .p12c. See Section 13 for the modified 1626 registration template. 1628 E.2. CMS SafeContents contentType 1630 Some applications will not want to bother with the PFX PDU of PKCS 1631 #12 at all. For those applications, it is possible to transmit 1632 SafeContents directly as CMS (PKCS #7) content. 1634 The CMS (TBD: or PKCS #12?) ASN.1 module is hereby enhanced to 1635 include an object identifier for SafeContents as a content type: 1637 IMPORTS 1638 SafeContents, bagtypes 1639 FROM PKCS-12 {1 2 840 113549 1 pkcs-12(12) modules(0) pkcs-12(1)} 1641 ContentSet CONTENT-TYPE ::= { 1642 -- Define the set of content types to be recognized. 1643 ct-Data | ct-SignedData | ct-EncryptedData | ct-EnvelopedData | 1644 ct-AuthenticatedData | ct-DigestedData | ct-SafeContents, ... } 1646 ct-SafeContents CONTENT-TYPE ::= 1647 { SafeContents IDENTIFIED BY id-safeContents } 1649 -- could be 1.2.840.113549.1.12.10.1.6 existing safeContentsBag OID, 1650 -- or a new 1.2.840.113549.1.12.10.2, 1651 -- or a new 1.2.840.113549.7.9 from PKCS #7, 1652 -- or a new 1.2.840.113549.1.9.16.1.37 from pkcs-9 smime ct 1653 id-safeContents OBJECT IDENTIFIER ::= {bagtypes 6} 1655 Figure 7: CMS ASN.1 Module Modification 1657 SafeContents is registered as a CMS Inner Content Type (ICT) with the 1658 identifier "safeContents". See Section 13 for the relevant 1659 registration and application/cms modification. 1661 Using this technique allows SafeContents directly in CMS content. 1662 Any kind of SafeBag is permitted inside; unlike Appendix E.1, this 1663 format is not further profiled. 1665 E.3. SafeContents-to-PKCS#12 BER Adapter 1667 An application that processes a SafeContents PDU directly may find it 1668 expedient to adapt it to a PFX PDU for ingestion into legacy code 1669 that only processes PKCS #12 data. The following adapter can be used 1670 for that purpose. Octets are listed in hexadecimal. Place the BER 1671 encoding of SafeContents in the position marked "(SafeContents)". 1672 The placeholders "LEN-" are [X.690] length octets, which are to be 1673 computed as follows: 1675 LEN-SC: The length in octets of the SafeContents. 1677 LEN-2: LEN-SC plus the length in octets of LEN-SC itself, plus 1. 1679 LEN-3: LEN-2 plus the length in octets of LEN-2 itself, plus 20. 1681 LEN-4: LEN-3 plus the length in octets of LEN-3 itself, plus 1. 1683 30 80 02 01 03 30 80 06092A864886F70D010701 A0 LEN-4 04 LEN-3 1684 30 80 30 80 06092A864886F70D010701 A0 LEN-2 04 LEN-SC 1685 (SafeContents) 1686 0000 0000 0000 0000 1688 Figure 8: BER Adapter 1690 Appendix F. Textual Encoding of Attributes 1692 From time to time, it is desirable to convey attributes independently 1693 of other PKIX, PKCS, or CMS structures. This appendix defines a 1694 textual encoding [RFC7468] format for attributes. 1696 Attributes are encoded using the "ATTRIBUTES" label. The encoded 1697 data MUST be a BER (DER strongly preferred; see Appendix B of 1698 [RFC7468]) encoded ASN.1 "SET OF Attribute", or, in rare cases, 1699 "SEQUENCE OF Attribute" structure as described throughout Directory, 1700 PKIX, PKCS, and CMS standards. Unless the collection is specifically 1701 ordered, emitting the "SET OF Attribute" variant is RECOMMENDED. 1703 No IETF document formally discusses what an attribute is (although 1704 [RFC4512] comes close). Workable definitions can be gleaned from 1705 [X.501] and [RFC4512]: 1707 Each attribute [in the Directory] provides a piece of information 1708 about, or describes a particular characteristic of, the object to 1709 which the entry corresponds. --Clause 8.2 of [X.501] 1711 An attribute consists of an _attribute type_, which identifies the 1712 class of information given by an attribute, and the corresponding 1713 _attribute values_, which are the particular instances of that 1714 class of information appearing in the attribute within the entry. 1715 --Clause 8.2 of [X.501] 1717 An entry [in the Directory] consists of a set of attributes that 1718 hold information about the object that the entry represents. 1719 --Section 2.2 of [RFC4512] 1721 An attribute is an attribute description (a type and zero or more 1722 options) with one or more associated values. An attribute is 1723 often referred to by its attribute description. --Section 2.2 of 1724 [RFC4512] 1726 An attribute is comprised of a type and a SET OF values. The 1727 collection of values is always unordered. Collections of attributes 1728 are almost always unordered, and are almost always stored in a 1729 "SET OF Attribute". A few protocols store attributes in a 1730 "SEQUENCE OF Attribute", but for nearly all cases, the ordering is 1731 stated to be irrelevant by the relevant standard document. 1733 The attribute type is a widely shared protocol element in LDAP/ 1734 Directory, PKIX, PKCS, and CMS standards. However, the collections 1735 of relevant attributes to particular occurrences of the structure (as 1736 represented by a table constraint on an occurence) are largely 1737 disjoint from one another. CMS attribute collections (e.g., 1738 "SignedAttributes", "UnsignedAttributes", "UnprotectedAttributes") 1739 share no common semantics with Directory attributes, for instance. 1740 The textual encoding provided in this section is appropriate for any 1741 collection of attributes, but only context can determine what kinds 1742 of attributes are appropriate, as well as the identity of the 1743 corresponding object. Figure 9 provides an example of the textual 1744 encoding, along with its corresponding Section 9 format. 1746 localKeyId=#0402534C,friendlyName=Chubby\F0\9F\90\B0 1747 -----BEGIN ATTRIBUTES----- 1748 MTQwEQYJKoZIhvcNAQkVMQQEAlNMMB8GCSqGSIb3DQEJFDESHhAAQwBoAHUAYgBi 1749 AHnYPdww 1750 -----END ATTRIBUTES----- 1752 Figure 9: Attributes Example 1754 Author's Address 1756 Sean Leonard 1757 Penango, Inc. 1758 5900 Wilshire Boulevard 1759 21st Floor 1760 Los Angeles, CA 90036 1761 USA 1763 Email: dev+ietf@seantek.com 1764 URI: http://www.penango.com/