pkcs11_parse_uri - Parse PKCS#11 URI Scheme
cc [flag...] file ... -lcryptoutil [library ... ]
#include <cryptoutil.h> int pkcs11_parse_uri(const char *str, pkcs11_uri_t *uri)
RFC 7512 specifies the PKCS#11 Uniform Resource Identifier (URI) Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, for identifying PKCS#11 libraries, or for identifying PKCS#11 tokens themselves. The URI is based on how PKCS#11 objects, libraries, and tokens are identified in the PKCS#11 Cryptographic Token Interface Standard.
The pkcs11_parse_uri() implementation supports the following attributes: token, manufacturer, serial, model, object, type, id, and pin-source. For more information on each attribute, see the RFC 7512 specification.
The pin-source query attribute specifies where the application or library should find the user's token PIN. The value of the attribute can be one of the following:
If the value is builtin-dialog, the PIN is prompted and read from the terminal.
If the value represents an URI, it is treated as an object containing the PIN (file://).
If the value is |<absolute-command-path>, the PIN is read from the output of an application specified with the absolute path <absolute-command-path> that character | representing a pipe does not have to be percent-encoded.
The PKCS#11 specification limits the length of some fields. For example, the manufacturer label can be up to thirty-two characters long, the PKCS#11 URI does not impose such limitations. It is up to the consumer of the PKCS#11 URI to perform any necessary sanity length checks.
The attributes that were supported in the previous versions of Oracle Solaris, but not defined in the RFC 7512 are deprecated in this Oracle Solaris release. The deprecated attributes are objecttype, manuf, pinfile, and passphrasedialog.
An empty PKCS#11 URI might be useful to PKCS#11 consumers:
pkcs11:Example 2 Identifying an Object
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 might not be required.
pkcs11:object=my-pubkey;objecttype=public
When a private key is specified, the pk11-pin-source attribute must be used to provide the user's PIN to the application.
Get PIN from a file:
pkcs11:object=my-key;type=private?pin-source=file:///etc/token_pin
Get PIN from a command /etc/mygetpin:
pkcs11:object=my-key;type=private?pin-source=|/etc/mygetpin
Get PIN from the terminal:
pkcs11:object=my-key;type=private?pin-source=builtin-dialog
The following example identifies a certificate in the software token. Note that all the attributes aside from type, may have an empty value. In this case, serial is empty. If this is not allowed, the customer of the URI can perform necessary checks.
Note that the notation of the id attribute value is entirely percent-encoded. It is not necessary to percent-encode , (comma) which is in the reserved set, since it does not conflict with any sub-delimiter used. The # (hash) character is a general delimiter as / (slash), so you must percent-encode it.
pkcs11:token=The%20Software%20PKCS%2311%20softtoken; manufacturer=Snake%20Oil,%20Inc.; serial=; model=1.0; object=my-certificate; type=cert; id=%69%95%3E%5C%f4%BD%EC%91 ?pin-source=file:///etc/ssh/token_pin
The token alone can be identified without specifying any PKCS#11 objects. A PIN may still be needed to list all objects, for example
pkcs11:token=Software%20PKCS%2311%20softtoken; manufacturer=Snake%20Oil,%20Inc. ?pin-source=file:///etc/ssh/token_pinExample 3 Using Special Characters
The following example shows that the attribute value can contain a semicolon. In such case, it is percent-encoded. You can also have lower characters in the id attribute value, but note that [RFC3986] recommends to use uppercase hexadecimal digits for all percent-encoded characters.
pkcs11:token=My%20token%25%20created%20by%20Joe; object=my-certificate; type=cert; id=%69%95%3e%5c%f4%bd%ec%91 ?pin-source=file:///etc/ssh/token_pin
If there is any need to include literal %; substring, for example, you must escape both characters. The token value must be read as:
The token name with a strange substring ';
then
pkcs11:token=A%20name%20with%20a%20strange%20substring%20'%25%3B'; object=my-certificate; type=cert ?pinfile=/etc/ssh/token_pin
The next example includes a small A with acute in the token name. You must encode it in octets according to the UTF-8 character encoding and then use the percent-encoding. Given that a small A with acute is U+225 Unicode code point, the UTF-8 encoding is 195 161 in decimal, which is %C3%A1 in the percent-encoding.
pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1; object=my-certificate; type=cert
See attributes(7) for descriptions of the following attributes:
|
J. Pechanec and D. Moffat, "The PKCS #11 URI Scheme", RFC 7512, April 2015
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, STD 66, January 2005.
OASIS PKCS 11 TC, "PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40", September 2014.