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