Authentication

Authentication happens during Machine onboarding, when the Machine registers to the Elemental Operator.

Elemental by default authenticates hosts through the Trusted Platform Module (TPM): the machine is authenticated through attestation, i.e., the machine proofs its identity through its TPM device.

In order for attestation to work, each onboarding machine must have a TPM 2.0 device, otherwise would not be able to register using secure TPM authentication.

TPM alternatives

The only officially supported registration method is based on TPM attestation and requires devices TPM 2.0 enabled.

If you want to enroll devices without a TPM 2.0 chip bypassing secure authentication, there are multiple ways to uniquely identify those machines and allow registration:

• emulating a TPM device via a simple software implementation
• identifying themselves through their network MAC address
• identifying themselves using their SMBIOS UUID

The authentication/identification method can be specified in the config:elemental:registration:auth field of the MachineRegistration resource.

warning

The only secure and officially supported authentication method in Elemental is the default one, based on TPM attestation. The TPM alternatives can be used for demo purposes or local deployments but are not reccomended for production use as the onboarding machines identity is not securely verified.

TPM emulation

TPM emulation performs authentication using a software that mimics TPM behavior and which is embedded in the Elemental Register client. The keys of the emulated TPM device are all generated by a single seed in a deterministic way: same seed results in the same TPM keys, so a different seed should be picked up in each enrolling host.

TPM emulation is enabled configuring the emulate-tpm and emulated-tpm-seed fields in the MachineRegistration configuration (see the config:elemental:registration section in the MachineRegistration reference for more details).

example MachineRegistration using TPM emulation

apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: fire-nodes-emulate-tpm
  namespace: fleet-default
spec:
  config:
    cloud-config:
      users:
        - name: root
          passwd: root
    elemental:
      install:
        reboot: true
        device: /dev/sda
        debug: true
      registration:
        emulate-tpm: true
        emulated-tpm-seed: -1
  machineInventoryLabels:
    element: fire
    manufacturer: "${Product/Vendor}"
    productName: "${Product/Name}"
    serialNumber: "${Product/Serial Number}"
    machineUUID: "${Product/UUID}"

TPM emulation configuration is detailed in the TPM emulation configuration section.

MAC address identification

When using MAC address identification, the host registers to the Elemental Operator using the MAC address from its Network Interface Card (NIC) as an identifier. In case the machine has more than one network interface, the MAC addresses are sorted lexicographically and the first one is selected.

To replace TPM authentication with MAC address identification, it is enough to set the mac value to the auth field in the config:elemental:registration section in the MachineRegistration reference.

example MachineRegistration using the MAC address as machine identifier

apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: fire-nodes-mac
  namespace: fleet-default
spec:
  config:
    cloud-config:
      users:
        - name: root
          passwd: root
    elemental:
      install:
        reboot: true
        device: /dev/sda
        debug: true
      registration:
        auth: mac
  machineInventoryLabels:
    element: fire
    manufacturer: "${Product/Vendor}"
    productName: "${Product/Name}"
    serialNumber: "${Product/Serial Number}"
    machineUUID: "${Product/UUID}"

warning

The MAC address is considered unique by the Elemental Operator. This is true for phisical devices, while if using VirtualMachines from different hypervisors and different network segments it is up to the administrator to ensure that the registering VMs have a unique MAC address.

SMBIOS UUID identification

The System Management BIOS (SMBIOS) specification defines data structures that can be used to read management information produced by the BIOS of a host.

When using the sys-uuid value as the auth field of the config:elemental:registration section in the MachineRegistration, the host registers to the Elemental Operator using the UUID value from the System Information table of the host SMBIOS data.

example MachineRegistration using the UUID from the SMBIOS System Information table as machine identifier

apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: fire-nodes-mac
  namespace: fleet-default
spec:
  config:
    cloud-config:
      users:
        - name: root
          passwd: root
    elemental:
      install:
        reboot: true
        device: /dev/sda
        debug: true
      registration:
        auth: sys-uuid
  machineInventoryLabels:
    element: fire
    manufacturer: "${System Information/Manufacturer}"
    productName: "${System Information/Product Name}"
    serialNumber: "${System Information/Serial Number}"
    machineUUID: "${System Information/UUID}"

warning

The SMBIOS System information/UUID value should be filled by the hardware vendor as a unique UUID for the host.

The SMBIOS data is not always reliable. This depends on the manufacturer. You may experience the UUID being missing, or the same UUID being applied to multiple devices within the same batch.

It is up to the administrator to ensure that the machines have unique System information/UUID SMBIOS values (the dmidecode tool could be of help), otherwise the machines will keep overwriting the same MachineInventory resource and the Elemental provisioning will fail.