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 that since pkcs11-tool can only perform
private key-based cryptographic operations - i.e., it can decrypt a ciphertext
or create a digital signature, but it can not 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
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
and 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 $
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 $
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 $
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 $
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 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 $
yhsm2-tool --pin xxxxxxxx --generate-random 64 | xxd -c 64 -p Using slot 0 with a present token (0x0) e3384c2a8f7263b46879d27d068779ebf82dfabe74bf057637a591a314dea86f12f35a79712950695dcbe54824eebe284430e942e1707991e315148e072d59f7 $
We would like to thank Uri Blumenthal (uri@mit.edu) for contributing to this document.