draft-pechanec-pkcs11uri-12.txt   draft-pechanec-pkcs11uri-13.txt 
Network Working Group J. Pechanec Network Working Group J. Pechanec
Internet-Draft D. Moffat Internet-Draft D. Moffat
Intended status: Standards Track Oracle Corporation Intended status: Standards Track Oracle Corporation
Expires: January 30, 2014 July 29, 2013 Expires: April 03, 2014 September 30, 2013
The PKCS#11 URI Scheme The PKCS#11 URI Scheme
draft-pechanec-pkcs11uri-12 draft-pechanec-pkcs11uri-13
Abstract Abstract
This memo specifies a PKCS#11 Uniform Resource Identifier (URI) This memo specifies a PKCS#11 Uniform Resource Identifier (URI)
Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, for Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, for
identifying PKCS#11 tokens themselves, or for identifying PKCS#11 identifying PKCS#11 tokens themselves, or for identifying PKCS#11
libraries. The URI is based on how PKCS#11 objects, tokens, and libraries. The URI is based on how PKCS#11 objects, tokens, and
libraries are identified in the PKCS#11 Cryptographic Token Interface libraries are identified in the PKCS#11 Cryptographic Token Interface
Standard. Standard.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 30, 2014. This Internet-Draft will expire on April 03, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 20 skipping to change at page 2, line 20
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 3
3. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . 3 3. PKCS#11 URI Scheme Definition . . . . . . . . . . . . . . . . 3
3.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . 3 3.1. PKCS#11 URI Scheme Name . . . . . . . . . . . . . . . . . 4
3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . 3 3.2. PKCS#11 URI Scheme Status . . . . . . . . . . . . . . . . 4
3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4 3.3. PKCS#11 URI Scheme Syntax . . . . . . . . . . . . . . . . 4
3.4. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 6 3.4. PKCS#11 URI Matching Guidelines . . . . . . . . . . . . . 7
4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 7 3.5. PKCS#11 URI Comparison . . . . . . . . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 4. Examples of PKCS#11 URIs . . . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 10 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.2. Informative References . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 7.2. Informative References . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec] The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec]
specifies an API, called Cryptoki, for devices which hold specifies an API, called Cryptoki, for devices which hold
cryptographic information and perform cryptographic functions. cryptographic information and perform cryptographic functions.
Cryptoki, pronounced crypto-key and short for cryptographic token Cryptoki, pronounced crypto-key and short for cryptographic token
interface, follows a simple object-based approach, addressing the interface, follows a simple object-based approach, addressing the
goals of technology independence (any kind of device may be used) and goals of technology independence (any kind of device may be used) and
resource sharing (multiple applications may access multiple devices), resource sharing (multiple applications may access multiple devices),
presenting applications with a common, logical view of the device - a presenting applications with a common, logical view of the device - a
cryptographic token. cryptographic token.
It is desirable for applications or libraries that work with PKCS#11 It is desirable for applications or libraries that work with PKCS#11
tokens to accept a common identifier that consumers could use to tokens to accept a common identifier that consumers could use to
identify an existing PKCS#11 object in a PKCS#11 token, an existing identify an existing PKCS#11 storage object in a PKCS#11 token, an
token itself, or an existing Cryptoki library. The set of object existing token itself, or an existing Cryptoki library (also called a
types that can be stored in a PKCS#11 token includes a public key, a producer, module, or provider). The set of storage object types that
private key, a certificate, a secret key, and a data object. These can be stored in a PKCS#11 token includes a certificate, a public,
objects can be uniquely identifiable via the PKCS#11 URI scheme private or secret key, and a data object. These objects can be
defined in this document. The set of attributes describing an object uniquely identifiable via the PKCS#11 URI scheme defined in this
can contain an object label, its type, and its ID. The set of document. The set of attributes describing a storage object can
attributes that identifies a PKCS#11 token can contain a token label, contain an object label, its type, and its ID. The set of attributes
a manufacturer name, a serial number, and a token model. Attributes that identifies a PKCS#11 token can contain a token label, a
manufacturer name, a serial number, and a token model. Attributes
that can identify a Cryptoki library are a library manufacturer, a that can identify a Cryptoki library are a library manufacturer, a
library description, and a library version. Library attributes may library description, and a library version. Library attributes may
be necessary to use if more than one PKCS#11 module provides a token be necessary to use if more than one Cryptoki library provides a
and/or PKCS#11 objects of the same name(s). token and/or PKCS#11 objects of the same name(s).
The PKCS#11 URI cannot identify other objects aside from storage
objects, for example a hardware feature or 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 token or an
API producer in such a case.
A subset of existing PKCS#11 structure members and object attributes A subset of existing PKCS#11 structure members and object attributes
was chosen believed to be sufficient in uniquely identifying a was chosen believed to be sufficient in uniquely identifying a
PKCS#11 token, object, or library in a configuration file, on a PKCS#11 token, storage object, or library in a configuration file, on
command line, or in a configuration property of something else. a command line, or in a configuration property of something else.
Should there be a need for a more complex information exchange on Should there be a need for a more complex information exchange on
PKCS#11 entities a different means of data marshalling should be PKCS#11 entities a different means of data marshalling should be
chosen accordingly. chosen accordingly.
A PKCS#11 URI is not intended to be used to create new PKCS#11 A PKCS#11 URI is not intended to be used to create new PKCS#11
objects in tokens, or to create PKCS#11 tokens. It is solely to be objects in tokens, or to create PKCS#11 tokens. It is solely to be
used to identify and work with existing objects, tokens, and Cryptoki used to identify and work with existing storage objects and tokens
libraries through the PKCS#11 API. through the PKCS#11 API, or identify Cryptoki libraries themselves.
The URI scheme defined in this document is designed specifically with The URI scheme defined in this document is designed specifically with
a mapping to the PKCS#11 API in mind. The URI uses only the scheme a mapping to the PKCS#11 API in mind. The URI uses the scheme, path
and the path components which are required by the Uniform Resource and query components defined in the Uniform Resource Identifier
Identifier (URI): Generic Syntax [RFC3986]. The URI scheme does not (URI): Generic Syntax [RFC3986] document. The URI does not use the
use the hierarchical element for a naming authority in the path since hierarchical element for a naming authority in the path since the
the authority part could not be mapped to PKCS#11 API elements. The authority part could not be mapped to PKCS#11 API elements. The URI
URI scheme does not use the optional query and fragment elements. does not use the fragment component.
If an application has no access to a producer or producers of the If an application has no access to a producer or producers of the
PKCS#11 API it is left to its implementation to provide adequate user PKCS#11 API it is left to its implementation to provide adequate user
interface to locate and load such producer(s). interface to locate and load such producer(s).
2. Contributors 2. Contributors
Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and
Jaroslav Imrich contributed to the development of this document. Jaroslav Imrich contributed to the development of this document.
skipping to change at page 3, line 42 skipping to change at page 4, line 4
If an application has no access to a producer or producers of the If an application has no access to a producer or producers of the
PKCS#11 API it is left to its implementation to provide adequate user PKCS#11 API it is left to its implementation to provide adequate user
interface to locate and load such producer(s). interface to locate and load such producer(s).
2. Contributors 2. Contributors
Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and Stef Walter, Nikos Mavrogiannopoulos, Nico Williams, Dan Winship, and
Jaroslav Imrich contributed to the development of this document. Jaroslav Imrich contributed to the development of this document.
3. PKCS#11 URI Scheme Definition 3. PKCS#11 URI Scheme Definition
In accordance with [RFC4395], this section provides the information In accordance with [RFC4395], this section provides the information
required to register the PKCS#11 URI scheme. required to register the PKCS#11 URI scheme.
3.1. PKCS#11 URI Scheme Name 3.1. PKCS#11 URI Scheme Name
pkcs11 pkcs11
3.2. PKCS#11 URI Scheme Status 3.2. PKCS#11 URI Scheme Status
Permanent. Permanent.
3.3. PKCS#11 URI Scheme Syntax 3.3. PKCS#11 URI Scheme Syntax
The PKCS#11 URI scheme is a sequence of attribute value pairs The PKCS#11 URI is a sequence of attribute value pairs separated by a
separated by a semicolon. In accordance with Section 2.5 of semicolon that form a one level path component, optionally followed
[RFC3986], the data should first be encoded as octets according to by a query. In accordance with Section 2.5 of [RFC3986], the data
the UTF-8 character encoding [RFC3629]; then only those octets that should first be encoded as octets according to the UTF-8 character
do not correspond to characters in the unreserved set or to permitted encoding [RFC3629]; then only those octets that do not correspond to
characters from the reserved set should be percent-encoded. This characters in the unreserved set or to permitted characters from the
specification suggests one allowable exception to that rule for the reserved set should be percent-encoded. This specification suggests
"id" attribute, as stated later in this section. Grammar rules one allowable exception to that rule for the "id" attribute, as
"unreserved" and "pct-encoded" in the PKCS#11 URI specification below stated later in this section. Grammar rules "unreserved" and "pct-
are imported from [RFC3986]. As a special case, note that according encoded" in the PKCS#11 URI specification below are imported from
to Appendix A of [RFC3986], a space must be percent-encoded. [RFC3986]. As a special case, note that according to Appendix A of
[RFC3986], a space must be percent-encoded.
PKCS#11 specification imposes various limitations on the value of PKCS#11 specification imposes various limitations on the value of
attributes, be it a more restrictive character set for the "serial" attributes, be it a more restrictive character set for the "serial"
attribute or fixed sized buffers for almost all the others, including attribute or fixed sized buffers for almost all the others, including
"token", "manufacturer", and "model" attributes. However, the "token", "manufacturer", and "model" attributes. However, the
PKCS#11 URI notation does not impose such limitations aside from PKCS#11 URI notation does not impose such limitations aside from
removing generic and PKCS#11 URI delimiters from a permitted removing generic and PKCS#11 URI delimiters from a permitted
character set. We believe that being too restrictive on the character set. We believe that being too restrictive on the
attribute values could limit the PKCS#11 URI's usefulness. What is attribute values could limit the PKCS#11 URI's usefulness. What is
more, possible future changes to the PKCS#11 specification should not more, possible future changes to the PKCS#11 specification should not
affect existing attributes. affect existing attributes.
A PKCS#11 URI takes the form (for explanation of Augmented BNF, see A PKCS#11 URI takes the form (for explanation of Augmented BNF, see
[RFC5234]): [RFC5234]):
pk11-URI = "pkcs11" ":" pk11-identifier pk11-URI = "pkcs11" ":" pk11-path *1("?" pk11-query)
pk11-identifier = *1(pk11-attr *(";" pk11-attr)) ; Path component and its attributes. Path may be empty.
pk11-attr = pk11-token / pk11-manuf / pk11-serial / pk11-path = *1(pk11-pattr *(";" pk11-pattr))
pk11-pattr = pk11-token / pk11-manuf / pk11-serial /
pk11-model / pk11-lib-manuf / pk11-model / pk11-lib-manuf /
pk11-lib-ver / pk11-lib-desc / pk11-lib-ver / pk11-lib-desc /
pk11-object / pk11-object-type / pk11-id / pk11-object / pk11-type / pk11-id /
pk11-pin-source pk11-x-pattr
; Section 2.2 of RFC 3986 specifies that all potentially reserved ; Query component and its attributes. Query may be empty.
; characters that do not conflict with actual delimiters of the URI pk11-qattr = pk11-pin-source / pk11-x-qattr
; do not have to be percent-encoded. So, ";" was removed as a pk11-query = *1(pk11-qattr *("&" pk11-qattr))
; sub-delimiter of the PKCS#11 URI's path and "/", "?", and "#" as ; RFC 3986 section 2.2 mandates all potentially reserved characters
; delimiters of generic URI components. ; that do not conflict with actual delimiters of the URI do not have
pk11-reserved-avail = ":" / "[" / "]" / "@" / "!" / "$" / ; to be percent-encoded.
"&" / "'" / "(" / ")" / "*" / "+" / pk11-res-avail = ":" / "[" / "]" / "@" / "!" / "$" /
"," / "=" "'" / "(" / ")" / "*" / "+" / "," / "="
pk11-char = unreserved / pk11-reserved-avail / pk11-path-res-avail = pk11-res-avail / "&"
pct-encoded ; We allow "/" and "?" in the query to be unencoded but "&" must
pk11-token = "token" "=" *pk11-char ; be encoded since it may be used as a delimiter in the component.
pk11-manuf = "manufacturer" "=" *pk11-char pk11-query-res-avail = pk11-res-avail / "/" / "?"
pk11-serial = "serial" "=" *pk11-char pk11-pchar = unreserved / pk11-path-res-avail / pct-encoded
pk11-model = "model" "=" *pk11-char pk11-qchar = unreserved / pk11-query-res-avail / pct-encoded
pk11-lib-manuf = "library-manufacturer" "=" *pk11-char pk11-token = "token" "=" *pk11-pchar
pk11-lib-desc = "library-description" "=" *pk11-char 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("." 1*DIGIT) pk11-lib-ver = "library-version" "=" 1*DIGIT *1("." 1*DIGIT)
pk11-object = "object" "=" *pk11-char pk11-object = "object" "=" *pk11-pchar
pk11-object-type = "object-type" "=" *1("public" / "private" / pk11-type = "type" "=" *1("public" / "private" / "cert" /
"cert" / "secret-key" / "data") "secret-key" / "data")
pk11-id = "id" "=" *pk11-char pk11-id = "id" "=" *pk11-pchar
pk11-pin-source = "pin-source" "=" *pk11-char pk11-pin-source = "pin-source" "=" *pk11-qchar
pk11-x-attr-nm-char = ALPHA / DIGIT / "-" / "_"
; Permitted value of a vendor specific attribute is based on
; whether the attribute is used in the path or in the query.
pk11-x-pattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-pchar
pk11-x-qattr = "x-" 1*pk11-x-attr-nm-char "=" *pk11-qchar
The URI path component contains attributes that identify a resource
in a one level hierarchy provided by Cryptoki producers. The query
component may contain a PIN source attribute that may be needed to
retrieve the resource identified by the URI path. Both path and
query components may contain vendor specific attributes. Such
attribute names must start with an "x-" prefix. Attributes in the
path component are delimited by ';' character, attributes in the
query component use '&' as a delimiter.
More specifically, '/' delimiter of generic URI components was The general '/' delimiter was removed from available characters that
removed from available characters that do not have to be percent- do not have to be percent-encoded in the path component so that
encoded so that the initial part of a PKCS#11 URI is never confused generic URI parsers never split the path component into multiple
with "path-rootless" part of the "hier-part" generic URI component as segments. The '/' delimiter can be used unencoded in the query
defined in Section 3 of [RFC3986]. Delimiters '?' and '#' of generic component. Delimiter '?' was removed since the PKCS#11 URI uses a
URI components were removed to allow for possible future extensions query component. Delimiter '#' was removed so that generic URI
of the PKCS#11 URI. All other delimiters of generic URI components parsers are not confused by unencoded hash characters. All other
are allowed to be used unencoded (':', '[', ']', and '@') in the generic delimiters are allowed to be used unencoded (':', '[', ']',
PKCS#11 URI. and '@') in the PKCS#11 URI.
The attribute "token" represents a token label and corresponds to the The attribute "token" represents a token label and corresponds to the
"label" member of the CK_TOKEN_INFO structure, the attribute "label" member of the CK_TOKEN_INFO structure, the attribute
"manufacturer" corresponds to the "manufacturerID" member of "manufacturer" corresponds to the "manufacturerID" member of
CK_TOKEN_INFO, the attribute "serial" corresponds to the CK_TOKEN_INFO, the attribute "serial" corresponds to the
"serialNumber" member of CK_TOKEN_INFO, the attribute "model" "serialNumber" member of CK_TOKEN_INFO, the attribute "model"
corresponds to the "model" member of CK_TOKEN_INFO, the attribute corresponds to the "model" member of CK_TOKEN_INFO, the attribute
"library-manufacturer" represents the Cryptoki library manufacturer "library-manufacturer" represents the Cryptoki library manufacturer
and corresponds to the "manufacturerID" member of the CK_INFO and corresponds to the "manufacturerID" member of the CK_INFO
structure, the attribute "library-description" corresponds to the structure, the attribute "library-description" corresponds to the
"libraryDescription" member of CK_INFO, the attribute "library- "libraryDescription" member of CK_INFO, the attribute "library-
version" corresponds to the "libraryVersion" member of CK_INFO, the version" corresponds to the "libraryVersion" member of CK_INFO, the
attribute "object" represents a PKCS#11 object label and corresponds attribute "object" represents a PKCS#11 object label and corresponds
to the "CKA_LABEL" object attribute, the attribute "object-type" to the "CKA_LABEL" object attribute, the attribute "type" represents
represents the type of the object and corresponds to the "CKA_CLASS" the type of the object and corresponds to the "CKA_CLASS" object
object attribute, the attribute "id" represents the object ID and attribute, the attribute "id" represents the object ID and
corresponds to the "CKA_ID" object attribute, and the attribute "pin- corresponds to the "CKA_ID" object attribute, and the attribute "pin-
source" specifies where the application or library should find the source" specifies where the application or library should find the
token PIN, if needed. token PIN, if needed.
The PKCS#11 URI must not contain duplicate attributes of the same The PKCS#11 URI must not contain duplicate attributes of the same
name. It means that each attribute may be present at most once in a name in the URI path component. It means that each attribute may be
PKCS#11 URI string. present at most once in the PKCS#11 URI path. Aside from the "pin-
source" attribute, duplicate 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.
The "pin-source" attribute may represent a filename that contains a The "pin-source" attribute may represent a filename that contains a
token PIN but an application may overload this attribute. For token PIN but an application may overload this attribute. For
example, "pin-source=%7Cprog-name" could mean to read a PIN from an example, "pin-source=%7Cprog-name" could mean to read a PIN from an
external application (%7C denotes a pipe '|' character). Note that external application (%7C denotes a pipe '|' character). Note that
an application may always ask for a PIN and/or interpret the "pin- an application may always ask for a PIN and/or interpret the "pin-
source" attribute by any means it decides to. However, as discussed source" attribute by any means it decides to. However, as discussed
in Section 6, the attribute should never contain the PIN itself. in Section 6, the attribute should never contain the PIN itself.
It is recommended to percent-encode the whole value of the "id" It is recommended to percent-encode the whole value of the "id"
attribute which is supposed to be handled as arbitrary binary data. attribute which is supposed to be handled as arbitrary binary data.
Value "M" of the "library-version" attribute should be interpreted as Value "M" of the "library-version" attribute should be interpreted as
"M" for the major and "0" for the minor version of the library. Note "M" for the major and "0" for the minor version of the library. Note
that if the "library-version" attribute is present, the major version that if the "library-version" attribute is present, the major version
number is mandatory. number is mandatory.
An empty PKCS#11 URI attribute that does allow for an empty value An empty PKCS#11 URI path attribute that does allow for an empty
matches a corresponding structure member or an object attribute with value matches a corresponding structure member or an object attribute
an empty value. Note that according to the PKCS#11 specification with an empty value. Note that according to the PKCS#11
[pkcs11_spec], empty character values in a PKCS#11 producer must be specification [pkcs11_spec], empty character values in a PKCS#11 API
padded with spaces and should not be NULL terminated. producer must be padded with spaces and should not be NULL
terminated.
3.4. PKCS#11 URI Comparison 3.4. PKCS#11 URI Matching Guidelines
The PKCS#11 URI can identify PKCS#11 storage objects, tokens, or
Cryptoki libraries. The following guidelines should help a PKCS#11
URI consumer (eg. an application accepting PKCS#11 URIs) to match the
URI with the desired resource.
o the consumer must know whether the URI is to identify PKCS#11
storage object(s), token(s), or Cryptoki producer(s).
o an unrecognized attribute in the URI path component, including a
vendor specific attribute, should result in an empty set of
matched resources. The consumer should consider whether an error
message presented to the user is appropriate in such a case.
o an unrecognized attribute in the URI query should be ignored. The
consumer should consider whether a warning message presented to
the user is appropriate in such a case.
o an attribute not present in the URI path but known to a consumer
matches everything. Each additional attribute present in the URI
path further restricts the selection.
o a logical extension of the above is that an empty URI path matches
everything. For example, if used to identify storage objects, it
matches all accessible objects in all tokens provided by all
PKCS#11 API producers found in the system.
o use of the PIN attribute may change the set of storage objects
visible to the consumer.
o in addition to the PIN attribute, query string attributes may
contain further information about how to perform the selection or
other related information.
3.5. PKCS#11 URI Comparison
Comparison of two URIs is a way of determining whether the URIs are Comparison of two URIs is a way of determining whether the URIs are
equivalent without comparing the actual resource the URIs point to. equivalent without comparing the actual resource the URIs point to.
The comparison of URIs aims to minimize false negatives while The comparison of URIs aims to minimize false negatives while
strictly avoiding false positives. strictly avoiding false positives.
Two PKCS#11 URIs are said to be equal if URIs as character strings Two 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 are identical as specified in Section 6.2.1 of [RFC3986], or if both
following rules are fulfilled: following rules are fulfilled:
o set of attributes present in the URI is equal. Note that the o set of attributes present in the URI is equal. Note that the
ordering of attributes in the URI string is not significant for ordering of attributes in the URI string is not significant for
the mechanism of comparison. the mechanism of comparison.
o values of respective attributes are equal based on rules specified o values of respective attributes are equal based on rules specified
below below
The rules for comparing values of respective attributes are: The rules for comparing values of respective attributes are:
o values of attributes "library-description", "library- o values of attributes "library-description", "library-
manufacturer", "manufacturer", "model", "object", "object-type", manufacturer", "manufacturer", "model", "object", "serial",
"serial", and "token" must be compared using a simple string "token", and "type" must be compared using a simple string
comparison as specified in Section 6.2.1 of [RFC3986] after the comparison as specified in Section 6.2.1 of [RFC3986] after the
case and the percent-encoding normalization are both applied as case and the percent-encoding normalization are both applied as
specified in Section 6.2.2 of [RFC3986] specified in Section 6.2.2 of [RFC3986]
o value of attribute "id" must be compared using the simple string o value of attribute "id" must be compared using the simple string
comparison after all bytes are percent-encoded using uppercase comparison after all bytes are percent-encoded using uppercase
letters for digits A-F letters for digits A-F
o value for attribute "pin-source", if deemed containing the o value for attribute "pin-source", if deemed containing the
filename with the PIN value, must be compared using the simple filename with the PIN value, must be compared using the simple
skipping to change at page 7, line 42 skipping to change at page 9, line 13
comparison is left to the application. comparison is left to the application.
o value of attribute "library-version" must be processed as a o value of attribute "library-version" must be processed as a
specific scheme-based normalization permitted by Section 6.2.3 of specific scheme-based normalization permitted by Section 6.2.3 of
[RFC3986]. The value must be split into a major and minor version [RFC3986]. The value must be split into a major and minor version
with character '.' (dot) serving as a delimiter. Library version with character '.' (dot) serving as a delimiter. Library version
"M" must be treated as "M" for the major version and "0" for the "M" must be treated as "M" for the major version and "0" for the
minor version. Resulting minor and major version numbers must be minor version. Resulting minor and major version numbers must be
then separately compared numerically. then separately compared numerically.
o when comparing vendor specific attributes it is recommended to
perform case and percent-encoding normalization before the values
are compared but the exact mechanism of comparison is left to the
application.
4. Examples of PKCS#11 URIs 4. Examples of PKCS#11 URIs
This section contains some examples of how PKCS#11 token objects, This section contains some examples of how PKCS#11 token objects,
PKCS#11 tokens, and PKCS#11 libraries can be identified using the PKCS#11 tokens, and PKCS#11 libraries can be identified using the
PKCS#11 URI scheme. Note that in some of the following examples, PKCS#11 URI scheme. Note that in some of the following examples,
newlines and spaces were inserted for better readability. As newlines and spaces were inserted for better readability. As
specified in Appendix C of [RFC3986], whitespace should be ignored specified in Appendix C of [RFC3986], whitespace should be ignored
when extracting the URI. Also note that all spaces as part of the when extracting the URI. Also note that all spaces as part of the
URI are percent-encoded, as specified in Appendix A of [RFC3986]. URI are percent-encoded, as specified in Appendix A of [RFC3986].
An empty PKCS#11 URI might be useful to PKCS#11 consumers: An empty PKCS#11 URI might be useful to PKCS#11 consumers:
pkcs11: pkcs11:
One of the simplest and most useful forms might be a PKCS#11 URI that One of the simplest and most useful forms might be a PKCS#11 URI that
specifies only an object label and its type. The default token is specifies only an object label and its type. The default token is
used so the URI does not specify it. Note that when specifying used so the URI does not specify it. Note that when specifying
public objects, a token PIN might not be required. public objects, a token PIN might not be required.
pkcs11:object=my-pubkey;object-type=public pkcs11:object=my-pubkey;type=public
When a private key is specified either the "pin-source" attribute or When a private key is specified either the "pin-source" attribute or
an application specific method would be usually used. Also note that an application specific method would be usually used. Note that '/'
'/' must be percent-encoded in the "pin-source" attribute value since is not percent-encoded in the "pin-source" attribute value since this
it must be prevented to be mistaken for a path segment delimiter. attribute is part of the query component, not the path, and thus is
separated by '?' from the rest of the URI.
pkcs11:object=my-key;object-type=private; pkcs11:object=my-key;type=private?pin-source=/etc/token
pin-source=%2Fetc%2Ftoken_pin
The following example identifies a certificate in the software token. The following example identifies a certificate in the software token.
Note an empty value for the attribute "serial". Also note that the Note an empty value for the attribute "serial". Also note that the
"id" attribute value is entirely percent-encoded, as recommended. "id" attribute value is entirely percent-encoded, as recommended.
While ',' is in the reserved set it does not have to be percent- While ',' is in the reserved set it does not have to be percent-
encoded since it does not conflict with any sub-delimiters used. The encoded since it does not conflict with any sub-delimiters used. The
'#' character as in "The Software PKCS#11 Softtoken" is a general '#' character as in "The Software PKCS#11 Softtoken" must be percent-
delimiter as '/' so it must be percent-encoded, too. encoded.
pkcs11:token=The%20Software%20PKCS%2311%20Softtoken; pkcs11:token=The%20Software%20PKCS%2311%20Softtoken;
manufacturer=Snake%20Oil,%20Inc.; manufacturer=Snake%20Oil,%20Inc.;
serial=;
model=1.0; model=1.0;
object=my-certificate; object=my-certificate;
object-type=cert; type=cert;
id=%69%95%3E%5C%F4%BD%EC%91; id=%69%95%3E%5C%F4%BD%EC%91;
pin-source=%2Fetc%2Ftoken_pin serial=
?pin-source=/etc/token_pin
The token alone can be identified without specifying any PKCS#11 The token alone can be identified without specifying any PKCS#11
objects. A PIN may still be needed to list all objects, for example. objects. A PIN may still be needed to list all objects, for example.
pkcs11:token=Software%20PKCS%2311%20softtoken; pkcs11:token=Software%20PKCS%2311%20softtoken;
manufacturer=Snake%20Oil,%20Inc.; manufacturer=Snake%20Oil,%20Inc.
pin-source=%2Fetc%2Ftoken_pin ?pin-source=/etc/token_pin
The Cryptoki library alone can be also identified without specifying The Cryptoki library alone can be also identified without specifying
a PKCS#11 token or object. a PKCS#11 token or object.
pkcs11:library-manufacturer=Snake%20Oil,%20Inc.; pkcs11:library-manufacturer=Snake%20Oil,%20Inc.;
library-description=Soft%20Token%20Library; library-description=Soft%20Token%20Library;
library-version=1.23 library-version=1.23
The following example shows that the attribute value can contain a The following example shows that the attribute value can contain a
semicolon. In such case, it is percent-encoded. The token attribute semicolon. In such case, it is percent-encoded. The token attribute
value must be read as "My token; created by Joe". Lower case letters value must be read as "My token; created by Joe". Lower case letters
can also be used in percent-encoding as shown below in the "id" can also be used in percent-encoding as shown below in the "id"
attribute value but note that Sections 2.1 and 6.2.2.1 of [RFC3986] attribute value but note that Sections 2.1 and 6.2.2.1 of [RFC3986]
read that all percent-encoded characters should use the uppercase read that all percent-encoded characters should use the uppercase
hexadecimal digits. More specifically, if the URI string was to be hexadecimal digits. More specifically, if the URI string was to be
compared, the algorithm defined in Section 3.4 explicitly requires compared, the algorithm defined in Section 3.5 explicitly requires
percent-encoding to use the uppercase digits A-F in the "id" percent-encoding to use the uppercase digits A-F in the "id"
attribute values. And as explained in Section 3.3, library version attribute values. And as explained in Section 3.3, library version
"3" should be interpreted as "3" for the major and "0" for the minor "3" should be interpreted as "3" for the major and "0" for the minor
version of the library. version of the library.
pkcs11:token=My%20token%25%20created%20by%20Joe; pkcs11:token=My%20token%25%20created%20by%20Joe;
library-version=3 library-version=3;
id=%01%02%03%Ba%dd%Ca%fe%04%05%06; id=%01%02%03%Ba%dd%Ca%fe%04%05%06
If there is any need to include literal "%;" substring, for example, If there is any need to include literal "%;" substring, for example,
both characters must be escaped. The token value must be read as "A both characters must be escaped. The token value must be read as "A
name with a substring %;". name with a substring %;".
pkcs11:token=A%20name%20with%20a%20substring%20%25%3B; pkcs11:token=A%20name%20with%20a%20substring%20%25%3B;
object=my-certificate; object=my-certificate;
object-type=cert; type=cert
pin-source=%2Fetc%2Ftoken_pin ?pin-source=/etc/token_pin
The next example includes a small A with acute in the token name. It 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 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 and then percent-encoded. Given that a small A with acute is U+225
unicode code point, the UTF-8 encoding is 195 161 in decimal, and unicode code point, the UTF-8 encoding is 195 161 in decimal, and
that is "%C3%A1" in percent-encoding. that is "%C3%A1" in percent-encoding.
pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1;
object=my-certificate; object=my-certificate;
object-type=cert type=cert
Both the path and query components may contain vendor specific
attributes. Attributes in the query component may be delimited by
either ';' or '&'. We use '&' in the example that follows.
pkcs11:token=my-token;
object=my-certificate;
type=cert;
x-vend-aaa=value-a
?pin-source=/etc/token_pin&
x-vend-bbb=value-b
5. IANA Considerations 5. IANA Considerations
This document moves the "pkcs11" URI scheme from the provisional to This document moves the "pkcs11" URI scheme from the provisional to
the permanent URI scheme registry. The registration template for the the permanent URI scheme registry. The registration template for the
URI scheme is accessible on http://www.iana.org/assignments/uri- URI scheme is accessible on http://www.iana.org/assignments/uri-
schemes. schemes.
6. Security Considerations 6. Security Considerations
 End of changes. 36 change blocks. 
113 lines changed or deleted 196 lines changed or added

This html diff was produced by rfcdiff 1.49. The latest version is available from https://github.com/ietf-tools/rfcdiff