idnits 2.17.1 draft-pechanec-pkcs11uri-14.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 21, 2014) is 3567 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 (~~), 2 warnings (==), 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. Moffat 4 Intended status: Standards Track Oracle Corporation 5 Expires: January 22, 2015 July 21, 2014 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-14 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 January 22, 2015. 36 Copyright Notice 38 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . 4 57 3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . 4 58 3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4 59 3.4. PKCS#11 URI Scheme Query Attribute Semantics . . . . . . 7 60 3.5. PKCS#11 URI Matching Guidelines . . . . . . . . . . . . . 9 61 3.6. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 10 62 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 11 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 67 7.2. Informative References . . . . . . . . . . . . . . . . . 15 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 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 storage object in a PKCS#11 token, an 85 existing token itself, or an existing Cryptoki library (also called a 86 producer, module, or provider). The set of storage object types that 87 can be stored in a PKCS#11 token includes a certificate, a public, 88 private or secret key, and a data object. These objects can be 89 uniquely identifiable via the PKCS#11 URI scheme defined in this 90 document. The set of attributes describing a storage object can 91 contain an object label, its type, and its ID. The set of attributes 92 that identifies a PKCS#11 token can contain a token label, a 93 manufacturer name, a serial number, and a token model. Attributes 94 that can identify a Cryptoki library are a library manufacturer, a 95 library description, and a library version. Library attributes may 96 be necessary to use if more than one Cryptoki library provides a 97 token and/or PKCS#11 objects of the same name(s). A set of query 98 attributes is provided as well. 100 The PKCS#11 URI cannot identify other objects defined in the 101 specification [pkcs11_spec] aside from storage objects. For example, 102 objects not identifiable by a PKCS#11 URI include a hardware feature 103 and mechanism. Note that a Cryptoki library does not have to provide 104 for storage objects at all. The URI can still be used to identify a 105 specific PKCS#11 token or an API producer in such a case. 107 A subset of existing PKCS#11 structure members and object attributes 108 was chosen believed to be sufficient in uniquely identifying a 109 PKCS#11 token, storage object, or library in a configuration file, on 110 a command line, or in a configuration property of something else. 111 Should there be a need for a more complex information exchange on 112 PKCS#11 entities a different means of data marshalling should be 113 chosen accordingly. 115 A PKCS#11 URI is not intended to be used to create new PKCS#11 116 objects in tokens, or to create PKCS#11 tokens. It is solely to be 117 used to identify and work with existing storage objects and tokens 118 through the PKCS#11 API, or identify Cryptoki libraries themselves. 120 The URI scheme defined in this document is designed specifically with 121 a mapping to the PKCS#11 API in mind. The URI uses the scheme, path 122 and query components defined in the Uniform Resource Identifier 123 (URI): Generic Syntax [RFC3986] document. The URI does not use the 124 hierarchical element for a naming authority in the path since the 125 authority part could not be mapped to PKCS#11 API elements. The URI 126 does not use the fragment component. 128 If an application has no access to a producer or producers of the 129 PKCS#11 API the query component module attributes can be used. 130 However, the PKCS#11 URI consumer can always decide to provide its 131 own adequate user interface to locate and load PKCS#11 API 132 producer(s). 134 2. Contributors 136 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 137 Jaroslav Imrich contributed to the development of this document. 139 3. PKCS#11 URI Scheme Definition 141 In accordance with [RFC4395], this section provides the information 142 required to register the PKCS#11 URI scheme. 144 3.1. PKCS#11 URI Scheme Name 146 pkcs11 148 3.2. PKCS#11 URI Scheme Status 150 Permanent. 152 3.3. PKCS#11 URI Scheme Syntax 154 The PKCS#11 URI is a sequence of attribute value pairs separated by a 155 semicolon that form a one level path component, optionally followed 156 by a query. In accordance with Section 2.5 of [RFC3986], the data 157 should first be encoded as octets according to the UTF-8 character 158 encoding [RFC3629]; then only those octets that do not correspond to 159 characters in the unreserved set or to permitted characters from the 160 reserved set should be percent-encoded. This specification suggests 161 one allowable exception to that rule for the "id" attribute, as 162 stated later in this section. Grammar rules "unreserved" and "pct- 163 encoded" in the PKCS#11 URI specification below are imported from 164 [RFC3986]. As a special case, note that according to Appendix A of 165 [RFC3986], a space must be percent-encoded. 167 PKCS#11 specification imposes various limitations on the value of 168 attributes, be it a more restrictive character set for the "serial" 169 attribute or fixed sized buffers for almost all the others, including 170 "token", "manufacturer", and "model" attributes. However, the 171 PKCS#11 URI notation does not impose such limitations aside from 172 removing generic and PKCS#11 URI delimiters from a permitted 173 character set. We believe that being too restrictive on the 174 attribute values could limit the PKCS#11 URI's usefulness. What is 175 more, possible future changes to the PKCS#11 specification should not 176 affect existing attributes. 178 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 179 [RFC5234]): 181 pk11-URI = "pkcs11" ":" pk11-path *1("?" pk11-query) 182 ; Path component and its attributes. Path may be empty. 183 pk11-path = *1(pk11-pattr *(";" pk11-pattr)) 184 pk11-pattr = pk11-token / pk11-manuf / pk11-serial / 185 pk11-model / pk11-lib-manuf / 186 pk11-lib-ver / pk11-lib-desc / 187 pk11-object / pk11-type / pk11-id / 188 pk11-x-pattr 189 ; Query component and its attributes. Query may be empty. 190 pk11-qattr = pk11-pin-source / pk11-pin-value / 191 pk11-module-name / pk11-module-path / 192 pk11-x-qattr 193 pk11-query = *1(pk11-qattr *("&" pk11-qattr)) 194 ; RFC 3986 section 2.2 mandates all potentially reserved characters 195 ; that do not conflict with actual delimiters of the URI do not have 196 ; to be percent-encoded. 197 pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" / 198 "'" / "(" / ")" / "*" / "+" / "," / "=" 199 pk11-path-res-avail = pk11-res-avail / "&" 200 ; We allow "/" and "?" in the query to be unencoded but "&" must 201 ; be encoded since it may be used as a delimiter in the component. 202 pk11-query-res-avail = pk11-res-avail / "/" / "?" / "|" 203 pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded 204 pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded 205 pk11-token = "token" "=" *pk11-pchar 206 pk11-manuf = "manufacturer" "=" *pk11-pchar 207 pk11-serial = "serial" "=" *pk11-pchar 208 pk11-model = "model" "=" *pk11-pchar 209 pk11-lib-manuf = "library-manufacturer" "=" *pk11-pchar 210 pk11-lib-desc = "library-description" "=" *pk11-pchar 211 pk11-lib-ver = "library-version" "=" 1*DIGIT *1("." 1*DIGIT) 212 pk11-object = "object" "=" *pk11-pchar 213 pk11-type = "type" "=" *1("public" / "private" / "cert" / 214 "secret-key" / "data") 215 pk11-id = "id" "=" *pk11-pchar 216 pk11-pin-source = "pin-source" "=" *pk11-qchar 217 pk11-pin-value = "pin-value" "=" *pk11-qchar 218 pk11-module-name = "module-name" = *pk11-qchar 219 pk11-module-path = "module-path" = *pk11-qchar 220 pk11-x-attr-nm-char = ALPHA / DIGIT / "-" / "_" 221 ; Permitted value of a vendor specific attribute is based on 222 ; whether the attribute is used in the path or in the query. 223 pk11-x-pattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-pchar 224 pk11-x-qattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-qchar 225 The URI path component contains attributes that identify a resource 226 in a one level hierarchy provided by Cryptoki producers. The query 227 component can contain a few attributes that may be needed to retrieve 228 the resource identified by the URI path. Both path and query 229 components may contain vendor specific attributes. Such attribute 230 names must start with an "x-" prefix. Attributes in the path 231 component are delimited by ';' character, attributes in the query 232 component use '&' as a delimiter. 234 The general '/' delimiter was removed from available characters that 235 do not have to be percent-encoded in the path component so that 236 generic URI parsers never split the path component into multiple 237 segments. The '/' delimiter can be used unencoded in the query 238 component. Delimiter '?' was removed since the PKCS#11 URI uses a 239 query component. Delimiter '#' was removed so that generic URI 240 parsers are not confused by unencoded hash characters. All other 241 generic delimiters are allowed to be used unencoded (':', '[', ']', 242 and '@') in the PKCS#11 URI. 244 The path component attribute "token" represents a token label and 245 corresponds to the "label" member of the CK_TOKEN_INFO structure, the 246 attribute "manufacturer" corresponds to the "manufacturerID" member 247 of CK_TOKEN_INFO, the attribute "serial" corresponds to the 248 "serialNumber" member of CK_TOKEN_INFO, the attribute "model" 249 corresponds to the "model" member of CK_TOKEN_INFO, the attribute 250 "library-manufacturer" represents the Cryptoki library manufacturer 251 and corresponds to the "manufacturerID" member of the CK_INFO 252 structure, the attribute "library-description" corresponds to the 253 "libraryDescription" member of CK_INFO, the attribute "library- 254 version" corresponds to the "libraryVersion" member of CK_INFO, the 255 attribute "object" represents a PKCS#11 object label and corresponds 256 to the "CKA_LABEL" object attribute, the attribute "type" represents 257 the type of the object and corresponds to the "CKA_CLASS" object 258 attribute, and the attribute "id" represents the object ID and 259 corresponds to the "CKA_ID" object attribute. The query component 260 attribute "pin-source" specifies where the application or library 261 should find the normal user's token PIN, the "pin-value" attribute 262 provides the normal user's PIN value directly, if needed, and the 263 "module-name" and "module-path" attributes modify default settings 264 for accessing PKCS#11 providers. For the definition of a "normal 265 user", see [pkcs11_spec]. 267 The ABNF rules above is a best effort definition and this paragraph 268 specifies additional constraints. The PKCS#11 URI must not contain 269 duplicate attributes of the same name in the URI path component. It 270 means that each attribute may be present at most once in the PKCS#11 271 URI path. Aside from the query attributes defined in this document, 272 duplicate attributes may be present in the URI query component and it 273 is up to the URI consumer to decide on how to deal with such 274 duplicates. 276 It is recommended to percent-encode the whole value of the "id" 277 attribute which is supposed to be handled as arbitrary binary data. 279 The "library-version" attribute represents the major and minor 280 version number of the library and its format is "M.N". Both numbers 281 are one byte in size, see the "libraryVersion" member of the CK_INFO 282 structure in [pkcs11_spec] for more information. Value "M" for the 283 attribute must be interpreted as "M" for the major and "0" for the 284 minor version of the library. If the attribute is present the major 285 version number is mandatory. 287 An empty PKCS#11 URI path attribute that does allow for an empty 288 value matches a corresponding structure member or an object attribute 289 with an empty value. Note that according to the PKCS#11 290 specification [pkcs11_spec], empty character values in a PKCS#11 API 291 producer must be padded with spaces and should not be NULL 292 terminated. 294 3.4. PKCS#11 URI Scheme Query Attribute Semantics 296 An application may always ask for a PIN by any means it decides to. 297 What is more, in order not to limit PKCS#11 URI portability the "pin- 298 source" attribute value format and interpretation is left to be 299 implementation specific. However, we recommend the certain rules to 300 be followed in descending order for the value of the "pin-source" 301 attribute: 303 o if the value represents a local absolute path the implementation 304 should use it as a PIN file containing the PIN value 306 o if the value contains "|" the 307 implementation should read the PIN from the output of an 308 application specified with absolute path "". Note that character "|" representing a pipe does not have 310 to be percent encoded in the query component of the PKCS#11 URI. 312 o if the value represents a URI treat it as an object containing the 313 PIN. Such a URI may be "file:", "https:", another PKCS#11 URI, or 314 something else. 316 o interpret the value as needed in an implementation dependend way 318 If a URI contains both "pin-source" and "pin-value" query attributes 319 the URI should be refused as invalid. 321 Use of the "pin-value" attribute may have security related 322 consequences. Section 6 should be consulted before this attribute is 323 ever used. Standard percent encoding rules should be followed for 324 the attribute value. 326 A consumer of PKCS#11 URIs may modify default settings for accessing 327 a PKCS#11 provider or providers by accepting query component 328 attributes "module-name" and "module-path"." 330 Processing the URI query module attributes should follow these rules: 332 o attribute "module-name" is expected to contain a case-insensitive 333 PKCS#11 module name (not path nor filename) without system 334 specific affixes. Such affix could be an ".so" or ".DLL" suffix, 335 or a "lib" prefix, for example. Not using system specific affixes 336 is expected to increase portability of PKCS#11 URIs among 337 different systems. A URI consumer searching for PKCS#11 modules 338 is expected to use a system or application specific locations to 339 find modules based on the name provided in the attribute. 341 o attribute "module-path" is expected to contain a system specific 342 absolute path to the PKCS#11 module, or a system specific absolute 343 path to the directory of where PKCS#11 modules are located. 345 o the URI consumer may refuse to accept either of the attributes, or 346 both. If use of an attribute present in the URI string is not 347 accepted a warning message should be presented to the provider of 348 the URI. 350 o if either of the module attributes is present, only those modules 351 found matching these query attributes should be used to search for 352 an object represented by the URI. 354 o use of the module attributes does not suppress matching of any 355 other URI path component attributes present in a URI. 357 o semantics of using both attributes in the same URI string is 358 implementation specific but such use should be avoided. Attribute 359 "module-name" is preferred to "module-path" due to its system 360 independent nature but the latter may be more suitable for 361 development and debugging. 363 o a URI may not contain multiple module attributes of the same name. 365 Use of the module attributes may have security related consequences. 366 Section 6 should be consulted before these attribute are ever used. 368 A word "module" was chosen over word "library" in these query 369 attribute names to avoid confusion with semantically different 370 library attributes used in the URI path component. 372 3.5. PKCS#11 URI Matching Guidelines 374 The PKCS#11 URI can identify PKCS#11 storage objects, tokens, or 375 Cryptoki libraries. The following guidelines should help a PKCS#11 376 URI consumer (eg. an application accepting PKCS#11 URIs) to match the 377 URI with the desired resource. 379 o the consumer must know whether the URI is to identify PKCS#11 380 storage object(s), token(s), or Cryptoki producer(s). 382 o if the consumer is willing to accept query component module 383 attributes only those PKCS#11 providers matching these attributes 384 should be worked with. See Section 3.4 for more information. 386 o an unrecognized attribute in the URI path component, including a 387 vendor specific attribute, should result in an empty set of 388 matched resources. The consumer should consider whether an error 389 message presented to the user is appropriate in such a case. 391 o an unrecognized attribute in the URI query should be ignored. The 392 consumer should consider whether a warning message presented to 393 the user is appropriate in such a case. 395 o an attribute not present in the URI path but known to a consumer 396 matches everything. Each additional attribute present in the URI 397 path further restricts the selection. 399 o a logical extension of the above is that an empty URI path matches 400 everything. For example, if used to identify storage objects it 401 matches all accessible objects in all tokens provided by all 402 PKCS#11 API producers found in the system. 404 o use of PIN attributes may change the set of storage objects 405 visible to the consumer. 407 o in addition to query component attributes defined in this 408 document, vendor specific query attributes may contain further 409 information about how to perform the selection or other related 410 information. 412 3.6. PKCS#11 URI Comparison 414 Comparison of two URIs is a way of determining whether the URIs are 415 equivalent without comparing the actual resource the URIs point to. 416 The comparison of URIs aims to minimize false negatives while 417 strictly avoiding false positives. 419 Two PKCS#11 URIs are said to be equal if URIs as character strings 420 are identical as specified in Section 6.2.1 of [RFC3986], or if both 421 following rules are fulfilled: 423 o set of attributes present in the URI is equal. Note that the 424 ordering of attributes in the URI string is not significant for 425 the mechanism of comparison. 427 o values of respective attributes are equal based on rules specified 428 below 430 The rules for comparing values of respective attributes are: 432 o values of path component attributes "library-description", 433 "library-manufacturer", "manufacturer", "model", "object", 434 "serial", "token", "type", and query component attribute "module- 435 name" must be compared using a simple string comparison as 436 specified in Section 6.2.1 of [RFC3986] after the case and the 437 percent-encoding normalization are both applied as specified in 438 Section 6.2.2 of [RFC3986]. 440 o value of attribute "id" must be compared using the simple string 441 comparison after all bytes are percent-encoded using uppercase 442 letters for digits A-F. 444 o value of "pin-source", if deemed containing the filename with the 445 PIN value, must be compared using the simple string comparison 446 after the full syntax based normalization as specified in 447 Section 6.2.2 of [RFC3986] is applied. If value of the "pin- 448 source" attribute is believed to be overloaded it is recommended 449 to perform case and percent-encoding normalization before the 450 values are compared but the exact mechanism of comparison is left 451 to the application. 453 o value of attribute "module-path" must be compared using the simple 454 string comparison after the full syntax based normalization as 455 specified in Section 6.2.2 of [RFC3986] is applied. 457 o value of attribute "library-version" must be processed as a 458 specific scheme-based normalization permitted by Section 6.2.3 of 459 [RFC3986]. The value must be split into a major and minor version 460 with character '.' (dot) serving as a delimiter. Library version 461 "M" must be treated as "M" for the major version and "0" for the 462 minor version. Resulting minor and major version numbers must be 463 then separately compared numerically. 465 o when comparing vendor specific attributes it is recommended to 466 perform case and percent-encoding normalization before the values 467 are compared but the exact mechanism of comparison is left to the 468 application. 470 4. Examples of PKCS#11 URIs 472 This section contains some examples of how PKCS#11 token objects, 473 PKCS#11 tokens, and PKCS#11 libraries can be identified using the 474 PKCS#11 URI scheme. Note that in some of the following examples, 475 newlines and spaces were inserted for better readability. As 476 specified in Appendix C of [RFC3986], whitespace should be ignored 477 when extracting the URI. Also note that all spaces as part of the 478 URI are percent-encoded, as specified in Appendix A of [RFC3986]. 480 An empty PKCS#11 URI might be useful to PKCS#11 consumers: 482 pkcs11: 484 One of the simplest and most useful forms might be a PKCS#11 URI that 485 specifies only an object label and its type. The default token is 486 used so the URI does not specify it. Note that when specifying 487 public objects, a token PIN might not be required. 489 pkcs11:object=my-pubkey;type=public 491 When a private key is specified either the "pin-source" attribute, 492 "pin-value, or an application specific method would be usually used. 493 Note that '/' is not percent-encoded in the "pin-source" attribute 494 value since this attribute is part of the query component, not the 495 path, and thus is separated by '?' from the rest of the URI. 497 pkcs11:object=my-key;type=private?pin-source=/etc/token 499 The following example identifies a certificate in the software token. 500 Note an empty value for the attribute "serial". Also note that the 501 "id" attribute value is entirely percent-encoded, as recommended. 502 While ',' is in the reserved set it does not have to be percent- 503 encoded since it does not conflict with any sub-delimiters used. The 504 '#' character as in "The Software PKCS#11 Softtoken" must be percent- 505 encoded. 507 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 508 manufacturer=Snake%20Oil,%20Inc.; 509 model=1.0; 510 object=my-certificate; 511 type=cert; 512 id=%69%95%3E%5C%F4%BD%EC%91; 513 serial= 514 ?pin-source=/etc/token_pin 516 The next example covers how to use the "module-name" query attribute. 517 Considering that the module is located in /usr/lib/libmypkcs11.so.1 518 file, the attribute value is "mypkcs11", ie. only the module name 519 without the full path, and without the platform specific "lib" prefix 520 and ".so.1" suffix. 522 pkcs11:object=my-sign-key; 523 type=private 524 ?module-name=mypkcs11 526 The following example covers how to use the "module-path" query 527 attribute. The attribute may be useful if a user needs to provide 528 the key via a PKCS#11 module stored on a removable media, for 529 example. 531 pkcs11:object=my-sign-key; 532 type=private 533 ?module-path=/mnt/libmypkcs11.so.1 535 The token alone can be identified without specifying any PKCS#11 536 objects. A PIN may still be needed to list all objects, for example. 537 Section 6 should be consulted before the "pin-value" attribute is 538 ever used. 540 pkcs11:token=Software%20PKCS%2311%20softtoken; 541 manufacturer=Snake%20Oil,%20Inc. 542 ?pin-value=the-pin 544 The Cryptoki library alone can be also identified without specifying 545 a PKCS#11 token or object. 547 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 548 library-description=Soft%20Token%20Library; 549 library-version=1.23 551 The following example shows that the attribute value can contain a 552 semicolon. In such case, it is percent-encoded. The token attribute 553 value must be read as "My token; created by Joe". Lower case letters 554 can also be used in percent-encoding as shown below in the "id" 555 attribute value but note that Sections 2.1 and 6.2.2.1 of [RFC3986] 556 read that all percent-encoded characters should use the uppercase 557 hexadecimal digits. More specifically, if the URI string was to be 558 compared, the algorithm defined in Section 3.6 explicitly requires 559 percent-encoding to use the uppercase digits A-F in the "id" 560 attribute values. And as explained in Section 3.3, library version 561 "3" should be interpreted as "3" for the major and "0" for the minor 562 version of the library. 564 pkcs11:token=My%20token%25%20created%20by%20Joe; 565 library-version=3; 566 id=%01%02%03%Ba%dd%Ca%fe%04%05%06 568 If there is any need to include literal "%;" substring, for example, 569 both characters must be escaped. The token value must be read as "A 570 name with a substring %;". 572 pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; 573 object=my-certificate; 574 type=cert 575 ?pin-source=/etc/token_pin 577 The next example includes a small A with acute in the token name. It 578 must be encoded in octets according to the UTF-8 character encoding 579 and then percent-encoded. Given that a small A with acute is U+225 580 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 581 that is "%C3%A1" in percent-encoding. 583 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 584 object=my-certificate; 585 type=cert 587 Both the path and query components may contain vendor specific 588 attributes. Attributes in the query component may be delimited by 589 either ';' or '&'. We use '&' in the example that follows. 591 pkcs11:token=my-token; 592 object=my-certificate; 593 type=cert; 594 x-vend-aaa=value-a 595 ?pin-source=/etc/token_pin& 596 x-vend-bbb=value-b 598 5. IANA Considerations 600 This document moves the "pkcs11" URI scheme from the provisional to 601 the permanent URI scheme registry. The registration template for the 602 URI scheme is accessible on http://www.iana.org/assignments/uri- 603 schemes. 605 6. Security Considerations 607 There are general security considerations for URI schemes discussed 608 in Section 7 of [RFC3986]. 610 From those security considerations, Section 7.1 of [RFC3986] applies 611 since there is no guarantee that the same PKCS#11 URI will always 612 identify the same object, token, or a library in the future. 614 Section 7.2 of [RFC3986] applies since by accepting query component 615 attributes "module-name" or "module-path" the consumer potentially 616 allows loading of arbitrary code into a process. 618 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 619 world readable command line arguments to run applications, stored in 620 public configuration files, or otherwise used in clear text. For 621 that reason the "pin-value" attribute should only be used if the URI 622 string itself is protected with the same level of security as the 623 token PIN by itself otherwise is. 625 7. References 627 7.1. Normative References 629 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 630 10646", RFC 3629, STD 63, November 2003. 632 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 633 Resource Identifier (URI): Generic Syntax", RFC 3986, STD 634 66, January 2005. 636 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 637 Specifications: ABNF", RFC 5234, STD 68, January 2008. 639 7.2. Informative References 641 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 642 Registration Procedures for New URI Schemes", RFC 4395, 643 February 2006. 645 [pkcs11_spec] 646 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 647 Standard v2.20", June 2004. 649 Authors' Addresses 651 Jan Pechanec 652 Oracle Corporation 653 4180 Network Circle 654 Santa Clara CA 95054 655 USA 657 Email: Jan.Pechanec@Oracle.COM 658 URI: http://www.oracle.com 660 Darren J. Moffat 661 Oracle Corporation 662 Oracle Parkway 663 Thames Valley Park 664 Reading RG6 1RA 665 UK 667 Email: Darren.Moffat@Oracle.COM 668 URI: http://www.oracle.com