idnits 2.17.1 draft-pechanec-pkcs11uri-16.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 (October 13, 2014) is 3484 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: April 16, 2015 October 13, 2014 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-16 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 April 16, 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 . . . . . . 8 60 3.5. PKCS#11 URI Matching Guidelines . . . . . . . . . . . . . 10 61 3.6. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 11 62 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 12 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 67 7.2. Informative References . . . . . . . . . . . . . . . . . 16 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 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. 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 producers. 133 2. Contributors 135 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 136 Jaroslav Imrich contributed to the development of this document. 138 3. PKCS#11 URI Scheme Definition 140 In accordance with [RFC4395], this section provides the information 141 required to register the PKCS#11 URI scheme. 143 3.1. PKCS#11 URI Scheme Name 145 pkcs11 147 3.2. PKCS#11 URI Scheme Status 149 Permanent. 151 3.3. PKCS#11 URI Scheme Syntax 153 The PKCS#11 URI is a sequence of attribute value pairs separated by a 154 semicolon that form a one level path component, optionally followed 155 by a query. In accordance with Section 2.5 of [RFC3986], the data 156 should first be encoded as octets according to the UTF-8 character 157 encoding [RFC3629]; then only those octets that do not correspond to 158 characters in the unreserved set or to permitted characters from the 159 reserved set should be percent-encoded. This specification suggests 160 one allowable exception to that rule for the "id" attribute, as 161 stated later in this section. Grammar rules "unreserved" and "pct- 162 encoded" in the PKCS#11 URI specification below are imported from 163 [RFC3986]. As a special case, note that according to Appendix A of 164 [RFC3986], a space must be percent-encoded. 166 PKCS#11 specification imposes various limitations on the value of 167 attributes, be it a more restrictive character set for the "serial" 168 attribute or fixed sized buffers for almost all the others, including 169 "token", "manufacturer", and "model" attributes. However, the 170 PKCS#11 URI notation does not impose such limitations aside from 171 removing generic and PKCS#11 URI delimiters from a permitted 172 character set. We believe that being too restrictive on the 173 attribute values could limit the PKCS#11 URI usefulness. What is 174 more, possible future changes to the PKCS#11 specification should not 175 affect existing attributes. 177 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 178 [RFC5234]): 180 pk11-URI = "pkcs11" ":" pk11-path *1("?" pk11-query) 181 ; Path component and its attributes. Path may be empty. 182 pk11-path = *1(pk11-pattr *(";" pk11-pattr)) 183 pk11-pattr = pk11-token / pk11-manuf / pk11-serial / 184 pk11-model / pk11-lib-manuf / 185 pk11-lib-ver / pk11-lib-desc / 186 pk11-object / pk11-type / pk11-id / 187 pk11-x-pattr 188 ; Query component and its attributes. Query may be empty. 189 pk11-qattr = pk11-pin-source / pk11-pin-value / 190 pk11-module-name / pk11-module-path / 191 pk11-x-qattr 192 pk11-query = *1(pk11-qattr *("&" pk11-qattr)) 193 ; RFC 3986 section 2.2 mandates all potentially reserved characters 194 ; that do not conflict with actual delimiters of the URI do not have 195 ; to be percent-encoded. 196 pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" / 197 "'" / "(" / ")" / "*" / "+" / "," / "=" 198 pk11-path-res-avail = pk11-res-avail / "&" 199 ; We allow "/" and "?" in the query to be unencoded but "&" must 200 ; be encoded since it may be used as a delimiter in the component. 201 pk11-query-res-avail = pk11-res-avail / "/" / "?" / "|" 202 pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded 203 pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded 204 pk11-token = "token" "=" *pk11-pchar 205 pk11-manuf = "manufacturer" "=" *pk11-pchar 206 pk11-serial = "serial" "=" *pk11-pchar 207 pk11-model = "model" "=" *pk11-pchar 208 pk11-lib-manuf = "library-manufacturer" "=" *pk11-pchar 209 pk11-lib-desc = "library-description" "=" *pk11-pchar 210 pk11-lib-ver = "library-version" "=" 1*DIGIT *1("." 1*DIGIT) 211 pk11-object = "object" "=" *pk11-pchar 212 pk11-type = "type" "=" *1("public" / "private" / "cert" / 213 "secret-key" / "data") 214 pk11-id = "id" "=" *pk11-pchar 215 pk11-pin-source = "pin-source" "=" *pk11-qchar 216 pk11-pin-value = "pin-value" "=" *pk11-qchar 217 pk11-module-name = "module-name" = *pk11-qchar 218 pk11-module-path = "module-path" = *pk11-qchar 219 pk11-x-attr-nm-char = ALPHA / DIGIT / "-" / "_" 220 ; Permitted value of a vendor specific attribute is based on 221 ; whether the attribute is used in the path or in the query. 222 pk11-x-pattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-pchar 223 pk11-x-qattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-qchar 224 The URI path component contains attributes that identify a resource 225 in a one level hierarchy provided by Cryptoki producers. The query 226 component can contain a few attributes that may be needed to retrieve 227 the resource identified by the URI path. Both path and query 228 components may contain vendor specific attributes. Such attribute 229 names must start with an "x-" prefix. Attributes in the path 230 component are delimited by ';' character, attributes in the query 231 component use '&' as a delimiter. 233 The general '/' delimiter was removed from available characters that 234 do not have to be percent-encoded in the path component so that 235 generic URI parsers never split the path component into multiple 236 segments. The '/' delimiter can be used unencoded in the query 237 component. Delimiter '?' was removed since the PKCS#11 URI uses a 238 query component. Delimiter '#' was removed so that generic URI 239 parsers are not confused by unencoded hash characters. All other 240 generic delimiters are allowed to be used unencoded (':', '[', ']', 241 and '@') in the PKCS#11 URI. 243 The following table presents mapping between the PKCS#11 URI path 244 component attributes and the PKCS#11 API structure members and object 245 attributes. Given that PKCS#11 URI users may be quite ignorant about 246 the PKCS#11 specification the mapping is a product of a necessary 247 compromise between how precisely are the URI attribute names mapped 248 to the names in the specification and the ease of use and 249 understanding of the URI scheme. 251 +----------------------+---------------------+----------------------+ 252 | URI component path | Attribute | Attribute | 253 | attribute name | represents | corresponds in the | 254 | | | PKCS#11 | 255 | | | specification to | 256 +----------------------+---------------------+----------------------+ 257 +----------------------+---------------------+----------------------+ 258 | id | key identifier for | "CKA_ID" object | 259 | | object | attribute | 260 +----------------------+---------------------+----------------------+ 261 | library-description | character-string | "libraryDescription" | 262 | | description of the | member of CK_INFO | 263 | | library | structure | 264 +----------------------+---------------------+----------------------+ 265 | library-manufacturer | ID of the Cryptoki | "manufacturerID" | 266 | | library | member of the | 267 | | manufacturer | CK_INFO structure | 268 +----------------------+---------------------+----------------------+ 269 | library-version | Cryptoki library | "libraryVersion" | 270 | | version number | member of CK_INFO | 271 | | | structure | 272 +----------------------+---------------------+----------------------+ 273 | manufacturer | ID of the token | "manufacturerID" | 274 | | manufacturer | member of | 275 | | | CK_TOKEN_INFO | 276 | | | structure | 277 +----------------------+---------------------+----------------------+ 278 | model | token model | "model" member of | 279 | | | CK_TOKEN_INFO | 280 | | | structure | 281 +----------------------+---------------------+----------------------+ 282 | object | description (name) | "CKA_LABEL" object | 283 | | of the object | attribute | 284 +----------------------+---------------------+----------------------+ 285 | serial | character-string | "serialNumber" | 286 | | serial number of | member of | 287 | | the token | CK_TOKEN_INFO | 288 | | | structure | 289 +----------------------+---------------------+----------------------+ 290 | token | application-defined | "label" member of | 291 | | label, assigned | the CK_TOKEN_INFO | 292 | | during token | structure | 293 | | initialization | | 294 +----------------------+---------------------+----------------------+ 295 | type | object class (type) | "CKA_CLASS" object | 296 | | | attribute | 297 +----------------------+---------------------+----------------------+ 299 Table 1: Mapping between URI path component attributes and PKCS#11 300 specification names 302 The query component attribute "pin-source" specifies where the 303 application or library should find the normal user's token PIN, the 304 "pin-value" attribute provides the normal user's PIN value directly, 305 if needed, and the "module-name" and "module-path" attributes modify 306 default settings for accessing PKCS#11 providers. For the definition 307 of a "normal user", see [pkcs11_spec]. 309 The ABNF rules above is a best effort definition and this paragraph 310 specifies additional constraints. The PKCS#11 URI must not contain 311 duplicate attributes of the same name in the URI path component. It 312 means that each attribute may be present at most once in the PKCS#11 313 URI path. Aside from the query attributes defined in this document, 314 duplicate attributes may be present in the URI query component and it 315 is up to the URI consumer to decide on how to deal with such 316 duplicates. 318 It is recommended to percent-encode the whole value of the "id" 319 attribute which is supposed to be handled as arbitrary binary data. 321 The "library-version" attribute represents the major and minor 322 version number of the library and its format is "M.N". Both numbers 323 are one byte in size, see the "libraryVersion" member of the CK_INFO 324 structure in [pkcs11_spec] for more information. Value "M" for the 325 attribute must be interpreted as "M" for the major and "0" for the 326 minor version of the library. If the attribute is present the major 327 version number is mandatory. Both "M" and "N" must be decimal 328 numbers. 330 An empty PKCS#11 URI path attribute that does allow for an empty 331 value matches a corresponding structure member or an object attribute 332 with an empty value. Note that according to the PKCS#11 333 specification [pkcs11_spec], empty character values in a PKCS#11 API 334 producer must be padded with spaces and should not be NULL 335 terminated. 337 3.4. PKCS#11 URI Scheme Query Attribute Semantics 339 An application may always ask for a PIN by any means it decides to. 340 What is more, in order not to limit PKCS#11 URI portability the "pin- 341 source" attribute value format and interpretation is left to be 342 implementation specific. However, we recommend the certain rules to 343 be followed in descending order for the value of the "pin-source" 344 attribute: 346 o if the value represents a local absolute path the implementation 347 should use it as a PIN file containing the PIN value 349 o if the value contains "|" the 350 implementation should read the PIN from the output of an 351 application specified with absolute path "". Note that character "|" representing a pipe does not have 353 to be percent encoded in the query component of the PKCS#11 URI. 355 o if the value represents a URI treat it as an object containing the 356 PIN. Such a URI may be "file:", "https:", another PKCS#11 URI, or 357 something else. 359 o interpret the value as needed in an implementation dependent way 361 If a URI contains both "pin-source" and "pin-value" query attributes 362 the URI should be refused as invalid. 364 Use of the "pin-value" attribute may have security related 365 consequences. Section 6 should be consulted before this attribute is 366 ever used. Standard percent encoding rules should be followed for 367 the attribute value. 369 A consumer of PKCS#11 URIs may modify default settings for accessing 370 a PKCS#11 provider or providers by accepting query component 371 attributes "module-name" and "module-path"." 373 Processing the URI query module attributes should follow these rules: 375 o attribute "module-name" is expected to contain a case-insensitive 376 PKCS#11 module name (not path nor filename) without system 377 specific affixes. Such affix could be an ".so" or ".DLL" suffix, 378 or a "lib" prefix, for example. Not using system specific affixes 379 is expected to increase portability of PKCS#11 URIs among 380 different systems. A URI consumer searching for PKCS#11 modules 381 is expected to use a system or application specific locations to 382 find modules based on the name provided in the attribute. 384 o attribute "module-path" is expected to contain a system specific 385 absolute path to the PKCS#11 module, or a system specific absolute 386 path to the directory of where PKCS#11 modules are located. For 387 security reasons, a URI with a relative path in this attribute 388 should be always rejected. 390 o the URI consumer may refuse to accept either of the attributes, or 391 both. If use of an attribute present in the URI string is not 392 accepted a warning message should be presented to the provider of 393 the URI. 395 o if either of the module attributes is present, only those modules 396 found matching these query attributes should be used to search for 397 an object represented by the URI. 399 o use of the module attributes does not suppress matching of any 400 other URI path component attributes present in a URI. 402 o semantics of using both attributes in the same URI string is 403 implementation specific but such use should be avoided. Attribute 404 "module-name" is preferred to "module-path" due to its system 405 independent nature but the latter may be more suitable for 406 development and debugging. 408 o a URI may not contain multiple module attributes of the same name. 410 Use of the module attributes may have security related consequences. 411 Section 6 should be consulted before these attributes are ever used. 413 A word "module" was chosen over word "library" in these query 414 attribute names to avoid confusion with semantically different 415 library attributes used in the URI path component. 417 3.5. PKCS#11 URI Matching Guidelines 419 The PKCS#11 URI can identify PKCS#11 storage objects, tokens, or 420 Cryptoki libraries. Note that since a URI may identify three 421 different types of entities the context within which the URI is used 422 may be needed to determine the type. For example, a URI with only 423 library attributes may either represent all objects in all tokens in 424 all Cryptoki libraries identified by the URI, all tokens in those 425 libraries, or just the libraries. 427 The following guidelines should help a PKCS#11 URI consumer (eg. an 428 application accepting PKCS#11 URIs) to match the URI with the desired 429 resource. 431 o the consumer must know whether the URI is to identify PKCS#11 432 storage object(s), token(s), or Cryptoki producer(s). 434 o if the consumer is willing to accept query component module 435 attributes only those PKCS#11 providers matching these attributes 436 should be worked with. See Section 3.4 for more information. 438 o an unrecognized attribute in the URI path component, including a 439 vendor specific attribute, should result in an empty set of 440 matched resources. The consumer should consider whether an error 441 message presented to the user is appropriate in such a case. 443 o an unrecognized attribute in the URI query should be ignored. The 444 consumer should consider whether a warning message presented to 445 the user is appropriate in such a case. 447 o an attribute not present in the URI path but known to a consumer 448 matches everything. Each additional attribute present in the URI 449 path further restricts the selection. 451 o a logical extension of the above is that an empty URI path matches 452 everything. For example, if used to identify storage objects it 453 matches all accessible objects in all tokens provided by all 454 PKCS#11 API producers found in the system. 456 o use of PIN attributes may change the set of storage objects 457 visible to the consumer. 459 o in addition to query component attributes defined in this 460 document, vendor specific query attributes may contain further 461 information about how to perform the selection or other related 462 information. 464 3.6. PKCS#11 URI Comparison 466 Comparison of two URIs is a way of determining whether the URIs are 467 equivalent without comparing the actual resource the URIs point to. 468 The comparison of URIs aims to minimize false negatives while 469 strictly avoiding false positives. 471 Two PKCS#11 URIs are said to be equal if URIs as character strings 472 are identical as specified in Section 6.2.1 of [RFC3986], or if both 473 following rules are fulfilled: 475 o set of attributes present in the URI is equal. Note that the 476 ordering of attributes in the URI string is not significant for 477 the mechanism of comparison. 479 o values of respective attributes are equal based on rules specified 480 below 482 The rules for comparing values of respective attributes are: 484 o values of path component attributes "library-description", 485 "library-manufacturer", "manufacturer", "model", "object", 486 "serial", "token", "type", and query component attribute "module- 487 name" must be compared using a simple string comparison as 488 specified in Section 6.2.1 of [RFC3986] after the case and the 489 percent-encoding normalization are both applied as specified in 490 Section 6.2.2 of [RFC3986]. 492 o value of attribute "id" must be compared using the simple string 493 comparison after all bytes are percent-encoded using uppercase 494 letters for digits A-F. 496 o value of attribute "library-version" must be processed as a 497 specific scheme-based normalization permitted by Section 6.2.3 of 498 [RFC3986]. The value must be split into a major and minor version 499 with character '.' (dot) serving as a delimiter. Library version 500 "M" must be treated as "M" for the major version and "0" for the 501 minor version. Resulting minor and major version numbers must be 502 then separately compared numerically. 504 o value of "pin-source", if deemed containing the filename with the 505 PIN value, must be compared using the simple string comparison 506 after the full syntax based normalization as specified in 507 Section 6.2.2 of [RFC3986] is applied. If value of the "pin- 508 source" attribute is believed to be overloaded it is recommended 509 to perform case and percent-encoding normalization before the 510 values are compared but the exact mechanism of comparison is left 511 to the application. 513 o value of attribute "module-path" must be compared using the simple 514 string comparison after the full syntax based normalization as 515 specified in Section 6.2.2 of [RFC3986] is applied. 517 o when comparing vendor specific attributes it is recommended to 518 perform case and percent-encoding normalization before the values 519 are compared but the exact mechanism of such a comparison is left 520 to the application. 522 4. Examples of PKCS#11 URIs 524 This section contains some examples of how PKCS#11 token objects, 525 PKCS#11 tokens, and PKCS#11 libraries can be identified using the 526 PKCS#11 URI scheme. Note that in some of the following examples, 527 newlines and spaces were inserted for better readability. As 528 specified in Appendix C of [RFC3986], whitespace should be ignored 529 when extracting the URI. Also note that all spaces as part of the 530 URI are percent-encoded, as specified in Appendix A of [RFC3986]. 532 An empty PKCS#11 URI might be useful to PKCS#11 consumers. See 533 Section 3.5 for more information on semantics of such a URI. 535 pkcs11: 537 One of the simplest and most useful forms might be a PKCS#11 URI that 538 specifies only an object label and its type. The default token is 539 used so the URI does not specify it. Note that when specifying 540 public objects, a token PIN might not be required. 542 pkcs11:object=my-pubkey;type=public 544 When a private key is specified either the "pin-source" attribute, 545 "pin-value, or an application specific method would be usually used. 546 Note that '/' is not percent-encoded in the "pin-source" attribute 547 value since this attribute is part of the query component, not the 548 path, and thus is separated by '?' from the rest of the URI. 550 pkcs11:object=my-key;type=private?pin-source=/etc/token 552 The following example identifies a certificate in the software token. 553 Note an empty value for the attribute "serial" which matches only 554 empty "serialNumber" member of the "CK_TOKEN_INFO" structure. Also 555 note that the "id" attribute value is entirely percent-encoded, as 556 recommended. While ',' is in the reserved set it does not have to be 557 percent-encoded since it does not conflict with any sub-delimiters 558 used. The '#' character as in "The Software PKCS#11 Softtoken" must 559 be percent-encoded. 561 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 562 manufacturer=Snake%20Oil,%20Inc.; 563 model=1.0; 564 object=my-certificate; 565 type=cert; 566 id=%69%95%3E%5C%F4%BD%EC%91; 567 serial= 568 ?pin-source=/etc/token_pin 570 The next example covers how to use the "module-name" query attribute. 571 Considering that the module is located in /usr/lib/libmypkcs11.so.1 572 file, the attribute value is "mypkcs11", meaning only the module name 573 without the full path, and without the platform specific "lib" prefix 574 and ".so.1" suffix. 576 pkcs11:object=my-sign-key; 577 type=private 578 ?module-name=mypkcs11 580 The following example covers how to use the "module-path" query 581 attribute. The attribute may be useful if a user needs to provide 582 the key via a PKCS#11 module stored on a removable media, for 583 example. Getting the PIN to access the private key here is left to 584 be application specific. 586 pkcs11:object=my-sign-key; 587 type=private 588 ?module-path=/mnt/libmypkcs11.so.1 590 In the context where a token is expected the token can be identified 591 without specifying any PKCS#11 objects. A PIN might still be needed 592 in the context of listing all objects in the token, for example. 593 Section 6 should be consulted before the "pin-value" attribute is 594 ever used. 596 pkcs11:token=Software%20PKCS%2311%20softtoken; 597 manufacturer=Snake%20Oil,%20Inc. 598 ?pin-value=the-pin 600 The Cryptoki library alone can be also identified without specifying 601 a PKCS#11 token or object. 603 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 604 library-description=Soft%20Token%20Library; 605 library-version=1.23 607 The following example shows that the attribute value can contain a 608 semicolon. In such case, it is percent-encoded. The token attribute 609 value must be read as "My token; created by Joe". Lower case letters 610 can also be used in percent-encoding as shown below in the "id" 611 attribute value but note that Sections 2.1 and 6.2.2.1 of [RFC3986] 612 read that all percent-encoded characters should use the uppercase 613 hexadecimal digits. More specifically, if the URI string was to be 614 compared the algorithm defined in Section 3.6 explicitly requires 615 percent-encoding to use the uppercase digits A-F in the "id" 616 attribute values. And as explained in Section 3.3, library version 617 "3" should be interpreted as "3" for the major and "0" for the minor 618 version of the library. 620 pkcs11:token=My%20token%25%20created%20by%20Joe; 621 library-version=3; 622 id=%01%02%03%Ba%dd%Ca%fe%04%05%06 624 If there is any need to include literal "%;" substring, for example, 625 both characters must be escaped. The token value must be read as "A 626 name with a substring %;". 628 pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; 629 object=my-certificate; 630 type=cert 632 The next example includes a small A with acute in the token name. It 633 must be encoded in octets according to the UTF-8 character encoding 634 and then percent-encoded. Given that a small A with acute is U+225 635 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 636 that is "%C3%A1" in percent-encoding. 638 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 639 object=my-certificate; 640 type=cert 642 Both the path and query components may contain vendor specific 643 attributes. Attributes in the query component must be delimited by 644 '&'. 646 pkcs11:token=my-token; 647 object=my-certificate; 648 type=cert; 649 x-vend-aaa=value-a 650 ?pin-source=/etc/token_pin 651 &x-vend-bbb=value-b 653 5. IANA Considerations 655 This document moves the "pkcs11" URI scheme from the provisional to 656 permanent URI scheme registry. The registration template for the URI 657 scheme is accessible on http://www.iana.org/assignments/uri-schemes. 659 6. Security Considerations 661 There are general security considerations for URI schemes discussed 662 in Section 7 of [RFC3986]. 664 From those security considerations, Section 7.1 of [RFC3986] applies 665 since there is no guarantee that the same PKCS#11 URI will always 666 identify the same object, token, or a library in the future. 668 Section 7.2 of [RFC3986] applies since by accepting query component 669 attributes "module-name" or "module-path" the consumer potentially 670 allows loading of arbitrary code into a process. 672 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 673 world readable command line arguments to run applications, stored in 674 public configuration files, or otherwise used in clear text. For 675 that reason the "pin-value" attribute should only be used if the URI 676 string itself is protected with the same level of security as the 677 token PIN itself otherwise is. 679 7. References 681 7.1. Normative References 683 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 684 10646", RFC 3629, STD 63, November 2003. 686 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 687 Resource Identifier (URI): Generic Syntax", RFC 3986, STD 688 66, January 2005. 690 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 691 Specifications: ABNF", RFC 5234, STD 68, January 2008. 693 7.2. Informative References 695 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 696 Registration Procedures for New URI Schemes", RFC 4395, 697 February 2006. 699 [pkcs11_spec] 700 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 701 Standard v2.20", June 2004. 703 Authors' Addresses 705 Jan Pechanec 706 Oracle Corporation 707 4180 Network Circle 708 Santa Clara CA 95054 709 USA 711 Email: Jan.Pechanec@Oracle.COM 712 URI: http://www.oracle.com 714 Darren J. Moffat 715 Oracle Corporation 716 Oracle Parkway 717 Thames Valley Park 718 Reading RG6 1RA 719 UK 721 Email: Darren.Moffat@Oracle.COM 722 URI: http://www.oracle.com