Manage smartcards with new p11-kit subcommands

P11-kit is an integral component to enable Hardware Security Module (HSM) and related technologies around PKCS#11. Over the years, its focus had mostly been on the library, with the bundled command-line tools not receiving much attention. When the user wanted to perform operations on the HSM or smartcard, they typically had to use tools from other packages. The most popular ones include p11tool from GnuTLS, modutil from NSS, and pkcs11-tool from OpenSC.

With p11-kit 0.25.1 release, the p11-kit command-line tool bundled with p11-kit has been extended with a handful of utilities, to make it possible to accomplish common operations with HSM without external tools.

The p11-kit tool

Previously, the p11-kit tool provided only 3 subcommands: list-modules, server, and remote. As the latter two are for enabling remote access to a PKCS#11 module, there was only list-modules for administration, which merely enumerates installed PKCS#11 modules and attached tokens. This is insufficient for practical use-cases such as generating new key-pair on a token, exporting keys for verification or just examining the objects stored on a token.

Listing modules, tokens, objects and mechanisms

P11-kit tool has been extended with many utility subcommands, such as list-objects, export-object, add-profile, etc., where most of these subcommands take a PKCS#11 URI as an argument to identify either a token or a storage object containing some arbitrary data like certificate or public key. To make it easy for the user to use these new subcommands, list-modules has been extended to also print URIs for both modules and tokens. The following is a truncated example output of list-modules subcommand:

$ p11-kit list-modules
module: p11-kit-trust
   path: /usr/lib64/pkcs11/p11-kit-trust.so
   uri: pkcs11:library-description=...;library-manufacturer=...
   ...
   token: System Trust
       uri: ...
       ...
   ...

Additionally, the user is now able to list just the tokens alone with the list-tokens subcommand. It takes a PKCS#11 URI which can be used to narrow down the search results. Optionally, an --only-uris option can be specified which will make the p11-kit tool display the URIs only. Following is an example output of list-tokens subcommand:

$ p11-kit list-tokens 'pkcs11:token=System%20Trust'
token: System Trust
   uri: pkcs11:...;token=System%20Trust
   manufacturer: PKCS#11 Kit
   model: p11-kit-trust
   ...
$ p11-kit list-tokens --only-uris pkcs11:token=System%20Trust
pkcs11:...;token=System%20Trust

To allow more detailed inspection of objects on a PKCS#11 token, the list-objects subcommand has been added. It requires a PKCS#11 URI to be specified to limit the search results, or an empty URI (“pkcs11:”) to match all objects across all tokens. The command displays some of the common attributes of an object. Additionally it displays PKCS#11 URI for storage objects (objects containing arbitrary data like certificates and keys) which can be used as an input to other p11-kit subcommands. The following example shows how to list public key objects with the list-objects subcommand:

$ p11-kit list-objects 'pkcs11:type=public'
Object: #0
   uri: ...
   class: public-key
   key-type: ec
   label: MY PUBLIC KEY

By default, the results only contain objects visible without authentication. In order to list the private objects, the user will need to authenticate to the token by using the --login option.

It might also be useful to the user to be able to list the mechanisms that a token supports. For this purpose the list-mechanisms subcommand has been added. It takes the PKCS#11 URI of a token and displays mechanisms with their supported key sizes and operations.

$ p11-kit list-mechanisms 'pkcs11:token=MyToken'
sha256: digest
sha256-hmac: sign verify key-size=32-512
sha256-rsa-pkcs: sign verify key-size=512-16384
sha256-rsa-pkcs-pss: sign verify key-size=512-16384
...

Generating a key-pair on a token

When the user builds a solution around PKCS#11, such as setting up an HTTPS server with NGINX or Apache HTTPD, they would need to create a key-pair on a PKCS#11 token first, so that the private key can be used to sign the certificate and TLS handshake.

For this purpose the generate-keypair subcommand has been added. This allows the user to generate a private key and the corresponding public key on a token. The subcommand requires the user to specify the token with a PKCS#11 URI, the key type with the --type option and the key length in bits with the --bits or a curve with the --curve option in case the key is based on an elliptic curve. Optionally, the user can specify a label for the key objects with the --label option. The following is an example of generating RSA and ECDSA key-pairs with the generate-keypair subcommand:

$ p11-kit generate-keypair --login --label=MyRSAKey --type=RSA --bits=2048 'pkcs11:token=MyToken'
$ p11-kit generate-keypair --login --label=MyECDSAKey --type=ECDSA --curve=SECP521R1 'pkcs11:token=MyToken'

Note that this operation usually requires a password (PIN) to be specified. In the example above the --login option is used which will prompt the user to input a PIN.

Exporting and importing certificates and public keys

After generating a key-pair, the public key needs to be extracted for verification. For that purpose, the export-object subcommand can be used. It takes a PKCS#11 URI of the public key object, which can be checked with the list-objects subcommand mentioned previously. The command will then print the public key to the terminal in PEM format.

$ p11-kit export-object --login 'pkcs11:token=MyToken;object=MyRSAKey;type=public'

Conversely, objects such as certificates can be imported into a token. This can be done with the import-object subcommand, which works similarly to export-object, but takes a PEM file through --file option. Optionally, an object label can be specified with --label option.

$ p11-kit import-object --login --file=MyCert.pem --label=MyCert 'pkcs11:token=MyToken'

While PKCS#11 allows arbitrary data to be stored, p11-kit currently only supports importing and exporting certificates and public keys.

To remove an object such as a certificate or a key from a PKCS#11 token, the delete-object subcommand can be used.

$ p11-kit delete-object --login 'pkcs11:object=MyCert'

Note that any of the above mentioned operations might require the user to authenticate into the token with the --login option.

Managing token profiles

Profile objects are used to describe which PKCS#11 profiles the token implements. As such, those objects are usually populated by the token manufacturer. However, it is not uncommon that the user wants to assert specific PKCS#11 profiles on their token as a hint for the clients: for example, when they use a token as a storage for public certificates, having a CKP_PUBLIC_CERTIFICATES_TOKEN profile object would help in informing the clients that there are certificates on the token which can be accessed without authentication.

To support such a use-case, the add-profile subcommand has been added. The command takes a PKCS#11 URI of a token and a PKCS#11 profile via --profile option. The profile can be specified either as a human-readable name (e.g., “public-certificates-token” for CKP_PUBLIC_CERTIFICATES_TOKEN) or a number:

$ p11-kit add-profile --profile=public-certificates-token 'pkcs11:token=MyToken'
$ p11-kit add-profile --profile=0x4 'pkcs11:token=MyToken'

To list and remove profile objects from a token, the list-profiles and delete-profile subcommands can be used:

$ p11-kit list-profiles 'pkcs11:token=MyToken'
baseline-provider
authentication-token
public-certificates-token
$ p11-kit delete-profile --profile=public-certificates-token 'pkcs11:token=MyToken'

Other improvements

Apart from the addition of the utility subcommands mentioned above, the output of existing subcommands have been made more user-friendly when invoked from the terminal. Lines that need user’s attention are highlighted and PKCS#11 URIs are marked as hyperlinks on supported terminal emulators, which can be opened with the default URI handler, such as gcr-viewer on GNOME desktop.

Another notable improvement is the addition of print-config subcommand. P11-kit maintains its own configuration files (system wide, per-user and per-module), though these are scattered in multiple locations and it is not intuitive how these files are merged and evaluated at run-time. The print-config subcommand enables users to display the actual merged configuration.

Conclusion

The p11-kit command-line tool has been expanded to allow users to perform basic operations on HSMs. The user is now able to list tokens and objects with following new subcommands: list-tokens, list-objects and list-mechanisms. The generate-keypair, import-object, export-object and delete-object subcommands can be used for easy management of keys and certificates on a PKCS#11 token. P11-kit tool now also supports management of PKCS#11 profiles with add-profile, delete-profile and list-profiles subcommands. Additionally, the existing subcommands have been modernized and extended to match the user's intuition. The print-config subcommand has been added to allow users to diagnose configuration issues.