The PKCS #11 URI Scheme
Extracted elements (30)
Query attribute names use 'module' rather than 'library' to avoid confusion with the semantically different 'library-*' path attributes that identify specific Cryptoki libraries. The path 'library-*' attributes identify an API producer; the query 'module-*' attributes modify provider lookup behavior.
The 'pin-source' attribute value format is intentionally left implementation-specific to avoid limiting PKCS #11 URI portability. A priority order of interpretations is provided (URI reference, then pipe command, then implementation-defined) as a SHOULD guideline rather than a strict requirement.
The PKCS #11 URI scheme does not use the hierarchical naming authority component in the path because the authority part could not be mapped to PKCS #11 API elements. It also does not use the fragment component. The scheme, path, and query components from RFC 3986 are used.
The URI scheme is designed solely to identify and work with existing PKCS #11 storage objects, tokens, and slots — not to create new objects or tokens. A subset of PKCS #11 structure members was chosen to be sufficient for unique identification while remaining easy to use on command lines and configuration files.
Slot ID is a Cryptoki-assigned number not guaranteed to be stable across PKCS #11 module initializations. It MAY be used to increase identification precision for libraries and modules that provide stable slot identifiers; in other scenarios, using slot IDs is likely to cause usability issues.
The 'module-name' attribute SHOULD contain only the module name without system-specific affixes (e.g., no '.so', '.DLL' suffix, no 'lib' prefix) to improve portability of PKCS #11 URIs across different operating systems.
The PKCS #11 specification does not specify a canonical form for CK_UTF8CHAR strings, creating false-negative and false-positive concerns when matching URI attributes. Applications SHOULD normalize names to NFC; applications MAY convert to a chosen normalization form before string comparison when matching URIs to older objects.
A PKCS #11 URI MUST NOT contain duplicate attributes of the same name in the URI path component; each attribute may appear at most once in the path. Duplicate vendor attributes MAY appear in the query component.
A URI MUST NOT contain multiple module attributes of the same name (i.e., duplicate 'module-name' or duplicate 'module-path').
An unrecognized attribute in the URI path component, including a vendor-specific attribute, SHOULD result in an empty set of matched resources. An unrecognized attribute in the URI query SHOULD be ignored.
If a PKCS #11 URI consumer encounters attribute values that would not be accepted by the PKCS #11 specification, it MUST refuse the URI as invalid.
If a URI contains both 'pin-source' and 'pin-value' query attributes, the URI SHOULD be refused as invalid.
String-based path attributes (library-description, library-manufacturer, manufacturer, model, object, serial, slot-description, slot-manufacturer, token, type) and 'module-name' MUST be compared using simple string comparison after case and percent-encoding normalization per RFC 3986 Section 6.2.2.
The '/' delimiter MUST be percent-encoded in the path component so generic URI parsers never split the path into multiple segments. The '?' MUST be percent-encoded in the path. The '#' MUST always be percent-encoded to prevent fragment identifier interpretation.
The 'id' attribute value MUST be compared using simple string comparison after all bytes are percent-encoded using uppercase letters for digits A-F. The 'slot-id' value MUST be compared numerically after scheme-based normalization.
The 'id' attribute value SHOULD NOT be encoded as UTF-8 because it can contain non-textual binary data; instead it SHOULD be entirely percent-encoded. All other textual attribute values SHOULD first be encoded as UTF-8 octets, then percent-encoded for characters outside the unreserved/permitted reserved sets.
The 'library-version' attribute major version number is REQUIRED when the attribute is present. Value 'M' MUST be interpreted as major version M and minor version 0. Both M and N MUST be decimal numbers.
The 'library-version' attribute MUST be split on '.' into major and minor, treating bare 'M' as minor=0, then major and minor MUST be compared numerically separately, as a scheme-based normalization per RFC 3986 Section 6.2.3.
The 'module-path' attribute SHOULD contain a system-specific absolute path to the PKCS #11 module or module directory. For security reasons, a URI with a relative path in this attribute SHOULD be rejected.
When matching UTF-8 string-based attributes with characters outside US-ASCII, it is RECOMMENDED to normalize all UTF-8 strings using Normalization Form C (NFC) before string comparison; otherwise false negatives or false positives may result.
The 'id' path attribute maps to CKA_ID and can contain arbitrary binary data. The 'object' attribute maps to CKA_LABEL (a UTF-8 string). The 'token' attribute maps to the 'label' member of CK_TOKEN_INFO. The 'slot-id' attribute is a decimal number of CK_SLOT_ID type.
The 'pin-source' query attribute specifies where to find the normal user's token PIN (URI, pipe command via '|<absolute-command-path>', or implementation-specific). The 'pin-value' attribute provides the PIN directly inline. The 'module-name' and 'module-path' attributes modify default PKCS #11 provider settings.
The pkcs11 URI scheme identifies PKCS #11 storage objects, tokens, slots, and Cryptoki libraries. It uses a path component of semicolon-delimited attribute-value pairs and an optional query component with ampersand-delimited attributes. The scheme does not use an authority component or fragment identifier.
The 'type' path attribute maps to CKA_CLASS and accepts values: 'public' (CKO_PUBLIC_KEY), 'private' (CKO_PRIVATE_KEY), 'cert' (CKO_CERTIFICATE), 'secret-key' (CKO_SECRET_KEY), and 'data' (CKO_DATA).
Vendor-specific attributes are allowed in both path and query components. Vendor attribute names MUST NOT clash with existing attribute names. The 'x-' prefix convention for vendor attributes is deprecated per BCP 178.
This document moves the 'pkcs11' URI scheme from the Provisional URI Schemes registry to the Permanent URI Schemes registry (IANA). Known consumers include GnuTLS, GNOME, p11-kit, Oracle Solaris 11+, OpenSC, OpenConnect, and FreeIPA.
Accepting the 'module-name' or 'module-path' query attributes potentially allows loading of arbitrary code into the consuming process, as specified in RFC 3986 Section 7.2. Consumers should carefully control whether to accept these attributes.
The 'pin-value' attribute embeds the token PIN directly in the URI string, which may appear in world-readable command-line arguments, public configuration files, or clear text. It SHOULD only be used if the URI string itself is protected with the same level of security as the PIN itself.
There is no guarantee that the same PKCS #11 URI will always identify the same object, token, slot, or library in the future (RFC 3986 Section 7.1 applies). The PKCS #11 specification does not provide means to authenticate devices to users; local and physical security are required.
The PKCS #11 URI ABNF defines pk11-URI as 'pkcs11:' followed by pk11-path and optional '?' pk11-query. Path attributes include token, manufacturer, serial, model, library-manufacturer, library-description, library-version, object, type, id, slot-description, slot-manufacturer, and slot-id. Query attributes include pin-source, pin-value, module-name, and module-path.