YubiHSM AES Support (2.3+)


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.

manual-icon.svg 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: The data to be encrypted needs to be in blocks of 16, 24 or 32 bytes, depending on if you use a 128,192, or 256 bit AES key.

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