doc: Add RFC documents

1 files changed, 1123 insertions, 0 deletions

diff --git a/doc/rfc/rfc7512.txt b/doc/rfc/rfc7512.txt
new file mode 100644
index 0000000..5bff33d
--- /dev/null
+++ b/doc/rfc/rfc7512.txt
@@ -0,0 +1,1123 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                       J. Pechanec
+Request for Comments: 7512                                     D. Moffat
+Category: Standards Track                             Oracle Corporation
+ISSN: 2070-1721                                               April 2015
+
+
+                        The PKCS #11 URI Scheme
+
+Abstract
+
+   This memo specifies a PKCS #11 Uniform Resource Identifier (URI)
+   Scheme for identifying PKCS #11 objects stored in PKCS #11 tokens and
+   also for identifying PKCS #11 tokens, slots, or libraries.  The URI
+   scheme is based on how PKCS #11 objects, tokens, slots, and libraries
+   are identified in "PKCS #11 v2.20: Cryptographic Token Interface
+   Standard".
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc7512.
+
+Copyright Notice
+
+   Copyright (c) 2015 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   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.
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 1]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. PKCS #11 URI Scheme Definition ..................................4
+      2.1. PKCS #11 URI Scheme Name ...................................4
+      2.2. PKCS #11 URI Scheme Status .................................4
+      2.3. PKCS #11 URI Scheme Syntax .................................4
+      2.4. PKCS #11 URI Scheme Query Attribute Semantics ..............9
+      2.5. PKCS #11 URI Matching Guidelines ..........................11
+      2.6. PKCS #11 URI Comparison ...................................12
+      2.7. Generating PKCS #11 URIs ..................................14
+   3. Examples of PKCS #11 URIs ......................................14
+   4. IANA Considerations ............................................17
+      4.1. URI Scheme Registration ...................................17
+   5. Internationalization Considerations ............................18
+   6. Security Considerations ........................................18
+   7. References .....................................................19
+      7.1. Normative References ......................................19
+      7.2. Informative References ....................................19
+   Contributors ......................................................20
+   Authors' Addresses ................................................20
+
+1.  Introduction
+
+   "PKCS #11 v2.20: Cryptographic Token Interface Standard" [PKCS11]
+   specifies an API, called Cryptoki, for devices that hold
+   cryptographic information and perform cryptographic functions.
+   Cryptoki (pronounced "crypto-key" and short for "cryptographic token
+   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
+   tokens to accept a common identifier that consumers could use to
+   identify an existing PKCS #11 storage object in a 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 token includes a certificate;
+   a data object; and a public, private, or secret key.  These objects
+   can be uniquely identifiable via the 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 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
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 2]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   manufacturer, description, and version.  Library attributes may be
+   necessary to use if more than one Cryptoki library provides a token
+   and/or PKCS #11 objects of the same name.  A set of query attributes
+   is provided as well.
+
+   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 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 token, slot, or an API producer in such a case.
+
+   A subset of existing PKCS #11 structure members and object attributes
+   was chosen to uniquely identify a 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, a different
+   means of data marshalling should be chosen accordingly.
+
+   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
+   used to identify and work with existing storage objects, tokens, and
+   slots through the 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 API in mind.  The URI scheme definition
+   uses the scheme, path, and query components defined in the "Uniform
+   Resource Identifier (URI): Generic 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 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, the query component module attributes can be used.
+   However, the PKCS #11 URI consumer can always decide to provide its
+   own adequate user interface to locate and load 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].
+
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 3]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+2.  PKCS #11 URI Scheme Definition
+
+   In accordance with [RFC4395], this section provides the information
+   required to register the PKCS #11 URI scheme.
+
+2.1.  PKCS #11 URI Scheme Name
+
+   pkcs11
+
+2.2.  PKCS #11 URI Scheme Status
+
+   Permanent
+
+2.3.  PKCS #11 URI Scheme Syntax
+
+   A PKCS #11 URI is a sequence of attribute value pairs separated by a
+   semicolon that form a 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, 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 Sections 2.5 and 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 URI
+   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 specification imposes various limitations on the value
+   of attributes, be it a more restrictive character set for the
+   "serial" attribute or fixed-size buffers for almost all the others,
+   including "token", "manufacturer", and "model" attributes.  The
+   syntax of the PKCS #11 URI scheme does not impose such limitations.
+   However, if the consumer of a PKCS #11 URI encounters values that
+   would not be accepted by the PKCS #11 specification, it MUST refuse
+   the URI as invalid.
+
+   A PKCS #11 URI takes the following form (for explanation of Augmented
+   BNF, see [RFC5234]):
+
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 4]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+ 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) ]
+ ; 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 / "-" / "_"
+ ; The permitted value of a 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
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 5]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   The URI path component contains attributes that identify a resource
+   in a 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
+   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.
+   The delimiter '?'  MUST be percent-encoded in the path component
+   since the PKCS #11 URI scheme uses a query component.  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 a PKCS #11 URI.
+
+   The following table presents mapping between the PKCS #11 URI path
+   component attributes and the PKCS #11 API structure members and
+   object attributes.  Given that PKCS #11 URI users may be quite
+   ignorant about the PKCS #11 specification, the mapping is a product
+   of a necessary compromise between how precisely the URI attribute
+   names are mapped to the names in the specification and the ease of
+   use and understanding of the URI scheme.
+
+   +----------------------+---------------------+----------------------+
+   | URI component path   | Attribute           | PKCS #11             |
+   | attribute name       | represents          | specification        |
+   |                      |                     | counterpart          |
+   +----------------------+---------------------+----------------------+
+   | id                   | key identifier for  | "CKA_ID" object      |
+   |                      | object              | attribute            |
+   +----------------------+---------------------+----------------------+
+   | library-description  | character-string    | "libraryDescription" |
+   |                      | description of the  | member of CK_INFO    |
+   |                      | library             | structure.  It is a  |
+   |                      |                     | UTF-8 string.        |
+
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 6]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   +----------------------+---------------------+----------------------+
+   | library-manufacturer | ID of the Cryptoki  | "manufacturerID"     |
+   |                      | library             | member of the        |
+   |                      | manufacturer        | CK_INFO structure.   |
+   |                      |                     | It is a UTF-8        |
+   |                      |                     | string.              |
+   +----------------------+---------------------+----------------------+
+   | library-version      | Cryptoki library    | "libraryVersion"     |
+   |                      | version number      | member of the        |
+   |                      |                     | CK_INFO structure.   |
+   +----------------------+---------------------+----------------------+
+   | manufacturer         | ID of the token     | "manufacturerID"     |
+   |                      | manufacturer        | member of            |
+   |                      |                     | CK_TOKEN_INFO        |
+   |                      |                     | structure.  It is a  |
+   |                      |                     | UTF-8 string.        |
+   +----------------------+---------------------+----------------------+
+   | model                | token model         | "model" member of    |
+   |                      |                     | CK_TOKEN_INFO        |
+   |                      |                     | structure.  It is a  |
+   |                      |                     | UTF-8 string.        |
+   +----------------------+---------------------+----------------------+
+   | object               | description (name)  | "CKA_LABEL" object   |
+   |                      | of the object       | attribute.  It is a  |
+   |                      |                     | UTF-8 string.        |
+   +----------------------+---------------------+----------------------+
+   | serial               | character-string    | "serialNumber"       |
+   |                      | serial number of    | member of            |
+   |                      | the token           | CK_TOKEN_INFO        |
+   |                      |                     | structure.           |
+   +----------------------+---------------------+----------------------+
+   | slot-description     | slot description    | "slotDescription"    |
+   |                      |                     | member of            |
+   |                      |                     | CK_SLOT_INFO         |
+   |                      |                     | structure.  It is a  |
+   |                      |                     | UTF-8 string.        |
+   +----------------------+---------------------+----------------------+
+   | slot-id              | Cryptoki-assigned   | decimal number of    |
+   |                      | value that          | "CK_SLOT_ID" type.   |
+   |                      | identifies a slot   |                      |
+   +----------------------+---------------------+----------------------+
+   | slot-manufacturer    | ID of the slot      | "manufacturerID"     |
+   |                      | manufacturer        | member of            |
+   |                      |                     | CK_SLOT_INFO         |
+   |                      |                     | structure.  It is a  |
+   |                      |                     | UTF-8 string.        |
+
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 7]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   +----------------------+---------------------+----------------------+
+   | token                | application-defined | "label" member of    |
+   |                      | label, assigned     | the CK_TOKEN_INFO    |
+   |                      | during token        | structure.  It is a  |
+   |                      | initialization      | UTF-8 string.        |
+   +----------------------+---------------------+----------------------+
+   | type                 | object class (type) | "CKA_CLASS" object   |
+   |                      |                     | attribute.           |
+   +----------------------+---------------------+----------------------+
+
+          Table 1: Mapping between URI Path Component Attributes
+                     and PKCS #11 Specification Names
+
+   The following table presents mapping between the "type" attribute
+   values and corresponding PKCS #11 object classes.
+
+                +-----------------+-----------------------+
+                | Attribute value | PKCS #11 object class |
+                +-----------------+-----------------------+
+                | cert            | CKO_CERTIFICATE       |
+                | data            | CKO_DATA              |
+                | private         | CKO_PRIVATE_KEY       |
+                | public          | CKO_PUBLIC_KEY        |
+                | secret-key      | CKO_SECRET_KEY        |
+                +-----------------+-----------------------+
+
+               Table 2: Mapping between the "type" Attribute
+                        and 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 providers.  For the
+   definition of a "normal user", see [PKCS11].
+
+   The ABNF rules above are a best-effort definition, and this paragraph
+   specifies additional constraints.  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
+   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 "CKA_ID" object attribute can contain arbitrary binary data.
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 8]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   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; 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, 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 module initializations.  However, there are
+   certain libraries and modules 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 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
+   specification [PKCS11], empty character values in a PKCS #11 API
+   producer must be padded with spaces and should not be NULL
+   terminated.
+
+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 URI portability, the
+   "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 the value represents a URI, it SHOULD be treated as an object
+      containing the PIN.  Such a URI may be "file:", "https:", another
+      PKCS #11 URI, or something else.
+
+   o  If the value contains "|<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 in the query component of a PKCS #11 URI.
+
+   o  Interpret the value as needed in an implementation-dependent way.
+
+
+
+
+Pechanec & Moffat            Standards Track                    [Page 9]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   If a URI contains both "pin-source" and "pin-value" query attributes,
+   the URI SHOULD be refused as invalid.
+
+   Use of the "pin-value" attribute may have security-related
+   consequences.  Section 6 should be consulted before this attribute is
+   ever used.  Standard percent-encoding rules SHOULD be followed for
+   the attribute value.
+
+   A consumer of PKCS #11 URIs MAY accept query component attributes
+   "module-name" and "module-path" in order to modify default settings
+   for accessing a 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 module name (not path nor filename) without system-specific
+      affixes; said affix could be a ".so" or ".DLL" suffix, or a "lib"
+      prefix, for example.  Not using system-specific affixes is
+      expected to increase portability of PKCS #11 URIs among different
+      systems.  A URI consumer searching for PKCS #11 modules SHOULD use
+      a system or application-specific locations to find modules based
+      on the name provided in the attribute.
+
+   o  The attribute "module-path" SHOULD contain a system-specific
+      absolute path to the PKCS #11 module or a system-specific absolute
+      path to the directory of where PKCS #11 modules are located.  For
+      security reasons, a URI with a relative path in this attribute
+      SHOULD be rejected.
+
+   o  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, a warning message SHOULD be presented to the provider of
+      the URI and system-specific module locations SHOULD be used.
+
+   o  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-
+      independent nature, but the latter may be more suitable for
+      development and debugging.
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 10]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   o  A URI MUST NOT contain multiple module attributes of the same
+      name.
+
+   Use of the module attributes may have security-related consequences.
+   Section 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.
+
+2.5.  PKCS #11 URI Matching Guidelines
+
+   A PKCS #11 URI can identify PKCS #11 storage objects, tokens, slots,
+   or Cryptoki libraries.  Note that since a URI may identify four
+   different types of 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 URI consumer (e.g., an
+   application accepting PKCS #11 URIs) to match the URI with the
+   desired resource.
+
+   o  The consumer needs to know whether the URI is to identify PKCS #11
+      storage object(s), token(s), slot(s), or Cryptoki producer(s).
+
+   o  If the consumer is willing to accept query component module
+      attributes, only those PKCS #11 providers matching these
+      attributes SHOULD be worked with.  See Section 2.4 for more
+      information.
+
+   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 can 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 can consider whether a warning message presented to the
+      user is appropriate in such a case.
+
+   o  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.
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 11]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   o  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, it matches all accessible objects in all tokens
+      provided by all relevant PKCS #11 API producers.
+
+   o  Note that use of PIN attributes may change the set of storage
+      objects visible to the consumer.
+
+   o  In addition to query component attributes defined in this
+      document, vendor-specific query attributes may contain further
+      information about how to perform the selection or other related
+      information.
+
+   As noted in Section 5, the PKCS #11 specification is not clear about
+   how to normalize 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
+   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), it
+   means that 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.
+
+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.  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 Sections 2.5 and 5.
+
+   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
+   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
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 12]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   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, as specified in
+      Section 6.2.1 of [RFC3986], after the case and the percent-
+      encoding normalization 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.  A
+      library-version "M" MUST be treated as "M" for the major version
+      and "0" for the minor version.  Then, resulting minor and major
+      version numbers MUST be 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>", MUST be compared using the simple
+      string comparison after the full syntax-based normalization, as
+      specified in Section 6.2.2 of [RFC3986], is applied.  If the value
+      of the "pin-source" attribute is believed to be overloaded, the
+      case and percent-encoding normalization SHOULD be applied before
+      the values are 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, as specified in Section 6.2.2 of [RFC3986], is
+      applied.
+
+   o  When comparing vendor-specific attributes, the case and percent-
+      encoding normalization, as specified in Section 6.2.2 of
+      [RFC3986], SHOULD be applied before the values are compared, but
+      the exact mechanism of such a comparison is left to the
+      application.
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 13]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+2.7.  Generating PKCS #11 URIs
+
+   When generating URIs for PKCS #11 resources, the exact set of
+   attributes used in a URI is inherently context specific.  A PKCS #11
+   URI template [RFC6570] support MAY be provided by a 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 URIs
+
+   This section contains some examples of how PKCS #11 token objects,
+   tokens, slots, and libraries can be identified using the PKCS #11 URI
+   scheme.  Note that in some of the following examples, 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 that are part of the URIs are
+   percent-encoded, as specified in Appendix A of [RFC3986].
+
+   An empty PKCS #11 URI might be useful to PKCS #11 consumers.  See
+   Section 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 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, either the "pin-source" attribute,
+   "pin-value", or an 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 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", 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,
+   it does not have to be percent-encoded since it does not conflict
+   with any sub-delimiters used.  The '#' character, as in "The Software
+   PKCS #11 Softtoken", MUST be percent-encoded.
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 14]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+     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 the /usr/lib/
+   libmypkcs11.so.1 file, the attribute value is "mypkcs11", meaning
+   only the module name without the full path and without the 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 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, the token can be
+   identified without specifying any PKCS #11 objects.  A PIN might
+   still be needed in the context of listing all objects in the token,
+   for example.  Section 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, the slot can be identified
+   without specifying any PKCS #11 objects in any token that may be
+   inserted in the slot.
+
+     pkcs11:slot-description=Sun%20Metaslot
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 15]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   The Cryptoki library alone can be also identified without specifying
+   a 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 a case, it MUST be percent-encoded.  The token attribute value
+   MUST be read as "My token; created by Joe".  Lowercase letters MAY 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] state that all
+   percent-encoded characters SHOULD use the uppercase hexadecimal
+   digits.  More specifically, if the URI string were to be compared,
+   the algorithm defined in Section 2.6 explicitly requires percent-
+   encoding to use the uppercase digits A-F in the "id" attribute
+   values.  And as explained in Section 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 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
+
+
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 16]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   Both the path and query components MAY contain 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
+
+4.1.  URI Scheme Registration
+
+   This document moves the "pkcs11" URI scheme from the "Provisional URI
+   Schemes" registry to the "Permanent URI Schemes" registry.  The
+   registration request complies with [RFC4395].
+
+      URI scheme name: pkcs11
+
+      URI scheme status: permanent
+
+      URI scheme syntax: Defined in Section 2.3 of [RFC7512].
+
+      URI scheme semantics: Defined in Section 1 of [RFC7512].
+
+      Encoding considerations: See Sections 2.3 and 5 of [RFC7512].
+
+      Applications/protocols that use this URI scheme name: For general
+      information, see Section 1 of [RFC7512].  A list of known
+      consumers of the PKCS #11 URI include GnuTLS, Gnome, p11-kit,
+      Oracle Solaris 11 and higher, OpenSC, OpenConnect, and FreeIPA.
+
+      Interoperability considerations: See Section 5 of [RFC7512].
+
+      Security considerations: See Section 6 of [RFC7512].
+
+      Contact: Jan Pechanec <Jan.Pechanec@Oracle.com>, Darren Moffat
+      <Darren.Moffat@Oracle.com>
+
+      Author/Change Controller: IESG <iesg@ietf.org>
+
+      References: [RFC7512]
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 17]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+5.  Internationalization Considerations
+
+   The 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
+   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 objects or label tokens 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 libraries, slots
+   (token readers), and tokens SHOULD use US-ASCII characters only for
+   their names, and if that is not possible, they SHOULD normalize their
+   names to NFC.  When listing 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 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 predate these
+   recommendations.  See also Section 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 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", the consumer potentially
+   allows loading of arbitrary code into a process.
+
+   Section 7.5 of [RFC3986] applies since a PKCS #11 URI may be used in
+   world-readable command-line arguments to run applications, stored in
+   public configuration files, or otherwise used in clear text.  For
+   that 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 specification does not provide means to authenticate
+   devices to users; it only 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
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 18]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   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 API elements.  See also Section 5.
+
+7.  References
+
+7.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997,
+              <http://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, November 2003,
+              <http://www.rfc-editor.org/info/rfc3629>.
+
+   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+              Resource Identifier (URI): Generic Syntax", STD 66, RFC
+              3986, January 2005,
+              <http://www.rfc-editor.org/info/rfc3986>.
+
+   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234, January 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,
+              <http://www.rfc-editor.org/info/bcp178>.
+
+   [PKCS11]   RSA Laboratories, "PKCS #11 v2.20: Cryptographic Token
+              Interface 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,
+              <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,
+              <http://www.rfc-editor.org/info/rfc6570>.
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 19]
+
+RFC 7512                 The PKCS #11 URI Scheme              April 2015
+
+
+   [UAX15]    Davis, M., Ed. and K. Whistler, Ed., "Unicode Standard
+              Annex #15: Unicode Normalization Forms", Version Unicode
+              7.0.0, June 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, CA 95054
+   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
+   United Kingdom
+
+   EMail: Darren.Moffat@Oracle.com
+   URI:   http://www.oracle.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Pechanec & Moffat            Standards Track                   [Page 20]
+