Beginning in YubiHSM firmware version 2.3, AES key generation, import, and encryption/decryption in ECB and CBC modes of operation are supported. AES keys can be 128, 192 , or 256 bits.
Note:
Not supported on the YubiHSM 2 FIPS, which is validated on firmware 2.2.
Encrypting, decrypting, and generating keys can be performed using yubihsm-shell (available as part of the YubiHSM 2 SDK), or most tools that support PKCS#11. This article covers how to use yubihsm-shell in interactive mode and non-interactive mode, and how to use PKCS#11 with pkcs11-tool to encrypt and decrypt data.
New capabilities
To control the use of AES keys in the YubiHSM, the following capabilities have been added in firmware 2.3:
| Name | Description |
| put-symmetric-key | Import Symmetric Keys |
| generate-symmetric-key | Generate Symmetric Keys |
| delete-symmetric-key | Delete Symmetric Keys |
| decrypt-ecb | Decrypt data in ECB mode |
| encrypt-ecb | Encrypt data in ECB mode |
| decrypt-cbc | Decrypt data in CBC mode |
| encrypt-cbc | Encrypt data in CBC mode |
New commands in the yubihsm-shell:
To use an AES key in the YubiHSM, the following commands have been added in the YubiHSM 2 SDK release version 2023.01:
| Command | Description |
| put symmetric | Import a Symmetric Key |
| generate symmetric | Generate a Symmetric Key on the HSM |
| decrypt aesecb | Decrypt data in ECB mode |
| decrypt aesecb | Encrypt data in ECB mode |
| decrypt aescbc | Decrypt data in CBC mode |
| decrypt aescbc | Encrypt data in CBC mode |
Support in the PKCS#11 Module
The following concepts have been added to the YubiHSM PKCS#11 module (beginning in the YubiHSM 2 SDK release version 2023.01) to support AES keys:
| Concept | Name | Description |
| Key type | CKK_AES | The type of key in CKO_SECRET_KEY objects |
| Mechanism | CKM_AES_KEY_GEN | Generate an AES key on the YubiHSM |
| CKM_AES_ECB | Encrypt/decrypt in ECB mode | |
| CKM_AES_CBC | Encrypt/decrypt in CBC mode | |
| CKM_AES_CBC_PAD | Encrypt/decrypt in CBC mode, automatically padding the plaintext using PKCS#7 padding |
YubiHSM-shell
Import Symmetric Keys
To import an existing AES key to the YubiHSM, use the put command and specify that it’s a symmetric key:
yubihsm> put symmetric 0 0 eas128_Imported all encrypt-cbc,decrypt-cbc aes128 f6b36e69cf4a23cab6d3f94d181b9364
Generate Symmetric Keys
To generate a symmetric key on the YubiHSM, use the generate command and specify that it’s a symmetric key, using either yubihsm-shell in interactive mode or non-interactive mode:
Using yubihsm-shell in interactive mode:
yubihsm> generate symmetric 0 0 eas128_Generated 1 encrypt-cbc:decrypt-cbc aes128
Using yubihsm-shell non-interactive mode:
yubihsm-shell -a generate-symmetric-key --label eas128_Generated --algorithm aes128 --capabilities encrypt-ecb,decrypt-ecb
Delete Symmetric Keys
To delete a symmetric key, use the delete command and specify that it’s a symmetric key:
yubihsm> delete 0 0xabbf symmetric-key
Encrypt/decrypt data
Encrypting and decrypting data can be performed using yubihsm-shell (available as part of the YubiHSM 2 SDK), or most tools that support PKCS#11. This example uses yubihsm-shell to encrypt and decrypt data:
Note:
Using yubihsm-shell in interactive mode:
yubihsm> encrypt aescbc 0 0xf9c8 78eb9b23accb4e06e45da7530d289820 "Hello YubiHSM!!!"
hKOYFC+stoTjBdUOHc84eg==
yubihsm> decrypt aescbc 0 0xf9c8 78eb9b23accb4e06e45da7530d289820 hKOYFC+stoTjBdUOHc84eg==
Hello YubiHSM!!!
Using yubihsm-shell in non-interactive mode:
yubihsm-shell -a encrypt-aesecb -i 0x39a9 -iv 78eb9b23accb4e06e45da7530d289820 --in Text.txt --out Text.bin
yubihsm-shell -a decrypt-aesecb -i 0x39a9 -iv 78eb9b23accb4e06e45da7530d289820 --in Text.bin
pkcs11-tool
Pkcs11-tool can be used to manage the data objects on the YubiHSM 2. Users can list and read PINs, keys and certificates stored on the YubiHSM 2. User PIN authentication is performed for operations that require it.
Note: Symmetric encryption was added to pkcs11-tool version 0.23.0.
Note: yubihsm_pkcs11 module has different file extensions depending on whether it is on Windows (.dll), MacOS (.dylib), or Linux (.so).
- Prerequisites for using pkcs11-tool are covered in Using OpenSC pkcs11-tool.
- To use the YubiHSM 2 with pkcs11-tool, a configuration file needs to be created and file has to be added to the computer's environment variables (most likely you have done this following previous setup of the YubiHSM 2). An example configuration file can be found under PKCS#11 Configuration in this document:
export YUBIHSM_PKCS11_CONF=”$(pwd)/yubihsm_pkcs11.conf”
export MODULE=/usr/lib/x86_64-linux-gnu/pkcs11/yubihsm_pkcs11.so
Generate AES keys
pkcs11-tool --module $MODULE --login --pin 0001password --keygen --key-type aes:16 --usage-decrypt --sensitive --private --extractable --label pkcs11_generated
Encrypting data
pkcs11-tool --module $MODULE --login --pin 0001password --encrypt --mechanism aes-cbc-pad --iv 78eb9b23accb4e06e45da7530d289820 --id 1f92 --input Text.txt --output Text.bin
Decrypting data
pkcs11-tool --module $MODULE --login --pin 0001password --decrypt --mechanism aes-cbc-pad --iv 78eb9b23accb4e06e45da7530d289820 --id 1f92 --input Text.bin --output Text2.txt