.. yk5-apps.rst .. _yk5-apps-label: ========================== Protocols and Applications ========================== The YubiKey 5 Series provides applications for FIDO2, OATH, OpenPGP, OTP, Smart Card, and U2F. The applications are all separate from each other, with separate storage for keys and credentials. For information on managing all these applications, see :ref:`yk5-tools-label`. Note that the OTP and OATH categories overlap. Technically, there are three true OTPs: * Yubico OTP (defined by Yubico) * OATH-HOTP (standard `RFC4226 `_) * OATH-TOTP (standard `RFC6238 `_) * We support the **Yubico OTP and OATH-HOTP directly on the touch-triggered OTP function** on the YubiKey. * We support **OATH-HOTP and OATH-TOTP directly on the OATH function** on the YubiKey (usually called OATH and used with Yubico authenticator). * We support a static password and Challenge-Response with `Touch-triggered OTP `_. Challenge-Response can also be used with software (such as Yubico Authenticator) to act as a single OATH-TOTP credential. All three of these OTPs are described in more detail below, see :ref:`oath-label` and :ref:`otp-label`. .. _fido-two-label: FIDO2 ====== The `FIDO2 `_ standard offers the same high level of security as FIDO U2F, since it is based on public key cryptography. In addition to providing phishing-resistant two-factor authentication, the FIDO2 application on the YubiKey allows for the storage of resident credentials, also called discoverable credentials. As these credentials can accommodate the username and other data, this enables truly passwordless authentication on sites and applications that support the WebAuthn protocol. YubiKeys in the 5 Series can hold up to 25 resident keys. .. Note:: .. include:: includes/ipad-pro-fido2.rst Locking FIDO2 Credentials ------------------------- The resident credentials can be left unlocked and used for strong single-factor authentication, or they can be protected by a PIN for two-factor authentication. * The FIDO2 PIN must be between 4 and 63 characters in length. * Once a FIDO2 PIN is set, it can be changed but it cannot be removed without resetting the FIDO2 application. * If the PIN is entered incorrectly 8 times in a row, the FIDO2 application locks. In order to restore this functionality, reset the FIDO2 application.  .. Note:: Resetting the FIDO2 application also resets the U2F key. This means the YubiKey must be re-registered not only with all the FIDO2 sites, but also with all U2F sites. .. Note:: The YubiKey 5Ci supports Credential Management to allow for selective deletion of resident keys. See `Enhancements to FIDO 2 Support `_ for details. Default Values -------------- PIN: None set. .. _yk-5-fips-aaguids: AAGUID Values ------------- The `FIDO2 specification `_ states that an Authenticator Attestation GUID (AAGUID) must be provided during attestation. An AAGUID is a 128-bit identifier indicating the type of the authenticator. New AAGUIDs are issued for new YubiKey products that support FIDO2, or when existing YubiKey products have FIDO2 features added or removed. For the complete list of AAGUIDs, see https://support.yubico.com/hc/en-us/articles/360016648959-YubiKey-Hardware-FIDO2-AAGUIDs. Supported Extensions -------------------- The YubiKey 5 Series supports only the AppID extension (``appid``) as defined by the `W3C Web Authentication API specification `_. This extension allows U2F credentials registered using the legacy FIDO JavaScript APIs to be used with WebAuthn. That means if you register a YubiKey in the 5 Series on a website that used U2F at that time and later upgrades to FIDO2, your U2F credentials continue to work on the website. ---- FIDO U2F ======== `FIDO U2F `_ is an open standard that provides strong, phishing-resistant two-factor authentication for web services using public key cryptography. U2F does not require any special drivers or configuration to use, just a compatible web browser. The U2F application on the YubiKey can be associated with an unlimited number of U2F sites. ---- .. _oath-label: OATH ==== The OATH application can store up to 32 OATH credentials, either OATH-TOTP (time-based One-Time Password) or OATH-HOTP (counter-based One-Time Password). These credentials are separate from those stored in the OTP application, and can only be accessed through the CCID channel. In order to manage these credentials and read the OTPs generated by the YubiKey, requires the `Yubico Authenticator `_. To restrict access to the OTPs, set a password for the OATH application. .. Note:: Developers: Using the OATH application functions on iOS requires the `Yubico iOS SDK `_. HOTP and TOTP ------------- Both **OATH-TOTP** and **OATH-HOTP** credentials are described in detail in the `OATH Overview `_. ---- .. _yk5-apps-openpgp-label: OpenPGP ======= The OpenPGP application provides an OpenPGP-compatible smart card in compliance with version 3.4 of the specification if the YubiKey firmware is 5.2.3 or later. If the firmware is an earlier version, the OpenPGP-compatible smart card is in compliance with version 2.0 of the specification. OpenPGP-compatible smart card can be used with compatible PGP software such as GnuPG (GPG) and can store one PGP key each for authentication, signing, and encryption. Similar to the PIV / Smart Card touch policy, the OpenPGP application can also be set to require the YubiKey's metal contact be touched to authorize an operation. .. Note:: Developers: Using the OpenPGP functions on iOS requires the `Yubico iOS SDK `_. YubiKey firmware 5.2.3 - 5.2.8 and 5.3.2 - 5.4.3 in combination with OpenPGP 3.4: * Extends existing RSA support for OpenPGP operations to ECC algorithms * Provides the Yubico Attestation feature for verifying keys generated on a YubiKey device * Utilizes separate x.509 cardholder certificates alongside the existing OpenPGP certificates for authentication, signature and encryption/decipher * Bring attestation functionality to OpenPGP keys and certificates generated on a YubiKey * Improves security by supporting Key Derivation Function (KDF) PINs. With KDF enabled, the PIN is stored as a hash on the YubiKey. The OpenPGP client will only pass the hashed value, never the PIN directly. Elliptic Curve Cryptographic (ECC) Algorithms --------------------------------------------- The YubiKey 5.2.3 firmware added support for ECC algorithms. These can be used for Signature, Authentication and Decipher keys. The full list of curves supported by OpenPGP 3.4 can be found in section 4.4.3.10 of the `OpenPGP Smart Card 3.4 spec `_ (page 35). In addition to :ref:`rsa-label`, YubiKeys support the following ECC algorithms: * secp256r1 * secp256k1 * secp384r1 * secp521r1 * brainpoolP256r1 * brainpoolP384r1 * brainpoolP512r1 * curve25519 * x25519 (decipher only) * ed25519 (sign / auth only) For further details on the new features, including key attestation, expanded encryption algorithms and additional cardholder certificates, refer to `Enhancements to OpenPGP Support `_. .. _rsa-label: RSA Algorithms -------------- * RSA 1024 * RSA 2048 * RSA 3072 (requires GnuPG version 2.0 or higher) * RSA 4096 (requires GnuPG version 2.0 or higher) Default Values -------------- * PIN: 123456 * Admin PIN: 12345678 ---- .. _otp-label: OTP === The OTP application provides two programmable slots, each of which can hold one of the types of credentials listed below. A Yubico OTP credential is programmed to slot 1 during manufacturing. Output is sent as a series of keystrokes from a virtual keyboard. * Trigger the YubiKey to produce the credential in the first slot by briefly touching the metal contact of the YubiKey. * If a credential has been programmed to the second slot, trigger the YubiKey to produce it by touching the contact for 3 seconds. Yubico OTP ---------- `Yubico OTP `_ is a strong authentication mechanism that is supported by the YubiKey 5 Series. Yubico OTP can be used as the second factor in a two-factor authentication (2FA) scheme or on its own, providing single-factor authentication. The OTP generated by the YubiKey has two parts, with the first 12 characters being the public identity which a validation server can link to a user, while the remaining 32 characters are the unique passcode that is changed each time an OTP is generated. The character representation of the Yubico OTP is designed to handle a variety of keyboard layouts. It is crucial that the same code is generated if a YubiKey is inserted into a German computer with a QWERTZ layout, a French one with an AZERTY layout, or a US one with a QWERTY layout. The “Modhex”, or Modified Hexadecimal coding, was invented by Yubico to use only specific characters to ensure that the YubiKey works with the maximum number of keyboard layouts. (USB keyboards send their keystrokes by means of “scan codes” rather than the actual character. The translation to keystrokes is done by the device to which the YubiKey is connected). Static Password --------------- A static password can be programmed to the YubiKey so that it will type the password for you when you touch the metal contact. For managing multiple passwords, see the `password managers `_ that the YubiKey can secure with two-factor authentication (2FA). HMAC-SHA1 Challenge-Response ---------------------------- This type of credential is most often used for offline authentication, as it does not require contacting a server for validation. An HMAC-SHA1 Challenge-Response credential enables software to send a challenge to the YubiKey and verify that an expected, predetermined response is returned. This credential can also be set to require a touch on the metal contact before the response is sent to the requesting software. This type of credential must be activated by the software sending the challenge; it cannot be activated by touching the metal contact on the YubiKey. .. Note:: Developers: Because the Challenge-Response function requires two-way communication with the YubiKey, using this feature on iOS requires the `Yubico iOS SDK `_. ---- .. _piv-smart-card-label: Smart Card (PIV Compatible) =========================== The YubiKey 5 Series provides a PIV-compatible smart card application. PIV, or FIPS 201, is a US government standard. It enables RSA or ECC sign/encrypt operations using a private key stored on a smart card through common interfaces like PKCS#11. On Windows, the smart card functionality can be extended with the `YubiKey Smart Card Minidriver `_. .. Note:: The YubiKey Smart Card Minidriver is not available for Android, Linux, macOS or iOS. The YubiKey 5 Series supports extended APDUs, extended ``Answer To Reset (ATR)``, and ``Answer To Select (ATS)``. Using the PIV APDUs on iOS requires the `Yubico iOS SDK `_. Default Values -------------- * PIN: 123456 * PUK: 12345678 * Management Key (3DES): ``010203040506070801020304050607080102030405060708`` Supported Algorithms -------------------- The YubiKey 5 Series supports the following algorithms on the PIV smart card application. * RSA 1024 * RSA 2048 * ECC P-256 * ECC P-384 Policies -------- PIN Policy ~~~~~~~~~~ To specify how often the PIN needs to be entered for access to the credential in a given slot, set a PIN policy for that slot. This policy must be set upon key generation or import. It cannot be changed later. Touch Policy ~~~~~~~~~~~~ In addition to requiring the PIN, the YubiKey can require a physical touch on the metal contact. Similar to the PIN policy, the touch policy must be set upon key generation or import. Slot Information ---------------- The keys and certificates for the smart card application are stored in slots, which are described below. The PIN policies described below are the defaults, before they are overridden with a custom PIN policy. **These slots are separate from the programmable slots in the OTP application.** Slot 9a: PIV Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This certificate and its associated private key is used to authenticate the card and the cardholder. This slot is used for system login, etc. To perform any private key operations, the end user PIN is required. Once the correct PIN has been provided, multiple private key operations may be performed without additional cardholder consent. Slot 9c: Digital Signature ~~~~~~~~~~~~~~~~~~~~~~~~~~ This certificate and its associated private key is used for digital signatures for the purpose of document, email, file, and executable signing. To perform any private key operations, the end user PIN is required. The PIN must be submitted immediately before each sign operation to ensure cardholder participation for every digital signature generated. Slot 9d: Key Management ~~~~~~~~~~~~~~~~~~~~~~~ This certificate and its associated private key is used for encryption to assure confidentiality. This slot is used for encrypting emails or files. The end user PIN is required to perform any private key operations. Once the correct PIN has been provided, multiple private key operations may be performed without additional cardholder consent. Slot 9e: Card Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This certificate and its associated private key is used to support additional physical access applications, such as providing physical access to buildings through PIV-enabled door locks. The end user PIN is NOT required to perform private key operations for this slot. Slots 82-95: Retired Key Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These slots are meant for previously used Key Management keys to be able to decrypt earlier encrypted documents or emails. Slot f9: Attestation ~~~~~~~~~~~~~~~~~~~~ This slot is only used for attestation of other keys generated on the device with instruction f9. This slot is not cleared on reset, but can be overwritten. Attestation ----------- Attestation enables you to verify that a key on the smart card application was generated on the YubiKey and was not imported. An X.509 certificate for the key to be attested is created if the key has been generated on the YubiKey. Included in the certificate are the following extensions that provide information about the YubiKey. * ``1.3.6.1.4.1.41482.3.3``: Firmware version, encoded as three bytes. For example, 050100 indicates firmware version 5.1.0. * ``1.3.6.1.4.1.41482.3.7``: Serial number of the YubiKey, encoded as an integer. * ``1.3.6.1.4.1.41482.3.8``: Two bytes, the first encoding the PIN policy and the second encoding the touch policy.   * PIN policy: * 01 - never require PIN * 02 - require PIN once per session * 03 - always require PIN. * Touch policy: * 01 - never require touch * 02 - always require touch * 03 - cache touch for 15 seconds. * ``1.3.6.1.4.1.41482.3.9``: YubiKey’s form factor, encoded as a one-byte octet-string.   * USB-A Keychain: 0x01 * USB-A Nano: 0x02 * USB-C Keychain: 0x03 * USB-C Nano: 0x04 * USB-C and Lightning®: 0x05 * Undefined: 0x00 PIV Metadata ------------ Background: How PIV Attestation Works ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A technical description of YubiKey PIV attestation is available at the `Yubico developer website `_. Attestation is performed on a public key that has been *generated on the YubiKey*. For example, consider an asymmetric key-pair that is generated on the YubiKey with the following ykman (YubiKey Manager) command: ``ykman piv generate-key 9c -`` This command generates an asymmetric key-pair, and stores the private key in the specified slot (9c in this example). The public key that has been generated is returned as output. The ykman attestation command can be executed for the key-pair at the slot (9c): ``ykman piv attest 9c C:\Test\attestation-cert-9c.cer`` The generated certificate is generated in real time at the YubiKey. The attestation certificate and private key, which are stored in slot f9, are used for signing the generated certificate for the slot (9c). The attestation certificate is used as template when creating the generated certificate for the slot (9c). In addition to the template attestation certificate, the `extensions and subject details `_ are appended to the generated certificate. However, the generated certificate is not the same as the X.509 certificate that may be issued by an external CA or self-signed on the YubiKey. For example, the X.509 certificate could be issued by the Microsoft ADCS and written to the YubiKey. The YubiKey Manager GUI can be used to generate a key-pair and self-sign the public key at the YubiKey. The public key at slot 9a can be attested (signed in real time by the CA attestation certificate) with the same ykman command as above: ``ykman piv attest 9a C:\Test\attestation-cert-9a.cer`` And the X.509 self-signed certificate can be exported from the YubiKey with the following ykman command: ``ykman piv export-certificate 9a C:\Test\self-signed-9a.cer`` The Shortcomings of PIV Attestation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PIV attestation only works for asymmetric keys that have been *generated on* the YubiKey. It does not work for asymmetric keys that have been *imported into* the YubiKey. For example, the following ykman command imports a PKCS #12 file into the YubiKey at slot 9e: ``ykman piv import-key 9e C:\\Test\\TestUser1.p12 -P 123456`` ``ykman piv import-certificate 9e C:\\Test\\TestUser1.p12 -P 123456`` These ykman commands unpack the PKCS #12 file, store the private key in the private key slot (9e), and store the X.509 certificate in the corresponding certificate slot. Now, if one tries to attest the public key at slot 9e with the ykman attestation command, the operation fails: ``ykman piv attest 9e C:\\Test\\attestation-9e.cer`` ``Error: Attestation failed.`` One more drawback with PIV attestation is performance, since generation of multiple PIV attestation certificates can be time-consuming. When To Use PIV Metadata ~~~~~~~~~~~~~~~~~~~~~~~~ PIV metadata should be used for the following cases: * If PIV attestation cannot be used (for imported keys), * If an attestation certificate is not required, PIV metadata can be used for achieving higher performance. Yubico PIV Library and Metadata API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PIV metadata is supported by YubiKey v5.3.0 firmware and above. YubiKey PIV metadata can be accessed by using the ``libykpiv`` library. The `Yubico PIV Tool `_ contains the library * ``libykpiv.so`` (for Linux), * ``libykpiv.dylib`` (for MacOS), * ``libykpiv.dll`` (for Windows). The source code of the ``libykpiv`` library is published at the `Yubico GitHub repo `_. libykpiv ;;;;;;;; The ``libykpiv`` library exposes a C API in the header file `ykpiv.h `_, which includes the functions ``ykpiv_get_metadata()`` and ``ykpiv_util_parse_metadata()``. The source code of these functions is available in the file `ykpiv.c `_. In particular, the function ``ykpiv_get_metadata()`` calls the underlying function ``_ykpiv_transfer_data()``, which transfers APDUs to the YubiKey PIV applet over the CCID interface. The function ``_ykpiv_transfer_data()`` takes the input parameter ``templ``, which is populated with the APDUs (``CLA``, ``INS``, ``P1``, ``P2``) that are specified at the Yubico developer website for `PIV extensions `_ under the section **GET METADATA**. The YubiKey returns the tag length values (TLVs) (``Algorithm``, ``Policy``, ``Origin``, etc.) that are specified in the same `PIV extensions `_ section, and the TLV-encoded output is returned in the ``ykpiv_get_metadata()`` parameter data. .. table:: TLVs Returned +---------------+------+---------------------------------------------+ | Key | TLV | Description | +===============+======+=============================================+ | Algorithm | 0x01 | Algorithm/type of the key | +---------------+------+---------------------------------------------+ | Policy | 0x02 | PIN and Touch policy of the key (keys only) | +---------------+------+---------------------------------------------+ | Origin | 0x03 | Origin of the key: imported or generated | +---------------+------+---------------------------------------------+ | Public key | 0x04 | Public key associated with the private key | +---------------+------+---------------------------------------------+ | Default value | 0x05 | | Whether the PIN/key has a default value | | | | | (PIN and PUK and Mgmt key only) | +---------------+------+---------------------------------------------+ | Retries | 0x06 | Number of retries left (PIN and PUK only) | +---------------+------+---------------------------------------------+ It is even possible to invoke the function ``ykpiv_transfer_data()`` directly for low-level APDU communication with the YubiKey’s PIV applet. The function ``ykpiv_util_parse_metadata()`` can be used for parsing the returned TLV-encoded object. Therefore, the developer can integrate the ``libykpiv`` library for low level programming with YubiKey PIV metadata. Using PIV Metadata with YKCS11 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `YKCS11 library `_ is part of the Yubico PIV Tool. YKCS11 is a `PKCS#11 module `_ that allows external applications to communicate with the PIV application running on a YubiKey. When the PKCS #11 function ``C_OpenSession()`` is called for a YubiKey PKCS #11 slot (which is a YubiKey PIV application in a PC/SC reader), then the YKCS11 library parses out the public keys for all PIV key slots. If PIV attestation is supported, the PIV attestation certificate is used for parsing out the public key. If PIV attestation is not supported, that is, if the key-pair has been imported into a YubiKey, then the YKCS11 library calls the functions ``ykpiv_get_metadata()`` and ``ykpiv_util_parse_metadata()`` to parse out the requested public key. If both attestation and PIV metadata fail, in that order, YKCS11 falls back to parse the public key from the X.509 certificate. .. Note:: The X.509 certificate’s public key may not match the private key in the YubiKey PIV slot. Changes ------- Answer to Reset (ATR) and Answer to Select (ATS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ATR has been changed from **Yubikey 4** to **YubiKey** and adds support for ATS. PIV Attestation Root CA ~~~~~~~~~~~~~~~~~~~~~~~~ YubiKeys 5 Series have a PIV attestation root certificate authority different than previous YubiKeys. Download the certificate of the new root certificate authority on the `PIV attestation `_ page. Easier Identification ~~~~~~~~~~~~~~~~~~~~~ The YubiKey 5 Series devices can report their form factor through the PIV application whether or not they have an NFC interface. This enables easier, programmatic identification of the physical attributes of the YubiKey. For more information about how to query this information, see the `YubiKey 5 Series Configuration Reference Guide `_. .. _yk5-piv-aes-mgmt-key-label: PIV AES Management Key ~~~~~~~~~~~~~~~~~~~~~~ Historically, the YubiKey PIV management key is a 3DES key. With the release of the YubiKey firmware version 5.4.2, the YubiKey PIV management key can also be an AES key. For more details, see the article on our Developer site, `YubiKey and PIV `_. Technically speaking, this feature expands the management key type held in PIV slot 9b to include AES keys (128, 192 and 256) as defined in the PIV specification (`SP800-78-4 `_, section 5). PIV management key in AES format renders the YubiKey compatible with current or future FIPS-compliant CMS services. ---- .. _yubihsm-auth-label: YubiHSM Auth ============ Introduction ------------ .. include:: includes/yubihsm-auth-intro.rst YubiHSM Auth uses hardware to protect the long-lived credentials for accessing a YubiHSM 2. This increases the security of the authentication credentials, as compared to the authentication solution for the YubiHSM 2 based on software credentials derived from the Password-Based Key Derivation Function 2 (PBKDF2) algorithm with a password as input. Credentials and PIN Codes ------------------------- Each YubiHSM Auth credential is comprised of two AES-128 keys which are used to derive the three session-specific AES-128 keys. The YubiHSM Auth application can store up to 32 YubiHSM Auth credentials in the YubiKey. Each YubiHSM Auth credential is protected by a 16-byte user access code provided to the YubiKey for each YubiHSM Auth operation. The access code is used to access the YubiHSM Auth Credential to derive the session-specific AES-128 keys. Storing or deleting YubiHSM Auth credentials requires a separate 16-byte admin access code. Each access code has a limit of eight retries and optionally, verification of user presence (touch). YubiHSM 2 Secure Channel ------------------------ Use the YubiKey YubiHSM Auth application to establish an encrypted and authenticated session to a YubiHSM 2. Although the YubiHSM 2 secure channel is based on the protocol Global Platform Secure Channel Protocol '03' (SCP03), there are two important differences: * The YubiHSM 2 secure channel protocol does not use APDUs, so the commands and possible options are not those of the complete SCP03 specification. * SCP03 uses key sets with three long-lived AES keys, while the YubiHSM 2 secure channel uses key sets with two long-lived AES keys. The YubiHSM 2 authentication protocol uses a set of static credentials called a long-lived key set. This consists of two AES-128 keys: * ENC: Used for deriving keys for command and response encryption, as specified in SCP03. * MAC: Used for deriving keys for command and response authentication, as specified in SCP03. The identical long-lived keyset is protected in the YubiHSM 2 and in the YubiKey YubiHSM Auth application. Those long-lived key sets are used by the YubiHSM Auth application to derive a set of three session-specific AES-128 keys using the challenge-response protocol as defined in SCP03: * Session Secure Channel Encryption Key (S-ENC): Used for data confidentiality. * Secure Channel Message Authentication Code Key for Command (S-MAC): Used for data and protocol integrity. * Secure Channel Message Authentication Code Key for Response (S-RMAC): Used for data and protocol integrity. The YubiHSM Auth session-specific keys are output from the YubiKey to the calling library, which uses the session keys to encrypt and authenticate commands and responses during a single session. The session keys are discarded afterwards. Architecture Overview --------------------- The figure below shows how the YubiHSM Auth application fits in to the YubiHSM 2 architecture. .. image:: graphics/yubihsm-auth-architecture.png The identical long-lived credentials (key sets) are protected in both the YubiKey YubiHSM Auth application and in the YubiHSM 2. The YubiHSM-Shell software tool can be used for generating the key sets in the YubiHSM 2, and the YubiHSM-Auth software tool can be used for importing the same key sets to the YubiKey YubiHSM Auth application. At the client, the YubiHSM authentication protocol is implemented in the ``libykhsmauth`` library, which derives the three session AES-keys by calling the YubiKey YubiHSM Auth CCID application. The session objects that are created can be used by the ``libyubihsm`` in the communication with YubiHSM. The YubiHSM session keys are therefore generated on the basis of the long-lived credentials that are protected in the YubiHSM 2 and YubiKey YubiHSM Auth in conjunction with the SCP03 derivation scheme. YubiHSM Auth Flowchart ---------------------- The flowchart below illustrates the authentication protocol communication with YubiHSM using the static keys on YubiHSM Auth. It is assumed that the YubiHSM and YubiHSM Auth application share the same static keyset. The steps are explained below. .. image:: graphics/yubihsm-auth-flowchart.png 1. The user launches YubiHSM-Shell and enters the commands ``connect`` and ``session open``, with the flag ``ykopen`` that indicates that the YubiKey with YubiHSM Auth shall be used. 2. The YubiHSM-Shell invokes the ``libyubihsm`` library, with a request to open a session to the YubiHSM 2. 3. The ``libyubihsm`` library generates a host challenge, and opens a session to the YubiHSM 2 device. 4. The YubiHSM 2 device generates an HSM challenge, and generates the session keys based on the HSM challenge, the host challenge, and the static key set in the YubiHSM 2 device. The YubiHSM 2 returns the HSM challenge in an HSM response to the ``libyubihsm`` library. 5. The ``libyubihsm`` library propagates the host challenge and HSM challenge to the YubiHSM Shell. 6. The user enters the Credential password for unlocking the static keyset in the YubiHSM Auth application in the YubiKey. The YubiHSM Shell invokes the ``libykhsmauth`` library, with a request to generate session keys. 7. The ``libykhsmauth`` library invokes the YubiHSM Auth application in the YubiKey with the Credential password, the HSM challenge and host challenge are used as input parameters. 8. The Credential password unlocks the static keyset in the YubiHSM Auth application, and the YubiHSM Auth application generates the session keys based on the static keys, HSM challenge, and host challenge. 9. The ``libykhsmauth`` library returns the session keys to YubiHSM Shell. 10. The YubiHSM Shell acknowledges the protocol handshake to ``libyubihsm``. 11. The ``libyubihsm`` sends the host response to the YubiHSM 2 device. The session keys can now be used for secure channel communication between ``YubiHSM-Shell/libyubihsm`` in the host and the YubiHSM device. Software and Tools ------------------ YubiHSM-Auth Software Tool ~~~~~~~~~~~~~~~~~~~~~~~~~~ The YubiHSM-Auth software tool is part of the `YubiHSM Shell `_, which is installed with the `YubiHSM SDK `_. YubiHSM-Auth tool can be used for: * Storing the YubiHSM Auth credentials on a YubiKey * Deleting the YubiHSM Auth credentials on a YubiKey * Listing the YubiHSM Auth credentials on a YubiKey * Changing the YubiHSM Auth management key on a YubiKey * Checking the number of retries of the YubiHSM Auth credential password * Checking the version of the YubiHSM Auth application * Calculating session keys, mainly for debugging and test purposes * Resetting the YubiHSM Auth application on a YubiKey First, the YubiHSM 2 device needs to be configured with an authentication key. The default authentication key password on ``KeyID=1`` is set to ``password``, and this should be changed or replaced with other authentication keys. For the examples in this section, however, it is assumed that the default authentication key is still present on the YubiHSM 2. To generate and store the equivalent YubiHSM Auth credentials on the YubiKey, use the ``yubihsm-auth`` command line tool. To invoke YubiHSM-Auth, simply run ``yubihsm-auth`` with the required commands and parameters. To get a list of available commands, parameters and their syntax, run: ``yubihsm-auth --help``. An example of how to use ``yubihsm-auth`` for storing YubiHSM Auth credentials on a YubiKey is shown below: .. code-block:: $ yubihsm-auth -a put --label="default key" --derivation-password="password" --credpwd="MyPassword" --touch=on --mgmkey="00000000000000000000000000000000" --verbose=5 Credential successfully stored Where: * ``-a put`` is the action to insert a YubiHSM Auth credential on the YubiKey * ``--label`` is the label of the YubiHSM Auth credential on the YubiKey * ``--derivation-password`` is used as input to the PBKDF2 algorithm, which is used for generating the two AES-128 keys that constitute the YubiHSM Auth credentials to be stored on the YubiKey * ``--credpwd`` is the password protecting the YubiHSM Auth credentials on the YubiKey * ``--touch`` is set to ``on``. This requires the user touch the YubiKey when accessing the YubiHSM Auth credential * ``--mgmkey`` is the management key that is needed for writing the YubiHSM Auth credentials on the YubiKey * ``--verbose`` is used to print more information as output .. Note:: We recommend using an offline air-gapped computer when storing the YubiHSM Auth credentials on the YubiKey. Now, the YubiKey YubiHSM Auth application can be used with `YubiHSM Shell `_ for authentication to the YubiHSM 2. Using YubiHSM-Auth with YubiHSM Shell ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to authenticate to the YubiHSM 2 device with static credentials that are protected in the YubiKey application called YubiHSM Auth. For more information on this YubiKey feature and how to configure it, see the YubiHSM User Guide, section `YubiHSM Auth `_. The YubiHSM Shell tool supports authentication with YubiHSM Auth credentials in both interactive mode and command-line mode. To use yubihsm-shell with the YubiHSM Auth-enabled YubiKey in interactive mode, open a session by executing the following yubihsm-shell command: .. code-block:: yubihsm> session ykopen