Using OpenSC pkcs11-tool

It may be convenient to define a shell-level alias for the pkcs11-tool --module ... command. It may also be convenient to add the environment variable to point at the yubihsm_pkcs11.so library.

To accomplish all of the above for the Bash shell one would add the following lines to the ~/.bash_profile or ~/.bashrc file:

export YUBIHSM_PKCS11_CONF=/path/to/user/home/yhsm2-p11.conf
export YUBIHSM_PKCS11_MODULE=/usr/local/lib/yubihsm_pkcs11.so
alias yhsm2-tool='pkcs11-tool --module ${YUBIHSM_PKCS11_MODULE} --login'

The --login option was added because practically no operation of the HSM device can be performed without logging in to it first.

Assuming that

  • RSA signing/verifying keypair has been generated with id 0x0401 and capabilities including asymmetric_sign_pkcs:asymmetric_sign_pss;
  • RSA encrypting/decrypting keypair has been generated with id 0x0402 and capabilities including asymmetric_decrypt_pkcs:asymmetric_decrypt_oaep;
  • ECDSA signing/verifying keypair has been generated with id 0x0203 and capabilities including asymmetric_sign_ecdsa:asymmetric_sign_decdsa;
  • EC keypair for deriving ECDH keys has been generated with id 0x0204 and capabilities including derive-ecdh;

The following commands illustrate the use of OpenSC pkcs11-tool with YubiHSM for cryptographic operations.

Note

The pkcs11-tool can only perform private key-based cryptographic operations. It can decrypt a ciphertext or create a digital signature, but it cannot encrypt a plaintext or verify a digital signature - OpenSSL is used to accomplish that.

The following files are used as samples:

  • t32.dat is a binary file containing 32 bytes;
  • t3200.dat is a binary file containing 3200 bytes;
  • t64.txt is a text file containing 65 bytes (64 ASCII characters and <CR>).
  • peer_key.der is a file containing an EC public key in DER format

Creating Digital Signatures

Examples how to create digital signature.

RSA-PSS

Step 1:

Sign a file using RSA-PSS padding with SHA-384.

$ yhsm2-tool --sign -m SHA384-RSA-PKCS-PSS --id 0401 -i
  t3200.dat -o t3200.dat.sig-pss
Using slot 0 with a present token (0x0)
Logging in to "YubiHSM".
Please enter User PIN:
Using signature algorithm SHA384-RSA-PKCS-PSS
PSS parameters: hashAlg=SHA384, mgf=MGF1-SHA384, salt_len=48
Step 2:

Verify the created signature with OpenSSL (with libp11 PKCS#11 engine installed).

$ openssl dgst -engine pkcs11 -keyform engine -verify
 "pkcs11:token=YubiHSM;id=%04%01;type=public" -signature
 t3200.dat.sig-pss -sigopt rsa_padding_mode:pss -sha384
 t3200.dat
engine "pkcs11" set.
Enter PKCS#11 token PIN for YubiHSM:
Verified OK

RSA-PKCS#1 v1.5

Sign a file using RSA-PKCS#1 v1.5 padding.

$ yhsm2-tool --sign --id 0401 -m SHA384-RSA-PKCS -i t3200.dat -o t3200.pkcs1.sig
Using slot 0 with a present token (0x0)
Logging in to "YubiHSM".
Please enter User PIN:
Using signature algorithm SHA384-RSA-PKCS

$ openssl dgst -engine pkcs11 -keyform engine -verify
   "pkcs11:token=YubiHSM;id=%04%01;type=public" -signature
   t3200.pkcs1.sig -sha384 t3200.dat
engine "pkcs11" set.
Enter PKCS#11 token PIN for YubiHSM:
Verified OK

ECDSA

Sign a file using ECDSA with SHA-384 hash.

$ yhsm2-tool --sign --id 0203 -m ECDSA-SHA384 -f openssl -i t3200.dat
  -o t3200.ec384.sig2
Using slot 0 with a present token (0x0)
Logging in to "YubiHSM".
Please enter User PIN:
Using signature algorithm ECDSA-SHA384

$ openssl dgst -engine pkcs11 -keyform engine -verify
  "pkcs11:token=YubiHSM;id=%02%03;type=public" -signature
  t3200.ec384.sig2 -sha384 t3200.dat
engine "pkcs11" set.
Enter PKCS#11 token PIN for YubiHSM:
Verified OK

Performing Decryption

Examples how to run decryption.

RSA-PKCS#1 v1.5

Decrypt a file using RSA-PKCS#1 v1.5 padding.

$ cat t64.txt
 4aa58c448f3264c777be1b5ad94cf3e0a68911ed3f18db9e568ff2179e263f76

$ yhsm2-tool --decrypt --id 0402 -m RSA-PKCS -i t64.txt.pkcs1
 Using slot 0 with a present token (0x0)
 Logging in to "YubiHSM".
 Please enter User PIN:
 Using decrypt algorithm RSA-PKCS
 4aa58c448f3264c777be1b5ad94cf3e0a68911ed3f18db9e568ff2179e263f76

RSA-OAEP

Decrypt a file using RSA-OAEP and SHA-384. The file t64.txt was encrypted with RSA-OAEP using SHA-384 for digest and Mask Generation Function (MGF).

$ cat t64.txt
 4aa58c448f3264c777be1b5ad94cf3e0a68911ed3f18db9e568ff2179e263f76

$ yhsm2-tool --decrypt --id 0402 -m RSA-PKCS-OAEP --hash-algorithm
  SHA384 --mgf MGF1-SHA384 -i t64.txt.oaep
Using slot 0 with a present token (0x0)
Logging in to "YubiHSM".
Please enter User PIN:
Using decrypt algorithm RSA-PKCS-OAEP
OAEP parameters: hashAlg=SHA384, mgf=MGF1-SHA384, source_type=0,
  source_ptr=0x0, source_len=0
4aa58c448f3264c777be1b5ad94cf3e0a68911ed3f18db9e568ff2179e263f76

$ yhsm2-tool --decrypt --id 0402 -m RSA-PKCS-OAEP --hash-algorithm
  SHA384 -i t64.txt.oaep
Using slot 0 with a present token (0x0)
Logging in to "YubiHSM".
Please enter User PIN:
Using decrypt algorithm RSA-PKCS-OAEP
OAEP parameters: hashAlg=SHA384, mgf=MGF1-SHA384, source_type=0, source_ptr=0x0, source_len=0
4aa58c448f3264c777be1b5ad94cf3e0a68911ed3f18db9e568ff2179e263f76

Derive ECDH Key

Derive an ECDH key using a private key on the YubiHSM and a public key read from a file.

$ yhsm2-tool --derive --input-file peer_key.der --id 0204
 Logging in to "YubiHSM".
Please enter User PIN:
Using slot 0 with a present token (0x0)
Using derive algorithm 0x00001050 ECDH1-DERIVE
34a03079c38947a679a924f3e20657cd4f69dd36df395b7e759e727524da87dc

Obtaining Random Data

$ yhsm2-tool --pin xxxxxxxx --generate-random 64 | xxd -c 64 -p
 Using slot 0 with a present token (0x0)
 e3384c2a8f7263b46879d27d068779ebf82dfabe74bf057637a591a314dea86f12f35a
 79712950695dcbe54824eebe284430e942e1707991e315148e072d59f7