.. hsm2-opensc-pkcs11.rst .. _hsm2-opensc-pkcs11-label: ========================== 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: .. code-block:: bash 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 ). * ``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. .. code-block:: bash $ 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). .. code-block:: bash $ 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. .. code-block:: bash $ 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. .. code-block:: bash $ 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. .. code-block:: bash $ 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). .. code-block:: bash $ 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. .. code-block:: bash $ 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 ---------------------- .. code-block:: bash $ yhsm2-tool --pin xxxxxxxx --generate-random 64 | xxd -c 64 -p Using slot 0 with a present token (0x0) e3384c2a8f7263b46879d27d068779ebf82dfabe74bf057637a591a314dea86f12f35a 79712950695dcbe54824eebe284430e942e1707991e315148e072d59f7