idnits 2.17.1 draft-pechanec-pkcs11uri-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 22, 2010) is 5148 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: 2 errors (**), 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 Sun Microsystems, Inc. 4 Intended status: Standards Track D. Moffat 5 Expires: September 23, 2010 Oracle Corporation 6 March 22, 2010 8 The PKCS#11 URI Scheme 9 draft-pechanec-pkcs11uri-01 11 Abstract 13 This memo specifies a PKCS#11 Uniform Resource Identifier (URI) 14 Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, or 15 for identifying PKCS#11 tokens themselves. The URI is based on how 16 PKCS#11 objects and tokens are identified in the PKCS#11 17 Cryptographic Token Interface Standard. 19 Status of this Memo 21 This Internet-Draft is submitted to IETF 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), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 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 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on September 23, 2010. 42 Copyright Notice 44 Copyright (c) 2010 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . . 3 61 2.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . . 3 62 2.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . . 3 63 2.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . . 3 64 3. Examples of PKCS#11 URI Schemes . . . . . . . . . . . . . . . . 5 65 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 67 6. Normative References . . . . . . . . . . . . . . . . . . . . . 7 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 70 1. Introduction 72 The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec] 73 specifies an API, called Cryptoki, for devices which hold 74 cryptographic information and perform cryptographic functions. 75 Cryptoki, pronounced crypto-key and short for cryptographic token 76 interface, follows a simple object-based approach, addressing the 77 goals of technology independence (any kind of device may be used) and 78 resource sharing (multiple applications may access multiple devices), 79 presenting applications with a common, logical view of the device - a 80 cryptographic token. 82 It is desirable for applications or libraries that work with PKCS#11 83 tokens to accept a common identifier that consumers could use to 84 identify an existing PKCS#11 object in a PKCS#11 token, or an 85 existing token itself. The set of object types that can be stored in 86 a PKCS#11 token includes a public key, a private key, a certificate, 87 a secret key, and a data object. These objects can be uniquely 88 identifiable via the PKCS#11 URI scheme defined in this document. 89 The set of attributes that identifies a PKCS#11 token can contain a 90 token label, a manufacturer name, a serial number, and a token model. 92 Note that the PKCS#11 URI is not intended to be used to create new 93 PKCS#11 objects in tokens, or to create PKCS#11 tokens. It is solely 94 to be used to identify existing objects or existing tokens. 96 2. PKCS#11 URI Scheme Definition 98 In accordance with [RFC4395], this section provides the information 99 required to register the PKCS#11 URI scheme. 101 2.1. PKCS#11 URI Scheme Name 103 pkcs11 105 2.2. PKCS#11 URI Scheme Status 107 Permanent. 109 2.3. PKCS#11 URI Scheme Syntax 111 The PKCS#11 URI scheme is a sequence of attribute value pairs. Most 112 attributes allow for an UTF8 string to be used as an value. However, 113 given that a semicolon is used as a delimiter of attribute value 114 pairs, semicolons used in such values must be escaped with a 115 backslash. A backslash that stands for itself must be escaped, too. 117 A PKCS#11 URL takes the form (for explanation of Augmented BNF, see 118 [RFC5234]): 120 semicolon = "\%x3B" 121 backslash = "\\" 122 hexa = 2*2( %x30-39 / %x41-46 / %x61-66 ) 124 ; Modified UTF8 definition rule based on UTF8-octets rule 125 ; introduced in RFC3629. 126 UTF8-octets-with-escapes= *( UTF8-char-with-escapes ) 127 UTF8-char-with-escapes = UTF8-1-with-escapes / UTF8-2 / UTF8-3 / 128 UTF8-4 129 UTF8-1-with-escapes = %x00-3A / semicolon / %x3C-5B / 130 backslash / %x5D-7F 131 UTF8-2 = %xC2-DF UTF8-tail 132 UTF8-3 = %xE0 %xA0-BF UTF8-tail / 133 %xE1-EC 2( UTF8-tail ) / 134 %xED %x80-9F UTF8-tail / 135 %xEE-EF 2( UTF8-tail ) 136 UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / 137 %xF1-F3 3( UTF8-tail ) / 138 %xF4 %x80-8F 2( UTF8-tail ) 139 UTF8-tail = %x80-BF 141 ; The actual PKCS#11 URI scheme definition starts here. 142 pk11-URI = "pkcs11" ":" pk11-identifier 143 pk11-identifier = *1( pk11-attr *( "%x3B" pk11-attr ) ) 144 pk11-attr = pk11-token / pk11-manufacturer / 145 pk11-serial / pk11-model / 146 pk11-object / pk11-objecttype / 147 pk11-id / pk11-passphrasedialog 148 ; The "pk11-ck-char" rule contains a complete list of characters 149 ; of the CK_CHAR type as defined in the PKCS#11 specification. 150 ; Those are a-z, A-Z, 0-9, a space, and all special characters 151 ; from the following list: !"#%&'()*+,-./:;<=>?[\]^_{|}~ 152 pk11-ck-char = %x41-5A / %x61-7A / %x30-39 / %x20-23 / 153 %x25-2F / %x3A / semicolon / %x3C-3F / 154 %x5B / backslash / %x5D-5F / %x7B-7E 155 ; Corresponds to the label field of the CK_TOKEN_INFO structure. 156 pk11-token = "token" "=" UTF8-octets-with-escapes 157 ; Corresponds to the manufacturerID field of the CK_TOKEN_INFO 158 ; structure. 159 pk11-manufacturer = "manufacturer" "=" UTF8-octets-with-escapes 160 ; Corresponds to the serialNumber field of the CK_TOKEN_INFO structure. 161 pk11-serial = "serial" "=" *( pk11-ck-char ) 162 ; Corresponds to the model field of the CK_TOKEN_INFO structure. 163 pk11-model = "model" "=" UTF8-octets-with-escapes 164 ; Corresponds to the CKA_LABEL object attribute. 166 pk11-object = "object" "=" UTF8-octets-with-escapes 167 ; Corresponds to the CKA_CLASS object attribute. 168 pk11-objecttype = "objecttype" "=" ( "public" / "private" / 169 "cert" / "secretkey" / "data" ) 170 ; Corresponds to the CKA_ID object attribute. 171 pk11-id = "id" "=" *1( hexa *( ":" hexa ) ) 172 pk11-passphrasedialog = "passphrasedialog" "=" "builtin" / exec 173 exec = "exec" ":" filename 174 filename = UTF8-octets-with-escapes 176 While the PKCS#11 specification limits the length of some fields, eg. 177 the manufacturer label can be up to thirty-two characters long, the 178 PKCS#11 URI does not impose such limitations. It is up to the 179 consumer of the PKCS#11 URI to perform any necessary sanity checks. 181 The "UTF8-octets-with-escapes" rule for the UTF8 string with escaped 182 ";" and "\" characters is based on the "UTF8-octets" rule defined in 183 [RFC3629]. 185 The attribute "token" represents a token label, the attribute 186 "manufacturer" represents a manufacturer ID, the attribute "serial" 187 represents a token serial number, the attribute "model" represents a 188 token model, the attribute "object" represents a PKCS#11 object 189 label, the attribute "objecttype" represents the type of the object, 190 the attribute "id" represents the object ID, and the attribute 191 "passphrasedialog" specifies how the application or library should 192 ask for the token PIN, if needed. The "builtin" value suggests that 193 the application or the library should use whatever means of reading 194 the PIN it can provide, and the "exec:" value specifies an 195 external application whose standard output should be used as the 196 token PIN. 198 3. Examples of PKCS#11 URI Schemes 200 This section contains some examples of how PKCS#11 tokens or PKCS#11 201 token objects can be identified using the PKCS#11 URI scheme. 203 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 205 pkcs11: 207 One of the simplest and most useful forms might be a PKCS#11 URI that 208 specifies only an object label and its type. The default token is 209 used so the URI does not specify it. Note that when specifying 210 public objects, a token PIN might not be required. 212 pkcs11:object=my-pubkey;objecttype=public 214 Specifying a private key will usually need to use the 215 "passphrasedialog" attribute: 217 pkcs11:object=my-key;objecttype=private;passphrasedialog=builtin 219 The following example identifies a certificate in the software token. 220 Note that all attributes aside from "passphrasedialog" and 221 "objecttype" may have an empty value. In our case, "serial" is 222 empty. It is up to the consumer of the URI to perform necessary 223 checks if that is not allowed. Note the notation of the "id" 224 attribute value. Also note that in all four of the following 225 examples, newlines and spaces were inserted for better readability. 226 Usage of newlines or spaces after semicolons is illegal in the 227 PKCS#11 URI scheme defined above. 229 pkcs11:token=Software PKCS#11 softtoken; 230 manufacturer=Snake Oil, Inc.; 231 serial=; 232 model=1.0; 233 object=my-certificate; 234 objecttype=cert; 235 id=69:95:3e:5c:f4:bd:ec:91; 236 passphrasedialog=exec:/bin/askpass.sh 238 The token alone can be identified without specifying any PKCS#11 239 objects. A PIN may still be needed to list all objects, for example. 241 pkcs11:token=Software PKCS#11 softtoken; 242 manufacturer=Snake Oil, Inc.; 243 passphrasedialog=exec:/bin/askpass.sh 245 The following example shows that the attribute value can contain a 246 semicolon. In this case, it must be escaped. We can also have 247 capital letters in the "id" attribute value. 249 pkcs11:token=My token\; created by Joe; 250 object=my-certificate; 251 objecttype=cert; 252 id=69:95:3E:5C:F4:BD:EC:91; 253 passphrasedialog=exec:/bin/askpass.sh 255 And if there is any need to include literal '\;' substring, for 256 example, we must escape both characters. The token value must be 257 read as "The token name with a strange substring '\;'" then. 259 pkcs11:token=The token name with a strange substring '\\\;'; 260 object=my-certificate; 261 objecttype=cert; 262 passphrasedialog=exec:/bin/askpass.sh 264 4. IANA Considerations 266 This document registers a URI scheme. The registration template can 267 be found in Section 2 of this document. 269 5. Security Considerations 271 There are many security considerations for URI schemes discussed in 272 [RFC3986]. 274 Given that the PKCS#11 URI is also supposed to be used in command 275 line arguments to running programs, and those arguments can be world 276 readable on some systems, the URI intentionaly does not allow for 277 specifying the PKCS#11 token PIN as a URI attribute. 279 6. Normative References 281 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 282 10646", RFC 3629, STD 63, November 2003. 284 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 285 Resource Identifier (URI): Generic Syntax", RFC 3986, 286 STD 66, January 2005. 288 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 289 Registration Procedures for New URI Schemes", RFC 4395, 290 February 2006. 292 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 293 Specifications: ABNF", RFC 5234, January 2008. 295 [pkcs11_spec] 296 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 297 Standard v2.20", June 2004. 299 Authors' Addresses 301 Jan Pechanec 302 Sun Microsystems, Inc. 303 The Park, building 3 304 V parku 2308/8 305 Prague 14800 306 CZ 308 Phone: +420 233 009 380 309 Email: Jan.Pechanec@Sun.COM 310 URI: http://www.sun.com 312 Darren J. Moffat 313 Oracle Corporation 314 Guillemont Park 315 Building 3 316 Camberley GU17 9QG 317 UK 319 Email: Darren.Moffat@Oracle.COM 320 URI: http://www.oracle.com