wdiff rfc7512.original rfc7512.txt

Network Working Group
Internet Engineering Task Force (IETF) J. Pechanec
Internet-Draft
Request for Comments: 7512 D. Moffat
Intended status:
Category: Standards Track Oracle Corporation
Expires: August 17, 2015 February 13,
ISSN: 2070-1721 April 2015

The PKCS#11 PKCS #11 URI Scheme
draft-pechanec-pkcs11uri-21

Abstract

This memo specifies a PKCS#11 PKCS #11 Uniform Resource Identifier (URI)
Scheme for identifying PKCS#11 PKCS #11 objects stored in PKCS#11 tokens, PKCS #11 tokens and
also for identifying PKCS#11 PKCS #11 tokens, slots slots, or libraries. The URI
scheme is based on how PKCS#11 PKCS #11 objects, tokens, slots, and libraries
are identified in the PKCS#11 "PKCS #11 v2.20: Cryptographic Token Interface Standard.
Standard".

Status of This Memo

This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force
(IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list It represents the consensus of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid the IETF community. It has
received public review and has been approved for a maximum publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of six months RFC 5741.

Information about the current status of this document, any errata,
and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

This Internet-Draft will expire on August 17, 2015.
http://www.rfc-editor.org/info/rfc7512.

This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3
3. PKCS#11 PKCS #11 URI Scheme Definition . . . . . . . . . . . . . . . . 4
3.1. PKCS#11
2.1. PKCS #11 URI Scheme Name . . . . . . . . . . . . . . . . . 4
3.2. PKCS#11
2.2. PKCS #11 URI Scheme Status . . . . . . . . . . . . . . . . 4
3.3. PKCS#11
2.3. PKCS #11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4
3.4. PKCS#11
2.4. PKCS #11 URI Scheme Query Attribute Semantics . . . . . . 9
3.5. PKCS#11
2.5. PKCS #11 URI Matching Guidelines . . . . . . . . . . . . . 11
3.6. PKCS#11
2.6. PKCS #11 URI Comparison . . . . . . . . . . . . . . . . . 12
3.7.
2.7. Generating PKCS#11 PKCS #11 URIs . . . . . . . . . . . . . . . . . 13
4.
3. Examples of PKCS#11 PKCS #11 URIs . . . . . . . . . . . . . . . . . . 14
5.
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
5.1.
4.1. URI Scheme Registration . . . . . . . . . . . . . . . . . 17
6.
5. Internationalization Considerations . . . . . . . . . . . . . 17
7.
6. Security Considerations . . . . . . . . . . . . . . . . . . . 18
8.
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
8.1.
7.1. Normative References . . . . . . . . . . . . . . . . . . 19
8.2. 18
7.2. Informative References . . . . . . . . . . . . . . . . . 19
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 20

1. Introduction

The PKCS #11:

"PKCS #11 v2.20: Cryptographic Token Interface Standard Standard" [PKCS11]
specifies an API, called Cryptoki, for devices which that hold
cryptographic information and perform cryptographic functions.
Cryptoki, pronounced crypto-key
Cryptoki (pronounced "crypto-key" and short for cryptographic "cryptographic token
interface,
interface") follows a simple object-based approach, addressing the
goals of technology independence (any kind of device may be used) and
resource sharing (multiple applications may access multiple devices),
presenting applications with a common, logical view of the device - --
a cryptographic token.

It is desirable for applications or libraries that work with PKCS#11 PKCS #11
tokens to accept a common identifier that consumers could use to
identify an existing PKCS#11 PKCS #11 storage object in a PKCS#11 PKCS #11 token, an
existing token itself, a slot, or an existing Cryptoki library (also
called a producer, module, or provider). The set of storage object
types that can be stored in a PKCS#11 PKCS #11 token includes a certificate, certificate;
a data object; and a public, private private, or secret key, and a data object. key. These objects
can be uniquely identifiable via the PKCS#11 PKCS #11 URI scheme defined in
this document. The set of attributes describing a storage object can
contain an object label, its type, and its ID. The set of attributes
that identifies a PKCS#11 PKCS #11 token can contain a token label,
manufacturer name, serial number, and token model. Attributes that
can identify a slot are a slot ID, description, and manufacturer.
Attributes that can identify a Cryptoki library are a library
manufacturer, description, and version. Library attributes may be
necessary to use if more than one Cryptoki library provides a token
and/or PKCS#11 PKCS #11 objects of the same name. A set of query attributes
is provided as well.

The PKCS#11

A PKCS #11 URI cannot identify other objects defined in the
specification [PKCS11] aside from storage objects. For example,
objects not identifiable by a PKCS#11 PKCS #11 URI include a hardware feature
and mechanism. Note that a Cryptoki library does not have to provide
for storage objects at all. The URI can still be used to identify a
specific PKCS#11 PKCS #11 token, slot slot, or an API producer in such a case.

A subset of existing PKCS#11 PKCS #11 structure members and object attributes
was chosen to uniquely identify a PKCS#11 PKCS #11 storage object, token,
slot, or library in a configuration file, on a command line, or in a
configuration property of something else. Should there be a need for
a more complex information exchange on PKCS#11 entities PKCS #11 entities, a different
means of data marshalling should be chosen accordingly.

A PKCS#11 PKCS #11 URI is not intended to be used to create new PKCS#11 PKCS #11
objects in tokens, tokens or to create PKCS#11 PKCS #11 tokens. It is solely to be
used to identify and work with existing storage objects, tokens, and
slots through the PKCS#11 PKCS #11 API, or to identify Cryptoki libraries
themselves.

The URI scheme defined in this document is designed specifically with
a mapping to the PKCS#11 PKCS #11 API in mind. The URI scheme definition
uses the scheme, path path, and query components defined in the Uniform "Uniform
Resource Identifier (URI): Generic Syntax Syntax" [RFC3986] document. The
URI scheme does not use the hierarchical element for a naming
authority in the path since the authority part could not be mapped to PKCS#11
PKCS #11 API elements. The URI scheme does not use the fragment
component.

If an application has no access to a producer or producers of the
PKCS#11 API
PKCS #11 API, the query component module attributes can be used.
However, the PKCS#11 PKCS #11 URI consumer can always decide to provide its
own adequate user interface to locate and load PKCS#11 PKCS #11 API
producers.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].

2. Contributors

Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship,
Jaroslav Imrich, and Mark Phalan contributed to the development of
this document.

3. PKCS#11 PKCS #11 URI Scheme Definition

In accordance with [RFC4395], this section provides the information
required to register the PKCS#11 PKCS #11 URI scheme.

3.1. PKCS#11

2.1. PKCS #11 URI Scheme Name

pkcs11

3.2. PKCS#11

2.2. PKCS #11 URI Scheme Status

Permanent.

3.3. PKCS#11

Permanent

2.3. PKCS #11 URI Scheme Syntax

The PKCS#11

A PKCS #11 URI is a sequence of attribute value pairs separated by a
semicolon that form a one level one-level path component, optionally followed
by a query. Except for the value of the "id" attribute defined later
in this section, these attribute value pairs and query components are
composed entirely of textual data and therefore SHOULD all first be
encoded as octets according to the UTF-8 character encoding
[RFC3629], in accordance with Section 2.5 of [RFC3986]; then then, only
those octets that do not correspond to characters in the unreserved
set or to permitted characters from the reserved set SHOULD be
percent-encoded. Note that the value of the "id" attribute SHOULD
NOT be encoded as UTF-8 because it can contain non-textual data,
instead it SHOULD be entirely percent-encoded. See important caveats
in Section 3.5 Sections 2.5 and Section 6 5 regarding working with UTF-8 strings containing
characters outside the US-ASCII character set.

Grammar rules "unreserved" and "pct-encoded" in the PKCS#11 PKCS #11 URI
specification
scheme definition below are imported from [RFC3986]. As a special
case, note that according to Appendix A of [RFC3986], a space must be
percent-encoded.

The PKCS#11 PKCS #11 specification imposes various limitations on the value
of attributes, be it a more restrictive character set for the
"serial" attribute or fixed sized fixed-size buffers for almost all the others,
including "token", "manufacturer", and "model" attributes. The
syntax of the
PKCS#11 PKCS #11 URI scheme does not impose such limitations.
However, if the consumer of a PKCS#11 PKCS #11 URI encounters values that
would not be accepted by the PKCS#11 PKCS #11 specification, it MUST refuse
the URI as invalid.

A PKCS#11 PKCS #11 URI takes the following form (for explanation of Augmented
BNF, see [RFC5234]):

pk11-URI = "pkcs11:" pk11-path [ "?" pk11-query ]
; Path component and its attributes. Path may be empty.
pk11-path = [ pk11-pattr *(";" pk11-pattr) ]
pk11-pattr = pk11-token / pk11-manuf / pk11-serial /
pk11-model / pk11-lib-manuf /
pk11-lib-ver / pk11-lib-desc /
pk11-object / pk11-type / pk11-id /
pk11-slot-desc / pk11-slot-manuf /
pk11-slot-id / pk11-v-pattr
; Query component and its attributes. Query may be empty.
pk11-qattr = pk11-pin-source / pk11-pin-value /
pk11-module-name / pk11-module-path /
pk11-v-qattr
pk11-query = [ pk11-qattr *("&" pk11-qattr) ]
; RFC 3986 section Section 2.2 of [RFC3986] mandates all potentially reserved characters
; that do not conflict with actual delimiters of the URI do not have
; to be percent-encoded.
pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" /
"'" / "(" / ")" / "*" / "+" / "," / "="
pk11-path-res-avail = pk11-res-avail / "&"
; "/" and "?" in the query component MAY be unencoded but "&" MUST
; be encoded since it functions as a delimiter within the component.
pk11-query-res-avail = pk11-res-avail / "/" / "?" / "|"
pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded
pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded
pk11-token = "token" "=" *pk11-pchar
pk11-manuf = "manufacturer" "=" *pk11-pchar
pk11-serial = "serial" "=" *pk11-pchar
pk11-model = "model" "=" *pk11-pchar
pk11-lib-manuf = "library-manufacturer" "=" *pk11-pchar
pk11-lib-desc = "library-description" "=" *pk11-pchar
pk11-lib-ver = "library-version" "=" 1*DIGIT [ "." 1*DIGIT ]
pk11-object = "object" "=" *pk11-pchar
pk11-type = "type" "=" ( "public" / "private" / "cert" /
"secret-key" / "data" )
pk11-id = "id" "=" *pk11-pchar
pk11-slot-manuf = "slot-manufacturer" "=" *pk11-pchar
pk11-slot-desc = "slot-description" "=" *pk11-pchar
pk11-slot-id = "slot-id" "=" 1*DIGIT
pk11-pin-source = "pin-source" "=" *pk11-qchar
pk11-pin-value = "pin-value" "=" *pk11-qchar
pk11-module-name = "module-name" "=" *pk11-qchar
pk11-module-path = "module-path" "=" *pk11-qchar
pk11-v-attr-nm-char = ALPHA / DIGIT / "-" / "_"
; Permitted The permitted value of a vendor specific vendor-specific attribute is based on
; whether the attribute is used in the path or in the query.
pk11-v-pattr = 1*pk11-v-attr-nm-char "=" *pk11-pchar
pk11-v-qattr = 1*pk11-v-attr-nm-char "=" *pk11-qchar
The URI path component contains attributes that identify a resource
in a one level one-level hierarchy provided by Cryptoki producers. The query
component can contain a few attributes that may be needed to retrieve
the resource identified by the URI path component. Attributes in the
path component are delimited by the ';' character, attributes in the
query component use '&' as a delimiter.

Both path and query components MAY contain vendor specific vendor-specific
attributes. Such attribute names MUST NOT clash with existing
attribute names. Note that in accordance with [BCP178], the
previously used convention of starting vendor attributes with an "x-"
prefix is now deprecated.

The general '/' delimiter MUST be percent-encoded in the path
component so that generic URI parsers never split the path component
into multiple segments. It MAY be unencoded in the query component.
Delimiter
The delimiter '?' MUST be percent-encoded in the path component
since the PKCS#11 PKCS #11 URI scheme uses a query component. Delimiter The delimiter
'#' MUST be always percent-encoded so that generic URI parsers do not
treat a hash as a beginning of a fragment identifier component. All
other generic delimiters MAY be used unencoded (':', '[', ']', and
'@') in the
PKCS#11 a PKCS #11 URI.

The following table presents mapping between the PKCS#11 PKCS #11 URI path
component attributes and the PKCS#11 PKCS #11 API structure members and
object attributes. Given that PKCS#11 PKCS #11 URI users may be quite
ignorant about the PKCS#11 specification PKCS #11 specification, the mapping is a product
of a necessary compromise between how precisely are the URI attribute
names are mapped to the names in the specification and the ease of
use and understanding of the URI scheme.

Table 1: Mapping between URI path component attributes Path Component Attributes and PKCS#11
specification names PKCS #11
Specification Names

The following table presents mapping between the "type" attribute
values and corresponding PKCS#11 PKCS #11 object classes.

+-----------------+----------------------+

Table 2: Mapping between the "type" attribute Attribute and PKCS#11 object
classes PKCS #11 Object
Classes

The query component attribute "pin-source" specifies where the
application or library should find the normal user's token PIN, the
"pin-value" attribute provides the normal user's PIN value directly,
if needed, and the "module-name" and "module-path" attributes modify
default settings for accessing PKCS#11 PKCS #11 providers. For the
definition of a "normal user", see [PKCS11].

The ABNF rules above is are a best effort definition best-effort definition, and this paragraph
specifies additional constraints. The PKCS#11 A PKCS #11 URI MUST NOT contain
duplicate attributes of the same name in the URI path component. It
means that each attribute may be present at most once in the PKCS#11 PKCS #11
URI path component. Aside from the query attributes defined in this
document, duplicate (vendor) attributes MAY be present in the URI
query component and it is up to the URI consumer to decide on how to
deal with such duplicates.

As stated earlier in this section, the value of the "id" attribute
can contain non-textual data. This is because the corresponding
PKCS#11 PKCS
#11 "CKA_ID" object attribute can contain arbitrary binary data.
Therefore, the whole value of the "id" attribute SHOULD be percent-
encoded.

The "library-version" attribute represents the major and minor
version number of the library and its format is "M.N". Both numbers
are one byte in size, size; see the "libraryVersion" member of the CK_INFO
structure in [PKCS11] for more information. Value "M" for the
attribute MUST be interpreted as "M" for the major and "0" for the
minor version of the library. If the attribute is present present, the major
version number is REQUIRED. Both "M" and "N" MUST be decimal
numbers.

Slot ID is a Cryptoki-assigned number that is not guaranteed to be
stable across PKCS#11 PKCS #11 module initializations. However, there are
certain libraries and modules which that provide stable slot identifiers.
For these cases, when the slot description and manufacturer ID is not
sufficient to uniquely identify a specific reader, the slot ID MAY be
used to increase the precision of the token identification. In other
scenarios, using the slot IDs is likely to cause usability issues.

An empty PKCS#11 PKCS #11 URI path component attribute that does allow for an
empty value matches a corresponding structure member or an object
attribute with an empty value. Note that according to the PKCS#11 PKCS #11
specification [PKCS11], empty character values in a PKCS#11 PKCS #11 API
producer must be padded with spaces and should not be NULL
terminated.

3.4. PKCS#11

2.4. PKCS #11 URI Scheme Query Attribute Semantics

An application can always ask for a PIN by any means it decides to.
What is more, in order not to limit PKCS#11 PKCS #11 URI portability portability, the "pin-
source"
"pin-source" attribute value format and interpretation is left to be
implementation specific. However, the following rules SHOULD be
followed in descending order for the value of the "pin-source"
attribute:

o if If the value represents a URI URI, it SHOULD be treated as an object
containing the PIN. Such a URI may be "file:", "https:", another
PKCS#11
PKCS #11 URI, or something else.

o if If the value contains "|<absolute-command-path>" "|<absolute-command-path>", the
implementation SHOULD read the PIN from the output of an
application specified with absolute path "<absolute-command-
path>". Note that character "|" representing a pipe does not have
to be percent encoded percent-encoded in the query component of the PKCS#11 a PKCS #11 URI.

o interpret Interpret the value as needed in an implementation dependent way implementation-dependent way.

If a URI contains both "pin-source" and "pin-value" query attributes attributes,
the URI SHOULD be refused as invalid.

Use of the "pin-value" attribute may have security related security-related
consequences. Section 7 6 should be consulted before this attribute is
ever used. Standard percent encoding percent-encoding rules SHOULD be followed for
the attribute value.

A consumer of PKCS#11 PKCS #11 URIs MAY accept query component attributes
"module-name" and "module-path" in order to modify default settings
for accessing a PKCS#11 PKCS #11 provider or providers.

Processing the URI query module attributes SHOULD follow these rules:

o The attribute "module-name" SHOULD contain a case-insensitive PKCS#11 PKCS
#11 module name (not path nor filename) without system specific
affixes. Such system-specific
affixes; said affix could be an a ".so" or ".DLL" suffix, or a "lib"
prefix, for example. Not using system specific system-specific affixes is
expected to increase portability of PKCS#11 PKCS #11 URIs among different
systems. A URI consumer searching for PKCS#11 PKCS #11 modules SHOULD use
a system or application specific application-specific locations to find modules based
on the name provided in the attribute.

o The attribute "module-path" SHOULD contain a system specific system-specific
absolute path to the PKCS#11 module, PKCS #11 module or a system specific system-specific absolute
path to the directory of where PKCS#11 PKCS #11 modules are located. For
security reasons, a URI with a relative path in this attribute
SHOULD be rejected.

o the The URI consumer MAY refuse to accept either of the attributes, or
both. If use of the attribute present in the URI string is not
accepted
accepted, a warning message SHOULD be presented to the provider of
the URI and system specific system-specific module locations SHOULD be used.

o if If either of the module attributes is present, only those modules
found matching these query attributes SHOULD be used to search for
an entity represented by the URI.

o The use of the module attributes does not suppress matching of any
other URI path component attributes present in a URI.

o The semantics of using both attributes in the same URI string is
implementation specific but such use SHOULD be avoided. Attribute
"module-name" is preferred to "module-path" due to its system system-
independent nature nature, but the latter may be more suitable for
development and debugging.

o a A URI MUST NOT contain multiple module attributes of the same
name.

Use of the module attributes may have security related security-related consequences.
Section 7 6 should be consulted before these attributes are ever used.

A word "module" was chosen over a word "library" in these query
attribute names to avoid confusion with semantically different
library attributes used in the URI path component.

3.5. PKCS#11

2.5. PKCS #11 URI Matching Guidelines

The PKCS#11

A PKCS #11 URI can identify PKCS#11 PKCS #11 storage objects, tokens, slots,
or Cryptoki libraries. Note that since a URI may identify four
different types of entities entities, the context within which the URI is used
may be needed to determine the type. For example, a URI with only
library attributes may either represent all objects in all tokens in
all Cryptoki libraries identified by the URI, all tokens in those
libraries, or just the libraries.

The following guidelines can help a PKCS#11 PKCS #11 URI consumer (eg. (e.g., an
application accepting PKCS#11 PKCS #11 URIs) to match the URI with the
desired resource.

o the The consumer needs to know whether the URI is to identify PKCS#11 PKCS #11
storage object(s), token(s), slot(s), or Cryptoki producer(s).

o if If the consumer is willing to accept query component module
attributes
attributes, only those PKCS#11 PKCS #11 providers matching these
attributes SHOULD be worked with. See Section 3.4 2.4 for more
information.

o an An unrecognized attribute in the URI path component, including a
vendor specific
vendor-specific attribute, SHOULD result in an empty set of
matched resources. The consumer can consider whether an error
message presented to the user is appropriate in such a case.

o an An unrecognized attribute in the URI query SHOULD be ignored. The
consumer can consider whether a warning message presented to the
user is appropriate in such a case.

o an An attribute not present in the URI path component but known to a
consumer matches everything. Each additional attribute present in
the URI path component further restricts the selection.

o a A logical extension of the above is that a URI with an empty path
component matches everything. For example, if used to identify
storage objects objects, it matches all accessible objects in all tokens
provided by all relevant PKCS#11 PKCS #11 API producers.

o note Note that use of PIN attributes may change the set of storage
objects visible to the consumer.

o in In addition to query component attributes defined in this
document, vendor specific vendor-specific query attributes may contain further
information about how to perform the selection or other related
information.

As noted in Section 6, 5, the PKCS#11 PKCS #11 specification is not clear about
how to normalize UTF-8 encoded UTF-8-encoded Unicode characters [RFC3629]. For
that reason, it is RECOMMENDED not to use characters outside the US-
ASCII character set for labels and names. However, those who
discover a need to use such characters should be cautious,
conservative, and expend extra effort to be sure they know what they
are doing and that failure to do so may create both operational and
security risks. It means that when matching UTF-8 string based string-based
attributes (see Table 1) with characters outside the US-ASCII
repertoire, normalizing all UTF-8 strings before string comparison
may be the only safe approach. For example, for objects (keys) (keys), it
means that PKCS#11 PKCS #11 attribute search template would only contain
attributes that are not UTF-8 strings and another pass through
returned objects is then needed for UTF-8 string comparison after the
normalization is applied.

3.6. PKCS#11

2.6. PKCS #11 URI Comparison

Comparison of two URIs is a way of determining whether the URIs are
equivalent without comparing the actual resource to which the URIs point to.
point. The comparison of URIs aims to minimize false negatives while
strictly avoiding false positives. When working with UTF-8 strings
with characters outside the US-ASCII character sets, see important
caveats in Section 3.5 Sections 2.5 and Section 6. 5.

Two PKCS#11 PKCS #11 URIs are said to be equal if URIs as character strings
are identical as specified in Section 6.2.1 of [RFC3986], or if both
of the following rules are fulfilled:

o The set of attributes present in the URI is equal. Note that the
ordering of attributes in the URI string is not significant for
the mechanism of comparison.

o The values of respective attributes are equal based on rules
specified below

The rules for comparing values of respective attributes are:

o The values of path component attributes "library-description",
"library-manufacturer", "manufacturer", "model", "object",
"serial", "slot-description", "slot-manufacturer", "token",
"type", and the query component attribute "module-name" MUST be
compared using a simple string comparison comparison, as specified in
Section 6.2.1 of [RFC3986] [RFC3986], after the case and the percent-encoding percent-
encoding normalization are were both applied as specified in
Section 6.2.2 of [RFC3986].

o The value of the attribute "id" MUST be compared using the simple
string comparison after all bytes are percent-encoded using
uppercase letters for digits A-F.

o The value of the attribute "library-version" MUST be processed as
a specific scheme-based normalization permitted by Section 6.2.3
of [RFC3986]. The value MUST be split into a major and minor
version with character '.' (dot) serving as a delimiter. Library version A
library-version "M" MUST be treated as "M" for the major version
and "0" for the minor version. Resulting Then, resulting minor and major
version numbers MUST be
then separately compared numerically.

o The value of the attribute "slot-id" MUST be processed as a
specific scheme-based normalization permitted by Section 6.2.3 of
[RFC3986] and compared numerically.

o The value of "pin-source", if containing a "file:" URI or "|<absolute-
command-path>",
"|<absolute-command-path>", MUST be compared using the simple
string comparison after the full syntax based normalization syntax-based normalization, as
specified in Section 6.2.2 of [RFC3986] [RFC3986], is applied. If the value
of the "pin-
source" "pin-source" attribute is believed to be overloaded overloaded, the
case and percent-encoding normalization SHOULD be applied before
the values are compared compared, but the exact mechanism of comparison is
left to the application.

o The value of the attribute "module-path" MUST be compared using
the simple string comparison after the full syntax based normalization syntax-based
normalization, as specified in Section 6.2.2 of [RFC3986] [RFC3986], is
applied.

o when When comparing vendor specific attributes vendor-specific attributes, the case and percent-
encoding normalization normalization, as specified in Section 6.2.2 of [RFC3986]
[RFC3986], SHOULD be applied before the values are compared compared, but
the exact mechanism of such a comparison is left to the
application.

3.7.

2.7. Generating PKCS#11 PKCS #11 URIs

When generating URIs for PKCS#11 resources PKCS #11 resources, the exact set of
attributes used in a URI is inherently context specific. A PKCS#11 PKCS #11
URI template [RFC6570] support MAY be provided by a URI generating URI-generating
application to list URIs to access the same resource(s) again if the
template captured the necessary context.

3. Examples of PKCS#11 PKCS #11 URIs

This section contains some examples of how PKCS#11 PKCS #11 token objects,
tokens, slots, and libraries can be identified using the PKCS#11 PKCS #11 URI
scheme. Note that in some of the following examples, newlines line breaks and
spaces were inserted for better readability. As specified in
Appendix C of [RFC3986], whitespace SHOULD be ignored when extracting
the URI. Also note that all spaces as that are part of the URI URIs are percent-
encoded,
percent-encoded, as specified in Appendix A of [RFC3986].

An empty PKCS#11 PKCS #11 URI might be useful to PKCS#11 PKCS #11 consumers. See
Section 3.5 2.5 for more information on semantics of such a URI.

pkcs11:

One of the simplest and most useful forms might be a PKCS#11 PKCS #11 URI
that specifies only an object label and its type. The default token
is used so the URI does not specify it. Note that when specifying
public objects, a token PIN may not be required.

pkcs11:object=my-pubkey;type=public

When a private key is specified specified, either the "pin-source" attribute,
"pin-value,
"pin-value", or an application specific application-specific method would be usually used.
Note that '/' is not percent-encoded in the "pin-source" attribute
value since this attribute is part of the query component, not the
path,
path component, and thus is separated by '?' from the rest of the
URI.

pkcs11:object=my-key;type=private?pin-source=file:/etc/token

The following example identifies a certificate in the software token.
Note the use of an empty value for the attribute "serial" "serial", which
matches only empty "serialNumber" member of the "CK_TOKEN_INFO"
structure. Also note that the "id" attribute value is entirely
percent-encoded, as recommended. While ',' is in the reserved set set,
it does not have to be percent-encoded since it does not conflict
with any sub-delimiters used. The '#' character character, as in "The Software PKCS#11 Softtoken"
PKCS #11 Softtoken", MUST be percent-encoded.

pkcs11:token=The%20Software%20PKCS%2311%20Softtoken;
manufacturer=Snake%20Oil,%20Inc.;
model=1.0;
object=my-certificate;
type=cert;
id=%69%95%3E%5C%F4%BD%EC%91;
serial=
?pin-source=file:/etc/token_pin
The next example covers how to use the "module-name" query attribute.
Considering that the module is located in /usr/lib/libmypkcs11.so.1 the /usr/lib/
libmypkcs11.so.1 file, the attribute value is "mypkcs11", meaning
only the module name without the full path, path and without the platform platform-
specific "lib" prefix and ".so.1" suffix.

pkcs11:object=my-sign-key;
type=private
?module-name=mypkcs11

The following example covers how to use the "module-path" query
attribute. The attribute may be useful if a user needs to provide
the key via a PKCS#11 PKCS #11 module stored on a removable media, for
example. Getting the PIN to access the private key here is left to
be application specific.

pkcs11:object=my-sign-key;
type=private
?module-path=/mnt/libmypkcs11.so.1

In the context of where a token is expected expected, the token can be
identified without specifying any PKCS#11 PKCS #11 objects. A PIN might
still be needed in the context of listing all objects in the token,
for example. Section 7 6 should be consulted before the "pin-value"
attribute is ever used.

pkcs11:token=Software%20PKCS%2311%20softtoken;
manufacturer=Snake%20Oil,%20Inc.
?pin-value=the-pin

In the context where a slot is expected expected, the slot can be identified
without specifying any PKCS#11 PKCS #11 objects in any token it that may be
inserted in it. the slot.

pkcs11:slot-description=Sun%20Metaslot

The Cryptoki library alone can be also identified without specifying
a PKCS#11 PKCS #11 token or object.

pkcs11:library-manufacturer=Snake%20Oil,%20Inc.;
library-description=Soft%20Token%20Library;
library-version=1.23
The following example shows an attribute value with a semicolon. In
such case a case, it MUST be percent-encoded. The token attribute value
MUST be read as "My token; created by Joe". Lower case Lowercase letters MAY be
used in percent-encoding percent-encoding, as shown below in the "id" attribute value value,
but note that Sections 2.1 and 6.2.2.1 of [RFC3986] read state that all
percent-encoded characters SHOULD use the uppercase hexadecimal
digits. More specifically, if the URI string was were to be compared compared,
the algorithm defined in Section 3.6 2.6 explicitly requires percent-encoding percent-
encoding to use the uppercase digits A-F in the "id" attribute
values. And as explained in Section 3.3, 2.3, library version "3" MUST be
interpreted as "3" for the major and "0" for the minor version of the
library.

pkcs11:token=My%20token%25%20created%20by%20Joe;
library-version=3;
id=%01%02%03%Ba%dd%Ca%fe%04%05%06

If there is any need to include a literal "%;" substring, for
example, both characters MUST be escaped. The token value MUST be
read as "A name with a substring %;".

pkcs11:token=A%20name%20with%20a%20substring%20%25%3B;
object=my-certificate;
type=cert

The next example includes a small A with acute in the token name. It
MUST be encoded in octets according to the UTF-8 character encoding
and then percent-encoded. Given that a small A with acute is U+225
unicode
Unicode code point, the UTF-8 encoding is 195 161 in decimal, and
that is "%C3%A1" in percent-encoding. See also Section 5 on the use
of characters outside the US-ASCII character set for labels.

pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1;
object=my-certificate;
type=cert

Both the path and query components MAY contain vendor specific vendor-specific
attributes. Attributes in the query component MUST be delimited by
'&'.

pkcs11:token=my-token;
object=my-certificate;
type=cert;
vendor-aaa=value-a
?pin-source=file:/etc/token_pin
&vendor-bbb=value-b

4. IANA Considerations

5.1.

4.1. URI Scheme Registration

This document moves the "pkcs11" URI scheme from the provisional "Provisional URI
Schemes" registry to
permanent the "Permanent URI scheme Schemes" registry. The
registration request complies with [RFC4395].

URI scheme name: pkcs11

URI scheme status: permanent

URI scheme syntax: defined Defined in Section 3.3 2.3 of [RFCXXXX] [RFC7512].

URI scheme semantics: defined Defined in Section 1 of [RFCXXXX] [RFC7512].

Encoding considerations: see Section 3.3 See Sections 2.3 and Section 6 5 of
[RFCXXXX] [RFC7512].

Applications/protocols that use this URI scheme name: for For general
information, see Section 1 of [RFCXXXX]. List [RFC7512]. A list of known
consumers of the PKCS#11 PKCS #11 URI include GnuTLS, Gnome, p11-kit,
Oracle Solaris 11 and higher, OpenSC, OpenConnect, and FreeIPA.

Interoperability considerations: see See Section 6 5 of [RFCXXXX] [RFC7512].

Security considerations: see See Section 7 6 of [RFCXXXX] [RFC7512].

Contact: Jan Pechanec <Jan.Pechanec@Oracle.COM>, <Jan.Pechanec@Oracle.com>, Darren Moffat
<Darren.Moffat@Oracle.COM>
<Darren.Moffat@Oracle.com>

Author/Change Controller: IESG <iesg@ietf.org>

References: [RFCXXXX]

6. [RFC7512]

5. Internationalization Considerations

The PKCS#11 PKCS #11 specification does not specify a canonical form for
strings of characters of the CK_UTF8CHAR type. This presents the
usual false negative and false positive (aliasing) concerns that
arise when dealing with unnormalized strings. Because all PKCS#11 PKCS #11
items are local and local security is assumed, these concerns are
mainly about usability and interoperability.

In order to improve the user experience, it is RECOMMENDED that
applications that create PKCS#11 PKCS #11 objects or label tokens do not use
characters outside the US-ASCII character set for the labels. If
that is not possible, labels SHOULD be normalized to Normalization
Form C (NFC) [UAX15]. For the same reason PKCS#11 reason, PKCS #11 libraries, slots
(token readers), and tokens SHOULD use US-ASCII characters only for
their names names, and if that is not possible, they SHOULD normalize their
names to NFC. When listing PKCS#11 PKCS #11 libraries, slots, tokens, and/or
objects, an application SHOULD normalize their names to NFC if
characters outside of the US-ASCII character set are expected. When
matching PKCS#11 PKCS #11 URIs to libraries, slots, tokens, and/or objects,
applications MAY convert names to a chosen normalization form before
the string comparison for matching, as those might pre-date predate these
recommendations. See also Section 3.5.

7. 2.5.

6. Security Considerations

There are general security considerations for URI schemes discussed
in Section 7 of [RFC3986].

From those security considerations, Section 7.1 of [RFC3986] applies
since there is no guarantee that the same PKCS#11 PKCS #11 URI will always
identify the same object, token, slot, or a library in the future.

Section 7.2 of [RFC3986] applies since by accepting query component
attributes "module-name" or "module-path" "module-path", the consumer potentially
allows loading of arbitrary code into a process.

Section 7.5 of [RFC3986] applies since the PKCS#11 a PKCS #11 URI may be used in
world readable command line
world-readable command-line arguments to run applications, stored in
public configuration files, or otherwise used in clear text. For
that reason reason, the "pin-value" attribute should only be used if the URI
string itself is protected with the same level of security as the
token PIN itself otherwise is.

The PKCS#11 PKCS #11 specification does not provide means to authenticate
devices to users; it only allows to authenticate authenticates users to tokens. Instead,
local and physical security are demanded: the user must be in
possession of their tokens, and the system into whose slots the
users' tokens are inserted must be secure. As a result, the usual
security considerations regarding normalization do not arise. For
the same reason, confusable script issues also do not arise.
Nonetheless, if use of characters outside the US-ASCII character set
is required, it is best to normalize to NFC all strings appearing in PKCS#11
PKCS #11 API elements. See also Section 6.

8. 5.

7. References

8.1.

7.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, STD 14, March 1997. 1997,
<http://www.rfc-editor.org/info/rfc2119>.

[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 3629, STD 63, RFC 3629, November 2003. 2003,
<http://www.rfc-editor.org/info/rfc3629>.

[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", RFC 3986, STD 66, RFC
3986, January 2005. 2005,
<http://www.rfc-editor.org/info/rfc3986>.

[RFC5234] Crocker, D. D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 5234, STD 68, RFC 5234, January 2008.

8.2. 2008,
<http://www.rfc-editor.org/info/rfc5234>.

7.2. Informative References

[BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham,
"Deprecating the "X-" Prefix and Similar Constructs in
Application Protocols", RFC 6648, BCP 178, June 2012. 2012,
<http://www.rfc-editor.org/info/bcp178>.

[PKCS11] RSA Laboratories, "PKCS #11: #11 v2.20: Cryptographic Token
Interface
Standard v2.20", Standard", Public Key Cryptography Standards
PKCS#11-v2.20, June 2004.

[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
Registration Procedures for New URI Schemes", BCP 35, RFC
4395, February 2006. 2006,
<http://www.rfc-editor.org/info/rfc4395>.

[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012. 2012,
<http://www.rfc-editor.org/info/rfc6570>.

[UAX15] Davis, M., Ed., Ed. and K. Whistler, K., Ed., and Unicode Consortium, "Unicode Standard
Annex #15 - #15: Unicode Normalization Forms, Forms", Version Unicode 7.0.0",
7.0.0, June 2014. 2014, <http://unicode.org/reports/tr15/>.

Contributors

Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship,
Jaroslav Imrich, and Mark Phalan contributed to the development of
this document. Shawn Emery shepherded the document.

Authors' Addresses

Jan Pechanec
Oracle Corporation
4180 Network Circle
Santa Clara Clara, CA 95054
USA

Email: Jan.Pechanec@Oracle.COM
United States

EMail: Jan.Pechanec@Oracle.com
URI: http://www.oracle.com

Darren J. Moffat
Oracle Corporation
Oracle Parkway
Thames Valley Park
Reading RG6 1RA
UK

Email: Darren.Moffat@Oracle.COM
United Kingdom

EMail: Darren.Moffat@Oracle.com
URI: http://www.oracle.com