idnits 2.17.1 draft-pechanec-pkcs11uri-20.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 (February 5, 2015) is 3367 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) == Missing Reference: 'RFCXXXX' is mentioned on line 785, but not defined -- Obsolete informational reference (is this intentional?): RFC 4395 (Obsoleted by RFC 7595) Summary: 0 errors (**), 0 flaws (~~), 3 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: August 9, 2015 February 5, 2015 7 The PKCS#11 URI Scheme 8 draft-pechanec-pkcs11uri-20 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 August 9, 2015. 35 Copyright Notice 37 Copyright (c) 2015 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 . . . . . . 9 59 3.5. PKCS#11 URI Matching Guidelines . . . . . . . . . . . . . 11 60 3.6. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 12 61 3.7. Generating PKCS#11 URIs . . . . . . . . . . . . . . . . . 13 62 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 14 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 64 5.1. URI Scheme Registration . . . . . . . . . . . . . . . . . 17 65 6. Internationalization Considerations . . . . . . . . . . . . . 17 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 69 8.2. Informative References . . . . . . . . . . . . . . . . . 19 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 72 1. Introduction 74 The PKCS #11: Cryptographic Token Interface Standard [PKCS11] 75 specifies an API, called Cryptoki, for devices which hold 76 cryptographic information and perform cryptographic functions. 77 Cryptoki, pronounced crypto-key and short for cryptographic token 78 interface, follows a simple object-based approach, addressing the 79 goals of technology independence (any kind of device may be used) and 80 resource sharing (multiple applications may access multiple devices), 81 presenting applications with a common, logical view of the device - a 82 cryptographic token. 84 It is desirable for applications or libraries that work with PKCS#11 85 tokens to accept a common identifier that consumers could use to 86 identify an existing PKCS#11 storage object in a PKCS#11 token, an 87 existing token itself, a slot, or an existing Cryptoki library (also 88 called a producer, module, or provider). The set of storage object 89 types that can be stored in a PKCS#11 token includes a certificate, a 90 public, private or secret key, and a data object. These objects can 91 be uniquely identifiable via the PKCS#11 URI scheme defined in this 92 document. The set of attributes describing a storage object can 93 contain an object label, its type, and its ID. The set of attributes 94 that identifies a PKCS#11 token can contain a token label, 95 manufacturer name, serial number, and token model. Attributes that 96 can identify a slot are a slot ID, description, and manufacturer. 97 Attributes that can identify a Cryptoki library are a library 98 manufacturer, description, and version. Library attributes may be 99 necessary to use if more than one Cryptoki library provides a token 100 and/or PKCS#11 objects of the same name. A set of query attributes 101 is provided as well. 103 The PKCS#11 URI cannot identify other objects defined in the 104 specification [PKCS11] aside from storage objects. For example, 105 objects not identifiable by a PKCS#11 URI include a hardware feature 106 and mechanism. Note that a Cryptoki library does not have to provide 107 for storage objects at all. The URI can still be used to identify a 108 specific PKCS#11 token, slot or an API producer in such a case. 110 A subset of existing PKCS#11 structure members and object attributes 111 was chosen to uniquely identify a PKCS#11 storage object, token, 112 slot, or library in a configuration file, on a command line, or in a 113 configuration property of something else. Should there be a need for 114 a more complex information exchange on PKCS#11 entities a different 115 means of data marshalling should be chosen accordingly. 117 A PKCS#11 URI is not intended to be used to create new PKCS#11 118 objects in tokens, or to create PKCS#11 tokens. It is solely to be 119 used to identify and work with existing storage objects, tokens, and 120 slots through the PKCS#11 API, or identify Cryptoki libraries 121 themselves. 123 The URI scheme defined in this document is designed specifically with 124 a mapping to the PKCS#11 API in mind. The URI uses the scheme, path 125 and query components defined in the Uniform Resource Identifier 126 (URI): Generic Syntax [RFC3986] document. The URI does not use the 127 hierarchical element for a naming authority in the path since the 128 authority part could not be mapped to PKCS#11 API elements. The URI 129 does not use the fragment component. 131 If an application has no access to a producer or producers of the 132 PKCS#11 API the query component module attributes can be used. 133 However, the PKCS#11 URI consumer can always decide to provide its 134 own adequate user interface to locate and load PKCS#11 API producers. 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 138 document are to be interpreted as described in [RFC2119]. 140 2. Contributors 142 Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and 143 Jaroslav Imrich contributed to the development of this document. 145 3. PKCS#11 URI Scheme Definition 147 In accordance with [RFC4395], this section provides the information 148 required to register the PKCS#11 URI scheme. 150 3.1. PKCS#11 URI Scheme Name 152 pkcs11 154 3.2. PKCS#11 URI Scheme Status 156 Permanent. 158 3.3. PKCS#11 URI Scheme Syntax 160 The PKCS#11 URI is a sequence of attribute value pairs separated by a 161 semicolon that form a one level path component, optionally followed 162 by a query. In accordance with Section 2.5 of [RFC3986], the textual 163 data SHOULD first be encoded as octets according to the UTF-8 164 character encoding [RFC3629]; then only those octets that do not 165 correspond to characters in the unreserved set or to permitted 166 characters from the reserved set should be percent-encoded. The only 167 PKCS#11 URI attribute defined in this document which MAY contain non- 168 textual data is the "id" attribute, as stated later in this section. 169 When working with UTF-8 strings with characters outside the US-ASCII 170 character sets, see important caveats in Section 3.5 and Section 6. 172 Grammar rules "unreserved" and "pct-encoded" in the PKCS#11 URI 173 specification below are imported from [RFC3986]. As a special case, 174 note that according to Appendix A of [RFC3986], a space must be 175 percent-encoded. 177 The PKCS#11 specification imposes various limitations on the value of 178 attributes, be it a more restrictive character set for the "serial" 179 attribute or fixed sized buffers for almost all the others, including 180 "token", "manufacturer", and "model" attributes. The syntax of the 181 PKCS#11 URI does not impose such limitations. However, if the 182 consumer of a PKCS#11 URI encounters values that would not be 183 accepted by the PKCS#11 specification, it MUST refuse the URI as 184 invalid. 186 A PKCS#11 URI takes the form (for explanation of Augmented BNF, see 187 [RFC5234]): 189 pk11-URI = "pkcs11:" pk11-path [ "?" pk11-query ] 190 ; Path component and its attributes. Path may be empty. 191 pk11-path = [ pk11-pattr *(";" pk11-pattr) ] 192 pk11-pattr = pk11-token / pk11-manuf / pk11-serial / 193 pk11-model / pk11-lib-manuf / 194 pk11-lib-ver / pk11-lib-desc / 195 pk11-object / pk11-type / pk11-id / 196 pk11-slot-desc / pk11-slot-manuf / 197 pk11-slot-id / pk11-v-pattr 198 ; Query component and its attributes. Query may be empty. 199 pk11-qattr = pk11-pin-source / pk11-pin-value / 200 pk11-module-name / pk11-module-path / 201 pk11-v-qattr 202 pk11-query = [ pk11-qattr *("&" pk11-qattr) ] 203 ; RFC 3986 section 2.2 mandates all potentially reserved characters 204 ; that do not conflict with actual delimiters of the URI do not have 205 ; to be percent-encoded. 206 pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" / 207 "'" / "(" / ")" / "*" / "+" / "," / "=" 208 pk11-path-res-avail = pk11-res-avail / "&" 209 ; "/" and "?" in the query component MAY be unencoded but "&" MUST 210 ; be encoded since it functions as a delimiter within the component. 211 pk11-query-res-avail = pk11-res-avail / "/" / "?" / "|" 212 pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded 213 pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded 214 pk11-token = "token" "=" *pk11-pchar 215 pk11-manuf = "manufacturer" "=" *pk11-pchar 216 pk11-serial = "serial" "=" *pk11-pchar 217 pk11-model = "model" "=" *pk11-pchar 218 pk11-lib-manuf = "library-manufacturer" "=" *pk11-pchar 219 pk11-lib-desc = "library-description" "=" *pk11-pchar 220 pk11-lib-ver = "library-version" "=" 1*DIGIT [ "." 1*DIGIT ] 221 pk11-object = "object" "=" *pk11-pchar 222 pk11-type = "type" "=" ( "public" / "private" / "cert" / 223 "secret-key" / "data" ) 224 pk11-id = "id" "=" *pk11-pchar 225 pk11-slot-manuf = "slot-manufacturer" "=" *pk11-pchar 226 pk11-slot-desc = "slot-description" "=" *pk11-pchar 227 pk11-slot-id = "slot-id" "=" 1*DIGIT 228 pk11-pin-source = "pin-source" "=" *pk11-qchar 229 pk11-pin-value = "pin-value" "=" *pk11-qchar 230 pk11-module-name = "module-name" "=" *pk11-qchar 231 pk11-module-path = "module-path" "=" *pk11-qchar 232 pk11-v-attr-nm-char = ALPHA / DIGIT / "-" / "_" 233 ; Permitted value of a vendor specific attribute is based on 234 ; whether the attribute is used in the path or in the query. 235 pk11-v-pattr = 1*pk11-v-attr-nm-char "=" *pk11-pchar 236 pk11-v-qattr = 1*pk11-v-attr-nm-char "=" *pk11-qchar 237 The URI path component contains attributes that identify a resource 238 in a one level hierarchy provided by Cryptoki producers. The query 239 component can contain a few attributes that may be needed to retrieve 240 the resource identified by the URI path component. Attributes in the 241 path component are delimited by ';' character, attributes in the 242 query component use '&' as a delimiter. 244 Both path and query components MAY contain vendor specific 245 attributes. Such attribute names MUST NOT clash with existing 246 attribute names. Note that in accordance with [BCP178], previously 247 used convention of starting vendor attributes with an "x-" prefix is 248 now deprecated. 250 The general '/' delimiter MUST be percent-encoded in the path 251 component so that generic URI parsers never split the path component 252 into multiple segments. It MAY be unencoded in the query component. 253 Delimiter '?' MUST be percent-encoded in the path component since 254 the PKCS#11 URI uses a query component. Delimiter '#' MUST be always 255 percent-encoded so that generic URI parsers do not treat a hash as a 256 beginning of a fragment identifier component. All other generic 257 delimiters MAY be used unencoded (':', '[', ']', and '@') in the 258 PKCS#11 URI. 260 The following table presents mapping between the PKCS#11 URI path 261 component attributes and the PKCS#11 API structure members and object 262 attributes. Given that PKCS#11 URI users may be quite ignorant about 263 the PKCS#11 specification the mapping is a product of a necessary 264 compromise between how precisely are the URI attribute names mapped 265 to the names in the specification and the ease of use and 266 understanding of the URI scheme. 268 +----------------------+---------------------+----------------------+ 269 | URI component path | Attribute | Attribute | 270 | attribute name | represents | corresponds in the | 271 | | | PKCS#11 | 272 | | | specification to | 273 +----------------------+---------------------+----------------------+ 274 | | | | 275 +----------------------+---------------------+----------------------+ 276 | id | key identifier for | "CKA_ID" object | 277 | | object | attribute | 278 +----------------------+---------------------+----------------------+ 279 | library-description | character-string | "libraryDescription" | 280 | | description of the | member of CK_INFO | 281 | | library | structure. It is a | 282 | | | UTF-8 string. | 283 +----------------------+---------------------+----------------------+ 284 | library-manufacturer | ID of the Cryptoki | "manufacturerID" | 285 | | library | member of the | 286 | | manufacturer | CK_INFO structure. | 287 | | | It is a UTF-8 | 288 | | | string. | 289 +----------------------+---------------------+----------------------+ 290 | library-version | Cryptoki library | "libraryVersion" | 291 | | version number | member of CK_INFO | 292 | | | structure | 293 +----------------------+---------------------+----------------------+ 294 | manufacturer | ID of the token | "manufacturerID" | 295 | | manufacturer | member of | 296 | | | CK_TOKEN_INFO | 297 | | | structure. It is a | 298 | | | UTF-8 string. | 299 +----------------------+---------------------+----------------------+ 300 | model | token model | "model" member of | 301 | | | CK_TOKEN_INFO | 302 | | | structure. It is a | 303 | | | UTF-8 string. | 304 +----------------------+---------------------+----------------------+ 305 | object | description (name) | "CKA_LABEL" object | 306 | | of the object | attribute. It is a | 307 | | | UTF-8 string. | 308 +----------------------+---------------------+----------------------+ 309 | serial | character-string | "serialNumber" | 310 | | serial number of | member of | 311 | | the token | CK_TOKEN_INFO | 312 | | | structure | 313 +----------------------+---------------------+----------------------+ 314 | slot-description | slot description | "slotDescription" | 315 | | | member of | 316 | | | CK_SLOT_INFO | 317 | | | structure. It is a | 318 | | | UTF-8 string. | 319 +----------------------+---------------------+----------------------+ 320 | slot-id | Cryptoki-assigned | decimal number of | 321 | | value that | "CK_SLOT_ID" type | 322 | | identifies a slot | | 323 +----------------------+---------------------+----------------------+ 324 | slot-manufacturer | ID of the slot | "manufacturerID" | 325 | | manufacturer | member of | 326 | | | CK_SLOT_INFO | 327 | | | structure. It is a | 328 | | | UTF-8 string. | 329 +----------------------+---------------------+----------------------+ 330 | token | application-defined | "label" member of | 331 | | label, assigned | the CK_TOKEN_INFO | 332 | | during token | structure. It is a | 333 | | initialization | UTF-8 string. | 334 +----------------------+---------------------+----------------------+ 335 | type | object class (type) | "CKA_CLASS" object | 336 | | | attribute | 337 +----------------------+---------------------+----------------------+ 339 Table 1: Mapping between URI path component attributes and PKCS#11 340 specification names 342 The following table presents mapping between the "type" attribute 343 values and corresponding PKCS#11 object classes. 345 +-----------------+----------------------+ 346 | Attribute value | PKCS#11 object class | 347 +-----------------+----------------------+ 348 | public | CKO_PUBLIC_KEY | 349 | private | CKO_PRIVATE_KEY | 350 | cert | CKO_CERTIFICATE | 351 | secret-key | CKO_SECRET_KEY | 352 | data | CKO_DATA | 353 +-----------------+----------------------+ 355 Table 2: Mapping between the "type" attribute and PKCS#11 object 356 classes 358 The query component attribute "pin-source" specifies where the 359 application or library should find the normal user's token PIN, the 360 "pin-value" attribute provides the normal user's PIN value directly, 361 if needed, and the "module-name" and "module-path" attributes modify 362 default settings for accessing PKCS#11 providers. For the definition 363 of a "normal user", see [PKCS11]. 365 The ABNF rules above is a best effort definition and this paragraph 366 specifies additional constraints. The PKCS#11 URI MUST NOT contain 367 duplicate attributes of the same name in the URI path component. It 368 means that each attribute may be present at most once in the PKCS#11 369 URI path component. Aside from the query attributes defined in this 370 document, duplicate (vendor) attributes MAY be present in the URI 371 query component and it is up to the URI consumer to decide on how to 372 deal with such duplicates. 374 The whole value of the "id" attribute SHOULD be percent-encoded since 375 the corresponding PKCS#11 "CKA_ID" object attribute can contain 376 arbitrary binary data. 378 The "library-version" attribute represents the major and minor 379 version number of the library and its format is "M.N". Both numbers 380 are one byte in size, see the "libraryVersion" member of the CK_INFO 381 structure in [PKCS11] for more information. Value "M" for the 382 attribute MUST be interpreted as "M" for the major and "0" for the 383 minor version of the library. If the attribute is present the major 384 version number is REQUIRED. Both "M" and "N" MUST be decimal 385 numbers. 387 Slot ID is a Cryptoki-assigned number that is not guaranteed stable 388 across PKCS#11 module initializations. However, there are certain 389 libraries and modules which provide stable slot identifiers. For 390 these cases, when the slot description and manufacturer ID is not 391 sufficient to uniquely identify a specific reader, the slot ID MAY be 392 used to increase the precision of the token identification. In other 393 scenarios, using the slot IDs is likely to cause usability issues. 395 An empty PKCS#11 URI path component attribute that does allow for an 396 empty value matches a corresponding structure member or an object 397 attribute with an empty value. Note that according to the PKCS#11 398 specification [PKCS11], empty character values in a PKCS#11 API 399 producer must be padded with spaces and should not be NULL 400 terminated. 402 3.4. PKCS#11 URI Scheme Query Attribute Semantics 404 An application can always ask for a PIN by any means it decides to. 405 What is more, in order not to limit PKCS#11 URI portability the "pin- 406 source" attribute value format and interpretation is left to be 407 implementation specific. However, the following rules SHOULD be 408 followed in descending order for the value of the "pin-source" 409 attribute: 411 o if the value represents a URI it SHOULD be treated as an object 412 containing the PIN. Such a URI may be "file:", "https:", another 413 PKCS#11 URI, or something else. 415 o if the value contains "|" the 416 implementation SHOULD read the PIN from the output of an 417 application specified with absolute path "". Note that character "|" representing a pipe does not have 419 to be percent encoded in the query component of the PKCS#11 URI. 421 o interpret the value as needed in an implementation dependent way 423 If a URI contains both "pin-source" and "pin-value" query attributes 424 the URI SHOULD be refused as invalid. 426 Use of the "pin-value" attribute may have security related 427 consequences. Section 7 should be consulted before this attribute is 428 ever used. Standard percent encoding rules SHOULD be followed for 429 the attribute value. 431 A consumer of PKCS#11 URIs MAY accept query component attributes 432 "module-name" and "module-path" in order to modify default settings 433 for accessing a PKCS#11 provider or providers. 435 Processing the URI query module attributes SHOULD follow these rules: 437 o attribute "module-name" SHOULD contain a case-insensitive PKCS#11 438 module name (not path nor filename) without system specific 439 affixes. Such affix could be an ".so" or ".DLL" suffix, or a 440 "lib" prefix, for example. Not using system specific affixes is 441 expected to increase portability of PKCS#11 URIs among different 442 systems. A URI consumer searching for PKCS#11 modules SHOULD use 443 a system or application specific locations to find modules based 444 on the name provided in the attribute. 446 o attribute "module-path" SHOULD contain a system specific absolute 447 path to the PKCS#11 module, or a system specific absolute path to 448 the directory of where PKCS#11 modules are located. For security 449 reasons, a URI with a relative path in this attribute SHOULD be 450 rejected. 452 o the URI consumer MAY refuse to accept either of the attributes, or 453 both. If use of the attribute present in the URI string is not 454 accepted a warning message SHOULD be presented to the provider of 455 the URI and system specific module locations SHOULD be used. 457 o if either of the module attributes is present, only those modules 458 found matching these query attributes SHOULD be used to search for 459 an entity represented by the URI. 461 o use of the module attributes does not suppress matching of any 462 other URI path component attributes present in a URI. 464 o semantics of using both attributes in the same URI string is 465 implementation specific but such use SHOULD be avoided. Attribute 466 "module-name" is preferred to "module-path" due to its system 467 independent nature but the latter may be more suitable for 468 development and debugging. 470 o a URI MUST NOT contain multiple module attributes of the same 471 name. 473 Use of the module attributes may have security related consequences. 474 Section 7 should be consulted before these attributes are ever used. 476 A word "module" was chosen over word "library" in these query 477 attribute names to avoid confusion with semantically different 478 library attributes used in the URI path component. 480 3.5. PKCS#11 URI Matching Guidelines 482 The PKCS#11 URI can identify PKCS#11 storage objects, tokens, slots, 483 or Cryptoki libraries. Note that since a URI may identify four 484 different types of entities the context within which the URI is used 485 may be needed to determine the type. For example, a URI with only 486 library attributes may either represent all objects in all tokens in 487 all Cryptoki libraries identified by the URI, all tokens in those 488 libraries, or just the libraries. 490 The following guidelines can help a PKCS#11 URI consumer (eg. an 491 application accepting PKCS#11 URIs) to match the URI with the desired 492 resource. 494 o the consumer needs to know whether the URI is to identify PKCS#11 495 storage object(s), token(s), slot(s), or Cryptoki producer(s). 497 o if the consumer is willing to accept query component module 498 attributes only those PKCS#11 providers matching these attributes 499 SHOULD be worked with. See Section 3.4 for more information. 501 o an unrecognized attribute in the URI path component, including a 502 vendor specific attribute, SHOULD result in an empty set of 503 matched resources. The consumer can consider whether an error 504 message presented to the user is appropriate in such a case. 506 o an unrecognized attribute in the URI query SHOULD be ignored. The 507 consumer can consider whether a warning message presented to the 508 user is appropriate in such a case. 510 o an attribute not present in the URI path component but known to a 511 consumer matches everything. Each additional attribute present in 512 the URI path component further restricts the selection. 514 o a logical extension of the above is that a URI with an empty path 515 component matches everything. For example, if used to identify 516 storage objects it matches all accessible objects in all tokens 517 provided by all relevant PKCS#11 API producers. 519 o note that use of PIN attributes may change the set of storage 520 objects visible to the consumer. 522 o in addition to query component attributes defined in this 523 document, vendor specific query attributes may contain further 524 information about how to perform the selection or other related 525 information. 527 As noted in Section 6, the PKCS#11 specification is not clear about 528 how to normalize UTF-8 encoded Unicode characters [RFC3629]. For 529 that reason, it is RECOMMENDED not to use characters outside the US- 530 ASCII character set for labels and names. However, those who 531 discover a need to use such characters should be cautious, 532 conservative, and expend extra effort to be sure they know what they 533 are doing and that failure to do so may create both operational and 534 security risks. It means that when matching UTF-8 string based 535 attributes (see Table 1) with characters outside the US-ASCII 536 repertoire, normalizing all UTF-8 strings before string comparison 537 may be the only safe approach. For example, for objects (keys) it 538 means that PKCS#11 attribute search template would only contain 539 attributes that are not UTF-8 strings and another pass through 540 returned objects is then needed for UTF-8 string comparison after the 541 normalization is applied. 543 3.6. PKCS#11 URI Comparison 545 Comparison of two URIs is a way of determining whether the URIs are 546 equivalent without comparing the actual resource the URIs point to. 547 The comparison of URIs aims to minimize false negatives while 548 strictly avoiding false positives. When working with UTF-8 strings 549 with characters outside the US-ASCII character sets, see important 550 caveats in Section 3.5 and Section 6. 552 Two PKCS#11 URIs are said to be equal if URIs as character strings 553 are identical as specified in Section 6.2.1 of [RFC3986], or if both 554 following rules are fulfilled: 556 o set of attributes present in the URI is equal. Note that the 557 ordering of attributes in the URI string is not significant for 558 the mechanism of comparison. 560 o values of respective attributes are equal based on rules specified 561 below 563 The rules for comparing values of respective attributes are: 565 o values of path component attributes "library-description", 566 "library-manufacturer", "manufacturer", "model", "object", 567 "serial", "slot-description", "slot-manufacturer", "token", 568 "type", and query component attribute "module-name" MUST be 569 compared using a simple string comparison as specified in 570 Section 6.2.1 of [RFC3986] after the case and the percent-encoding 571 normalization are both applied as specified in Section 6.2.2 of 572 [RFC3986]. 574 o value of attribute "id" MUST be compared using the simple string 575 comparison after all bytes are percent-encoded using uppercase 576 letters for digits A-F. 578 o value of attribute "library-version" MUST be processed as a 579 specific scheme-based normalization permitted by Section 6.2.3 of 580 [RFC3986]. The value MUST be split into a major and minor version 581 with character '.' (dot) serving as a delimiter. Library version 582 "M" MUST be treated as "M" for the major version and "0" for the 583 minor version. Resulting minor and major version numbers MUST be 584 then separately compared numerically. 586 o value of attribute "slot-id" MUST be processed as a specific 587 scheme-based normalization permitted by Section 6.2.3 of [RFC3986] 588 and compared numerically. 590 o value of "pin-source", if containing a "file:" URI or "|", MUST be compared using the simple string 592 comparison after the full syntax based normalization as specified 593 in Section 6.2.2 of [RFC3986] is applied. If value of the "pin- 594 source" attribute is believed to be overloaded the case and 595 percent-encoding normalization SHOULD be applied before the values 596 are compared but the exact mechanism of comparison is left to the 597 application. 599 o value of attribute "module-path" MUST be compared using the simple 600 string comparison after the full syntax based normalization as 601 specified in Section 6.2.2 of [RFC3986] is applied. 603 o when comparing vendor specific attributes the case and percent- 604 encoding normalization as specified in Section 6.2.2 of [RFC3986] 605 SHOULD be applied before the values are compared but the exact 606 mechanism of such a comparison is left to the application. 608 3.7. Generating PKCS#11 URIs 610 When generating URIs for PKCS#11 resources the exact set of 611 attributes used in a URI is inherently context specific. A PKCS#11 612 URI template [RFC6570] support MAY be provided by a URI generating 613 application to list URIs to access the same resource(s) again if the 614 template captured the necessary context. 616 4. Examples of PKCS#11 URIs 618 This section contains some examples of how PKCS#11 token objects, 619 tokens, slots, and libraries can be identified using the PKCS#11 URI 620 scheme. Note that in some of the following examples, newlines and 621 spaces were inserted for better readability. As specified in 622 Appendix C of [RFC3986], whitespace SHOULD be ignored when extracting 623 the URI. Also note that all spaces as part of the URI are percent- 624 encoded, as specified in Appendix A of [RFC3986]. 626 An empty PKCS#11 URI might be useful to PKCS#11 consumers. See 627 Section 3.5 for more information on semantics of such a URI. 629 pkcs11: 631 One of the simplest and most useful forms might be a PKCS#11 URI that 632 specifies only an object label and its type. The default token is 633 used so the URI does not specify it. Note that when specifying 634 public objects, a token PIN may not be required. 636 pkcs11:object=my-pubkey;type=public 638 When a private key is specified either the "pin-source" attribute, 639 "pin-value, or an application specific method would be usually used. 640 Note that '/' is not percent-encoded in the "pin-source" attribute 641 value since this attribute is part of the query component, not the 642 path, and thus is separated by '?' from the rest of the URI. 644 pkcs11:object=my-key;type=private?pin-source=file:/etc/token 646 The following example identifies a certificate in the software token. 647 Note an empty value for the attribute "serial" which matches only 648 empty "serialNumber" member of the "CK_TOKEN_INFO" structure. Also 649 note that the "id" attribute value is entirely percent-encoded, as 650 recommended. While ',' is in the reserved set it does not have to be 651 percent-encoded since it does not conflict with any sub-delimiters 652 used. The '#' character as in "The Software PKCS#11 Softtoken" MUST 653 be percent-encoded. 655 pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; 656 manufacturer=Snake%20Oil,%20Inc.; 657 model=1.0; 658 object=my-certificate; 659 type=cert; 660 id=%69%95%3E%5C%F4%BD%EC%91; 661 serial= 662 ?pin-source=file:/etc/token_pin 664 The next example covers how to use the "module-name" query attribute. 665 Considering that the module is located in /usr/lib/libmypkcs11.so.1 666 file, the attribute value is "mypkcs11", meaning only the module name 667 without the full path, and without the platform specific "lib" prefix 668 and ".so.1" suffix. 670 pkcs11:object=my-sign-key; 671 type=private 672 ?module-name=mypkcs11 674 The following example covers how to use the "module-path" query 675 attribute. The attribute may be useful if a user needs to provide 676 the key via a PKCS#11 module stored on a removable media, for 677 example. Getting the PIN to access the private key here is left to 678 be application specific. 680 pkcs11:object=my-sign-key; 681 type=private 682 ?module-path=/mnt/libmypkcs11.so.1 684 In the context where a token is expected the token can be identified 685 without specifying any PKCS#11 objects. A PIN might still be needed 686 in the context of listing all objects in the token, for example. 687 Section 7 should be consulted before the "pin-value" attribute is 688 ever used. 690 pkcs11:token=Software%20PKCS%2311%20softtoken; 691 manufacturer=Snake%20Oil,%20Inc. 692 ?pin-value=the-pin 694 In the context where a slot is expected the slot can be identified 695 without specifying any PKCS#11 objects in any token it may be 696 inserted in it. 698 pkcs11:slot-description=Sun%20Metaslot 700 The Cryptoki library alone can be also identified without specifying 701 a PKCS#11 token or object. 703 pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; 704 library-description=Soft%20Token%20Library; 705 library-version=1.23 707 The following example shows an attribute value with a semicolon. In 708 such case it MUST be percent-encoded. The token attribute value MUST 709 be read as "My token; created by Joe". Lower case letters MAY be 710 used in percent-encoding as shown below in the "id" attribute value 711 but note that Sections 2.1 and 6.2.2.1 of [RFC3986] read that all 712 percent-encoded characters SHOULD use the uppercase hexadecimal 713 digits. More specifically, if the URI string was to be compared the 714 algorithm defined in Section 3.6 explicitly requires percent-encoding 715 to use the uppercase digits A-F in the "id" attribute values. And as 716 explained in Section 3.3, library version "3" MUST be interpreted as 717 "3" for the major and "0" for the minor version of the library. 719 pkcs11:token=My%20token%25%20created%20by%20Joe; 720 library-version=3; 721 id=%01%02%03%Ba%dd%Ca%fe%04%05%06 723 If there is any need to include literal "%;" substring, for example, 724 both characters MUST be escaped. The token value MUST be read as "A 725 name with a substring %;". 727 pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; 728 object=my-certificate; 729 type=cert 731 The next example includes a small A with acute in the token name. It 732 MUST be encoded in octets according to the UTF-8 character encoding 733 and then percent-encoded. Given that a small A with acute is U+225 734 unicode code point, the UTF-8 encoding is 195 161 in decimal, and 735 that is "%C3%A1" in percent-encoding. 737 pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; 738 object=my-certificate; 739 type=cert 741 Both the path and query components MAY contain vendor specific 742 attributes. Attributes in the query component MUST be delimited by 743 '&'. 745 pkcs11:token=my-token; 746 object=my-certificate; 747 type=cert; 748 vendor-aaa=value-a 749 ?pin-source=file:/etc/token_pin 750 &vendor-bbb=value-b 752 5. IANA Considerations 754 5.1. URI Scheme Registration 756 This document moves the "pkcs11" URI scheme from the provisional to 757 permanent URI scheme registry. The registration request complies 758 with [RFC4395]. 760 URI scheme name: pkcs11 762 URI scheme status: permanent 764 URI scheme syntax: defined in Section 3.3 of [RFCXXXX] 766 URI scheme semantics: defined in Section 1 of [RFCXXXX] 768 Encoding considerations: see Section 3.3 and Section 6 of 769 [RFCXXXX] 771 Applications/protocols that use this URI scheme name: for general 772 information, see Section 1 of [RFCXXXX]. List of known consumers 773 of the PKCS#11 URI include GnuTLS, Gnome, p11-kit, Oracle 774 Solaris 11 and higher, OpenSC, OpenConnect, and FreeIPA. 776 Interoperability considerations: see Section 6 of [RFCXXXX] 778 Security considerations: see Section 7 of [RFCXXXX] 780 Contact: Jan Pechanec , Darren Moffat 781 783 Author/Change Controller: IESG 785 References: [RFCXXXX] 787 6. Internationalization Considerations 789 The PKCS#11 specification does not specify a canonical form for 790 strings of characters of the CK_UTF8CHAR type. This presents the 791 usual false negative and false positive (aliasing) concerns that 792 arise when dealing with unnormalized strings. Because all PKCS#11 793 items are local and local security is assumed, these concerns are 794 mainly about usability and interoperability. 796 In order to improve the user experience, it is RECOMMENDED that 797 applications that create PKCS#11 objects or label tokens do not use 798 characters outside the US-ASCII character set for the labels. If 799 that is not possible, labels SHOULD be normalized to Normalization 800 Form C (NFC) [UAX15]. For the same reason PKCS#11 libraries, slots 801 (token readers), and tokens SHOULD use US-ASCII characters only for 802 their names and if that is not possible, they SHOULD normalize their 803 names to NFC. When listing PKCS#11 libraries, slots, tokens, and/or 804 objects, an application SHOULD normalize their names to NFC if 805 characters outside of the US-ASCII character set are expected. When 806 matching PKCS#11 URIs to libraries, slots, tokens, and/or objects, 807 applications MAY convert names to a chosen normalization form before 808 the string comparison for matching, as those might pre-date these 809 recommendations. See also Section 3.5. 811 7. Security Considerations 813 There are general security considerations for URI schemes discussed 814 in Section 7 of [RFC3986]. 816 From those security considerations, Section 7.1 of [RFC3986] applies 817 since there is no guarantee that the same PKCS#11 URI will always 818 identify the same object, token, slot, or a library in the future. 820 Section 7.2 of [RFC3986] applies since by accepting query component 821 attributes "module-name" or "module-path" the consumer potentially 822 allows loading of arbitrary code into a process. 824 Section 7.5 of [RFC3986] applies since the PKCS#11 URI may be used in 825 world readable command line arguments to run applications, stored in 826 public configuration files, or otherwise used in clear text. For 827 that reason the "pin-value" attribute should only be used if the URI 828 string itself is protected with the same level of security as the 829 token PIN itself otherwise is. 831 The PKCS#11 specification does not provide means to authenticate 832 devices to users; it only allows to authenticate users to tokens. 833 Instead, local and physical security are demanded: the user must be 834 in possession of their tokens, and system into whose slots the users' 835 tokens are inserted must be secure. As a result, the usual security 836 considerations regarding normalization do not arise. For the same 837 reason, confusable script issues also do not arise. Nonetheless, if 838 use of characters outside the US-ASCII character set is required, it 839 is best to normalize to NFC all strings appearing in PKCS#11 API 840 elements. See also Section 6. 842 8. References 843 8.1. Normative References 845 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 846 Requirement Levels", RFC 2119, STD 14, March 1997. 848 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 849 10646", RFC 3629, STD 63, November 2003. 851 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 852 Resource Identifier (URI): Generic Syntax", RFC 3986, STD 853 66, January 2005. 855 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 856 Specifications: ABNF", RFC 5234, STD 68, January 2008. 858 8.2. Informative References 860 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 861 "Deprecating the "X-" Prefix and Similar Constructs in 862 Application Protocols", RFC 6648, BCP 178, June 2012. 864 [PKCS11] RSA Laboratories, "PKCS #11: Cryptographic Token Interface 865 Standard v2.20", June 2004. 867 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 868 Registration Procedures for New URI Schemes", RFC 4395, 869 February 2006. 871 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 872 and D. Orchard, "URI Template", RFC 6570, March 2012. 874 [UAX15] Davis, M., Ed., Whistler, K., Ed., and Unicode Consortium, 875 "Unicode Standard Annex #15 - Unicode Normalization Forms, 876 Version Unicode 7.0.0", June 2014. 878 Authors' Addresses 880 Jan Pechanec 881 Oracle Corporation 882 4180 Network Circle 883 Santa Clara CA 95054 884 USA 886 Email: Jan.Pechanec@Oracle.COM 887 URI: http://www.oracle.com 888 Darren J. Moffat 889 Oracle Corporation 890 Oracle Parkway 891 Thames Valley Park 892 Reading RG6 1RA 893 UK 895 Email: Darren.Moffat@Oracle.COM 896 URI: http://www.oracle.com