idnits 2.17.1 draft-pechanec-pkcs11uri-03.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 (November 8, 2010) is 4916 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: May 12, 2011 November 8, 2010 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-03 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 May 12, 2011. 36 Copyright Notice 38 Copyright (c) 2010 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-objecttype / pk11-id / pk11-pinfile 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, we just removed ";". 146 pk11-reserved-avail = ":" / "/" / "?" / "#" / "[" / "]" / "@" / 147 "!" / "$" / "&" / "'" / "(" / ")" / "*" / 148 "+" / "," / "=" 149 pk11-value = *(unreserved / pk11-reserved-avail / 150 pct-encoded) 151 ; The "pk11-ck-char" rule contains a complete list of characters 152 ; of the CK_CHAR type as defined in the PKCS#11 specification. Those 153 ; are a-z, A-Z, 0-9, a space, and all special characters from the 154 ; following list: !"#%&'()*+,-./:;<=>?[\]^_{|}~. Note that some 155 ; special characters not part of the reserved and unreserved sets 156 ; must be percent-encoded. 158 pk11-ck-char = unreserved / "%20" / "!" / "%22" / "#" / 159 "%25" / "&" / "'" / "(" / ")" / "*" / 160 "+" / "," / "-" / "." / "/" / ":" / "%3B" / 161 "%3C" / "=" / "%3E" / "?" / "[" / "%5C" / 162 "]" / "%5E" / "_" / "%7B" / "%7C" / "%7D" / 163 "~" 164 ; Corresponds to the label field of the CK_TOKEN_INFO structure. 165 pk11-token = "token" "=" pk11-value 166 ; Corresponds to the manufacturerID field of the CK_TOKEN_INFO 167 ; structure. 168 pk11-manuf = "manufacturer" "=" pk11-value 169 ; Corresponds to the serialNumber field of the CK_TOKEN_INFO structure. 170 pk11-serial = "serial" "=" *pk11-ck-char 171 ; Corresponds to the model field of the CK_TOKEN_INFO structure. 172 pk11-model = "model" "=" pk11-value 173 ; Corresponds to the manufacturerID field of the CK_INFO structure. 174 pk11-lib-manuf = "library-manufacturer" "=" pk11-value 175 ; Corresponds to the libraryDescription field of the CK_INFO structure. 176 pk11-lib-desc = "library-description" "=" pk11-value 177 ; Corresponds to the libraryVersion field of the CK_INFO structure. 178 pk11-lib-ver = "library-version" "=" 1*DIGIT *("." 1*DIGIT) 179 ; Corresponds to the CKA_LABEL object attribute. 180 pk11-object = "object" "=" pk11-value 181 ; Corresponds to the CKA_CLASS object attribute. 182 pk11-objecttype = "objecttype" "=" ("public" / "private" / 183 "cert" / "secretkey" / "data") 184 ; Corresponds to the CKA_ID object attribute. 185 pk11-id = "id" "=" *pct-encoded 186 pk11-pinfile = "pinfile" "=" pk11-value 188 While the PKCS#11 specification limits the length of some fields, eg. 189 the manufacturer label can be up to thirty-two characters long, the 190 PKCS#11 URI does not impose such limitations. It is up to the 191 consumer of the PKCS#11 URI to perform any necessary sanity length 192 checks. 194 The attribute "token" represents a token label, the attribute 195 "manufacturer" represents a token manufacturer ID, the attribute 196 "serial" represents a token serial number, the attribute "model" 197 represents a token model, the attribute "library-manufacturer" 198 represents the Cryptoki library manufacturer, the attribute "library- 199 description" represents the character string description of the 200 library, the attribute "library-version" represents the Cryptoki 201 library version, the attribute "object" represents a PKCS#11 object 202 label, the attribute "objecttype" represents the type of the object, 203 the attribute "id" represents the object ID, and the attribute 204 "pinfile" specifies where the application or library should find the 205 token PIN, if needed. Application could overload this attribute. 207 For example, "pinfile=%7Cprog-name" could mean to read a PIN from an 208 external application (%7C denotes a pipe '|' character). Note that 209 an application can always ask for a PIN by any means it decides to. 211 4. Examples of PKCS#11 URI Schemes 213 This section contains some examples of how PKCS#11 tokens or PKCS#11 214 token objects can be identified using the PKCS#11 URI scheme. Note 215 that in some of the following examples, newlines and spaces were 216 inserted for better readability which is allowed by [RFC3986]. Also 217 note that all spaces as part of the URI are percent-encoded, as 218 required by [RFC3986]. 220 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 222 pkcs11: 224 One of the simplest and most useful forms might be a PKCS#11 URI that 225 specifies only an object label and its type. The default token is 226 used so the URI does not specify it. Note that when specifying 227 public objects, a token PIN might not be required. 229 pkcs11:object=my-pubkey;objecttype=public 231 When a private key is specified either the "pinfile" attribute or an 232 application specific method must be used. Also note that we can not 233 use literal "/" in the "pinfile" attribute since this character is 234 part of the reserved set, used to delimit components that are 235 significant to the generic parser's hierarchical interpretation of an 236 identifier. We must percent-encode it. 238 pkcs11:object=my-key;objecttype=private;pinfile=%2Fetc%2Ftoken_pin 240 The following example identifies a certificate in the software token. 241 Note that all attributes aside from "objecttype" may have an empty 242 value. In our case, "serial" is empty. It is up to the consumer of 243 the URI to perform necessary checks if that is not allowed. Note the 244 notation of the "id" attribute value which is entirely percent- 245 encoded. We do not have to percent-encode "," which is in the 246 reserverd set since it does not conflict with any sub-delimiter used. 247 The '#' character is a general delimiter as "/" so we must percent- 248 encode it. 250 pkcs11:token=The%20Software%20PKCS%2311%20softtoken; 251 manufacturer=Snake%20Oil,%20Inc.; 252 serial=; 253 model=1.0; 254 object=my-certificate; 255 objecttype=cert; 256 id=%69%95%3E%5C%f4%BD%EC%91; 257 pinfile=%2Fetc%2Fssh%2Ftoken_pin 259 The token alone can be identified without specifying any PKCS#11 260 objects. A PIN may still be needed to list all objects, for example. 262 pkcs11:token=Software%20PKCS%2311%20softtoken; 263 manufacturer=Snake%20Oil,%20Inc.; 264 pinfile=%2Fetc%2Fssh%2Ftoken_pin 266 The Cryptoki library alone can be also identified without specifying 267 any PKCS#11 objects. 269 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 270 library-description=Soft%20Token%20Library; 271 library-version=1.23 273 The following example shows that the attribute value can contain a 274 semicolon. In such case, it is percent-encoded. We can also have 275 lower characters in the "id" attribute value but note that [RFC3986] 276 recommends to use upercase hexadecimal digits for all percent-encoded 277 characters. 279 pkcs11:token=My%20token%25%20created%20by%20Joe; 280 object=my-certificate; 281 objecttype=cert; 282 id=%69%95%3e%5c%f4%bd%ec%91; 283 pinfile=%2Fetc%2Fssh%2Ftoken_pin 285 And if there is any need to include literal '%;' substring, for 286 example, we must escape both characters. The token value must be 287 read as "The token name with a strange substring '\;'" then. 289 pkcs11:token=A%20name%20with%20a%20strange%20substring%20'%25%3B'; 290 object=my-certificate; 291 objecttype=cert; 292 pinfile=/etc/ssh/token_pin 294 The next example includes a small A with acute in the token name. We 295 must encode it in octets according to the UTF-8 character encoding 296 and then use the percent-encoding. Given that a small A with acute 297 is U+225 unicode code point, the UTF-8 encoding is 195 161 in 298 decimal, which is "%C3%A1" in the percent-encoding. 300 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 301 object=my-certificate; 302 objecttype=cert; 304 5. IANA Considerations 306 This document registers a URI scheme. The registration template can 307 be found in Section 2 of this document. 309 6. Security Considerations 311 There are many security considerations for URI schemes discussed in 312 [RFC3986]. 314 Given that the PKCS#11 URI is also supposed to be used in command 315 line arguments to running programs, and those arguments can be world 316 readable on some systems, the URI intentionaly does not allow for 317 specifying the PKCS#11 token PIN as a URI attribute. 319 7. Normative References 321 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 322 10646", RFC 3629, STD 63, November 2003. 324 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 325 Resource Identifier (URI): Generic Syntax", RFC 3986, 326 STD 66, January 2005. 328 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 329 Registration Procedures for New URI Schemes", RFC 4395, 330 February 2006. 332 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 333 Specifications: ABNF", RFC 5234, January 2008. 335 [pkcs11_spec] 336 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 337 Standard v2.20", June 2004. 339 Authors' Addresses 341 Jan Pechanec 342 Oracle Corporation 343 The Park, building 3 344 V parku 2308/8 345 Prague 14800 346 CZ 348 Phone: +420 233 009 380 349 Email: Jan.Pechanec@Oracle.COM 350 URI: http://www.oracle.com 352 Darren J. Moffat 353 Oracle Corporation 354 Guillemont Park 355 Building 3 356 Camberley GU17 9QG 357 UK 359 Email: Darren.Moffat@Oracle.COM 360 URI: http://www.oracle.com