idnits 2.17.1 draft-pechanec-pkcs11uri-12.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 1 instance 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 29, 2013) is 3917 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 4395 (Obsoleted by RFC 7595) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Pechanec 3 Internet-Draft D. Moffat 4 Intended status: Standards Track Oracle Corporation 5 Expires: January 30, 2014 July 29, 2013 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-12 10 Abstract 12 This memo specifies a PKCS#11 Uniform Resource Identifier (URI) 13 Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, for 14 identifying PKCS#11 tokens themselves, or for identifying PKCS#11 15 libraries. The URI is based on how PKCS#11 objects, tokens, and 16 libraries are identified in the PKCS#11 Cryptographic Token Interface 17 Standard. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 30, 2014. 36 Copyright Notice 38 Copyright (c) 2013 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . 3 56 3.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . 3 57 3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . 3 58 3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4 59 3.4. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 6 60 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 7 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 65 7.2. Informative References . . . . . . . . . . . . . . . . . 10 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 68 1. Introduction 70 The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec] 71 specifies an API, called Cryptoki, for devices which hold 72 cryptographic information and perform cryptographic functions. 73 Cryptoki, pronounced crypto-key and short for cryptographic token 74 interface, follows a simple object-based approach, addressing the 75 goals of technology independence (any kind of device may be used) and 76 resource sharing (multiple applications may access multiple devices), 77 presenting applications with a common, logical view of the device - a 78 cryptographic token. 80 It is desirable for applications or libraries that work with PKCS#11 81 tokens to accept a common identifier that consumers could use to 82 identify an existing PKCS#11 object in a PKCS#11 token, an existing 83 token itself, or an existing Cryptoki library. The set of object 84 types that can be stored in a PKCS#11 token includes a public key, a 85 private key, a certificate, a secret key, and a data object. These 86 objects can be uniquely identifiable via the PKCS#11 URI scheme 87 defined in this document. The set of attributes describing an object 88 can contain an object label, its type, and its ID. The set of 89 attributes that identifies a PKCS#11 token can contain a token label, 90 a manufacturer name, a serial number, and a token model. Attributes 91 that can identify a Cryptoki library are a library manufacturer, a 92 library description, and a library version. Library attributes may 93 be necessary to use if more than one PKCS#11 module provides a token 94 and/or PKCS#11 objects of the same name(s). 96 A subset of existing PKCS#11 structure members and object attributes 97 was chosen believed to be sufficient in uniquely identifying a 98 PKCS#11 token, object, or library in a configuration file, on a 99 command line, or in a configuration property of something else. 100 Should there be a need for a more complex information exchange on 101 PKCS#11 entities a different means of data marshalling should be 102 chosen accordingly. 104 A PKCS#11 URI is not intended to be used to create new PKCS#11 105 objects in tokens, or to create PKCS#11 tokens. It is solely to be 106 used to identify and work with existing objects, tokens, and Cryptoki 107 libraries through the PKCS#11 API. 109 The URI scheme defined in this document is designed specifically with 110 a mapping to the PKCS#11 API in mind. The URI uses only the scheme 111 and the path components which are required by the Uniform Resource 112 Identifier (URI): Generic Syntax [RFC3986]. The URI scheme does not 113 use the hierarchical element for a naming authority in the path since 114 the authority part could not be mapped to PKCS#11 API elements. The 115 URI scheme does not use the optional query and fragment elements. 117 If an application has no access to a producer or producers of the 118 PKCS#11 API it is left to its implementation to provide adequate user 119 interface to locate and load such producer(s). 121 2. Contributors 123 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 124 Jaroslav Imrich contributed to the development of this document. 126 3. PKCS#11 URI Scheme Definition 128 In accordance with [RFC4395], this section provides the information 129 required to register the PKCS#11 URI scheme. 131 3.1. PKCS#11 URI Scheme Name 133 pkcs11 135 3.2. PKCS#11 URI Scheme Status 136 Permanent. 138 3.3. PKCS#11 URI Scheme Syntax 140 The PKCS#11 URI scheme is a sequence of attribute value pairs 141 separated by a semicolon. In accordance with Section 2.5 of 142 [RFC3986], the data should first be encoded as octets according to 143 the UTF-8 character encoding [RFC3629]; then only those octets that 144 do not correspond to characters in the unreserved set or to permitted 145 characters from the reserved set should be percent-encoded. This 146 specification suggests one allowable exception to that rule for the 147 "id" attribute, as stated later in this section. Grammar rules 148 "unreserved" and "pct-encoded" in the PKCS#11 URI specification below 149 are imported from [RFC3986]. As a special case, note that according 150 to Appendix A of [RFC3986], a space must be percent-encoded. 152 PKCS#11 specification imposes various limitations on the value of 153 attributes, be it a more restrictive character set for the "serial" 154 attribute or fixed sized buffers for almost all the others, including 155 "token", "manufacturer", and "model" attributes. However, the 156 PKCS#11 URI notation does not impose such limitations aside from 157 removing generic and PKCS#11 URI delimiters from a permitted 158 character set. We believe that being too restrictive on the 159 attribute values could limit the PKCS#11 URI's usefulness. What is 160 more, possible future changes to the PKCS#11 specification should not 161 affect existing attributes. 163 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 164 [RFC5234]): 166 pk11-URI = "pkcs11" ":" pk11-identifier 167 pk11-identifier = *1(pk11-attr *(";" pk11-attr)) 168 pk11-attr = pk11-token / pk11-manuf / pk11-serial / 169 pk11-model / pk11-lib-manuf / 170 pk11-lib-ver / pk11-lib-desc / 171 pk11-object / pk11-object-type / pk11-id / 172 pk11-pin-source 173 ; Section 2.2 of RFC 3986 specifies that all potentially reserved 174 ; characters that do not conflict with actual delimiters of the URI 175 ; do not have to be percent-encoded. So, ";" was removed as a 176 ; sub-delimiter of the PKCS#11 URI's path and "/", "?", and "#" as 177 ; delimiters of generic URI components. 178 pk11-reserved-avail = ":" / "[" / "]" / "@" / "!" / "$" / 179 "&" / "'" / "(" / ")" / "*" / "+" / 180 "," / "=" 181 pk11-char = unreserved / pk11-reserved-avail / 182 pct-encoded 183 pk11-token = "token" "=" *pk11-char 184 pk11-manuf = "manufacturer" "=" *pk11-char 185 pk11-serial = "serial" "=" *pk11-char 186 pk11-model = "model" "=" *pk11-char 187 pk11-lib-manuf = "library-manufacturer" "=" *pk11-char 188 pk11-lib-desc = "library-description" "=" *pk11-char 189 pk11-lib-ver = "library-version" "=" 1*DIGIT *1("." 1*DIGIT) 190 pk11-object = "object" "=" *pk11-char 191 pk11-object-type = "object-type" "=" *1("public" / "private" / 192 "cert" / "secret-key" / "data") 193 pk11-id = "id" "=" *pk11-char 194 pk11-pin-source = "pin-source" "=" *pk11-char 196 More specifically, '/' delimiter of generic URI components was 197 removed from available characters that do not have to be percent- 198 encoded so that the initial part of a PKCS#11 URI is never confused 199 with "path-rootless" part of the "hier-part" generic URI component as 200 defined in Section 3 of [RFC3986]. Delimiters '?' and '#' of generic 201 URI components were removed to allow for possible future extensions 202 of the PKCS#11 URI. All other delimiters of generic URI components 203 are allowed to be used unencoded (':', '[', ']', and '@') in the 204 PKCS#11 URI. 206 The attribute "token" represents a token label and corresponds to the 207 "label" member of the CK_TOKEN_INFO structure, the attribute 208 "manufacturer" corresponds to the "manufacturerID" member of 209 CK_TOKEN_INFO, the attribute "serial" corresponds to the 210 "serialNumber" member of CK_TOKEN_INFO, the attribute "model" 211 corresponds to the "model" member of CK_TOKEN_INFO, the attribute 212 "library-manufacturer" represents the Cryptoki library manufacturer 213 and corresponds to the "manufacturerID" member of the CK_INFO 214 structure, the attribute "library-description" corresponds to the 215 "libraryDescription" member of CK_INFO, the attribute "library- 216 version" corresponds to the "libraryVersion" member of CK_INFO, the 217 attribute "object" represents a PKCS#11 object label and corresponds 218 to the "CKA_LABEL" object attribute, the attribute "object-type" 219 represents the type of the object and corresponds to the "CKA_CLASS" 220 object attribute, the attribute "id" represents the object ID and 221 corresponds to the "CKA_ID" object attribute, and the attribute "pin- 222 source" specifies where the application or library should find the 223 token PIN, if needed. 225 The PKCS#11 URI must not contain duplicate attributes of the same 226 name. It means that each attribute may be present at most once in a 227 PKCS#11 URI string. 229 The "pin-source" attribute may represent a filename that contains a 230 token PIN but an application may overload this attribute. For 231 example, "pin-source=%7Cprog-name" could mean to read a PIN from an 232 external application (%7C denotes a pipe '|' character). Note that 233 an application may always ask for a PIN and/or interpret the "pin- 234 source" attribute by any means it decides to. However, as discussed 235 in Section 6, the attribute should never contain the PIN itself. 237 It is recommended to percent-encode the whole value of the "id" 238 attribute which is supposed to be handled as arbitrary binary data. 239 Value "M" of the "library-version" attribute should be interpreted as 240 "M" for the major and "0" for the minor version of the library. Note 241 that if the "library-version" attribute is present, the major version 242 number is mandatory. 244 An empty PKCS#11 URI attribute that does allow for an empty value 245 matches a corresponding structure member or an object attribute with 246 an empty value. Note that according to the PKCS#11 specification 247 [pkcs11_spec], empty character values in a PKCS#11 producer must be 248 padded with spaces and should not be NULL terminated. 250 3.4. PKCS#11 URI Comparison 252 Comparison of two URIs is a way of determining whether the URIs are 253 equivalent without comparing the actual resource the URIs point to. 254 The comparison of URIs aims to minimize false negatives while 255 strictly avoiding false positives. 257 Two PKCS#11 URIs are said to be equal if URIs as character strings 258 are identical as specified in Section 6.2.1 of [RFC3986], or if both 259 following rules are fulfilled: 261 o set of attributes present in the URI is equal. Note that the 262 ordering of attributes in the URI string is not significant for 263 the mechanism of comparison. 265 o values of respective attributes are equal based on rules specified 266 below 268 The rules for comparing values of respective attributes are: 270 o values of attributes "library-description", "library- 271 manufacturer", "manufacturer", "model", "object", "object-type", 272 "serial", and "token" must be compared using a simple string 273 comparison as specified in Section 6.2.1 of [RFC3986] after the 274 case and the percent-encoding normalization are both applied as 275 specified in Section 6.2.2 of [RFC3986] 277 o value of attribute "id" must be compared using the simple string 278 comparison after all bytes are percent-encoded using uppercase 279 letters for digits A-F 281 o value for attribute "pin-source", if deemed containing the 282 filename with the PIN value, must be compared using the simple 283 string comparison after the full syntax based normalization as 284 specified in Section 6.2.2 of [RFC3986] is applied. If value of 285 the "pin-source" attribute is believed to be overloaded it is 286 recommended to perform case and percent-encoding normalization 287 before the values are compared but the exact mechanism of 288 comparison is left to the application. 290 o value of attribute "library-version" must be processed as a 291 specific scheme-based normalization permitted by Section 6.2.3 of 292 [RFC3986]. The value must be split into a major and minor version 293 with character '.' (dot) serving as a delimiter. Library version 294 "M" must be treated as "M" for the major version and "0" for the 295 minor version. Resulting minor and major version numbers must be 296 then separately compared numerically. 298 4. Examples of PKCS#11 URIs 300 This section contains some examples of how PKCS#11 token objects, 301 PKCS#11 tokens, and PKCS#11 libraries can be identified using the 302 PKCS#11 URI scheme. Note that in some of the following examples, 303 newlines and spaces were inserted for better readability. As 304 specified in Appendix C of [RFC3986], whitespace should be ignored 305 when extracting the URI. Also note that all spaces as part of the 306 URI are percent-encoded, as specified in Appendix A of [RFC3986]. 308 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 310 pkcs11: 312 One of the simplest and most useful forms might be a PKCS#11 URI that 313 specifies only an object label and its type. The default token is 314 used so the URI does not specify it. Note that when specifying 315 public objects, a token PIN might not be required. 317 pkcs11:object=my-pubkey;object-type=public 319 When a private key is specified either the "pin-source" attribute or 320 an application specific method would be usually used. Also note that 321 '/' must be percent-encoded in the "pin-source" attribute value since 322 it must be prevented to be mistaken for a path segment delimiter. 324 pkcs11:object=my-key;object-type=private; 325 pin-source=%2Fetc%2Ftoken_pin 327 The following example identifies a certificate in the software token. 328 Note an empty value for the attribute "serial". Also note that the 329 "id" attribute value is entirely percent-encoded, as recommended. 330 While ',' is in the reserved set it does not have to be percent- 331 encoded since it does not conflict with any sub-delimiters used. The 332 '#' character as in "The Software PKCS#11 Softtoken" is a general 333 delimiter as '/' so it must be percent-encoded, too. 335 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 336 manufacturer=Snake%20Oil,%20Inc.; 337 serial=; 338 model=1.0; 339 object=my-certificate; 340 object-type=cert; 341 id=%69%95%3E%5C%F4%BD%EC%91; 342 pin-source=%2Fetc%2Ftoken_pin 344 The token alone can be identified without specifying any PKCS#11 345 objects. A PIN may still be needed to list all objects, for example. 347 pkcs11:token=Software%20PKCS%2311%20softtoken; 348 manufacturer=Snake%20Oil,%20Inc.; 349 pin-source=%2Fetc%2Ftoken_pin 351 The Cryptoki library alone can be also identified without specifying 352 a PKCS#11 token or object. 354 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 355 library-description=Soft%20Token%20Library; 356 library-version=1.23 358 The following example shows that the attribute value can contain a 359 semicolon. In such case, it is percent-encoded. The token attribute 360 value must be read as "My token; created by Joe". Lower case letters 361 can also be used in percent-encoding as shown below in the "id" 362 attribute value but note that Sections 2.1 and 6.2.2.1 of [RFC3986] 363 read that all percent-encoded characters should use the uppercase 364 hexadecimal digits. More specifically, if the URI string was to be 365 compared, the algorithm defined in Section 3.4 explicitly requires 366 percent-encoding to use the uppercase digits A-F in the "id" 367 attribute values. And as explained in Section 3.3, library version 368 "3" should be interpreted as "3" for the major and "0" for the minor 369 version of the library. 371 pkcs11:token=My%20token%25%20created%20by%20Joe; 372 library-version=3 373 id=%01%02%03%Ba%dd%Ca%fe%04%05%06; 375 If there is any need to include literal "%;" substring, for example, 376 both characters must be escaped. The token value must be read as "A 377 name with a substring %;". 379 pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; 380 object=my-certificate; 381 object-type=cert; 382 pin-source=%2Fetc%2Ftoken_pin 384 The next example includes a small A with acute in the token name. It 385 must be encoded in octets according to the UTF-8 character encoding 386 and then percent-encoded. Given that a small A with acute is U+225 387 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 388 that is "%C3%A1" in percent-encoding. 390 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 391 object=my-certificate; 392 object-type=cert 394 5. IANA Considerations 396 This document moves the "pkcs11" URI scheme from the provisional to 397 the permanent URI scheme registry. The registration template for the 398 URI scheme is accessible on http://www.iana.org/assignments/uri- 399 schemes. 401 6. Security Considerations 403 There are general security considerations for URI schemes discussed 404 in Section 7 of [RFC3986]. 406 From those security considerations, Section 7.1 of [RFC3986] applies 407 since there is no guarantee that the same PKCS#11 URI will always 408 identify the same object, token, or a library in the future. 410 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 411 command line arguments to run applications, and those arguments can 412 be world readable on some systems. For that reasons, the URI 413 intentionally does not allow for specifying the PKCS#11 token PIN as 414 a URI attribute. 416 7. References 418 7.1. Normative References 420 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 421 10646", RFC 3629, STD 63, November 2003. 423 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 424 Resource Identifier (URI): Generic Syntax", RFC 3986, STD 425 66, January 2005. 427 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 428 Specifications: ABNF", RFC 5234, STD 68, January 2008. 430 7.2. Informative References 432 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 433 Registration Procedures for New URI Schemes", RFC 4395, 434 February 2006. 436 [pkcs11_spec] 437 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 438 Standard v2.20", June 2004. 440 Authors' Addresses 441 Jan Pechanec 442 Oracle Corporation 443 4180 Network Circle 444 Santa Clara CA 95054 445 USA 447 Email: Jan.Pechanec@Oracle.COM 448 URI: http://www.oracle.com 450 Darren J. Moffat 451 Oracle Corporation 452 Oracle Parkway 453 Thames Valley Park 454 Reading RG6 1RA 455 UK 457 Email: Darren.Moffat@Oracle.COM 458 URI: http://www.oracle.com