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