.. hsm2-core-concepts.rst .. _hsm2-core-concepts-label: ================ Core Concepts ================ .. _hsm2-concepts-objects-label: Objects ========= The first concept that we will present is the Object. Any persistently stored and self-contained piece of information present in a YubiHSM 2 is an Object. This is intentionally a very generic and broad definition which can be easily rephrased as *everything is an Object*. Objects have associated properties that characterize them and give them different meanings. Regardless of the kind and the specific properties, any YubiHSM 2 device can store up to 256 Objects. Their combined size cannot exceed 126 KB. Object Type ------------- To identify what an Object can and cannot do, we define an attribute called Object Type, or simply Type. A Type is not enough to *uniquely* identify an Object, but it defines the set of operations that can be performed with or on it. The following types are defined: Authentication Key ------------------- An Authentication Key is one of the most fundamental Objects there are. Authentication Keys can be used to establish a Session with a device. See :ref:`hsm2-concepts-create-authenticate-session-label`. An Authentication Key is basically two long-lived AES keys: an encryption key and a MAC key. When establishing a Session, the long-lived keys are used to generate three session keys: * An encryption key used to encrypt the messages exchanged with the device * A MAC key used to create an authentication tag for each message sent to the device * A response MAC key used to create an authentication tag for each response message sent by the device The session keys are temporary and are destroyed when the Session is no longer in use. Asymmetric Key ------------------- An Asymmetric Key Object is what the YubiHSM 2 uses to represent an asymmetric key-pair where only the private key can be used to perform cryptographic operations. HMAC Key ------------------- An HMAC Key is a secret key used when computing and verifying HMAC signatures. Opaque ------------------- An Opaque Object is an unchecked kind of Object, normally used to store raw data in the device. No specific restrictions (besides size limitations) are imposed to this type of Object. OTP AEAD Key ------------------- An OTP AEAD Key Object is a secret key used to decrypt Yubico OTP values for further verification by a validation process. Symmetric Key ------------------- Available with firmware version 2.3.1 or later. A Symmetric Key Object is a secret key used when encrypting and decrypting AES. Object Types are encoded as an 8-bit value. Template ------------------- A Template Object is a binary template used for example to validate SSH certificate requests. Wrap Key ------------------- A Wrap Key Object is a secret key used to wrap and unwrap Objects during the export and import process. Object Types are encoded as an 8-bit value. .. _hsm2-concepts-algorithms-label: ALGORITHMS =========== .. table:: +----------------+-------+----------------+---------------+-------------------+ | Name | Value || yubihsm-shell | EC Curve | Usage | | | || name | | | +================+=======+================+===============+===================+ | RSA PKCS1 SHA1 | 1 | rsa-pkcs1-sha1 | || RSA sign with | | | | | || PKCS1.5 | +----------------+-------+----------------+---------------+-------------------+ || RSA PKCS1 | 2 || rsa-pkcs1- | || RSA sign with | || SHA256 | || sha256 | || PKCS1.5 | +----------------+-------+----------------+---------------+-------------------+ || RSA PKCS1 | 3 || rsa-pkcs1- | || RSA sign with | || SHA384 | || sha384 | || PKCS1.5 | +----------------+-------+----------------+---------------+-------------------+ || RSA PKCS1 | 4 || rsa-pkcs1- | || RSA sign with | || SHA512 | || sha512 | || PKCS1.5 | +----------------+-------+----------------+---------------+-------------------+ | RSA PSS SHA1 | 5 | rsa-pss-sha1 | | RSA sign with PSS | +----------------+-------+----------------+---------------+-------------------+ | RSA PSS SHA256 | 6 | rsa-pss-sha256 | | RSA sign with PSS | +----------------+-------+----------------+---------------+-------------------+ | RSA PSS SHA384 | 7 | rsa-pss-sha384 | | RSA sign with PSS | +----------------+-------+----------------+---------------+-------------------+ | RSA PSS SHA512 | 8 | rsa-pss-sha512 | | RSA sign with PSS | +----------------+-------+----------------+---------------+-------------------+ | RSA 2048 | 9 | rsa2048 | | Generate RSA key | +----------------+-------+----------------+---------------+-------------------+ | RSA 3072 | 10 | rsa3072 | | Generate RSA key | +----------------+-------+----------------+---------------+-------------------+ | RSA 4096 | 11 | rsa4096 | | Generate RSA key | +----------------+-------+----------------+---------------+-------------------+ | EC P256 | 12 | ecp256 | secp256r1 | Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC P384 | 13 | ecp384 | secp384r1 | Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC P521 | 14 | ecp521 | secp521r1 | Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC K256 | 15 | eck256 | secp256k1 | Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC BP256 | 16 | ecbp256 | brainpool256r1| Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC BP384 | 17 | ecbp384 | brainpool384r1| Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | EC BP512 | 18 | ecbp512 | brainpool512r1| Generate EC key | +----------------+-------+----------------+---------------+-------------------+ | HMAC SHA1 | 19 | hmac-sha1 | | Generate HMAC key | +----------------+-------+----------------+---------------+-------------------+ | HMAC SHA256 | 20 | hmac-sha256 | | Generate HMAC key | +----------------+-------+----------------+---------------+-------------------+ | HMAC SHA384 | 21 | hmac-sha384 | | Generate HMAC key | +----------------+-------+----------------+---------------+-------------------+ | HMAC SHA512 | 22 | hmac-sha512 | | Generate HMAC key | +----------------+-------+----------------+---------------+-------------------+ | ECDSA SHA1 | 23 | ecdsa-sha1 | | ECDSA sign | +----------------+-------+----------------+---------------+-------------------+ | EC ECDH | 24 | ecdh | | | +----------------+-------+----------------+---------------+-------------------+ | RSA OAEP SHA1 | 25 | rsa-oaep-sha1 | || RSA decrypt with | | | | | || OAEP | +----------------+-------+----------------+---------------+-------------------+ | RSA OAEP SHA256| 26 || rsa-oaep- | || RSA decrypt with | | | || sha256 | || OAEP | +----------------+-------+----------------+---------------+-------------------+ | RSA OAEP SHA384| 27 || rsa-oaep- | || RSA decrypt with | | | || sha384 | || OAEP | +----------------+-------+----------------+---------------+-------------------+ | RSA OAEP SHA512| 28 || rsa-oaep- | || RSA decrypt with | | | || sha512 | || OAEP | +----------------+-------+----------------+---------------+-------------------+ | AES128 CCM WRAP| 29 || aes128-ccm- | | Generate Wrap key | | | || wrap | | | +----------------+-------+----------------+---------------+-------------------+ | Opaque Data | 30 | opaque-data | || Store raw data | | | | | || as an opaque | | | | | || object | +----------------+-------+----------------+---------------+-------------------+ || Opaque X509 | 31 || opaque-x509- | || Store | || Certificate | || certificate | || X509Certificate | || | || | || as an opaque | || | || | || object | +----------------+-------+----------------+---------------+-------------------+ | MGF1 SHA1 | 32 | mgf1-sha1 | || RSA sign with | | | | | || PSS and RSA | | | | | || decrypt with OAEP| +----------------+-------+----------------+---------------+-------------------+ | MGF1 SHA256 | 33 | mgf1-sha256 | || RSA sign with | | | | | || PSS and RSA | | | | | || decrypt with OAEP| +----------------+-------+----------------+---------------+-------------------+ | MGF1 SHA384 | 34 | mgf1-sha384 | || RSA sign with PSS| | | | | || and RSA decrypt | | | | | || with OAEP | +----------------+-------+----------------+---------------+-------------------+ | MGF1 SHA512 | 35 | mgf1-sha512 | || RSA sign with PSS| | | | | || and RSA decrypt | | | | | || with OAEP | +----------------+-------+----------------+---------------+-------------------+ | SSH Template | 36 | template-ssh | || Store an SSH | | | | | || template (a | | | | | || binary object | | | | | || used to restrict | | | | | || how and when an | | | | | || SSH CA private | | | | | || key should be | | | | | || used) | +----------------+-------+----------------+---------------+-------------------+ || Yubico OTP | 37 || aes128-yubico | || Generate OTP AEAD| || AES128 | || -otp | || key | +----------------+-------+----------------+---------------+-------------------+ || Yubico AES | 38 || aes128-yubico-| || Store | || Authentication| || authentication| || authentication | || | || | || key | +----------------+-------+----------------+---------------+-------------------+ || Yubico OTP | 39 || aes192-yubico | || Generate OTP AEAD| || AES192 | || -otp | || key | +----------------+-------+----------------+---------------+-------------------+ || Yubico OTP | 40 || aes256-yubico | || Generate OTP AEAD| || AES256 | || -otp | || key | +----------------+-------+----------------+---------------+-------------------+ || AES192 CCM | 41 || aes192-ccm- | || Generate and | || WRAP | || wrap | || store wrap key | +----------------+-------+----------------+---------------+-------------------+ || AES256 CCM | 42 || aes256-ccm- | || Generate and | || WRAP | || wrap | || store wrap key | +----------------+-------+----------------+---------------+-------------------+ | ECDSA SHA256 | 43 | ecdsa-sha256 | | ECDSA sign | +----------------+-------+----------------+---------------+-------------------+ | ECDSA SHA384 | 44 | ecdsa-sha384 | | ECDSA sign | +----------------+-------+----------------+---------------+-------------------+ | ECDSA SHA512 | 45 | ecdsa-sha512 | | ECDSA sign | +----------------+-------+----------------+---------------+-------------------+ | ED25519 | 46 | ed25519 | | Generate ED key | +----------------+-------+----------------+---------------+-------------------+ | EC P224 | 47 | ecp224 | secp224r1 | Generate EC key | +----------------+-------+----------------+---------------+-------------------+ .. _hsm2-concepts-attestation-label: Attestation ============ Asymmetric keys in the YubiHSM can be attested by another Asymmetric key. The attestation process creates a new x509 certificate for the attested key. The device comes pre-loaded with an attestation key and certificate referenced by ID ``0``. It is possible to use your own key and certificate for attestation, these then must have the same ID and the key has to have the ``sign-attestation-certificate`` Capability set. Details --------- * Serial is a random 16 byte integer * Issuer is the subject of the attesting certificate * Dates is copied from the attesting certificate * Subject is the string ``YubiHSM Attestation id 0x`` with the attested ID appended * If the attesting key is RSA the signature is SHA256-PKCS#1v1.5 * If the attesting key is EC the signature is ECDSA-SHA256 Certificate Extensions ------------------------ Some certificate extensions are added in the generated certificate and the pre-loaded certificate: .. table:: +-----------------------+---------------------------------------+-------------+ | OID | Description | Data Type | +=======================+=======================================+=============+ | 1.3.6.1.4.1.41482.4.1 | Firmware version | Octet String| +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.2 | Serial number | Integer | +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.3 | Origin | Bit String | +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.4 | :ref:`hsm2-concepts-domain-label` | Bit String | +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.5 | :ref:`hsm2-concepts-capability-label` | Bit String | +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.6 | :ref:`hsm2-concepts-objectid-label` | Integer | +-----------------------+---------------------------------------+-------------+ | 1.3.6.1.4.1.41482.4.9 | :ref:`hsm2-concepts-label-label` | Utf8String | +-----------------------+---------------------------------------+-------------+ Pre-Loaded Certificates ------------------------ The pre-loaded certificate can be fetched as an opaque object with ID 0. This will in turn be signed by an intermediate CA which is signed by a `Yubico root CA `_. Intermediates: --------------- `E45DA5F361B091B30D8F2C6FA040DB6FEF57918E.pem `_ .. _hsm2-concepts-capability-label: Capability ============ A Capability is an attribute that can be given to an :ref:`hsm2-concepts-objects-label` allowing specific operations to be performed on or with it. Commands like digital signature generation and data decryption require (and check) for a predetermined set of Capabilities to be present on an Object. Further below is the list of existing Capabilities. It is important to know that there are no restrictions on which Capabilities can be set on an Object. Specifically, this means that it is possible to assign meaningless Capabilities to Objects that will never be able to use them, for example it is possible to have an Asymmetric Object with the Capability ``verify-hmac``. Such a Capability only makes sense for HMAC Key objects, but the device allows defining a superset. Lack of Capabilities required for a specific operation causes a command requiring that Capability to fail. Delegated Capabilities ----------------------- Every Object stored on the device has an associated set of Capabilities. There is a second set of so-called Delegated Capabilities that only Authentication Keys and Wrap Keys have. This is used to capture the indirection that Authentication Keys and Wrap Keys can be used as a means of storing more Objects on a device. In both cases Delegated Capabilities are used as a filter. For Authentication Keys, Delegated Capabilities define the set of Capabilities that can be set or "bestowed" onto an Object created by the Authentication Key. Any operation attempting to create Objects with a Capability outside of this set fails. For Wrap Keys, Delegated Capabilities define the set of Capabilities that an Object can have when imported or exported using the Wrap Key. A larger set of Capabilities causes the import operation to fail. Protocol Details ----------------- A Set of Capabilities is an 8-byte value. Each Capability is identified by a specific bit, as shown in the ``Hex Mask`` column below. .. table:: +---------------------+--------------------+-----------------+-----------------+ || Name || Hex Mask || Applicable || Description | || || || Objects || | +=====================+====================+=================+=================+ |---------------------------**Asymmetric Keys**--------------------------------| +---------------------+--------------------+-----------------+-----------------+ || delete-asymmetric | 0x0000020000000000 || authentication || Delete | || -key | || -key || Delete | || | || || Asymmetric | || | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ || generate-asymmetric| 0x0000000000000010 || authentication || Generate | || -key | || -key || Asymmetric Key | || | || || Objects | +---------------------+--------------------+-----------------+-----------------+ || put-asymmetric-key | 0x0000000000000008 || authentication || Write | || | || -key || Asymmetric Key | || | || || Objects | +---------------------+--------------------+-----------------+-----------------+ |---------------------------**Authentication Keys**----------------------------| +---------------------+--------------------+-----------------+-----------------+ || delete-authen- | 0x0000010000000000 || authentication || Delete | || tication-key | || -key || Authentication | || | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ || put-authentication | 0x0000000000000004 || authentication || Write | || -key | || -key || Authentication | || | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ || change- | 0x0000400000000000 || authentication || Replace | || authentication-key | || -key || Authentication | || | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ |--------------------------------**Certificate**-------------------------------| +---------------------+--------------------+-----------------+-----------------+ || sign-attestation- | 0x0000000400000000 || authentication || Attest | || certificate | || -key, || properties of | || | || asymmetric-key || Asymmetric | || | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | sign-ssh-certificate| 0x0000000002000000 || authentication || Sign SSH | | | || -key, || certificates | | | || asymmetric-key || | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Data**-----------------------------------| +---------------------+--------------------+-----------------+-----------------+ | decrypt-cbc | 0x0010000000000000 || authentication || Decrypt data | | | || -key, || using AES CBC | | | || symmetric-key || mode. Available| | | || || with firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ | decrypt-ecb | 0x0004000000000000 || authentication || Decrypt data | | | || -key, || using AES ECB | | | || symmetric-key || mode. Available| | | || || with firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ | decrypt-oaep | 0x0000000000000400 || authentication || Decrypt | | | || -key, || data using | | | || asymmetric-key || RSA-OAEP | +---------------------+--------------------+-----------------+-----------------+ | decrypt-pkcs | 0x0000000000000200 || authentication || Decrypt | | | || -key, || data using | | | || asymmetric-key || RSA-PKCS1v1.5 | +---------------------+--------------------+-----------------+-----------------+ | encrypt-cbc | 0x0020000000000000 || authentication || Encypt data | | | || -key, || using AES CBC | | | || symmetric-key || mode. Available| | | || || with firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ | encrypt-ecb | 0x0008000000000000 || authentication || Encypt data | | | || -key, || using AES ECB | | | || symmetric-key || mode. Available| | | || || with firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**ECDH**-----------------------------------| +---------------------+--------------------+-----------------+-----------------+ | derive-ecdh | 0x0000000000000800 || authentication || Perform | | | || -key, || ECDH | | | || asymmetric-key || | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Global**---------------------------------| +---------------------+--------------------+-----------------+-----------------+ | get-option | 0x0000000000040000 || authentication || Read device- | | | || -key || global options | +---------------------+--------------------+-----------------+-----------------+ | set-option | 0x0000000000020000 || authentication || Write device- | | | || -key || global options | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**HMAC**-----------------------------------| +---------------------+--------------------+-----------------+-----------------+ | delete-hmac-key | 0x0000080000000000 || authentication || Delete HMAC | | | || -key || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | generate-hmac-key | 0x0000000000200000 || authentication || Generate HMAC | | | || -key || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | put-mac-key | 0x0000000000100000 || authentication || Write HMAC | | | || -key || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | sign-hmac | 0x0000000000400000 || authentication || Compute HMAC | | | || -key, hmac-key || of data | +---------------------+--------------------+-----------------+-----------------+ | verify-hmac | 0x0000000000800000 || authentication || Verify HMAC | | | || -key, hmac-key || of data | +---------------------+--------------------+-----------------+-----------------+ |---------------------------------------**Log**--------------------------------| +---------------------+--------------------+-----------------+-----------------+ | get-log-entries | 0x0000000001000000 || authentication || Read the Log | | | || -key || Store | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Opaque**---------------------------------| +---------------------+--------------------+-----------------+-----------------+ | delete-opaque | 0x0000008000000000 || authentication || Delete Opaque | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ | get-opaque | 0x0000000000000001 || authentication || Read Opaque | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ | put-opaque | 0x0000000000000002 || authentication || Write Opaque | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**OTP**------------------------------------| +---------------------+--------------------+-----------------+-----------------+ | create-otp-aead | 0x0000000040000000 || authentication || Create OTP | | | || -key, || AEAD | | | || otp-aead-key || | +---------------------+--------------------+-----------------+-----------------+ | decrypt-otp | 0x0000000020000000 || authentication || Decrypt OTP | | | || -key, || | | | || otp-aead-key || | +---------------------+--------------------+-----------------+-----------------+ | delete-otp-aead-key | 0x0000200000000000 || authentication || Delete OTP | | | || -key || AEAD Key | | | || || Objects | +---------------------+--------------------+-----------------+-----------------+ || generate-otp-aead | 0x0000001000000000 || authentication || Generate OTP | || -key | || -key || AEAD Key | || | || || Objects | +---------------------+--------------------+-----------------+-----------------+ || put-otp-aead-key | 0x0000000800000000 || authentication || Write OTP AEAD | || certificate | || -key || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | randomize-otp-aead | 0x0000000080000000 || authentication || Create OTP | | | || -key, || AEAD from | | | || otp-aead-key || random data | +---------------------+--------------------+-----------------+-----------------+ || rewrap-from-otp- | 0x0000000100000000 || authentication || Rewrap AEADs | || aead-key | || -key, || from one OTP | || | || otp-aead-key || AEAD Key | || | || || Object to | || | || || another | +---------------------+--------------------+-----------------+-----------------+ || rewrap-to-otp- | 0x0000000200000000 || authentication || Rewrap AEADs | || aead-key | || -key, || to one OTP | || | || otp-aead-key || AEAD Key | || | || || Object from | || | || || another | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Random**---------------------------------| +---------------------+--------------------+-----------------+-----------------+ | get-pseudo-random | 0x0000000000080000 || authentication || Extract | | | || -key || random bytes | +---------------------+--------------------+-----------------+-----------------+ |--------------------------------------**Reset**-------------------------------| +---------------------+--------------------+-----------------+-----------------+ | reset-device | 0x0000000010000000 || authentication || Perform a | | | || -key || factory reset | | | || || on the device | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Signatures**-----------------------------| +---------------------+--------------------+-----------------+-----------------+ | sign-ecdsa | 0x0000000000000080 || authentication || Compute | | | || -key, || digital | | | || asymmetric-key || signatures | | | || || using ECDSA | +---------------------+--------------------+-----------------+-----------------+ | sign-eddsa | 0x0000000000000100 || authentication || Compute | | | || -key, || digital | | | || asymmetric-key || signatures | | | || || using EDDSA | +---------------------+--------------------+-----------------+-----------------+ | sign-pkcs | 0x0000000000000020 || authentication || Compute | | | || -key, || signatures | | | || asymmetric-key || using RSA- | | | || || PKCS1v1.5 | +---------------------+--------------------+-----------------+-----------------+ | sign-pss | 0x0000000000000040 || authentication || Compute | | | || -key, || digital | | | || asymmetric-key || signatures | | | || || using using | | | || || RSA-PSS | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Template**-------------------------------| +---------------------+--------------------+-----------------+-----------------+ | delete-template | 0x0000100000000000 || authentication || Delete | | | || -key || Template | | | || || Objects | +---------------------+--------------------+-----------------+-----------------+ | get-template | 0x0000000004000000 || authentication || Read Template | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ | put-template | 0x0000000008000000 || authentication || Write Template | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ |-----------------------------------**Wrap** ----------------------------------| +---------------------+--------------------+-----------------+-----------------+ | delete-wrap-key | 0x0000040000000000 || authentication || Delete | | | || -key || Delete Wrap | | | || || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | export-wrapped | 0x0000000000001000 || authentication || Export other | | | || -key, wrap-key || Objects under | | | || || wrap | +---------------------+--------------------+-----------------+-----------------+ || exportable-under | 0x0000000000010000 | all || Mark an Object | || -wrap | | || as exportable | || | | || under wrap | +---------------------+--------------------+-----------------+-----------------+ | generate-wrap-key | 0x0000000000008000 || authentication || Generate Wrap | | | || -key || Key Objects | +---------------------+--------------------+-----------------+-----------------+ | import-wrapped | 0x0000000000002000 || authentication || Import wrapped | | | || -key, wrap-key || Objects | +---------------------+--------------------+-----------------+-----------------+ | put-wrap-key | 0x0000000000004000 || authentication || Write Wrap Key | | | || -key || Objects | +---------------------+--------------------+-----------------+-----------------+ | unwrap-data | 0x0000004000000000 || authentication || Unwrap user- | | | || -key, wrap-key || provided data | +---------------------+--------------------+-----------------+-----------------+ | wrap-data | 0x0000002000000000 || authentication || Wrap user- | | | || -key, wrap-key || provided data | +---------------------+--------------------+-----------------+-----------------+ |------------------------------**Symmetric Keys** -----------------------------| +---------------------+--------------------+-----------------+-----------------+ || generate-symmetric | 0x0001000000000000 || authentication || Generate AES | || -key | || -key || key. Available | || | || || with firmware | || | || || version 2.3.1 | || | || || or later. | +---------------------+--------------------+-----------------+-----------------+ | put-symmetric-key | 0x0000800000000000 || authentication || Import AES key.| | | || -key || Available with | | | || || firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ | delete-symmetric-key| 0x0002000000000000 || authentication || Delete AES key.| | | || -key || Available with | | | || || firmware | | | || || version 2.3.1 | | | || || or later. | +---------------------+--------------------+-----------------+-----------------+ .. _hsm2-concepts-domain-label: Domain ============ A Domain is a logical partition that can be conceptually mapped to a container. In a YubiHSM 2 there are ``16`` independent Domains; an Object can belong to one or more Domains. .. include:: /includes/multiple-domains.rst Domains serve as a means to secure Objects so that they cannot be addressed by independent applications running on the same device. This is achieved by specifying the Object’s Domain. Only users or applications that belong to the same Domain as an Object can access it or use it. The details involved in accessing an Object are explained in the :ref:`hsm2-concepts-effective-capabilities-label` page. Protocol Details ----------------- Domains are encoded as 16-bit values, where each Domain is represented by a bit .. table:: +------------------+--------------+ | Domain Number | Hex Mask | +==================+==============+ | 1 | 0x0001 | +------------------+--------------+ | 2 | 0x0002 | +------------------+--------------+ | 3 | 0x0004 | +------------------+--------------+ | 4 | 0x0008 | +------------------+--------------+ | 5 | 0x0010 | +------------------+--------------+ | 6 | 0x0020 | +------------------+--------------+ | 7 | 0x0040 | +------------------+--------------+ | 8 | 0x0080 | +------------------+--------------+ | 9 | 0x0100 | +------------------+--------------+ | 10 | 0x0200 | +------------------+--------------+ | 11 | 0x0400 | +------------------+--------------+ | 12 | 0x0800 | +------------------+--------------+ | 13 | 0x1000 | +------------------+--------------+ | 14 | 0x2000 | +------------------+--------------+ | 15 | 0x4000 | +------------------+--------------+ | 16 | 0x8000 | +------------------+--------------+ .. _hsm2-concepts-effective-capabilities-label: Effective Capabilities (Tying It All Together) =============================================== This document describes how Object-related concepts interact with each another. Let us assume that we are establishing a Session with Authentication Key ``0xabcd`` so that the Session can use the Asymmetric Key ``0x1234`` to sign some data. We are assuming that Asymmetric Key ``0x1234`` is an RSA 2048-bit key and that we would like to generate a signature using RSASSA-PSS. .. _hsm2-concepts-create-authenticate-session-label: Create and Authenticate a Session --------------------------------- Creating and authenticating a Session requires knowledge of what the long-lived keys are (or what the associated derivation password is). When a valid Session is established, certain properties of the Authentication Key used to create the Session are inherited by the Session itself. These are: * The Domain(s) to which the Authentication Key belongs (for more information, see :ref:`hsm2-concepts-domain-label`), * The Capabilities of the Authentication Key (see :ref:`hsm2-concepts-capability-label`) and * The Delegated Capabilities (see :ref:`hsm2-concepts-capability-label`) associated with Authentication Key ``0xabcd`` . The Session's inherited properties serve to ensure that the only Objects stored in the HSM 2 that we can see and access are those that belong to the same Domain(s) as Authentication Key ``0xabcd``. Generate a Signature -------------------- The required capability must be set on both the Authentication Key used to establish the Session (Authentication Key ``0xabcd``) and the target Object used to perform the operation (Asymmetric Key ``0x1234``). Assuming that Asymmetric Key ``0x1234`` is in one such Domain, we can now continue and ask the HSM 2 to generate a signature. To do so we will send the ``Sign Data`` command over the Session. It will not execute successfully unless the arguments of the command are valid, i.e., no malformed data can be sent to the device or an error will occur. **Both** Authentication Key ``0xabcd`` and Asymmetric Key ``0x1234`` must have the Capability ``sign-pss`` set. Effective Capabilities and Role Definition ------------------------------------------ The overlap between * The Capabilities of the Authentication Key used to establish the Session and * The Capabilities of the target Object involved in the operation defines the **Effective Capabilities**. An operation on a given target Object over a given Session can succeed only if the Capabilities required by the operation are included in the Effective Capabilities. The interaction between Domains and Effective Capabilities enables flexible setup and role definition. For example, * It is possible to assign a set of Capabilities to an Object, and then distribute those Capabilities across different Authentication Keys so that each key is enabled to perform only a single operation on the target Object, and no key performs the same operation as any other key. * Similarly, it is possible to disable specified operations by not assigning the requisite Capabilities to an Authentication Key. For example, an "Administrator" Authentication Key could be enabled only to create keys while a "User" Authentication Key could be enabled only to use those same keys. Workflow --------- 1. Determine which Objects will have operations performed on them 2. Determine which Authentication Keys you will use 3. Determine which operations will be performed 4. Use a spreadsheet (if necessary) to map out the interaction between the first three items 5. With the aid of the spreadsheet, create domains to enable the interaction. .. include:: /includes/multiple-domains.rst 6. You could construct your domains: * per operation - put an Object and an Authentication Key into each domain, or * per Object - put the Authentication Key(s) for all the operations to be performed on each Object into a single domain * per Authentication Key - put the requisite Object(s) into each Domain. For example, if you wanted Jan to do the signing and Ola to do the importing, you could adopt any of the above options, but the Effective Capabilities enable you to assign far more complex webs of responsibilities. 7. Use the spreadsheet to set the Capabilities and Delegated Capabilities appropriately, "appropriateness" being determined by the Objects and operations to be performed on them. .. _hsm2-concepts-errors-label: Errors ======= Below are error codes returned by a YubiHSM device. .. table:: +--------------------------+-------+-------------------------------------------+ | Name | Value | Description | +==========================+=======+===========================================+ | OK | 0x00 | Success | +--------------------------+-------+-------------------------------------------+ | INVALID COMMAND | 0x01 | Unknown command | +--------------------------+-------+-------------------------------------------+ | INVALID DATA | 0x02 | Malformed data for the command | +--------------------------+-------+-------------------------------------------+ | INVALID SESSION | 0x03 | The session has expired or does not exist | +--------------------------+-------+-------------------------------------------+ | AUTHENTICATION FAILED | 0x04 | Wrong Authentication Key | +--------------------------+-------+-------------------------------------------+ | SESSIONS FULL | 0x05 | No more available sessions | +--------------------------+-------+-------------------------------------------+ | SESSION FAILED | 0x06 | Session setup failed | +--------------------------+-------+-------------------------------------------+ | STORAGE FAILED | 0x07 | Storage full | +--------------------------+-------+-------------------------------------------+ | WRONG LENGTH | 0x08 | Wrong data length for the command | +--------------------------+-------+-------------------------------------------+ | INSUFFICIENT PERMISSIONS | 0x09 | Insufficient permissions for the command | +--------------------------+-------+-------------------------------------------+ | LOG FULL | 0x0a | The log is full and force audit is enabled| +--------------------------+-------+-------------------------------------------+ | OBJECT NOT FOUND | 0x0b | No object found matching given ID and Type| +--------------------------+-------+-------------------------------------------+ | INVALID ID | 0x0c | Invalid ID | +--------------------------+-------+-------------------------------------------+ || SSH CA CONSTRAINT | 0x0e | Constraints in SSH Template not met | || VIOLATION | | | +--------------------------+-------+-------------------------------------------+ | INVALID OTP | 0x0f | OTP decryption failed | +--------------------------+-------+-------------------------------------------+ | DEMO MODE | 0x10 | Demo device must be power-cycled | +--------------------------+-------+-------------------------------------------+ | OBJECT EXISTS | 0x11 | Unable to overwrite object | +--------------------------+-------+-------------------------------------------+ .. _hsm2-concepts-label-label: Label ======== A Label is a sequence of bytes that can be used to add a mnemonic reference to Objects. Protocol Details ---------------- Labels are ``40`` bytes long. As far as the YubiHSM is concerned, the label is only a string of raw bytes and are not restricted to printable characters or valid UTF-8 glyphs. .. _hsm2-concepts-logs-label: Logs ====== A YubiHSM 2 device maintains a list of recently executed commands in a portion of non-volatile memory known as the Log Store. This allows to log commands across different power cycles. Specific commands are used to extract logs from the device. Since the Log Store uses non-volatile memory, it can only store up to ``62`` different entries. When the Log Store is full, it is used as a circular buffer, meaning that the least recently used entry is overwritten. It is possible to set the device in Force Audit mode. When this is done entries from the Log Store must be retrieved or commands that cannot be logged will fail. Together with individual commands, also power-on and reboot events are logged. Establishing a session is logged like any other operation, however those commands are always allowed, independent of the current status of the Log Store. This is so that it is always possible to retrieve logs and free up the Log Store, even when the device is in Force Audit mode and the Log Store is full. However, the number of unlogged authentication and power-up events is stored in a counter that is retrieved as part of the log retrieval. Entries in the Log Store are organized to form a chain of hashes. This allows auditors to verify that a given set of entries has not been tampered with after extraction, and that all entries are present. More details on the format of log entries can be found in the protocol description document for :ref:`hsm2-cmd-get-log-entries-label`. .. _hsm2-concepts-objectid-label: Object ID ================= The ID property is used to identify an Object of a given Type. This means that to **uniquely** identify an Object stored on a YubiHSM 2, the couple ``(Type, ID)`` is required. There can be more than one Object with a given ID and more than one Object with a given Type, but only one Object with a specific ID and Type. This is so that logical connections between Objects can be established by giving a set of connected Objects of different Types the same ID. An Object ID can have values in the range ``[0-65535]`` or ``[0x0000-0xffff]`` in hexadecimal. Note that this range is larger than the maximum number of Objects that can be stored in the device (256). Regardless of the type, ID ``0x0000`` and ``0xffff`` are reserved for internal Objects. Protocol Details ----------------- Object IDs are encoded as 16-bit values. .. _hsm2-concepts-options-label: Options ============ Options are device-global settings. The following Options are defined: .. table:: +-------------------+--------------+ | Option Name | Hex Value | +===================+==============+ | force-audit | 0x01 | +-------------------+--------------+ | command-audit | 0x03 | +-------------------+--------------+ The data payload is Option-specific. Force Audit ------------- This Option is used to enable Force Audit mode which prevents the device from performing additional operations whilst the :ref:`hsm2-concepts-logs-label` is full. The Option accepts three different values: * 0x00: Option disabled * 0x01: Option enabled * 0x02: Option permanently enabled (only possible to turn off through factory reset) Command Audit --------------- This Option is used to enable or disable logging of specific commands. Logging commands has a noticeable impact on performance. By default logging is enabled for all operations. The Option accepts three different values: * 0x00: Option disabled * 0x01: Option enabled * 0x02: Option permanently enabled (only possible to turn off through factory reset) Multiple commands can be specified at once with the syntax ``C1 V1, C2 V2, ..., Cn Vn`` where ``Ci`` is the Command Code and ``Vi`` is the Option Value. An example of this syntax can be found at the :ref:`hsm2-cmd-set-option-label` description. .. _hsm2-concepts-sequence-label: Sequence ============ Sequence is a one-byte value that is part of the metadata associated with an Object. The Sequence describes how many times an Object with a given ID and Type has been written. This is mostly useful for caching to determine if new data needs to be fetched from the device. Protocol Details ------------------- Sequence is 8 bits long and will wrap. .. _hsm2-concepts-session-label: Session ============ A Session is not a property of a specific Object, but rather it is used to describe a logical connection between an application and a device. Sessions are end-to-end encrypted and authenticated using Session Keys. Those keys are derived from long-lived, pre-shared Authentication Key Objects as part of the sessions authentication process. The Session creation and authentication protocol is based on Global Platform SCP03. On a single YubiHSM 2 it is possible to establish up to ``16`` independent and concurrent Sessions. Note that while multiple concurrent Sessions can be active at a given time, the device still serves as a rendezvous point. This means that time-consuming operations, like generating a long RSA key, will block commands in other Sessions. Sessions are addressed with a number in the range ``[0-15]``. Sessions have an expiration period of 30 seconds of inactivity in order to prevent resource starvation. After such a period, the device will consider a Session inactive and will move it to the pool of re-usable Sessions. Whenever a command is executed on a given Session, the inactivity timer is reset, meaning that if a Session is being constantly used then it will not expire. Some of the operations that can be performed on a YubiHSM 2 do *not* require a Session. The implications are that the command and its response will travel unencrypted to and from the device. These commands are only generic status commands, making Sessions effectively required for any meaningful operation. The long-lived keys required to derive Sessions can be explicitly used in the relevant commands. There are however built-in functionalities to derive those keys from a password using ``10,000`` iterations of ``PBKDF2`` with the salt ``Yubico``, making the process more human-friendly. **Every new or factory-reset YubiHSM 2 has a default Authentication Key with ID 1 and all Capabilities and all Domains set.** This is equivalent to a superuser or an administrator. The long-lived keys for this Object are derived using the process described before with the password password. .. WARNING:: It is crucial to delete this well-known Authentication Key before deployment.