IDevID and IAK
=================

.. warning::
    This page is still under development and not complete. It will be so until
    this warning is removed.


Introduction
------------

The IEEE 802.1AR Standard [#]_ defines a secure device identifier (DevID) as "a cryptographic identity that is bound to a device and used to assert the device’s identity".  The initial identity is defined as an IDevID/IAK ("I" for initial) and is first created in the factory where the server, switch, or other device is built before shipping. The IDevID credential is intended to be usable for the life of the product.

The IEEE 802.1AR Standard can be used together with TPM-based keys and certificates as described in [#tcg]_. This standard from the `Trusted Computing Group (TCG) <https://trustedcomputinggroup.org/>`_ applies the IEEE Standard 802.1AR device identity module definition and formatting to keys protected by a TPM (conforming to version 2.0 of the TPM specification). The security of IDevIDs/IAKs are anchored in the TPM and its Endorsement Key (EK) as well as in the correct provisioning of the IDevID/IAK certificates by the device manufacturer.

The IDevID and IAK keys are generated by the TPM at the OEM factory and certified by the device manufacturer's certificate authority (CA). The CA enforces the TCG-defined provisioning protocol which ensures that the IDevID/IAK keys are resident in the TPM, similar to the standard process used to verify that an attestation key (AK) and endorsement key (EK) are colocated within a TPM. The IDevID certificates include information about the identity of the device, for example, the device's serial number. This can be used to bootstrap onboarding of devices for verification by Keylime. Using IDevID provides important security guarantees by ensuring that a device is identifiable, genuine and authorised. This allows for secure, automatic enrolment of devices even when they are geographically distributed (in remote or branch offices, for example).

How to use 
---------- 

To allow IDevID and IAK registration, the registrar needs to be, at minimum, loaded with the manufacturer certificates used to provision the IDevID and IAK and configured to accept any TPM identity for registration (the default behaviour). Optionally, the registrar can be configured to **require** an IDevID and IAK in order to register new devices. The agent needs to be configured to turn on IDevID and IAK regeneration, with the correct template selected, and also needs to know where it's IDevID and IAK certificates are stored.

Registrar
^^^^^^^^^

The certificates for the authority that signed the registering device's IAK and IDevID need to be added to the ``TPM_CERT_STORE``, the default location being ``/var/lib/keylime/tpm_cert_store``. The cert store can hold certificates fom multiple authorities if you have devices from different manufacturers. Keylime will look through the store until a match is detected.

With the manufacturer certificates added, the Keylime registrar will accept IDevIDs and IAKs received from agents during registration. In the default configuration, the registrar will not prevent an agent from registering with just an EK instead (and no IDevID and IAK). To disable this behaviour and make the use of IDevID and IAK a requirement for registering devices, the configuration option ``tpm_identity`` needs to be changed, either by modifying ``registrar.conf``:

    tpm_identity = iak_idevid

or alternatively by overriding the configuration option by setting the ``KEYLIME_REGISTRAR_TPM_IDENTITY`` environment variable.

Agent
^^^^^

For the agent to use its IDevID and IAK to register, the IAK and IDevID certificates need to be added to the ``keylime_dir`` and named ``iak-cert.crt`` and ``idevid-cert.crt`` respectively. Alternatively, the ``iak_cert`` and ``idevid_cert`` configuration options can be set to absolute paths or filenames relative to the ``keylime_dir``.

As with the registrar, the configuration options can either be set in the config file, ``agent.conf`` for the agent, or overridden using environment variables.

Next, the functionality should be enabled by changing ``enable_iak_idevid`` to ``true``. Finally, if using a standard template, the ``iak_idevid_template`` configuration option should be left with the default value ``detect``. This will cause the Keylime agent to detect what template was used from the imported certificates. With all this complete your agent should be ready to register using its IDevID and IAK.

.. note::
    The following information can be used to manually set either the template or the individual algorithms and should not be required for the majority of users. The detect function mentioned above should be used instead.

The template used by the certificates can also be manually specified. If the wrong template is chosen, the agent will fail to match the regenerated keys against the imported certificates and registration will fail.

The template should be set using the ``iak_idevid_template`` configuration option. As an alternative, the ``iak_idevid_template`` option can be set to ``manual`` and the ``iak_idevid_asymmetric_alg`` and ``iak_idevid_name_alg`` options can be used to manually set the algorithms, but this is not recommended, and **these options are ignored** if ``iak_idevid_template`` is not set to ``manual``.

Template definitions can be found in section 7.3.4 of [#tcg]_. If you don't know what template your IAK and IDevID use, the following table can be used to match your algorithms to a template:

==========  ===============  ==========
 Template    asymmetricAlg    nameAlg
==========  ===============  ==========
H-1         RSA 2048         SHA256
H-2         ECC NIST P256    SHA256
H-3         ECC NIST P384    SHA384
H-4         ECC NIST P521    SHA512
H-5         ECC SM2 P256     SM3_256
==========  ===============  ==========


.. [#] IEEE Standard for Local and Metropolitan Area Networks - Secure Device Identity, https://standards.ieee.org/standard/802_1AR-2018.html  
.. [#tcg] TPM 2.0 Keys for Device Identity and Attestation, https://trustedcomputinggroup.org/wp-content/uploads/TPM-2p0-Keys-for-Device-Identity-and-Attestation_v1_r12_pub10082021.pdf

