PKCS 11

PKCS#11 with YubiHSM 2

Configuration

The PKCS#11 module requires a configuration file, default location for this file is current directory and default name is yubihsm_pkcs11.conf using the environment variable YUBIHSM_PKCS11_CONF one can point to a custom location and name.

Configuration options can also be passed as a string in the pReserved field of C_Initialize, using the OpenSSL PKCS#11 engine this can be set in the INIT_ARGS configuration value. This is technically a violation of the PKCS#11 specification (which mandates pReserved to be set to NULL) and is not supported by all applications.

Accepted configuration options:

connector: URL pointing at the connector to contact, mandatory
debug: Turn on PKCS#11 debugging, default off
dinout: Turn on call tracing, default off
libdebug: Turn on debug of libyubihsm, default off
debug-file: File to write debug information to, default stderr
cacert: File with cacert to verify connector https cert with (not available on Windows)
proxy: Proxy server for reaching the connector (not available on Windows)
timeout: Timeout to use for initial connection to the connector (in seconds), default 5

A sample configuration file can be found further below.

Logging In

All interesting operations through the PKCS#11 interface require a logged-in session, and one peculiarity of the PKCS#11 interface is that the user PIN MUST be prefixed by the ID (16 bits, in hexadecimal, zero padded if required) of the corresponding Authentication Key.

Assuming 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.

Note that the concept of a Security Officer (SO) is not supported by the device, and the PIN management functions are not implemented for neither user nor SO.

It is recommended that PIN (Authentication Key) management is performed via the yubihsm-shell utility or the libyubihsm functions.

PKCS#11 on Windows

After installing yubihsm-shell using the windows installer, in addition to setting YUBIHSM_PKCS11_CONF environment variable, the YubiHSM Shell\bin directory needs to be added to the system path in order for other applications to be able to load it. This is because the yubihsm-pkcs11.dll is dynamically linked to the libyubihsm*.dll and libcrypto-1_1.dll libraries and they need to be accessible for the PKCS#11 module to be useful.

On Windows 10, setting the system path is done by following these steps:

1- Go to Control Panel → System and Security → System → Advanced system setting

2- Click “Environment Variables…“

3- Under System Variables, highlight “Path“ and click “Edit…“

4- Click “New“ and add the absolute path to YubiHSM Shell/bin

5- Under System Variables, click “New“ and add the environment variable YUBIHSM_PKCS11_CONF and set it to the path to the YubiHSM2 PKCS11 configuration file

If setting the system path is not desirable, the libyubihsm*.dll and libcrypto-1_1.dll can be copied into the same directory as the application that needs to access the PKCS#11 module.

A Note for Developers

If LoadLibrary is called with an absolute path, it will not look for dependencies of the specified DLL in that directory, but rather in the startup directory of the application that calls LoadLibrary. The solution is to either:

Call LoadLibraryEx with the flag LOAD_WITH_ALTERED_SEARCH_PATH for absolute paths
Add the directory where the PKCS#11 module is located to the system PATH
Or copy the dependencies into the application directory.

Please note that calling LoadLibraryEx with that flag for a non-absolute path is undefined behavior according to MS docs. For example, the way Pkcs11Interop does it is to set a variable to LOAD_WITH_ALTERED_SEARCH_PATH if the path looks absolute, and 0 otherwise; and then always calling LoadLibraryEx. If the flags is 0 then LoadLibraryEx behaves exactly like LoadLibrary.

PKCS#11 with JAVA

Due to design and implementation choices, there are some peculiarities when generating or importing keys into the YubiHSM 2 using SunPKCS#11 provider and YubiHSM 2 PKCS#11 module. JAVA SunPKCS#11 provider requires the ability to change a key’s properties after creation in order for it to be able to use the keys later on. However, YubiHSM 2 does not allow such operation (All key properties have to be set at the time of creation and cannot be changed after the fact). The key information here is that the asymmetric key and its corresponding X509Certificate need to be accessed via the same ID on the device. Later versions of YubiHSM 2 PKCS#11 module provide a way to achieve this via the use of Meta Objects, but it could be worth it to make sure that this requirement is met manually, especially if the number of objects created on the YubiHSM 2 needs to be limited.

Version 2.4.0 or later

In version 2.4.0, the use of Meta Objects is introduced. Meta Objects are opaque objects with algorithm opaque-data that store the values of CKA_ID and CKA_LABEL attributes of another object on the YubiHSM 2, thus working around the hard limit on the length of those values and the inability to change those attributes after the fact. The label of a Meta Object is always Meta object for followed by a HEX value representing the ID, type and sequence of the actual object it is tied to (referred to as an Original Object).

Meta Objects are created as needed when the function to create an object is called with CKA_ID and/or CKA_LABEL values that are longer than 2 and 40 bytes respectively, or when the function to change one of those values is called. Meta Objects store these values as unencrypted raw data. When an Original Object is deleted, its corresponding Meta Object is also deleted automatically.

Meta Objects are only used within PKCS#11 context and their existence and use are invisible to PKCS#11 clients or users. They are, however, visible to yubihsm-shell users.

Version 2.3.2 or earlier

When using SunPKCS11 provider, it’s important to know that generating asymmetric keys using C_GenerateKeyPair will not work. In order for SunPKCS11 to be able to use asymmetric keys on the YubiHSM2 device, both the asymmetric key and its X509Certificate must be stored under the same ObjectID. Once an asymmetric key and its X509Certificate are stored in the YubiHSM 2 under the same ObjectID, there is no problem whatsoever to use and manage the key using PKCS#11, including deleting it.

To generate asymmetric keys on the YubiHSM 2 so that they are accessible by SunPKCS11 provider, either yubihsm-setup or yubihsm-shell can be used.

yubihsm-setup

Use the subcommand ejbca to generate an asymmetric key on the YubiHSM2 and store it and its X509Certificate under the same ObjectID

yubihsm-setup -d ejbca

yubihsm-shell

Using yubihsm-shell, the attestation functionality can be leveraged to produce a self-signed X509Certificate that can then be imported using the same ObjectID as the generated asymmetric key.

Generate asymmetric key and note its ObjectID
yubihsm-shell -a generate-asymmetric-key -i <KEY_OBJECT_ID> -l <OBJECT_LABEL> -d <OBJECT_DOMAINS> -c <KEY_CAPABILITIES> -A <KEY_ALGORITHM>

Sign an attestation certificate for the generated key using the YubiHSM attestation key (with ObjectID=0)
yubihsm-shell -a sign-attestation-certificate -i <KEY_OBJECT_ID> --attestation-id 0 --out cert.pem

Import the attestation certificate to use it as a template when signing the self-signed certificate. Use the same ObjectID as the generated key
yubihsm-shell -a put-opaque -i <KEY_OBJECT_ID> -l <OBJECT_LABEL> -A opaque-x509-certificate --informat=PEM --in cert.pem

Sign an attestation certificate for the generated key using the generated key itself
yubihsm-shell -a sign-attestation-certificate -i <KEY_OBJECT_ID> --attestation-id=<KEY_OBJECT_ID> --out selfsigned_cert.pem

Delete the template certificate to make room for the self-signed certificate to be imported
yubihsm-shell -a delete-object -i <KEY_OBJECT_ID> -t opaque

Import the self-signed certificate using the same ObjectID as the generated key
yubihsm-shell -a put-opaque -i <KEY_OBJECT_ID> -l <OBJECT_LABEL> -A opaque-x509-certificate --informat=PEM --in selfsigned_cert.pem

Note that if a YubiHSM 2 device does not come with an attestation key with ObjectID 0, any other asymmetric key can be used instead. Since the whole purpose of signing the first attestation certificate is to produce an X509Certificate to use as a template, any X509Certificate with the desired attributes present can be used as a template instead.

Also note that when using a key for signing an attestation certificate, the signing key’s capabilities must include sign-attestation-certificate.

Software Operations

C_Encrypt and C_Verify for Asymmetric Keys are performed in software, as well as all of the C_Digest operations.

PKCS#11 Attributes

There are a number of attributes defined in PKCS#11 that do not translate to Capabilities of the YubiHSM 2 device, and are therefore treated as always having a fixed value.

PKCS#11	YubiHSM 2	Rationale
CKA_PRIVATE	CK_TRUE	Login is always required
CKA_DESTROYABLE	CK_TRUE	Objects can always be deleted from the device
CKA_MODIFIABLE	CK_FALSE	Objects are immutable on the device
CKA_COPYABLE	CK_FALSE	Objects are immutable on the device
CKA_SENSITIVE	CK_TRUE	All objects are sensitive
CKA_ALWAYS_SENSITIVE	CK_TRUE	Objects are immutable on the device

Capabilities and Domains

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 module.

Object Capabilities are set on creation, depending on their Type, e.g. an RSA signing key (CKK_RSA) created via C_CreateObject with the attribute CKA_SIGN set will have the following Capabilities set sign-pkcs,sign-pss.

Similarly for EC (CKK_EC), the key would have sign-ecdsa set.

See the following tables for mappings:

PKCS#11	RSA (CKK_RSA)	EC (CKK_EC)	Wrap (CKK_YUBICO_AES*_CCM_WRAP)	HMAC (CKK_SHA*_HMAC)
CKA_SIGN	sign-pkcs,sign-pss	sign-ecdsa	N/A	sign-hmac
CKA_VERIFY	N/A	N/A	N/A	verify-hmac
CKA_ENCRYPT	N/A	N/A	wrap-data	N/A
CKA_DECRYPT	decrypt-pkcs,decrypt-oaep	N/A	unwrap-data	N/A
CKA_DERIVE	N/A	derive-ecdh	N/A	N/A
CKA_WRAP	N/A	N/A	export-wrapped	N/A
CKA_UNWRAP	N/A	N/A	import-wrapped	N/A
CKA_EXTRACTABLE	export-under-wrap	export-under-wrap	export-under-wrap	export-under-wrap

PKCS#11 Objects

Not all PKCS#11 Object types are implemented, this is a list of what is implemented and what it maps to.

PKCS#11	Supported CKK	Comment
CKO_PRIVATE_KEY	CKK_RSA, CKK_EC	RSA 2048, 3072 & 4096 with e=0x10001, EC with secp224r1, secp256r1, secp384r1, secp521r1, secp256k1, brainpool256r1, brainpool384r1, brainpool512r1
CKO_PUBLIC_KEY		does not exist in device, only as a property of a private key
CKO_SECRET_KEY	CKK_SHA_1_HMAC, CKK_SHA256_HMAC, CKK_SHA384_HMAC, CKK_SHA512_HMAC, CKK_YUBICO_AES128_CCM_WRAP, CKK_YUBICO_AES192_CCM_WRAP, CKK_YUBICO_AES256_CCM_WRAP
CKO_CERTIFICATE		Opaque object with algorithm YH_ALGO_OPAQUE_X509_CERTIFICATE
CKO_DATA		Opaque object with algorithm YH_ALGO_OPAQUE_DATA

PKCS#11 Functions

Not all functions in PKCS#11 are implemented in the module, this is a list of what is implemented.

PKCS#11	Comment
C_Initialize
C_Finalize
C_GetInfo
C_GetFunctionList
C_GetSlotList
C_GetSlotInfo
C_GetTokenInfo
C_GetMechanismList
C_GetMechanismInfo
C_OpenSession
C_CloseSession
C_CloseAllSessions
C_GetSessionInfo
C_Login
C_Logout
C_CreateObject	with CKO_PRIVATE_KEY, CKO_SECRET_KEY, CKO_CERTIFICATE or CKO_DATA
C_DestroyObject
C_GetObjectSize
C_GetAttributeValue
C_FindObjectsInit
C_FindObjects
C_FindObjectsFinal
C_EncryptInit	Encrypt with Wrap Key or do software encryption for RSA key
C_Encrypt
C_EncryptUpdate
C_EncryptFinal
C_DecryptInit	Decrypt with Wrap Key or RSA key
C_Decrypt
C_DecryptUpdate
C_DecryptFinal
C_DeriveKey	Derive key using ECDH as a PKCS#11 session object
C_DigestInit	Do software digest with CKM_SHA_1, CKM_SHA256, CKM_SHA384 or CKM_SHA512
C_Digest
C_DigestUpdate
C_DigestFinal
C_SignInit	Sign with HMAC Key or Asymmetric Key
C_Sign
C_SignUpdate
C_SignFinal
C_VerifyInit	Verify HMAC or software verify asymmetric
C_Verify
C_VerifyUpdate
C_VerifyFinal
C_GenerateKey	Generate HMAC Key or Wrap Key
C_GenerateKeyPair	Generate Asymmetric Key
C_WrapKey	Wrap an object with Wrap Key
C_UnwrapKey	Unwrap an object with Wrap Key
C_GenerateRandom	Generate up to 2021 bytes of random

PKCS#11 Vendor Definitions

Working with the device Wrap Keys requires using vendor-specific definitions, these are listed in the table below. The Wrap Keys can be used with C_WrapKey, C_Unwrapkey, C_Encrypt & C_Decrypt.

CKM_YUBICO_AES_CCM_WRAP	0xd9554204
CKK_YUBICO_AES128_CCM_WRAP	0xd955421d
CKK_YUBICO_AES192_CCM_WRAP	0xd9554229
CKK_YUBICO_AES256_CCM_WRAP	0xd955422a

PKCS#11 Configuration

Configuration File Sample

Below is a sample of a yubihsm_pkcs11.conf configuration file.

# This is a sample configuration file for the YubiHSM PKCS#11 module
# Uncomment the various options as needed

# URL of the connector to use. This can be a comma-separated list
connector = http://127.0.0.1:12345

# Enables general debug output in the module
#
# debug

# Enables function tracing (ingress/egress) debug output in the module
#
# dinout

# Enables libyubihsm debug output in the module
#
# libdebug

# Redirects the debug output to a specific file. The file is created
# if it does not exist. The content is appended
#
# debug-file = /tmp/yubihsm_pkcs11_debug

# CA certificate to use for HTTPS validation. Point this variable to
# a file containing one or more certificates to use when verifying
# a peer. Currently not supported on Windows
#
# cacert = /tmp/cacert.pem

# Proxy server to use for the connector
# Currently not supported on Windows
#
# proxy = http://proxyserver.local.com:8080

# Timeout in seconds to use for the initial connection to the connector
# timeout = 5

INIT_ARGS Sample

Below is a sample of using the INIT_ARGS configuration with an openssl.cnf file.

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /path/to/engine_pkcs11.so
MODULE_PATH = /path/to/yubihsm_pkcs11.so
INIT_ARGS = connector=http://127.0.0.1:12345 debug
init = 0

Note	OpenSSL 1.1 will auto-load modules present in the system engine directory (like `/usr/lib/x86_64-linux-gnu/engines-1.1`) so the `dynamic_path` line has to be dropped there. The error shown will mention "conflicting engine id".