PKCS#11

The tdx Volt can be configured to use a PKCS#11-compliant hardware security module (HSM) to secure the tdx Volt key.

This page will describe the steps involved in using a YubiKey 5 hardware security module to secure the tdx Volt key.

This example uses the Personal Identity Verification (PIV) application on the YubiKey. PIV is a standard for smart cards used for secure authentication.

This document is intended as a quick-start guide. You should read the YubiKey documentation for more detailed information about how to securely configure your YubiKey.

Prerequisites

  • A YubiKey 5 hardware security module
  • The YubiKey PIN (the default is 123456)
  • The YubiKey management software (ykman) installed on your computer
  • You may also need to install the OpenSC software to enable PKCS#11 support, depending on your operating system

Installation

The YubiKey needs to be configured with a PIV key pair and a certificate. The key pair will be used to secure the tdx Volt key.

We will use the ykman command-line tool to create the key pair and configure the YubiKey. The ykman tool is available for Windows, macOS, and Linux, see the details here.

There is also a graphical user interface available for Windows and macOS, see Yubico website for more information.

Generate a key pair

The following command will generate a key pair on the YubiKey. The private key will be stored in slot 9a on the YubiKey, and the public key will be written to a file on the local file system called yubi-public.pem.

Slot 9a is typically used for the PIV authentication key, see the Appendix below for more information.

The following command will generate the key pair:

Terminal window
ykman piv keys generate 9a ./yubi-public.pem

We also need to generate a certificate for the key pair. The following command will generate a self-signed certificate and store it in the slot on the device. Replace the Alice with your own name or the subject of the certificate holder.

Terminal window
ykman piv certificates generate -s "CN=Alice" 9a ./yubi-public.pem

See the YubiKey documentation for full details of how to configure the key pair generation, including algorithm selection and key size etc.

Configure the tdx Volt

To create a tdx Volt that is secured by the YubiKey, you need to specify the PKCS#11 key strategy when creating the tdx Volt. See the Create a Volt page for more information.

Appendix

You will need to know the slot number of the PIV key pair on your YubiKey.

Slot 9a is typically used for the PIV authentication key. You can confirm that the key pair is available by running the pkcs11-tool command, which is part of the OpenSC software:

Terminal window
pkcs11-tool -v -O

You should see output similar to the following, look for the PIV AUTH pubkey label and note the ID field value:

Terminal window
Using slot 0 with a present token (0x0)
Public Key Object; RSA 2048 bits
  label:      PIV AUTH pubkey
  ID:         01
  Usage:      encrypt, verify, verifyRecover, wrap
  Access:     none

If this isn’t the case, you will need to use the slot number shown rather than 01 when configuring your tdx Volt.