TheRock/rocm-systems/projects/cuid/docs/conceptual/what_is_cuid.rst

.. meta::
  :description: The Component Unified ID (CUID) generates a deterministic unique ID for various devices such as GPUs, CPUs, NICs, and platforms in a data center environment.
  :keywords: CUID description, CUID documentation, understand CUID, CUID information

.. _what-is-cuid:

**************
What is CUID?
**************

The Component Unified Identifier (CUID) is a unique value generated by combining device-specific data into a 122-bit ID value and displayed to the user in a UUIDv8 style format. This can either be a primary CUID or a derived CUID. The CUID library implements the necessary logic and functions to generate both types of CUIDs.

Primary CUID
=============

The following table shows the corresponding bits for device-specific data, which are further used to generate a primary CUID:

.. list-table:: Device-specific data in bits
   :widths: 20 40 60
   :header-rows: 1

   * - Bits
     - Device-specific data
     - Details

   * - 0:63
     - Device serial number/Fingerprint
     - This serial number can be available as any of the following:

       * PCIe configuration DSN caps (endpoint).

       * SMBIOS platform serial number.

       * ACPI or other architectural component identifier. If ACPI is unavailable, a software-generated fingerprint from proprietary individual marker is used.

       This serial number can be MSB 0-extended if smaller than 64 bits or truncated if larger.

   * - 64:71
     - UnitID (part 1)
     - Used if the component supports a unit ID; otherwise, this value is 0.

   * - 72:79
     - RevisionID
     - Used if the component supports revision ID; otherwise, this value is 0.

   * - 80:95
     - DeviceID
     - The device ID can be available as any of the following:

       * Present in the PCIe configuration space.

       * Present in the SMBIOS ID.

       * For CPU: Family number and Model number values combined.

   * - 96:111
     - VendorID
     - The vendor ID can be available as any of the following:

       * Present in the PCIe configuration space.

       * SMBIOS vendor ID.

       The vendor ID follows the PCIe vendor ID 16-bit value definition, such as 0x1022 or 0x1002 for AMD.

   * - 112:117
     - UnitID (part 2)
     - Used only if the UnitID value is >= 256; otherwise, this value is considered 0.

   * - 118:121
     - Device Type
     - Present as ``amdcuid_device_type_t`` in ``amd_cuid.h``.

The values present in the corresponding bit positions (first column in the preceding table) are also used to fill out a UUIDv8 style format to generate the primary CUID as shown in the following table:

.. list-table:: UUIDv8 style format
  :widths: 20 40 40
  :header-rows: 1

  * - Bit position
    - Value
    - Note

  * - 0:47
    - ID value (part 1)
    - LSB of ID value.

  * - 48:51
    - A fixed value of 8
    - The value is fixed for `RFC 9562 <https://www.rfc-editor.org/rfc/rfc9562.html>`_ compliance.

  * - 52:63
    - ID value (part 2)
    -

  * - 64:65
    - A fixed value of 10b
    - The value is fixed for `RFC 9562 <https://www.rfc-editor.org/rfc/rfc9562.html>`_ compliance.

  * - 66:127
    - ID value (part 3)
    - MSB of ID value.

Because the device serial number is protected information, the primary CUID generated from it is also protected at the same level. Users with the right privilege can consider the primary CUID as the direct link between the device and its derived CUID.

Derived CUID
=============

For typical day-to-day operations, the derived CUID is used. It is derived by hashing the primary CUID using HMAC-SHA2-256 (keyed hash) using a 256-bit key. The derived CUID obscures hardware details from lower-privilege software and prevents precomputed table attacks.

To protect the serial number consisting sensitive information, the tool users must provide the 256-bit key required for the keyed hashing function, as described in FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC). This key must be unique, random, and protected from unauthorized use. The secure storage of the key might require additional management overhead.

The key should be accessible only to privileged users or the privileged service, which can then use the key, along with the primary CUID, in the HMAC-SHA2-256 function to generate the derived CUID. Note that if the key changes due to key rotation, the derived CUID will also change. However, because the primary CUIDs always remain the same, these can always be used to trace the derived CUIDs back to their respective devices.