idnits 2.17.1 draft-pechanec-pkcs11uri-17.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 (December 31, 2014) is 3403 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: July 4, 2015 December 31, 2014 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-17 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, and 14 also for identifying PKCS#11 tokens, slots or libraries. The URI is 15 based on how PKCS#11 objects, tokens, slots, and libraries are 16 identified in the PKCS#11 Cryptographic Token Interface Standard. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 4, 2015. 35 Copyright Notice 37 Copyright (c) 2014 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . 4 55 3.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . 4 56 3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . 4 57 3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4 58 3.4. PKCS#11 URI Scheme Query Attribute Semantics . . . . . . 8 59 3.5. PKCS#11 URI Matching Guidelines . . . . . . . . . . . . . 10 60 3.6. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 11 61 3.7. Generating PKCS#11 URIs . . . . . . . . . . . . . . . . . 12 62 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 13 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 66 7.1. Normative References . . . . . . . . . . . . . . . . . . 17 67 7.2. Informative References . . . . . . . . . . . . . . . . . 17 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 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, a slot, or an existing Cryptoki library (also 86 called a producer, module, or provider). The set of storage object 87 types that can be stored in a PKCS#11 token includes a certificate, a 88 public, private or secret key, and a data object. These objects can 89 be 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, 93 manufacturer name, serial number, and token model. Attributes that 94 can identify a slot are a slot ID, description, and manufacturer. 95 Attributes that can identify a Cryptoki library are a library 96 manufacturer, description, and version. Library attributes may be 97 necessary to use if more than one Cryptoki library provides a token 98 and/or PKCS#11 objects of the same name. A set of query attributes 99 is provided as well. 101 The PKCS#11 URI cannot identify other objects defined in the 102 specification [pkcs11_spec] aside from storage objects. For example, 103 objects not identifiable by a PKCS#11 URI include a hardware feature 104 and mechanism. Note that a Cryptoki library does not have to provide 105 for storage objects at all. The URI can still be used to identify a 106 specific PKCS#11 token, slot or an API producer in such a case. 108 A subset of existing PKCS#11 structure members and object attributes 109 was chosen to uniquely identify a PKCS#11 storage object, token, 110 slot, or library in a configuration file, on a command line, or in a 111 configuration property of something else. Should there be a need for 112 a more complex information exchange on PKCS#11 entities a different 113 means of data marshalling should be 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, tokens, and 118 slots through the PKCS#11 API, or identify Cryptoki libraries 119 themselves. 121 The URI scheme defined in this document is designed specifically with 122 a mapping to the PKCS#11 API in mind. The URI uses the scheme, path 123 and query components defined in the Uniform Resource Identifier 124 (URI): Generic Syntax [RFC3986] document. The URI does not use the 125 hierarchical element for a naming authority in the path since the 126 authority part could not be mapped to PKCS#11 API elements. The URI 127 does not use the fragment component. 129 If an application has no access to a producer or producers of the 130 PKCS#11 API the query component module attributes can be used. 131 However, the PKCS#11 URI consumer can always decide to provide its 132 own adequate user interface to locate and load PKCS#11 API producers. 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 2. Contributors 140 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 141 Jaroslav Imrich contributed to the development of this document. 143 3. PKCS#11 URI Scheme Definition 145 In accordance with [RFC4395], this section provides the information 146 required to register the PKCS#11 URI scheme. 148 3.1. PKCS#11 URI Scheme Name 150 pkcs11 152 3.2. PKCS#11 URI Scheme Status 154 Permanent. 156 3.3. PKCS#11 URI Scheme Syntax 158 The PKCS#11 URI is a sequence of attribute value pairs separated by a 159 semicolon that form a one level path component, optionally followed 160 by a query. In accordance with Section 2.5 of [RFC3986], the data 161 should first be encoded as octets according to the UTF-8 character 162 encoding [RFC3629]; then only those octets that do not correspond to 163 characters in the unreserved set or to permitted characters from the 164 reserved set should be percent-encoded. This specification suggests 165 one allowable exception to that rule for the "id" attribute, as 166 stated later in this section. Note that if a URI does carry 167 characters outside of the ASCII character set a conversion to an 168 Internationalized Resource Identifier (IRI) defined in [RFC3987] may 169 be considered. Grammar rules "unreserved" and "pct-encoded" in the 170 PKCS#11 URI specification below are imported from [RFC3986]. As a 171 special case, note that according to Appendix A of [RFC3986], a space 172 must be percent-encoded. 174 The PKCS#11 specification imposes various limitations on the value of 175 attributes, be it a more restrictive character set for the "serial" 176 attribute or fixed sized buffers for almost all the others, including 177 "token", "manufacturer", and "model" attributes. However, the 178 PKCS#11 URI notation does not impose such limitations aside from 179 removing generic and PKCS#11 URI delimiters from a permitted 180 character set. We believe that being too restrictive on the 181 attribute values could limit the PKCS#11 URI usefulness. What is 182 more, possible future changes to the PKCS#11 specification should not 183 affect existing attributes. 185 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 186 [RFC5234]): 188 pk11-URI = "pkcs11:" pk11-path [ "?" pk11-query ] 189 ; Path component and its attributes. Path may be empty. 190 pk11-path = [ pk11-pattr *(";" pk11-pattr) ] 191 pk11-pattr = pk11-token / pk11-manuf / pk11-serial / 192 pk11-model / pk11-lib-manuf / 193 pk11-lib-ver / pk11-lib-desc / 194 pk11-object / pk11-type / pk11-id / 195 pk11-slot-desc / pk11-slot-manuf / 196 pk11-slot-id / pk11-v-pattr 197 ; Query component and its attributes. Query may be empty. 198 pk11-qattr = pk11-pin-source / pk11-pin-value / 199 pk11-module-name / pk11-module-path / 200 pk11-v-qattr 201 pk11-query = [ pk11-qattr *("&" pk11-qattr) ] 202 ; RFC 3986 section 2.2 mandates all potentially reserved characters 203 ; that do not conflict with actual delimiters of the URI do not have 204 ; to be percent-encoded. 205 pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" / 206 "'" / "(" / ")" / "*" / "+" / "," / "=" 207 pk11-path-res-avail = pk11-res-avail / "&" 208 ; "/" and "?" in the query component MAY be unencoded but "&" MUST 209 ; be encoded since it functions as a delimiter within the component. 210 pk11-query-res-avail = pk11-res-avail / "/" / "?" / "|" 211 pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded 212 pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded 213 pk11-token = "token" "=" *pk11-pchar 214 pk11-manuf = "manufacturer" "=" *pk11-pchar 215 pk11-serial = "serial" "=" *pk11-pchar 216 pk11-model = "model" "=" *pk11-pchar 217 pk11-lib-manuf = "library-manufacturer" "=" *pk11-pchar 218 pk11-lib-desc = "library-description" "=" *pk11-pchar 219 pk11-lib-ver = "library-version" "=" 1*DIGIT [ "." 1*DIGIT ] 220 pk11-object = "object" "=" *pk11-pchar 221 pk11-type = "type" "=" ( "public" / "private" / "cert" / 222 "secret-key" / "data" ) 223 pk11-id = "id" "=" *pk11-pchar 224 pk11-slot-manuf = "slot-manufacturer" "=" *pk11-pchar 225 pk11-slot-desc = "slot-description" "=" *pk11-pchar 226 pk11-slot-id = "slot-id" "=" 1*DIGIT 227 pk11-pin-source = "pin-source" "=" *pk11-qchar 228 pk11-pin-value = "pin-value" "=" *pk11-qchar 229 pk11-module-name = "module-name" "=" *pk11-qchar 230 pk11-module-path = "module-path" "=" *pk11-qchar 231 pk11-v-attr-nm-char = ALPHA / DIGIT / "-" / "_" 232 ; Permitted value of a vendor specific attribute is based on 233 ; whether the attribute is used in the path or in the query. 234 pk11-v-pattr = 1*pk11-v-attr-nm-char "=" *pk11-pchar 235 pk11-v-qattr = 1*pk11-v-attr-nm-char "=" *pk11-qchar 236 The URI path component contains attributes that identify a resource 237 in a one level hierarchy provided by Cryptoki producers. The query 238 component can contain a few attributes that may be needed to retrieve 239 the resource identified by the URI path. Attributes in the path 240 component are delimited by ';' character, attributes in the query 241 component use '&' as a delimiter. 243 Both path and query components may contain vendor specific 244 attributes. Such attribute names MUST NOT clash with existing 245 attribute names. Note that in accordance with [BCP178], previously 246 used convention of starting vendor attributes with an "x-" prefix is 247 now depricated. 249 The general '/' delimiter MUST be percent-encoded in the path 250 component so that generic URI parsers never split the path component 251 into multiple segments. It MAY be unencoded in the query component. 252 Delimiter '?' MUST be percent-encoded in the path component since 253 the PKCS#11 URI uses a query component. Delimiter '#' MUST be always 254 percent-encoded so that generic URI parsers do not treat a hash as a 255 beginning of a fragment identifier component. All other generic 256 delimiters MAY be used unencoded (':', '[', ']', and '@') in the 257 PKCS#11 URI. 259 The following table presents mapping between the PKCS#11 URI path 260 component attributes and the PKCS#11 API structure members and object 261 attributes. Given that PKCS#11 URI users may be quite ignorant about 262 the PKCS#11 specification the mapping is a product of a necessary 263 compromise between how precisely are the URI attribute names mapped 264 to the names in the specification and the ease of use and 265 understanding of the URI scheme. 267 +----------------------+---------------------+----------------------+ 268 | URI component path | Attribute | Attribute | 269 | attribute name | represents | corresponds in the | 270 | | | PKCS#11 | 271 | | | specification to | 272 +----------------------+---------------------+----------------------+ 273 | | | | 274 +----------------------+---------------------+----------------------+ 275 | id | key identifier for | "CKA_ID" object | 276 | | object | attribute | 277 +----------------------+---------------------+----------------------+ 278 | library-description | character-string | "libraryDescription" | 279 | | description of the | member of CK_INFO | 280 | | library | structure | 281 +----------------------+---------------------+----------------------+ 282 | library-manufacturer | ID of the Cryptoki | "manufacturerID" | 283 | | library | member of the | 284 | | manufacturer | CK_INFO structure | 285 +----------------------+---------------------+----------------------+ 286 | library-version | Cryptoki library | "libraryVersion" | 287 | | version number | member of CK_INFO | 288 | | | structure | 289 +----------------------+---------------------+----------------------+ 290 | manufacturer | ID of the token | "manufacturerID" | 291 | | manufacturer | member of | 292 | | | CK_TOKEN_INFO | 293 | | | structure | 294 +----------------------+---------------------+----------------------+ 295 | model | token model | "model" member of | 296 | | | CK_TOKEN_INFO | 297 | | | structure | 298 +----------------------+---------------------+----------------------+ 299 | object | description (name) | "CKA_LABEL" object | 300 | | of the object | attribute | 301 +----------------------+---------------------+----------------------+ 302 | serial | character-string | "serialNumber" | 303 | | serial number of | member of | 304 | | the token | CK_TOKEN_INFO | 305 | | | structure | 306 +----------------------+---------------------+----------------------+ 307 | slot-description | slot description | "slotDescription" | 308 | | | member of | 309 | | | CK_SLOT_INFO | 310 | | | structure | 311 +----------------------+---------------------+----------------------+ 312 | slot-id | Cryptoki-assigned | decimal number of | 313 | | value that | "CK_SLOT_ID" type | 314 | | identifies a slot | | 315 +----------------------+---------------------+----------------------+ 316 | slot-manufacturer | ID of the slot | "manufacturerID" | 317 | | manufacturer | member of | 318 | | | CK_SLOT_INFO | 319 | | | structure | 320 +----------------------+---------------------+----------------------+ 321 | token | application-defined | "label" member of | 322 | | label, assigned | the CK_TOKEN_INFO | 323 | | during token | structure | 324 | | initialization | | 325 +----------------------+---------------------+----------------------+ 326 | type | object class (type) | "CKA_CLASS" object | 327 | | | attribute | 328 +----------------------+---------------------+----------------------+ 330 Table 1: Mapping between URI path component attributes and PKCS#11 331 specification names 333 The query component attribute "pin-source" specifies where the 334 application or library should find the normal user's token PIN, the 335 "pin-value" attribute provides the normal user's PIN value directly, 336 if needed, and the "module-name" and "module-path" attributes modify 337 default settings for accessing PKCS#11 providers. For the definition 338 of a "normal user", see [pkcs11_spec]. 340 The ABNF rules above is a best effort definition and this paragraph 341 specifies additional constraints. The PKCS#11 URI MUST NOT contain 342 duplicate attributes of the same name in the URI path component. It 343 means that each attribute may be present at most once in the PKCS#11 344 URI path. Aside from the query attributes defined in this document, 345 duplicate (vendor) attributes MAY be present in the URI query 346 component and it is up to the URI consumer to decide on how to deal 347 with such duplicates. 349 The whole value of the "id" attribute SHOULD be percent-encoded since 350 it is supposed to be handled as arbitrary binary data. 352 The "library-version" attribute represents the major and minor 353 version number of the library and its format is "M.N". Both numbers 354 are one byte in size, see the "libraryVersion" member of the CK_INFO 355 structure in [pkcs11_spec] for more information. Value "M" for the 356 attribute MUST be interpreted as "M" for the major and "0" for the 357 minor version of the library. If the attribute is present the major 358 version number is REQUIRED. Both "M" and "N" MUST be decimal 359 numbers. 361 Slot ID is a Cryptoki-assigned number that is not guaranteed stable 362 across PKCS#11 module initializations. However, there are certain 363 libraries and modules which provide stable slot identifiers. For 364 these cases, when the slot description and manufacturer ID is not 365 sufficient to uniquely identify a specific reader, the slot ID MAY be 366 used to increase the precision of the token identification. In other 367 scenarios, using the slot IDs is likely to cause usability issues. 369 An empty PKCS#11 URI path attribute that does allow for an empty 370 value matches a corresponding structure member or an object attribute 371 with an empty value. Note that according to the PKCS#11 372 specification [pkcs11_spec], empty character values in a PKCS#11 API 373 producer must be padded with spaces and should not be NULL 374 terminated. 376 3.4. PKCS#11 URI Scheme Query Attribute Semantics 378 An application MAY always ask for a PIN by any means it decides to. 379 What is more, in order not to limit PKCS#11 URI portability the "pin- 380 source" attribute value format and interpretation is left to be 381 implementation specific. However, the following rules SHOULD be 382 followed in descending order for the value of the "pin-source" 383 attribute: 385 o if the value represents a local absolute path the implementation 386 SHOULD use it as a PIN file containing the PIN value 388 o if the value contains "|" the 389 implementation SHOULD read the PIN from the output of an 390 application specified with absolute path "". Note that character "|" representing a pipe does not have 392 to be percent encoded in the query component of the PKCS#11 URI. 394 o if the value represents a URI it SHOULD be treated as an object 395 containing the PIN. Such a URI may be "file:", "https:", another 396 PKCS#11 URI, or something else. 398 o interpret the value as needed in an implementation dependent way 400 If a URI contains both "pin-source" and "pin-value" query attributes 401 the URI SHOULD be refused as invalid. 403 Use of the "pin-value" attribute may have security related 404 consequences. Section 6 should be consulted before this attribute is 405 ever used. Standard percent encoding rules SHOULD be followed for 406 the attribute value. 408 A consumer of PKCS#11 URIs MAY modify default settings for accessing 409 a PKCS#11 provider or providers by accepting query component 410 attributes "module-name" and "module-path"." 412 Processing the URI query module attributes SHOULD follow these rules: 414 o attribute "module-name" SHOULD contain a case-insensitive PKCS#11 415 module name (not path nor filename) without system specific 416 affixes. Such affix could be an ".so" or ".DLL" suffix, or a 417 "lib" prefix, for example. Not using system specific affixes is 418 expected to increase portability of PKCS#11 URIs among different 419 systems. A URI consumer searching for PKCS#11 modules SHOULD use 420 a system or application specific locations to find modules based 421 on the name provided in the attribute. 423 o attribute "module-path" SHOULD contain a system specific absolute 424 path to the PKCS#11 module, or a system specific absolute path to 425 the directory of where PKCS#11 modules are located. For security 426 reasons, a URI with a relative path in this attribute SHOULD be 427 rejected. 429 o the URI consumer MAY refuse to accept either of the attributes, or 430 both. If use of an attribute present in the URI string is not 431 accepted a warning message SHOULD be presented to the provider of 432 the URI. 434 o if either of the module attributes is present, only those modules 435 found matching these query attributes SHOULD be used to search for 436 an entity represented by the URI. 438 o use of the module attributes does not suppress matching of any 439 other URI path component attributes present in a URI. 441 o semantics of using both attributes in the same URI string is 442 implementation specific but such use SHOULD be avoided. Attribute 443 "module-name" is preferred to "module-path" due to its system 444 independent nature but the latter may be more suitable for 445 development and debugging. 447 o a URI MUST NOT contain multiple module attributes of the same 448 name. 450 Use of the module attributes may have security related consequences. 451 Section 6 should be consulted before these attributes are ever used. 453 A word "module" was chosen over word "library" in these query 454 attribute names to avoid confusion with semantically different 455 library attributes used in the URI path component. 457 3.5. PKCS#11 URI Matching Guidelines 459 The PKCS#11 URI can identify PKCS#11 storage objects, tokens, slots, 460 or Cryptoki libraries. Note that since a URI may identify four 461 different types of entities the context within which the URI is used 462 may be needed to determine the type. For example, a URI with only 463 library attributes may either represent all objects in all tokens in 464 all Cryptoki libraries identified by the URI, all tokens in those 465 libraries, or just the libraries. 467 The following guidelines can help a PKCS#11 URI consumer (eg. an 468 application accepting PKCS#11 URIs) to match the URI with the desired 469 resource. 471 o the consumer MUST know whether the URI is to identify PKCS#11 472 storage object(s), token(s), slot(s), or Cryptoki producer(s). 474 o if the consumer is willing to accept query component module 475 attributes only those PKCS#11 providers matching these attributes 476 SHOULD be worked with. See Section 3.4 for more information. 478 o an unrecognized attribute in the URI path component, including a 479 vendor specific attribute, SHOULD result in an empty set of 480 matched resources. The consumer SHOULD consider whether an error 481 message presented to the user is appropriate in such a case. 483 o an unrecognized attribute in the URI query SHOULD be ignored. The 484 consumer SHOULD consider whether a warning message presented to 485 the user is appropriate in such a case. 487 o an attribute not present in the URI path but known to a consumer 488 matches everything. Each additional attribute present in the URI 489 path further restricts the selection. 491 o a logical extension of the above is that an empty URI path matches 492 everything. For example, if used to identify storage objects it 493 matches all accessible objects in all tokens provided by all 494 PKCS#11 API producers found in the system. 496 o note that use of PIN attributes may change the set of storage 497 objects visible to the consumer. 499 o in addition to query component attributes defined in this 500 document, vendor specific query attributes may contain further 501 information about how to perform the selection or other related 502 information. 504 3.6. PKCS#11 URI Comparison 506 Comparison of two URIs is a way of determining whether the URIs are 507 equivalent without comparing the actual resource the URIs point to. 508 The comparison of URIs aims to minimize false negatives while 509 strictly avoiding false positives. 511 Two PKCS#11 URIs are said to be equal if URIs as character strings 512 are identical as specified in Section 6.2.1 of [RFC3986], or if both 513 following rules are fulfilled: 515 o set of attributes present in the URI is equal. Note that the 516 ordering of attributes in the URI string is not significant for 517 the mechanism of comparison. 519 o values of respective attributes are equal based on rules specified 520 below 522 The rules for comparing values of respective attributes are: 524 o values of path component attributes "library-description", 525 "library-manufacturer", "manufacturer", "model", "object", 526 "serial", "slot-description", "slot-manufacturer", "token", 527 "type", and query component attribute "module-name" MUST be 528 compared using a simple string comparison as specified in 529 Section 6.2.1 of [RFC3986] after the case and the percent-encoding 530 normalization are both applied as specified in Section 6.2.2 of 531 [RFC3986]. 533 o value of attribute "id" MUST be compared using the simple string 534 comparison after all bytes are percent-encoded using uppercase 535 letters for digits A-F. 537 o value of attribute "library-version" MUST be processed as a 538 specific scheme-based normalization permitted by Section 6.2.3 of 539 [RFC3986]. The value MUST be split into a major and minor version 540 with character '.' (dot) serving as a delimiter. Library version 541 "M" MUST be treated as "M" for the major version and "0" for the 542 minor version. Resulting minor and major version numbers MUST be 543 then separately compared numerically. 545 o value of attribute "slot-id" MUST be processed as a specific 546 scheme-based normalization permitted by Section 6.2.3 of [RFC3986] 547 and compared numerically. 549 o value of "pin-source", if deemed containing the filename with the 550 PIN value, MUST be compared using the simple string comparison 551 after the full syntax based normalization as specified in 552 Section 6.2.2 of [RFC3986] is applied. If value of the "pin- 553 source" attribute is believed to be overloaded the case and 554 percent-encoding normalization SHOULD be applied before the values 555 are compared but the exact mechanism of comparison is left to the 556 application. 558 o value of attribute "module-path" MUST be compared using the simple 559 string comparison after the full syntax based normalization as 560 specified in Section 6.2.2 of [RFC3986] is applied. 562 o when comparing vendor specific attributes the case and percent- 563 encoding normalization as specified in Section 6.2.2 of [RFC3986] 564 SHOULD be applied before the values are compared but the exact 565 mechanism of such a comparison is left to the application. 567 3.7. Generating PKCS#11 URIs 569 When generating URIs for PKCS#11 resources the exact set of 570 attributes used in a URI is inherently context specific. A PKCS#11 571 URI template [RFC6570] support MAY be provided by a URI generating 572 application to list URIs to access the same resource(s) again if the 573 template captured the necessary context. 575 4. Examples of PKCS#11 URIs 577 This section contains some examples of how PKCS#11 token objects, 578 tokens, slots, and libraries can be identified using the PKCS#11 URI 579 scheme. Note that in some of the following examples, newlines and 580 spaces were inserted for better readability. As specified in 581 Appendix C of [RFC3986], whitespace SHOULD be ignored when extracting 582 the URI. Also note that all spaces as part of the URI are percent- 583 encoded, as specified in Appendix A of [RFC3986]. 585 An empty PKCS#11 URI might be useful to PKCS#11 consumers. See 586 Section 3.5 for more information on semantics of such a URI. 588 pkcs11: 590 One of the simplest and most useful forms might be a PKCS#11 URI that 591 specifies only an object label and its type. The default token is 592 used so the URI does not specify it. Note that when specifying 593 public objects, a token PIN may not be required. 595 pkcs11:object=my-pubkey;type=public 597 When a private key is specified either the "pin-source" attribute, 598 "pin-value, or an application specific method would be usually used. 599 Note that '/' is not percent-encoded in the "pin-source" attribute 600 value since this attribute is part of the query component, not the 601 path, and thus is separated by '?' from the rest of the URI. 603 pkcs11:object=my-key;type=private?pin-source=/etc/token 605 The following example identifies a certificate in the software token. 606 Note an empty value for the attribute "serial" which matches only 607 empty "serialNumber" member of the "CK_TOKEN_INFO" structure. Also 608 note that the "id" attribute value is entirely percent-encoded, as 609 recommended. While ',' is in the reserved set it does not have to be 610 percent-encoded since it does not conflict with any sub-delimiters 611 used. The '#' character as in "The Software PKCS#11 Softtoken" MUST 612 be percent-encoded. 614 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 615 manufacturer=Snake%20Oil,%20Inc.; 616 model=1.0; 617 object=my-certificate; 618 type=cert; 619 id=%69%95%3E%5C%F4%BD%EC%91; 620 serial= 621 ?pin-source=/etc/token_pin 623 The next example covers how to use the "module-name" query attribute. 624 Considering that the module is located in /usr/lib/libmypkcs11.so.1 625 file, the attribute value is "mypkcs11", meaning only the module name 626 without the full path, and without the platform specific "lib" prefix 627 and ".so.1" suffix. 629 pkcs11:object=my-sign-key; 630 type=private 631 ?module-name=mypkcs11 633 The following example covers how to use the "module-path" query 634 attribute. The attribute may be useful if a user needs to provide 635 the key via a PKCS#11 module stored on a removable media, for 636 example. Getting the PIN to access the private key here is left to 637 be application specific. 639 pkcs11:object=my-sign-key; 640 type=private 641 ?module-path=/mnt/libmypkcs11.so.1 643 In the context where a token is expected the token can be identified 644 without specifying any PKCS#11 objects. A PIN might still be needed 645 in the context of listing all objects in the token, for example. 646 Section 6 should be consulted before the "pin-value" attribute is 647 ever used. 649 pkcs11:token=Software%20PKCS%2311%20softtoken; 650 manufacturer=Snake%20Oil,%20Inc. 651 ?pin-value=the-pin 653 In the context where a slot is expected the slot can be identified 654 without specifying any PKCS#11 objects in any token it may be 655 inserted in it. 657 pkcs11:slot-description=Sun%20Metaslot 659 The Cryptoki library alone can be also identified without specifying 660 a PKCS#11 token or object. 662 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 663 library-description=Soft%20Token%20Library; 664 library-version=1.23 666 The following example shows an attribute value with a semicolon. In 667 such case it MUST be percent-encoded. The token attribute value MUST 668 be read as "My token; created by Joe". Lower case letters MAY be 669 used in percent-encoding as shown below in the "id" attribute value 670 but note that Sections 2.1 and 6.2.2.1 of [RFC3986] read that all 671 percent-encoded characters SHOULD use the uppercase hexadecimal 672 digits. More specifically, if the URI string was to be compared the 673 algorithm defined in Section 3.6 explicitly requires percent-encoding 674 to use the uppercase digits A-F in the "id" attribute values. And as 675 explained in Section 3.3, library version "3" MUST be interpreted as 676 "3" for the major and "0" for the minor version of the library. 678 pkcs11:token=My%20token%25%20created%20by%20Joe; 679 library-version=3; 680 id=%01%02%03%Ba%dd%Ca%fe%04%05%06 682 If there is any need to include literal "%;" substring, for example, 683 both characters MUST be escaped. The token value MUST be read as "A 684 name with a substring %;". 686 pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; 687 object=my-certificate; 688 type=cert 690 The next example includes a small A with acute in the token name. It 691 MUST be encoded in octets according to the UTF-8 character encoding 692 and then percent-encoded. Given that a small A with acute is U+225 693 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 694 that is "%C3%A1" in percent-encoding. 696 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 697 object=my-certificate; 698 type=cert 700 Both the path and query components MAY contain vendor specific 701 attributes. Attributes in the query component MUST be delimited by 702 '&'. 704 pkcs11:token=my-token; 705 object=my-certificate; 706 type=cert; 707 vendor-aaa=value-a 708 ?pin-source=/etc/token_pin 709 &vendor-bbb=value-b 711 5. IANA Considerations 713 This document moves the "pkcs11" URI scheme from the provisional to 714 permanent URI scheme registry. 716 The registration template is as follows: 718 URI scheme name: pkcs11 720 URI scheme status: permanent 722 URI scheme syntax: see Section 3.3 724 URI scheme semantics: see Section 1 726 Encoding considerations: see Section 3.3 728 Applications/protocols that use this URI scheme name: for general 729 information, see Section 1. List of known consumers of the 730 PKCS#11 URI include GnuTLS, Gnome, p11-kit, Solaris 11 and higher, 731 OpenSC, OpenConnect, and FreeIPA. 733 Interoperability considerations: N/A 735 Security considerations: see Section 6 737 Contact: see Authors' Addresses section 739 Author/Change Controller: see Authors' Addresses section 741 References: see References section 743 6. Security Considerations 745 There are general security considerations for URI schemes discussed 746 in Section 7 of [RFC3986]. 748 From those security considerations, Section 7.1 of [RFC3986] applies 749 since there is no guarantee that the same PKCS#11 URI will always 750 identify the same object, token, slot, or a library in the future. 752 Section 7.2 of [RFC3986] applies since by accepting query component 753 attributes "module-name" or "module-path" the consumer potentially 754 allows loading of arbitrary code into a process. 756 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 757 world readable command line arguments to run applications, stored in 758 public configuration files, or otherwise used in clear text. For 759 that reason the "pin-value" attribute should only be used if the URI 760 string itself is protected with the same level of security as the 761 token PIN itself otherwise is. 763 7. References 765 7.1. Normative References 767 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 768 Requirement Levels", RFC 2119, STD 14, March 1997. 770 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 771 10646", RFC 3629, STD 63, November 2003. 773 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 774 Resource Identifier (URI): Generic Syntax", RFC 3986, STD 775 66, January 2005. 777 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 778 Specifications: ABNF", RFC 5234, STD 68, January 2008. 780 7.2. Informative References 782 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 783 "Deprecating the "X-" Prefix and Similar Constructs in 784 Application Protocols", RFC 6648, BCP 178, June 2012. 786 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 787 Identifiers (IRIs)", RFC 3987, January 2005. 789 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 790 Registration Procedures for New URI Schemes", RFC 4395, 791 February 2006. 793 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 794 and D. Orchard, "URI Template", RFC 6570, March 2012. 796 [pkcs11_spec] 797 RSA Laboratories, "PKCS #11: Cryptographic Token Interface 798 Standard v2.20", June 2004. 800 Authors' Addresses 801 Jan Pechanec 802 Oracle Corporation 803 4180 Network Circle 804 Santa Clara CA 95054 805 USA 807 Email: Jan.Pechanec@Oracle.COM 808 URI: http://www.oracle.com 810 Darren J. Moffat 811 Oracle Corporation 812 Oracle Parkway 813 Thames Valley Park 814 Reading RG6 1RA 815 UK 817 Email: Darren.Moffat@Oracle.COM 818 URI: http://www.oracle.com