.. PIV_Commands.rst .. _piv-commands-label: ============ PIV Commands ============ Acronyms and their definitions are listed at the bottom of the :ref:`base-commands-label` page. ykman piv [OPTIONS] COMMAND [ARGS]... ===================================== Manage the PIV Application. Examples -------- **Generate** an ECC P-256 private key and a self-signed certificate in slot 9a: .. code-block:: $ ykman piv keys generate --algorithm ECCP256 9a pubkey.pem $ ykman piv certificates generate --subject "yubico" 9a pubkey.pem **Change the PIN** from 123456 to 654321: .. code-block:: $ ykman piv access change-pin --pin 123456 --new-pin 654321 **Reset all PIV data** and restore default settings: .. code-block:: $ ykman piv reset Options ------- .. table:: +-----------------------+---------------------------------------------------+ | Option | Description | +=======================+===================================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------+---------------------------------------------------+ Commands -------- .. table:: +-------------------+-------------------------------------------------------+ | Command | Description | +===================+=======================================================+ | ``access`` | Manage PIN, PUK and Management Key. | +-------------------+-------------------------------------------------------+ | ``certificates`` | Manage certificates. | +-------------------+-------------------------------------------------------+ | ``info`` | Display general status of the PIV application. | +-------------------+-------------------------------------------------------+ | ``keys`` | Manage private keys. | +-------------------+-------------------------------------------------------+ | ``objects`` | Manage PIV data objects. | +-------------------+-------------------------------------------------------+ | ``reset`` | Reset all PIV data. | +-------------------+-------------------------------------------------------+ ykman piv access [OPTIONS] COMMAND [ARGS]... ============================================ Manage PIN, PUK, and Management Key. Options ------- .. table:: +-----------------------+---------------------------------------------------+ | Option | Description | +=======================+===================================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------+---------------------------------------------------+ Commands -------- .. table:: +---------------------------+-----------------------------------------------+ | Command | Description | +===========================+===============================================+ | ``change-management-key`` | Change the management key. | +---------------------------+-----------------------------------------------+ | ``change-pin`` | Change the PIN code. | +---------------------------+-----------------------------------------------+ | ``change-puk`` | Change the PUK code. | +---------------------------+-----------------------------------------------+ | ``set-retries`` | Set the number of PIN and PUK retry attempts. | +---------------------------+-----------------------------------------------+ | ``unblock-pin`` | Unblock the PIN (using PUK). | +---------------------------+-----------------------------------------------+ ykman piv access change-management-key [OPTIONS] ================================================ Change the management key. Management functionality is guarded by a management key. This key is required for administrative tasks, such as generating key pairs. A random key may be generated and stored on the YubiKey, protected by PIN. Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ || ``-a, --algorithm [TDES|`` || Management key algorithm. | || ``AES128|AES192|AES256]`` || [Default: ``TDES``] | +-----------------------------------+---------------------------------------+ | ``-f, --force`` | Confirm the action without prompting. | +-----------------------------------+---------------------------------------+ | ``-g, --generate`` || Generate a random management key. | | || Implied by ``--protect`` unless | | || ``--new-management-key`` is also | | || given. Conflicts with | | || ``--new-management-key``. | +-----------------------------------+---------------------------------------+ | ``-m, --management-key TEXT`` | Current management key. | +-----------------------------------+---------------------------------------+ | ``-n, --new-management-key TEXT`` | A new management key. | +-----------------------------------+---------------------------------------+ | ``-p, --protect`` || Store new management key on the | | || YubiKey, protected by PIN. A random | | || key is used if no key is provided. | +-----------------------------------+---------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +-----------------------------------+---------------------------------------+ | ``-t, --touch`` || Require touch on YubiKey when | | || prompted for management key. | +-----------------------------------+---------------------------------------+ ykman piv access change-pin [OPTIONS] ===================================== Change the PIN code. The PIN must be between 6 and 8 characters long, and it can be any type of alphanumeric character. For cross-platform compatibility, numeric PINs are recommended. Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-n, --new-pin TEXT`` | A new PIN. | +-----------------------------------+---------------------------------------+ | ``-P, --pin TEXT`` | Current PIN code. | +-----------------------------------+---------------------------------------+ ykman piv access change-puk [OPTIONS] ===================================== Change the PUK code. If the PIN is lost or blocked it can be reset using a PUK. The PUK must be between 6 and 8 characters long, and it can be any type of alphanumeric character. Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-n, --new-puk TEXT`` | A new PUK code. | +-----------------------------------+---------------------------------------+ | ``-p, --puk TEXT`` | Current PUK code. | +-----------------------------------+---------------------------------------+ ykman piv access set-retries [OPTIONS] PIN-RETRIES PUK-RETRIES ============================================================== Set the number of PIN and PUK retry attempts. .. NOTE:: This resets the PIN and PUK to their factory defaults. Arguments ---------- .. table:: +-----------------+---------------------------------------------------------+ | Argument | Description | +=================+=========================================================+ | ``PIN-RETRIES`` | Set number of retries for PIN attempts. | +-----------------+---------------------------------------------------------+ | ``PUK-RETRIES`` | Set number of retries for PUK attempts. | +-----------------+---------------------------------------------------------+ Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-f, --force`` | Confirm the action without prompting. | +-----------------------------------+---------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +-----------------------------------+---------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +-----------------------------------+---------------------------------------+ ykman piv access unblock-pin [OPTIONS] ====================================== Unblock the PIN (using PUK). Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-n, --new-pin NEW-PIN`` | A new PIN code. | +-----------------------------------+---------------------------------------+ | ``-p, --puk TEXT`` | Current PUK code. | +-----------------------------------+---------------------------------------+ ykman piv certificates [OPTIONS] COMMAND [ARGS]... ================================================== Manage certificates. Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ Commands -------- .. table:: +--------------+------------------------------------------------------------+ | Option | Description | +==============+============================================================+ | ``delete`` | Delete a certificate. | +--------------+------------------------------------------------------------+ | ``export`` | Export an X.509 certificate. | +--------------+------------------------------------------------------------+ | ``generate`` | Generate a self-signed X.509 certificate. | +--------------+------------------------------------------------------------+ | ``import`` | Import an X.509 certificate. | +--------------+------------------------------------------------------------+ | ``request`` | Generate a Certificate Signing Request (CSR). | +--------------+------------------------------------------------------------+ ykman piv certificates delete [OPTIONS] SLOT ============================================ Delete a certificate. Delete a certificate from a PIV slot on the YubiKey. Arguments --------- .. table:: +-----------------------------------+---------------------------------------+ | Argument | Description | +===================================+=======================================+ | ``SLOT`` | PIV slot of the certificate. | +-----------------------------------+---------------------------------------+ Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +-----------------------------------+---------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +-----------------------------------+---------------------------------------+ ykman piv certificates export [OPTIONS] SLOT CERTIFICATE ======================================================== Export an X.509 certificate. Reads a certificate from one of the PIV slots on the YubiKey. Arguments --------- .. table:: +-----------------+---------------------------------------------------------+ | Argument | Description | +=================+=========================================================+ | ``SLOT`` | PIV slot of the certificate. | +-----------------+---------------------------------------------------------+ | ``CERTIFICATE`` || File to write certificate to. Use ``'-'`` to | | || use ``stdout``. | +-----------------+---------------------------------------------------------+ Options ------- .. table:: +-----------------------------------+---------------------------------------+ | Option | Description | +===================================+=======================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------------------+---------------------------------------+ | ``-F, --format [PEM|DER]`` | Encoding format. [Default: ``PEM``] | +-----------------------------------+---------------------------------------+ ykman piv certificates generate [OPTIONS] SLOT PUBLIC-KEY ========================================================= Generate a self-signed X.509 certificate. A self-signed certificate is generated and written to one of the slots on the YubiKey. A private key must already be present in the corresponding key slot. Arguments --------- .. table:: +-----------------+---------------------------------------------------------+ | Argument | Description | +=================+=========================================================+ | ``SLOT`` | PIV slot of the certificate. | +-----------------+---------------------------------------------------------+ | ``PUBLIC-KEY`` || File containing a public key. Use ``'-'`` to use | | || ``stdin``. | +-----------------+---------------------------------------------------------+ Options ------- .. table:: +----------------------------------+----------------------------------------+ | Option | Description | +==================================+========================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------------+----------------------------------------+ || ``-a, --hash-algorithm`` | Hash algorithm. [default: SHA256] | || ``[SHA1|SHA256|SHA384|SHA512]`` | | +----------------------------------+----------------------------------------+ | ``-d, --valid-days INTEGER`` || Number of days until the certificate | | || expires. [Default: ``365``] | +----------------------------------+----------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +----------------------------------+----------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +----------------------------------+----------------------------------------+ | ``-s, --subject TEXT`` || Subject for the certificate, as an | | || RFC 4514 string. [required]. | +----------------------------------+----------------------------------------+ ykman piv certificates import [OPTIONS] SLOT CERTIFICATE ======================================================== Import an X.509 certificate. Write a certificate to one of the PIV slots on the YubiKey. Arguments --------- .. table:: +-----------------+---------------------------------------------------------+ | Argument | Description | +=================+=========================================================+ | ``SLOT`` | PIV slot of the certificate. | +-----------------+---------------------------------------------------------+ | ``CERTIFICATE`` || File containing the certificate. Use ``'-'`` to | | || use ``stdin``. | +-----------------+---------------------------------------------------------+ Options ------- .. table:: +-------------------------------+-------------------------------------------+ | Option | Description | +===============================+===========================================+ | ``-h, --help`` | Show this message and exit. | +-------------------------------+-------------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +-------------------------------+-------------------------------------------+ | ``-p, --password TEXT`` || A password may be needed to decrypt | | || the data. | +-------------------------------+-------------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +-------------------------------+-------------------------------------------+ | ``-v, --verify`` || Verify that the certificate matches the | | || private key in the slot. | +-------------------------------+-------------------------------------------+ ykman piv certificates request [OPTIONS] SLOT PUBLIC-KEY CSR ============================================================ Generate a Certificate Signing Request (CSR). A private key must already be present in the corresponding key slot. Arguments --------- .. table:: +----------------+----------------------------------------------------------+ | Argument | Description | +================+==========================================================+ | ``CSR`` | File to write CSR to. Use ``'-'`` to use ``stdout``. | +----------------+----------------------------------------------------------+ | ``PUBLIC-KEY`` || File containing a public key. Use ``'-'`` to use | | || ``stdin``. | +----------------+----------------------------------------------------------+ | ``SLOT`` | PIV slot of the certificate. | +----------------+----------------------------------------------------------+ Options ------- .. table:: +----------------------------------+----------------------------------------+ | Option | Description | +==================================+========================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------------+----------------------------------------+ || ``-a, --hash-algorithm`` | Hash algorithm. [default: SHA256] | || ``[SHA1|SHA256|SHA384|SHA512]`` | | +----------------------------------+----------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +----------------------------------+----------------------------------------+ | ``-s, --subject TEXT`` || Subject for the requested certificate,| | || as an RFC 4514 string. [Required] | +----------------------------------+----------------------------------------+ ykman piv info [OPTIONS] ======================== Display general status of PIV application. Options ------- .. table:: +-----------------------+---------------------------------------------------+ | Option | Description | +=======================+===================================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------+---------------------------------------------------+ ykman piv keys [OPTIONS] COMMAND [ARGS]... ========================================== Manage private keys. Options ------- .. table:: +-----------------------+---------------------------------------------------+ | Option | Description | +=======================+===================================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------+---------------------------------------------------+ Commands -------- .. table:: +---------------+-----------------------------------------------------------+ | Command | Description | +===============+===========================================================+ | ``attest`` | Generate an attestation certificate for a key pair. | +---------------+-----------------------------------------------------------+ | ``export`` | Export a public key corresponding to a stored private key.| +---------------+-----------------------------------------------------------+ | ``generate`` | Generate an asymmetric key pair. | +---------------+-----------------------------------------------------------+ | ``import`` | Import a private key from file. | +---------------+-----------------------------------------------------------+ ykman piv keys attest [OPTIONS] SLOT CERTIFICATE ================================================ Generate an attestation certificate for a key pair. Attestation is used to show that an asymmetric key was generated on the YubiKey and therefore doesn't exist outside the device. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``CERTIFICATE`` || File to write attestation certificate to. Use ``'-'`` | | || to use ``stdout``. | +------------------+--------------------------------------------------------+ | ``SLOT`` | PIV slot of the private key. | +------------------+--------------------------------------------------------+ Options ------- .. table:: +----------------------------+----------------------------------------------+ | Option | Description | +============================+==============================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------+----------------------------------------------+ | ``-F, --format [PEM|DER]`` | Encoding format. [Default: ``PEM``] | +----------------------------+----------------------------------------------+ ykman piv keys export [OPTIONS] SLOT PUBLIC-KEY ================================================ Export a public key corresponding to a stored private key. This command uses several different mechanisms for exporting the public key corresponding to a stored private key, which may fail. If a certificate is stored in the slot it is assumed to contain the correct public key. If this is not the case, the wrong public key will be returned. The ``--verify`` flag can be used to verify that the public key being returned matches the private key, by using the slot to create and verify a signature. This may require the PIN to be provided. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``PUBLIC-KEY`` || File containing the generated public key. Use ``-`` to| | || use ``stdout``. | +------------------+--------------------------------------------------------+ | ``SLOT`` | PIV slot of the private key. | +------------------+--------------------------------------------------------+ Options ------- .. table:: +----------------------------+----------------------------------------------+ | Option | Description | +============================+==============================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------+----------------------------------------------+ | ``-F, --format [PEM|DER]`` | Encoding format. [default: ``PEM``] | +----------------------------+----------------------------------------------+ | ``-P, --pin TEXT`` | PIN code (used for ``--verify``). | +----------------------------+----------------------------------------------+ | ``-v, --verify`` || Verify that the public key matches the | | || private key in the slot. | +----------------------------+----------------------------------------------+ ykman piv keys generate [OPTIONS] SLOT PUBLIC-KEY ================================================= Generate an asymmetric key pair. The private key is generated on the YubiKey, and written to one of the slots. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``PUBLIC-KEY`` || File containing the generated public key. Use ``'-'`` | | || to use ``stdout``. | +------------------+--------------------------------------------------------+ | ``SLOT`` | PIV slot of the private key. | +------------------+--------------------------------------------------------+ Options ------- .. table:: +-------------------------------+-------------------------------------------+ | Option | Description | +===============================+===========================================+ | ``-h, --help`` | Show this message and exit. | +-------------------------------+-------------------------------------------+ || ``-a, --algorithm [RSA1024`` || Algorithm to use in key generation. | || ``RSA2048|ECCP256|ECCP384]`` || [Default: ``RSA2048``] | +-------------------------------+-------------------------------------------+ | ``-F, --format [PEM|DER]`` | Encoding format. [Default: ``PEM``] | +-------------------------------+-------------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +-------------------------------+-------------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +-------------------------------+-------------------------------------------+ || ``--pin-policy [DEFAULT|`` | PIN policy for slot. | || ``NEVER|ONCE|ALWAYS]`` | | +-------------------------------+-------------------------------------------+ || ``--touch-policy [DEFAULT|`` | Touch policy for slot. | || ``NEVER|ALWAYS|CACHED]`` | | +-------------------------------+-------------------------------------------+ ykman piv keys import [OPTIONS] SLOT PRIVATE-KEY ================================================ Import a private key from file. Write a private key to one of the PIV slots on the YubiKey. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``PRIVATE-KEY`` || File containing the private key. Use ``'-'`` to use | | || ``stdin``. | +------------------+--------------------------------------------------------+ | ``SLOT`` | PIV slot of the private key. | +------------------+--------------------------------------------------------+ Options ------- .. table:: +----------------------------------+----------------------------------------+ | Option | Description | +==================================+========================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------------+----------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +----------------------------------+----------------------------------------+ || ``--pin-policy [DEFAULT|NEVER`` | PIN policy for slot. | || ``ONCE|ALWAYS]`` | | +----------------------------------+----------------------------------------+ | ``-p, --password TEXT`` || Password used to decrypt the private | | || key. | +----------------------------------+----------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +----------------------------------+----------------------------------------+ || ``--touch-policy [DEFAULT|`` | Touch policy for slot. | || ``NEVER|ALWAYS|CACHED]`` | | +----------------------------------+----------------------------------------+ ykman piv objects [OPTIONS] COMMAND [ARGS]... ============================================= Manage PIV data objects. Examples --------- **Write** the contents of a file to data object with ID: ``abc123:`` .. code-block:: $ ykman piv objects import abc123 myfile.txt **Read** the contents of the data object with ID: ``abc123 into a file:`` .. code-block:: $ ykman piv objects export abc123 myfile.txt **Generate** a random value for CHUID: .. code-block:: $ ykman piv objects generate chuid Options ------- .. table:: +----------------------------------+----------------------------------------+ | Option | Description | +==================================+========================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------------+----------------------------------------+ Commands --------- .. table:: +------------------+--------------------------------------------------------+ | Command | Description | +==================+========================================================+ | ``export`` | Export an arbitrary PIV data object. | +------------------+--------------------------------------------------------+ | ``generate`` | Generate and write data for a supported data object. | +------------------+--------------------------------------------------------+ | ``import`` | Write an arbitrary PIV object. | +------------------+--------------------------------------------------------+ ykman piv objects export [OPTIONS] OBJECT OUTPUT ================================================ Export an arbitrary PIV data object. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``OBJECT`` | Name of PIV data object, or ID in HEX. | +------------------+--------------------------------------------------------+ | ``OUTPUT`` | File to write object to. Use ``'-'`` to use ``stdout``.| +------------------+--------------------------------------------------------+ Options ------- .. table:: +----------------------------+----------------------------------------------+ | Option | Description | +============================+==============================================+ | ``-h, --help`` | Show this message and exit. | +----------------------------+----------------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +----------------------------+----------------------------------------------+ ykman piv objects generate [OPTIONS] OBJECT =========================================== Generate and write data for a supported data object. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``OBJECT`` || Name of PIV data object, or ID in HEX. | | || Supported data objects are: | | || ``CHUID`` (Card Holder Unique ID) | | || ``CCC`` (Card Capability Container) | +------------------+--------------------------------------------------------+ Options ------- .. table:: +--------------------------------+------------------------------------------+ | Option | Description | +================================+==========================================+ | ``-h, --help`` | Show this message and exit. | +--------------------------------+------------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +--------------------------------+------------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +--------------------------------+------------------------------------------+ ykman piv objects import [OPTIONS] OBJECT DATA ============================================== Write an arbitrary PIV object. Write a PIV object by providing the object id. Yubico writable PIV objects are available in the range 5f0000 - 5fffff. Arguments ---------- .. table:: +------------------+--------------------------------------------------------+ | Argument | Description | +==================+========================================================+ | ``DATA`` || File containing the data to be written. Use ``'-'`` to| | || use ``stdin``. | +------------------+--------------------------------------------------------+ | ``OBJECT`` | Name of PIV data object, or ID in HEX. | +------------------+--------------------------------------------------------+ Options ------- .. table:: +--------------------------------+------------------------------------------+ | Option | Description | +================================+==========================================+ | ``-h, --help`` | Show this message and exit. | +--------------------------------+------------------------------------------+ | ``-m, --management-key TEXT`` | The management key. | +--------------------------------+------------------------------------------+ | ``-P, --pin TEXT`` | PIN code. | +--------------------------------+------------------------------------------+ ykman piv reset [OPTIONS] ========================= Reset all PIV data. This action wipes all data and restores factory settings for the PIV application on your YubiKey. Options ------- .. table:: +-----------------------+---------------------------------------------------+ | Option | Description | +=======================+===================================================+ | ``-h, --help`` | Show this message and exit. | +-----------------------+---------------------------------------------------+ | ``-f, --force`` | Confirm the action without prompting. | +-----------------------+---------------------------------------------------+ ---- Click for `Yubico Support `_.