idnits 2.17.1 draft-pechanec-pkcs11uri-05.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 (Aug 2011) is 4630 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: February 2, 2012 Aug 2011 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-05 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 libraries, or for identifying PKCS#11 tokens 15 themselves. The URI is based on how PKCS#11 objects, libraries, and 16 tokens 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 February 2, 2012. 36 Copyright Notice 38 Copyright (c) 2011 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. Most 125 attributes allow for an UTF-8 string to be used as an value. In 126 accordance with [RFC3986], the data should first be encoded as octets 127 according to the UTF-8 character encoding [RFC3629]; then only those 128 octets that do not correspond to characters in the unreserved set or 129 to permitted characters from the reserved set should be percent- 130 encoded. Rules "unreserved" and "pct-encoded" in the PKCS#11 URI 131 specification below were imported from [RFC3986]. As a special case, 132 note that according to [RFC3986], a space must be percent-encoded. 134 A PKCS#11 URL takes the form (for explanation of Augmented BNF, see 135 [RFC5234]): 137 pk11-URI = "pkcs11" ":" pk11-identifier 138 pk11-identifier = *1(pk11-attr *(";" pk11-attr)) 139 pk11-attr = pk11-token / pk11-manuf / pk11-serial / 140 pk11-model / pk11-lib-manuf / pk11-lib-ver / 141 pk11-lib-desc / pk11-object / 142 pk11-object-type / pk11-id / pk11-pin-source 143 ; Section 2.2 of RFC 3986 specifies that all potentially reserved 144 ; characters that do not conflict with actual delimiters of the URI 145 ; do not have to be percent-encoded. So, ";" was removed as a 146 ; sub-delimiter of the PKCS#11 URI's path and "/", "?", and "#" as 147 ; delimiters in a generic URI syntax. While "/" can not be at the 148 ; beginning of a PKCS#11 URI attribute name and thus it could not be 149 ; mistaken for the first character of "//" that introduces an authority 150 ; section (which is not part of the PKCS#11 URI), the "/" character 151 ; also delimits segments of the URI path. However, PKCS#11 URI can have 152 ; at most one path segment. 153 pk11-reserved-avail = ":" / "[" / "]" / "@" / "!" / "$" / "&" / 154 "'" / "(" / ")" / "*" / "+" / "," / "=" 155 pk11-value = *(unreserved / pk11-reserved-avail / 156 pct-encoded) 158 ; The "pk11-ck-char" rule contains a complete list of characters 159 ; of the CK_CHAR type as defined in the PKCS#11 specification. Those 160 ; are a-z, A-Z, 0-9, a space, and all characters from the 161 ; following list: !"#%&'()*+,-./:;<=>?[\]^_{|}~ (some 162 ; of them are already included in the unreserved set). Note that 163 ; special characters not part of the reserved and unreserved sets 164 ; must be percent-encoded. 165 pk11-ck-char = unreserved / "%20" / "!" / "%22" / "%23" / 166 "%25" / "&" / "'" / "(" / ")" / "*" / 167 "+" / "," / "%2F" / ":" / "%3B" / "%3C" / 168 "=" / "%3E" / "%3F" / "[" / "%5C" / "]" / 169 "%5E" / "%7B" / "%7C" / "%7D" 170 ; Corresponds to the label field of the CK_TOKEN_INFO structure. 171 pk11-token = "token" "=" pk11-value 172 ; Corresponds to the manufacturerID field of the CK_TOKEN_INFO 173 ; structure. 174 pk11-manuf = "manufacturer" "=" pk11-value 175 ; Corresponds to the serialNumber field of the CK_TOKEN_INFO structure. 176 pk11-serial = "serial" "=" *pk11-ck-char 177 ; Corresponds to the model field of the CK_TOKEN_INFO structure. 178 pk11-model = "model" "=" pk11-value 179 ; Corresponds to the manufacturerID field of the CK_INFO structure. 180 pk11-lib-manuf = "library-manufacturer" "=" pk11-value 181 ; Corresponds to the libraryDescription field of the CK_INFO structure. 182 pk11-lib-desc = "library-description" "=" pk11-value 183 ; Corresponds to the libraryVersion field of the CK_INFO structure. 184 pk11-lib-ver = "library-version" "=" 1*DIGIT *("." 1*DIGIT) 185 ; Corresponds to the CKA_LABEL object attribute. 186 pk11-object = "object" "=" pk11-value 187 ; Corresponds to the CKA_CLASS object attribute. 188 pk11-object-type = "object-type" "=" ("public" / "private" / 189 "cert" / "secret-key" / "data") 190 ; Corresponds to the CKA_ID object attribute. 191 pk11-id = "id" "=" *pct-encoded 192 pk11-pin-source = "pin-source" "=" pk11-value 194 While the PKCS#11 specification limits the length of some fields, eg. 195 the manufacturer label can be up to thirty-two characters long, the 196 PKCS#11 URI does not impose such limitations. It is up to the 197 consumer of the PKCS#11 URI to perform any necessary sanity length 198 checks. 200 The attribute "token" represents a token label, the attribute 201 "manufacturer" represents a token manufacturer ID, the attribute 202 "serial" represents a token serial number, the attribute "model" 203 represents a token model, the attribute "library-manufacturer" 204 represents the Cryptoki library manufacturer, the attribute "library- 205 description" represents the character string description of the 206 library, the attribute "library-version" represents the Cryptoki 207 library version, the attribute "object" represents a PKCS#11 object 208 label, the attribute "object-type" represents the type of the object, 209 the attribute "id" represents the object ID, and the attribute "pin- 210 source" specifies where the application or library should find the 211 token PIN, if needed. It could be a filename that contains the PIN 212 but an application could overload this attribute. For example, "pin- 213 source=%7Cprog-name" could mean to read a PIN from an external 214 application (%7C denotes a pipe '|' character). Note that an 215 application can always ask for a PIN and/or interpret the "pin- 216 source" attribute by any means it decides to. 218 4. Examples of PKCS#11 URI Schemes 220 This section contains some examples of how PKCS#11 tokens or PKCS#11 221 token objects can be identified using the PKCS#11 URI scheme. Note 222 that in some of the following examples, newlines and spaces were 223 inserted for better readability which is allowed by [RFC3986]. Also 224 note that all spaces as part of the URI are percent-encoded, as 225 required by [RFC3986]. 227 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 229 pkcs11: 231 One of the simplest and most useful forms might be a PKCS#11 URI that 232 specifies only an object label and its type. The default token is 233 used so the URI does not specify it. Note that when specifying 234 public objects, a token PIN might not be required. 236 pkcs11:object=my-pubkey;object-type=public 238 When a private key is specified either the "pin-source" attribute or 239 an application specific method must be used. Also note that "/" must 240 be percent-encoded in the "pin-source" attribute value since as 241 mentioned in Section 3.3, it must be prevented to be mistaken for a 242 path segment delimiter. 244 pkcs11:object=my-key;object-type=private; 245 pin-source=%2Fetc%2Ftoken_pin 247 The following example identifies a certificate in the software token. 248 Note that all attributes aside from "object-type" may have an empty 249 value. In our case, "serial" is empty. It is up to the consumer of 250 the URI to perform necessary checks if that is not allowed. Note the 251 notation of the "id" attribute value which is entirely percent- 252 encoded. While "," is in the reserverd set it does not have to be 253 percent-encoded since it does not conflict with any sub-delimiters 254 used. The '#' character is a general delimiter as "/" so it must be 255 percent-encoded. 257 pkcs11:token=The%20Software%20PKCS%2311%20softtoken; 258 manufacturer=Snake%20Oil,%20Inc.; 259 serial=; 260 model=1.0; 261 object=my-certificate; 262 object-type=cert; 263 id=%69%95%3E%5C%f4%BD%EC%91; 264 pin-source=%2Fetc%2Ftoken_pin 266 The token alone can be identified without specifying any PKCS#11 267 objects. A PIN may still be needed to list all objects, for example. 269 pkcs11:token=Software%20PKCS%2311%20softtoken; 270 manufacturer=Snake%20Oil,%20Inc.; 271 pin-source=%2Fetc%2Ftoken_pin 273 The Cryptoki library alone can be also identified without specifying 274 any PKCS#11 objects. 276 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 277 library-description=Soft%20Token%20Library; 278 library-version=1.23 280 The following example shows that the attribute value can contain a 281 semicolon. In such case, it is percent-encoded. Lower characters 282 can also be used as in the "id" attribute value but note that 283 [RFC3986] recommends to use upercase hexadecimal digits for all 284 percent-encoded characters. 286 pkcs11:token=My%20token%25%20created%20by%20Joe; 287 object=my-certificate; 288 object-type=cert; 289 id=%69%95%3e%5c%f4%bd%ec%91; 290 pin-source=%2Fetc%2Ftoken_pin 292 And if there is any need to include literal '%;' substring, for 293 example, both characters must be escaped. The token value must be 294 read as "The token name with a strange substring '\;'" then. 296 pkcs11:token=A%20name%20with%20a%20strange%20substring%20'%25%3B'; 297 object=my-certificate; 298 object-type=cert; 299 pin-source=%2Fetc%2Ftoken_pin 301 The next example includes a small A with acute in the token name. It 302 must be encoded in octets according to the UTF-8 character encoding 303 and then percent-encoded. Given that a small A with acute is U+225 304 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 305 that is "%C3%A1" in percent-encoding. 307 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 308 object=my-certificate; 309 object-type=cert; 311 5. IANA Considerations 313 This document registers a URI scheme. The registration template can 314 be found in Section 3 of this document. 316 6. Security Considerations 318 There are security considerations for URI schemes discussed in 319 [RFC3986]. 321 Given that the PKCS#11 URI is also supposed to be used in command 322 line arguments to running programs, and those arguments can be world 323 readable on some systems, the URI intentionaly does not allow for 324 specifying the PKCS#11 token PIN as a URI attribute. 326 7. Normative References 328 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 329 10646", RFC 3629, STD 63, November 2003. 331 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 332 Resource Identifier (URI): Generic Syntax", RFC 3986, 333 STD 66, January 2005. 335 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 336 Registration Procedures for New URI Schemes", RFC 4395, 337 February 2006. 339 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 340 Specifications: ABNF", RFC 5234, January 2008. 342 [pkcs11_spec] 343 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 344 Standard v2.20", June 2004. 346 Authors' Addresses 348 Jan Pechanec 349 Oracle Corporation 350 4180 Network Circle 351 Santa Clara CA 95054 352 US 354 Email: Jan.Pechanec@Oracle.COM 355 URI: http://www.oracle.com 357 Darren J. Moffat 358 Oracle Corporation 359 Oracle Parkway 360 Thames Valley Park 361 Reading RG6 1RA 362 UK 364 Email: Darren.Moffat@Oracle.COM 365 URI: http://www.oracle.com