.. piv-tool-tasks.rst .. _piv-tool-tasks: ===================== PIV Tool Common Tasks ===================== For a list of all available options ``--help`` can be given. For more information about what's happening ``--verbose`` can be added to any command. For much more information ``--verbose=2`` may be used. YubiKey Related Tasks ====================== Change the management key -------------------------- Change the management key used for administrative authentication: .. code:: yubico-piv-tool -aset-mgm-key See :ref:`set-mgm-key`. Display PIV tool version -------------------------- Display PIV tool version running on the YubiKey: .. code:: yubico-piv-tool -aversion See :ref:`version`. Generate a new private key ---------------------------- .. code-block:: yubico-piv-tool -k${key} -agenerate -s9c See :ref:`generate`. Generate a new ECC-P256 key ---------------------------- Generate a new ECC-P256 key on device in slot 9a and print the public key on stdout: .. code:: yubico-piv-tool -s9a -AECCP256 -agenerate See :ref:`generate`. Import a key into slot 85 -------------------------- Import a key into slot 85 and set the touch policy: Both options only available on YubiKey 4 and 5: .. code:: yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem See :ref:`import-key`. Reset PIN/PUK retry counter AND codes -------------------------------------- Default pin 123456 puk 12345678. .. code-block:: yubico-piv-tool -k${key} -averify -P${pin} -apin-retries --pin-retries=3 --puk-retries=3 See :ref:`verify-pin`. Reset the application after PIN/PUK modified ---------------------------------------------- PIN/PUK need to be blocked hence trying a couple of times — you need to modify this if you have changed the default number of PIN/PUK retries. .. code-block:: yubico-piv-tool -averify-pin -P471112 yubico-piv-tool -averify-pin -P471112 yubico-piv-tool -averify-pin -P471112 yubico-piv-tool -averify-pin -P471112 yubico-piv-tool -achange-puk -P471112 -N6756789 yubico-piv-tool -achange-puk -P471112 -N6756789 yubico-piv-tool -achange-puk -P471112 -N6756789 yubico-piv-tool -achange-puk -P471112 -N6756789 yubico-piv-tool -areset See :ref:`verify-pin`, :ref:`change-puk`, and :ref:`reset`. Run a signature test -------------------- Read out the certificate from a slot and then run a signature test: .. code:: yubico-piv-tool -aread-cert -s9a yubico-piv-tool -averify-pin -atest-signature -s9a See :ref:`read-cert` and :ref:`verify-pin`. Set a random chuid -------------------- Set a random `chuid`, import a key, and import a certificate from a PKCS12 file, into slot 9c: .. code:: yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key -aimport-cert See :ref:`set-chuid`, :ref:`import-key`, and :ref:`import-cert`. Set the touch policy --------------------- Import a key into slot 85 and set the touch policy: Both options only available on YubiKey 4 and 5 or newer: .. code:: yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem See :ref:`import-key` and :ref:`piv-tool-command-options`. Certificate Related Tasks ========================= Compress a large certificate ----------------------------- Import a large certificate and use ``yubico-piv-tool`` to apply GZIP compression. Compression is required for certificates larger than 2048 bytes in order to have fit: .. code:: yubico-piv-tool -s9c -icert.pem --compress -aimport-cert See :ref:`import-cert` and :ref:`generate`. Delete a certificate --------------------- Delete a certificate in slot 9a, with management key being asked for: .. code:: yubico-piv-tool -adelete-certificate -s9a -k See :ref:`delete-cert`. Generate a certificate request ------------------------------- Generate a certificate request with public key from stdin and print the resulting request on stdout: .. code:: yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest See :ref:`generate`. Generate a self-signed certificate ----------------------------------- Generate a self-signed certificate with public key from stdin and print the certificate, for later import on stdout: .. code:: yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify -aselfsign See :ref:`generate`. Import a certificate ---------------------- Import a certificate from stdin: .. code:: yubico-piv-tool -s9a -aimport-certificate See :ref:`import-cert` and :ref:`generate`. Import a large certificate --------------------------- Import a large certificate that requires compression. Certificates larger than 2048 bytes require compression in order to fit: .. code:: openssl x509 -in cert.pem -outform DER | gzip -9 > der.gz yubico-piv-tool -s9c -ider.gz -KGZIP -aimport-cert See :ref:`import-cert`. Import a large certificate --------------------------- Import a certificate which is larger than 2048 bytes and have the yubico-piv-tool do the GZIP compression in order to fit: .. code:: yubico-piv-tool -s9c -icert.pem --compress -aimport-cert See :ref:`import-cert`. Read out the certificate -------------------------- Read out the certificate from a slot and then run a signature test: .. code:: yubico-piv-tool -aread-cert -s9a yubico-piv-tool -averify-pin -atest-signature -s9a See :ref:`read-cert`, :ref:`verify-pin`, and :ref:`test-signature`. Show certificate information ------------------------------ Show some certificate information and some other data: .. code:: yubico-piv-tool -astatus See :ref:`status`.