Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

pkcs11_parse_uri (7)

Name

pkcs11_parse_uri - Parse PKCS#11 URI Scheme

Synopsis

cc [flag...] file ... -lcryptoutil [library ... ]
#include <cryptoutil.h>
int pkcs11_parse_uri(const char *str, pkcs11_uri_t *uri)

Description

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.

Supported Attributes

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.


Note -  The 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.

Deprecated Attributes

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.

Examples

Example 1 Using an Empty PKCS#11 URI

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.


Note -  The / (slash) character need not to be percent-encoded in the pk11-pin-source query.

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_pin
  
Example 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

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library/security/pkcs11_softtoken
Interface Stability
Uncommitted

See Also

[RFC7512]

J. Pechanec and D. Moffat, "The PKCS #11 URI Scheme", RFC 7512, April 2015

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, STD 66, January 2005.

[pkcs11_spec]

OASIS PKCS 11 TC, "PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40", September 2014.