The YubiHSM PKCS#11 Module is a native library to interact with a YubiHSM 2 device using the PKCS#11 interface.
This library works as a translation layer between
software using PKCS#11. For example, a function in this implementation
takes the input as specified by PKCS#11, translates it into the input
expected by the corresponding function in
libyubihsm, calls that
function and then translates the result into the return value expected
The Connector is a component required by a YubiHSM 2 device that performs the communication between the device and applications using it.
A connector can be either an external process communicating over HTTP
http://localhost:12345), or directly linked in by
libyubihsm in the case of direct USB access.
The PKCS#11 module requires a configuration file containing the URL of
the Connector and other configuration options. The default location
for that file is the current directory and its default name is
yubihsm_pkcs11.conf. However, using the environment variable
YUBIHSM_PKCS11_CONF, one can point to a custom location and name.
Below is an example of a
This file will turn on debug messages for the PKCS#11 module
libdebug) and functions call tracing
A full list of the configuration options can be found on the developers website.
One of the possible parameters given to the PKCS#11
pReserved, can also be used to provide configuration
options to the module. While this is technically in violation of the
PKCS#11 specifications which requires that field to be set to
some application such as OpenSSL support this behavior.
An example of using this technique can be found on the developers website.
All interesting operations available through the PKCS#11 interface require a logged-in session. One peculiarity of the YubiHSM PKCS#11 module is that the user PIN MUST be prefixed with the ID (16 bits, in hexadecimal, zero padded if required) of the Authentication Key that should be used to perform the login operation.
For example, to use the default Authentication Key with ID
1 and password
password, the user PIN would then be
0001password. To be compliant with PKCS#11
standards, the Authentication Key password MUST be at least
8 characters long.
There are a number of settable attributes defined by PKCS#11 that do not accurately translate to YubiHSM 2 Capabilities and are therefore treated as always having a fixed value. A list of those attributes and their values can be found on the developers website.
Objects created via the PKCS#11 module inherit the Domains of the Authentication Key used to establish the session. The Domains can not be changed or modified via the PKCS#11 module.
A table mapping PKCS#11 objects to YubiHSM 2 Capabilities can be found on the developers website.
Not all PKCS#11 Object Types are implemented. A list of what is implemented is available here.
Code examples of how to use the PKCS#11 module from C programs can be found in the test link:tests/ecdh_derive_test.c
To derive an ECDH key using a public key in the file
peer.key and a
private key in the YubiHSM 2 with OpenSC
pkcs11-tool, the following
command can be used:
pkcs11-tool -vvv --module yubihsm_pkcs11.so --derive -i peer.key --id 64 --login --pin 0001password
The private key in YubiHSM 2 has Object ID
0x0064 and the public key
peer.key is expected to be in DER format. By default, this
command will expect to find a
yubihsm_pkcs11.conf file in the