idnits 2.17.1 draft-pechanec-pkcs11uri-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 21, 2013) is 4053 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 (~~), 1 warning (==), 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. J. Moffat 4 Intended status: Standards Track Oracle Corporation 5 Expires: September 22, 2013 March 21, 2013 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-09 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 September 22, 2013. 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 . . . . . . . . . . . . . . . . 3 59 3.4. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 6 60 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 7 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 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, or an 83 existing token itself, or an existing Cryptoki library. The set of 84 object types that can be stored in a PKCS#11 token includes a public 85 key, a private key, a certificate, a secret key, and a data object. 86 These 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 Note that the PKCS#11 URI is not intended to be used to create new 97 PKCS#11 objects in tokens, or to create PKCS#11 tokens. It is solely 98 to be used to identify and work with existing objects, tokens, and 99 Cryptoki libraries through PKCS#11 API. 101 The URI scheme defined in this document is designed specifically with 102 a mapping to the PKCS#11 API in mind. The URI uses only the scheme 103 and the path components which are required by the Uniform Resource 104 Identifier (URI): Generic Syntax [RFC3986]. The URI scheme does not 105 use the hierarchical element for a naming authority in the path since 106 the authority part could not be mapped to PKCS#11 API elements. The 107 URI scheme does not use the optional query and fragment elements. 109 If an application has no access to a producer or producers of the 110 PKCS#11 API it is left to its implementation to provide adequate user 111 interface to locate and load such producer(s). 113 2. Contributors 115 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 116 Jaroslav Imrich contributed to the development of this document. 118 3. PKCS#11 URI Scheme Definition 120 In accordance with [RFC4395], this section provides the information 121 required to register the PKCS#11 URI scheme. 123 3.1. PKCS#11 URI Scheme Name 125 pkcs11 127 3.2. PKCS#11 URI Scheme Status 129 Permanent. 131 3.3. PKCS#11 URI Scheme Syntax 133 The PKCS#11 URI scheme is a sequence of attribute value pairs 134 separated by a semicolon. In accordance with Section 2.5 of 135 [RFC3986], the data should first be encoded as octets according to 136 the UTF-8 character encoding [RFC3629]; then only those octets that 137 do not correspond to characters in the unreserved set or to permitted 138 characters from the reserved set should be percent-encoded. This 139 specification suggests one allowable exception to that rule for the 140 "id" attribute, as stated later in this section. Grammar rules 141 "unreserved" and "pct-encoded" in the PKCS#11 URI specification below 142 were imported from [RFC3986]. As a special case, note that according 143 to Appendix A of [RFC3986], a space must be percent-encoded. 145 PKCS#11 specification imposes various limitations on the value of 146 attributes, be it a more restrictive character set for the "serial" 147 attribute or fixed sized buffers for almost all the others, including 148 "token", "manufacturer", and "model" attributes. However, the 149 PKCS#11 URI notation does not impose such limitations aside from 150 removing generic and PKCS#11 URI delimiters from a permitted 151 character set. We believe that being too restrictive on the 152 attribute values could limit the PKCS#11 URI's usefulness. What is 153 more, possible future changes to the PKCS#11 specification will not 154 affect existing attributes. 156 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 157 [RFC5234]): 159 pk11-URI = "pkcs11" ":" pk11-identifier 160 pk11-identifier = *1(pk11-attr *(";" pk11-attr)) 161 pk11-attr = pk11-token / pk11-manuf / pk11-serial / 162 pk11-model / pk11-lib-manuf / 163 pk11-lib-ver / pk11-lib-desc / 164 pk11-object / pk11-object-type / pk11-id / 165 pk11-pin-source 166 ; Section 2.2 of RFC 3986 specifies that all potentially reserved 167 ; characters that do not conflict with actual delimiters of the URI 168 ; do not have to be percent-encoded. So, ";" was removed as a 169 ; sub-delimiter of the PKCS#11 URI's path and "/", "?", and "#" as 170 ; delimiters of generic URI components. 171 pk11-reserved-avail = ":" / "[" / "]" / "@" / "!" / "$" / 172 "&" / "'" / "(" / ")" / "*" / "+" / 173 "," / "=" 174 pk11-char = unreserved / pk11-reserved-avail / 175 pct-encoded 176 pk11-token = "token" "=" *pk11-char 177 pk11-manuf = "manufacturer" "=" *pk11-char 178 pk11-serial = "serial" "=" *pk11-char 179 pk11-model = "model" "=" *pk11-char 180 pk11-lib-manuf = "library-manufacturer" "=" *pk11-char 181 pk11-lib-desc = "library-description" "=" *pk11-char 182 pk11-lib-ver = "library-version" "=" *DIGIT *1("." 1*DIGIT) 183 pk11-object = "object" "=" *pk11-char 184 pk11-object-type = "object-type" "=" *1("public" / "private" / 185 "cert" / "secret-key" / "data") 186 pk11-id = "id" "=" *pk11-char 187 pk11-pin-source = "pin-source" "=" *pk11-char 189 More specifically, "/" delimiter of generic URI components was 190 removed from available characters that do not have to be percent- 191 encoded so that the initial part of a PKCS#11 URI is never confused 192 with "path-rootless" part of the "hier-part" generic URI component as 193 defined in Section 3 of [RFC3986]. Delimiters "?" and "#" of 194 generic URI components were removed to allow for possible future 195 extensions of the PKCS#11 URI. All other delimiters of generic URI 196 components are allowed to be used unencoded (":", "[", "]", and "@") 197 in the PKCS#11 URI. 199 The attribute "token" represents a token label and corresponds to the 200 "label" member of the CK_TOKEN_INFO structure, the attribute 201 "manufacturer" corresponds to the "manufacturerID" member of 202 CK_TOKEN_INFO, the attribute "serial" corresponds to the 203 "serialNumber" member of CK_TOKEN_INFO, the attribute "model" 204 corresponds to the "model" member of CK_TOKEN_INFO, the attribute 205 "library-manufacturer" represents the Cryptoki library manufacturer 206 and corresponds to the "manufacturerID" member of the CK_INFO 207 structure, the attribute "library-description" corresponds to the 208 "libraryDescription" member of CK_INFO, the attribute "library- 209 version" corresponds to the "libraryVersion" member of CK_INFO, the 210 attribute "object" represents a PKCS#11 object label and corresponds 211 to the "CKA_LABEL" object attribute, the attribute "object-type" 212 represents the type of the object and corresponds to the "CKA_CLASS" 213 object attribute, the attribute "id" represents the object ID and 214 corresponds to the "CKA_ID" object attribute, and the attribute "pin- 215 source" specifies where the application or library should find the 216 token PIN, if needed. 218 The "pin-source" attribute may represent a filename that contains a 219 token PIN but an application may overload this attribute. For 220 example, "pin-source=%7Cprog-name" could mean to read a PIN from an 221 external application (%7C denotes a pipe '|' character). Note that 222 an application may always ask for a PIN and/or interpret the "pin- 223 source" attribute by any means it decides to. 225 It is recommended to percent-encode the whole value of the "id" 226 attribute which is supposed to be handled as arbitrary binary data. 227 Value "M" of the "library-version" attribute should be interpreted as 228 "M" for the major and "0" for the minor version of the library. 229 Library version ".N" should be interpreted as "0" for the major and 230 "N" for the minor version of the library. 232 3.4. PKCS#11 URI Comparison 234 Comparison of two URIs is a way of determining whether the URIs are 235 equivalent without comparing the actual resource the URIs point to. 236 The comparison of URIs aims to minimize false negatives while 237 strictly avoiding false positives. 239 Two PKCS#11 URIs are said to be equal if URIs as character strings 240 are identical as specified in Section 6.2.1 of [RFC3986], or if both 241 following rules are fulfilled: 243 o set of attributes present in the URI is equal. Note that the 244 ordering of attributes in the URI string is not significant for 245 the mechanism of comparison. 247 o values of respective attributes are equal based on rules specified 248 below 250 The rules for comparing values of respective attributes are: 252 o values of attributes "token", "manufacturer", "serial", "model", 253 "library-manufacturer", "library-description", "object", and 254 "object-type" must be compared using simple string comparison 255 (Section 6.2.1 of [RFC3986]) after the case and the percent- 256 encoding normalization are both applied as specified in 257 Section 6.2.2 of [RFC3986] 259 o value of attribute "id" must be compared using simple string 260 comparison after all bytes are percent-encoded using uppercase 261 letters for digits A-F 263 o value for attribute "pin-source", if deemed containing the 264 filename with the PIN value, must be compared using the simple 265 string comparison after the full syntax based normalization as 266 specified in Section 6.2.2 of [RFC3986] is applied. If value of 267 the "pin-source" attribute is believed to be overloaded it is 268 recommended to perform case and percent-encoding normalization 269 before the values are compared but the exact mechanism of 270 comparison is left to the application. 272 o value of attribute "library-version" must be processed as a 273 specific scheme-based normalization permitted by Section 6.2.3 of 274 [RFC3986]. The value must be split into a major and minor version 275 with character "." (dot) serving as a delimiter. Library version 276 "M" must be treated as "M" for the major version and "0" for the 277 minor version. Library version ".N" must be treated as "0" for 278 the major version and "N" for the minor version. Resulting minor 279 and major version numbers must be then separately compared 280 numerically. 282 4. Examples of PKCS#11 URIs 284 This section contains some examples of how PKCS#11 token objects, 285 PKCS#11 tokens, and PKCS#11 libraries can be identified using the 286 PKCS#11 URI scheme. Note that in some of the following examples, 287 newlines and spaces were inserted for better readability. As 288 specified in Appendix C of [RFC3986], whitespace should be ignored 289 when extracting the URI. Also note that all spaces as part of the 290 URI are percent-encoded, as specified in Appendix A of [RFC3986]. 292 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 294 pkcs11: 296 One of the simplest and most useful forms might be a PKCS#11 URI that 297 specifies only an object label and its type. The default token is 298 used so the URI does not specify it. Note that when specifying 299 public objects, a token PIN might not be required. 301 pkcs11:object=my-pubkey;object-type=public 303 When a private key is specified either the "pin-source" attribute or 304 an application specific method would be usually used. Also note that 305 "/" must be percent-encoded in the "pin-source" attribute value since 306 it must be prevented to be mistaken for a path segment delimiter. 308 pkcs11:object=my-key;object-type=private; 309 pin-source=%2Fetc%2Ftoken_pin 311 The following example identifies a certificate in the software token. 312 Note that all attributes may have an empty value. In our case, 313 "serial" is empty. It is up to the consumer of the URI to perform 314 necessary checks if that is not allowed. Note that the "id" 315 attribute value is entirely percent-encoded, as recommended. While 316 "," is in the reserved set it does not have to be percent-encoded 317 since it does not conflict with any sub-delimiters used. The '#' 318 character as in "The Software PKCS#11 Softtoken" is a general 319 delimiter as "/" so it must be percent-encoded, too. 321 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 322 manufacturer=Snake%20Oil,%20Inc.; 323 serial=; 324 model=1.0; 325 object=my-certificate; 326 object-type=cert; 327 id=%69%95%3E%5C%f4%BD%EC%91; 328 pin-source=%2Fetc%2Ftoken_pin 330 The token alone can be identified without specifying any PKCS#11 331 objects. A PIN may still be needed to list all objects, for example. 333 pkcs11:token=Software%20PKCS%2311%20softtoken; 334 manufacturer=Snake%20Oil,%20Inc.; 335 pin-source=%2Fetc%2Ftoken_pin 337 The Cryptoki library alone can be also identified without specifying 338 a PKCS#11 token or object. 340 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 341 library-description=Soft%20Token%20Library; 342 library-version=1.23 344 The following example shows that the attribute value can contain a 345 semicolon. In such case, it is percent-encoded. The token value 346 must be read as "My token; created by Joe". Lower characters can 347 also be used in percent-encoding as shown below in the "id" attribute 348 value but note that Section 2.1 of [RFC3986] recommends to use 349 uppercase hexadecimal digits for all percent-encoded characters. As 350 explained in Section 3.3, library version "3" should be interpreted 351 as "3" for the major and "0" for the minor version of the library. 353 pkcs11:token=My%20token%25%20created%20by%20Joe; 354 library-version=3 355 id=%69%95%3e%5c%f4%bd%ec%91; 357 And if there is any need to include literal '%;' substring, for 358 example, both characters must be escaped. The token value must be 359 read as "A name with a strange substring '\;'". 361 pkcs11:token=A%20name%20with%20a%20strange%20substring%20'%25%3B'; 362 object=my-certificate; 363 object-type=cert; 364 pin-source=%2Fetc%2Ftoken_pin 366 The next example includes a small A with acute in the token name. It 367 must be encoded in octets according to the UTF-8 character encoding 368 and then percent-encoded. Given that a small A with acute is U+225 369 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 370 that is "%C3%A1" in percent-encoding. 372 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 373 object=my-certificate; 374 object-type=cert 376 5. IANA Considerations 378 This document registers a URI scheme. 380 6. Security Considerations 382 There are security considerations for URI schemes discussed in 383 Section 7 of [RFC3986]. 385 More specifically, Section 7.1 of [RFC3986] applies since there is no 386 guarantee that the same URI will always identify the same object, 387 token, or a library in the future. 389 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 390 command line arguments to run applications, and those arguments can 391 be world readable on some systems. For that reasons, the URI 392 intentionally does not allow for specifying the PKCS#11 token PIN as 393 a URI attribute. 395 7. References 397 7.1. Normative References 399 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 400 10646", RFC 3629, STD 63, November 2003. 402 [RFC3986] Berners-Lee, T., Fielding, R. T., and L. Masinter, 403 "Uniform Resource Identifier (URI): Generic Syntax", RFC 404 3986, STD 66, January 2005. 406 [RFC5234] Crocker, D. H. and P. Overell, "Augmented BNF for Syntax 407 Specifications: ABNF", RFC 5234, STD 68, January 2008. 409 7.2. Informative References 411 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 412 Registration Procedures for New URI Schemes", RFC 4395, 413 February 2006. 415 [pkcs11_spec] 416 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 417 Standard v2.20", June 2004. 419 Authors' Addresses 421 Jan Pechanec 422 Oracle Corporation 423 4180 Network Circle 424 Santa Clara CA 95054 425 USA 427 Email: Jan.Pechanec@Oracle.COM 428 URI: http://www.oracle.com 429 Darren J. Moffat 430 Oracle Corporation 431 Oracle Parkway 432 Thames Valley Park 433 Reading RG6 1RA 434 UK 436 Email: Darren.Moffat@Oracle.COM 437 URI: http://www.oracle.com