idnits 2.17.1 draft-pechanec-pkcs11uri-06.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 (February 29, 2012) is 4439 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 normative reference: RFC 4395 (Obsoleted by RFC 7595) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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: September 1, 2012 February 29, 2012 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-06 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 1, 2012. 36 Copyright Notice 38 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . . 4 56 3.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . . 4 57 3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . . 4 58 3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . . 4 59 4. Examples of PKCS#11 URI Schemes . . . . . . . . . . . . . . . . 6 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 62 7. Normative References . . . . . . . . . . . . . . . . . . . . . 8 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 65 1. Introduction 67 The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec] 68 specifies an API, called Cryptoki, for devices which hold 69 cryptographic information and perform cryptographic functions. 70 Cryptoki, pronounced crypto-key and short for cryptographic token 71 interface, follows a simple object-based approach, addressing the 72 goals of technology independence (any kind of device may be used) and 73 resource sharing (multiple applications may access multiple devices), 74 presenting applications with a common, logical view of the device - a 75 cryptographic token. 77 It is desirable for applications or libraries that work with PKCS#11 78 tokens to accept a common identifier that consumers could use to 79 identify an existing PKCS#11 object in a PKCS#11 token, or an 80 existing token itself, or an existing Cryptoki library. The set of 81 object types that can be stored in a PKCS#11 token includes a public 82 key, a private key, a certificate, a secret key, and a data object. 83 These objects can be uniquely identifiable via the PKCS#11 URI scheme 84 defined in this document. The set of attributes describing an object 85 can contain an object label, its type, and its ID. The set of 86 attributes that identifies a PKCS#11 token can contain a token label, 87 a manufacturer name, a serial number, and a token model. Attributes 88 that can identify a Cryptoki library are a library manufacturer, a 89 library description, and a library version. 91 Note that the PKCS#11 URI is not intended to be used to create new 92 PKCS#11 objects in tokens, or to create PKCS#11 tokens. It is solely 93 to be used to identify existing objects, tokens, or Cryptoki 94 libraries. 96 The URI scheme defined in this document is designed specifically with 97 a mapping to the PKCS#11 API in mind. The URI uses only the scheme 98 and the path components which are required by the Uniform Resource 99 Identifier generic syntax [RFC3986]. The URI scheme does not use the 100 hierarchical element for a naming authority in the path since the 101 authority part could not be mapped to PKCS#11 API elements. The URI 102 scheme does not use the optional query and fragment elements. 104 2. Contributors 106 Stef Walter, Nikos Mavrogiannopoulos, and Nico Williams contributed 107 to the development of this document. 109 3. PKCS#11 URI Scheme Definition 111 In accordance with [RFC4395], this section provides the information 112 required to register the PKCS#11 URI scheme. 114 3.1. PKCS#11 URI Scheme Name 116 pkcs11 118 3.2. PKCS#11 URI Scheme Status 120 Permanent. 122 3.3. PKCS#11 URI Scheme Syntax 124 The PKCS#11 URI scheme is a sequence of attribute value pairs 125 separated by a semicolon. In accordance with [RFC3986], the data 126 should first be encoded as octets according to the UTF-8 character 127 encoding [RFC3629]; then only those octets that do not correspond to 128 characters in the unreserved set or to permitted characters from the 129 reserved set should be percent-encoded. Rules "unreserved" and "pct- 130 encoded" in the PKCS#11 URI specification below were imported from 131 [RFC3986]. As a special case, note that according to [RFC3986], a 132 space must be percent-encoded. 134 PKCS#11 specification imposes various limitations on the value of 135 attributes, be it a more restrictive character set for the "serial" 136 attribute or fixed sized buffers for almost all the others, including 137 "token", "manufacturer", and "model" attributes. However, the 138 PKCS#11 URI notation does not impose such limitations aside from 139 removing generic and PKCS#11 URI delimiters from a permitted 140 character set. We believe that being too restrictive on the 141 attribute values could limit the PKCS#11 URI's usefulness. What is 142 more, possible future changes to the PKCS#11 specification will not 143 affect existing attributes. 145 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 146 [RFC5234]): 148 pk11-URI = "pkcs11" ":" pk11-identifier 149 pk11-identifier = *1(pk11-attr *(";" pk11-attr)) 150 pk11-attr = pk11-token / pk11-manuf / pk11-serial / 151 pk11-model / pk11-lib-manuf / 152 pk11-lib-ver / pk11-lib-desc / 153 pk11-object / pk11-object-type / pk11-id / 154 pk11-pin-source 155 ; Section 2.2 of RFC 3986 specifies that all potentially reserved 156 ; characters that do not conflict with actual delimiters of the URI 157 ; do not have to be percent-encoded. So, ";" was removed as a 158 ; sub-delimiter of the PKCS#11 URI's path and "/", "?", and "#" as 159 ; delimiters in a generic URI syntax. 160 pk11-reserved-avail = ":" / "[" / "]" / "@" / "!" / "$" / 161 "&" / "'" / "(" / ")" / "*" / "+" / 162 "," / "=" 163 pk11-char = unreserved / pk11-reserved-avail / 164 pct-encoded 165 pk11-token = "token" "=" *pk11-char 166 pk11-manuf = "manufacturer" "=" *pk11-char 167 pk11-serial = "serial" "=" *pk11-char 168 pk11-model = "model" "=" *pk11-char 169 pk11-lib-manuf = "library-manufacturer" "=" *pk11-char 170 pk11-lib-desc = "library-description" "=" *pk11-char 171 pk11-lib-ver = "library-version" "=" *DIGIT *1("." 1*DIGIT) 172 pk11-object = "object" "=" *pk11-char 173 pk11-object-type = "object-type" "=" *1("public" / "private" / 174 "cert" / "secret-key" / "data") 175 pk11-id = "id" "=" *pk11-char 176 pk11-pin-source = "pin-source" "=" *pk11-char 178 The attribute "token" represents a token label and corresponds to the 179 "label" member of the CK_TOKEN_INFO structure, the attribute 180 "manufacturer" corresponds to the "manufacturerID" member of 181 CK_TOKEN_INFO, the attribute "serial" corresponds to the 182 "serialNumber" member of CK_TOKEN_INFO, the attribute "model" 183 corresponds to the "model" member of CK_TOKEN_INFO, the attribute 184 "library-manufacturer" represents the Cryptoki library manufacturer 185 and corresponds to the "manufacturerID" member of the CK_INFO 186 structure, the attribute "library-description" corresponds to the 187 "libraryDescription" member of CK_INFO, the attribute "library- 188 version" corresponds to the "libraryVersion" member of CK_INFO, the 189 attribute "object" represents a PKCS#11 object label and corresponds 190 to the "CKA_LABEL" object attribute, the attribute "object-type" 191 represents the type of the object and corresponds to the "CKA_CLASS" 192 object attribute, the attribute "id" represents the object ID and 193 corresponds to the "CKA_ID" object attribute, and the attribute "pin- 194 source" specifies where the application or library should find the 195 token PIN, if needed. 197 The "pin-source" attribute may represent a filename that contains a 198 token PIN but an application may overload this attribute. For 199 example, "pin-source=%7Cprog-name" could mean to read a PIN from an 200 external application (%7C denotes a pipe '|' character). Note that 201 an application may always ask for a PIN and/or interpret the "pin- 202 source" attribute by any means it decides to. 204 It is recommended to percent-encode the whole value of the "id" 205 attribute which is supposed to be handled as arbitrary binary data. 207 4. Examples of PKCS#11 URI Schemes 209 This section contains some examples of how PKCS#11 token objects, 210 PKCS#11 tokens, and PKCS#11 libraries can be identified using the 211 PKCS#11 URI scheme. Note that in some of the following examples, 212 newlines and spaces were inserted for better readability which is 213 allowed by [RFC3986]. Also note that all spaces as part of the URI 214 are percent-encoded, as required by [RFC3986]. 216 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 218 pkcs11: 220 One of the simplest and most useful forms might be a PKCS#11 URI that 221 specifies only an object label and its type. The default token is 222 used so the URI does not specify it. Note that when specifying 223 public objects, a token PIN might not be required. 225 pkcs11:object=my-pubkey;object-type=public 227 When a private key is specified either the "pin-source" attribute or 228 an application specific method would be usually used. Also note that 229 "/" must be percent-encoded in the "pin-source" attribute value since 230 it must be prevented to be mistaken for a path segment delimiter. 232 pkcs11:object=my-key;object-type=private; 233 pin-source=%2Fetc%2Ftoken_pin 235 The following example identifies a certificate in the software token. 236 Note that all attributes may have an empty value. In our case, 237 "serial" is empty. It is up to the consumer of the URI to perform 238 necessary checks if that is not allowed. Note that the "id" 239 attribute value is entirely percent-encoded, as recommended. While 240 "," is in the reserved set it does not have to be percent-encoded 241 since it does not conflict with any sub-delimiters used. The '#' 242 character as in "The Software PKCS#11 Softtoken" is a general 243 delimiter as "/" so it must be percent-encoded, too. 245 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 246 manufacturer=Snake%20Oil,%20Inc.; 247 serial=; 248 model=1.0; 249 object=my-certificate; 250 object-type=cert; 251 id=%69%95%3E%5C%f4%BD%EC%91; 252 pin-source=%2Fetc%2Ftoken_pin 254 The token alone can be identified without specifying any PKCS#11 255 objects. A PIN may still be needed to list all objects, for example. 257 pkcs11:token=Software%20PKCS%2311%20softtoken; 258 manufacturer=Snake%20Oil,%20Inc.; 259 pin-source=%2Fetc%2Ftoken_pin 261 The Cryptoki library alone can be also identified without specifying 262 any PKCS#11 objects. 264 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 265 library-description=Soft%20Token%20Library; 266 library-version=1.23 268 The following example shows that the attribute value can contain a 269 semicolon. In such case, it is percent-encoded. The token value 270 must be read as "My token; created by Joe". Lower characters can 271 also be used in percent-encoding as shown below in the "id" attribute 272 value but note that [RFC3986] recommends to use upercase hexadecimal 273 digits for all percent-encoded characters. Library version ".9" 274 should be interpreted as "0" for the major and "9" for the minor 275 version of the library. Similarly, library version "9" would be 276 interpreted as "9" for the major and "0" for the minor version of the 277 library. 279 pkcs11:token=My%20token%25%20created%20by%20Joe; 280 library-version=.9 281 id=%69%95%3e%5c%f4%bd%ec%91; 283 And if there is any need to include literal '%;' substring, for 284 example, both characters must be escaped. The token value must be 285 read as "A name with a strange substring '\;'". 287 pkcs11:token=A%20name%20with%20a%20strange%20substring%20'%25%3B'; 288 object=my-certificate; 289 object-type=cert; 290 pin-source=%2Fetc%2Ftoken_pin 292 The next example includes a small A with acute in the token name. It 293 must be encoded in octets according to the UTF-8 character encoding 294 and then percent-encoded. Given that a small A with acute is U+225 295 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 296 that is "%C3%A1" in percent-encoding. 298 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 299 object=my-certificate; 300 object-type=cert 302 5. IANA Considerations 304 This document registers a URI scheme. The registration template can 305 be found in Section 3 of this document. 307 6. Security Considerations 309 There are security considerations for URI schemes discussed in 310 [RFC3986]. 312 Given that the PKCS#11 URI is also supposed to be used in command 313 line arguments to running programs, and those arguments can be world 314 readable on some systems, the URI intentionaly does not allow for 315 specifying the PKCS#11 token PIN as a URI attribute. 317 7. Normative References 319 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 320 10646", RFC 3629, STD 63, November 2003. 322 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 323 Resource Identifier (URI): Generic Syntax", RFC 3986, 324 STD 66, January 2005. 326 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 327 Registration Procedures for New URI Schemes", RFC 4395, 328 February 2006. 330 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 331 Specifications: ABNF", RFC 5234, January 2008. 333 [pkcs11_spec] 334 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 335 Standard v2.20", June 2004. 337 Authors' Addresses 339 Jan Pechanec 340 Oracle Corporation 341 4180 Network Circle 342 Santa Clara CA 95054 343 US 345 Email: Jan.Pechanec@Oracle.COM 346 URI: http://www.oracle.com 348 Darren J. Moffat 349 Oracle Corporation 350 Oracle Parkway 351 Thames Valley Park 352 Reading RG6 1RA 353 UK 355 Email: Darren.Moffat@Oracle.COM 356 URI: http://www.oracle.com