Intel Gaudi Secure Boot Flow

This document outlines the steps required to enable Secure Boot for Intel® Gaudi® 2 and Intel® Gaudi® 3 AI accelerators on Ubuntu 22.04 and Ubuntu 24.04. Enabling this feature ensures that only signed drivers can be loaded, preventing the use of unsigned drivers and modules.

Prerequisites

• Enable Secure firmware as described in Intel Gaudi Secure Firmware Flow.

• Verify that Secure Boot is enabled in BIOS:

  

• Install Ubuntu 22.04 or Ubuntu 24.04 if it is not already installed. Follow the necessary installation procedures based on your hardware configuration.

• Make sure you have root privileges. If you do not have them, switch to root user by running sudo su.

Secure Boot Enabling Flow

Verify Secure Boot Status

Wait for the OS to boot and check the Secure Boot status by running the following:

sudo mokutil --sb-state

Expected output:

SecureBoot enabled

In case the output shows that the Secure Boot status is “disabled”, recheck your BIOS settings.

Install Headers and Modules

Install headers and modules by running the below:

sudo apt install linux-headers-`uname -r`
sudo apt install linux-modules-`uname -r`
sudo apt install linux-modules-extra-`uname -r`

Install Driver and Software

Note

• Skip the steps below in case the driver and software are already installed.

• When installing on a fresh OS, the driver initialization fails as the modules have not been signed yet. Ignore these error messages and proceed with the installation.

1. Install the driver and software as described in Install Driver and Software.

2. Install the software dependencies:

   ./habanalabs-installer.sh install -t dependencies
   

Generate Public and Private Keys

1. Set up a folder for key generation:

   sudo mkdir ~/secure_boot
   cd ~/secure_boot
   

2. Create an OpenSSL (openssl.cnf) file by using the example below:

   # This definition stops the following lines checking if $HOME isn't defined.
   HOME                    = .
   RANDFILE                = $ENV::HOME/.rnd
   [ req ]
   distinguished_name      = req_distinguished_name
   x509_extensions         = v3
   string_mask             = utf8only
   prompt                  = no
   
   [ req_distinguished_name ]
   countryName             = CA  # Update according to your configuration
   stateOrProvinceName     = Intel Ave  # Update according to your configuration
   localityName            = Folsom  # Update according to your configuration
   0.organizationName      = Intel  # Update according to your configuration
   commonName              = Secure Boot Signing  # Update according to your configuration
   emailAddress            = [email protected]  # Update according to your configuration
   
   [ v3 ]
   subjectKeyIdentifier    = hash
   authorityKeyIdentifier  = keyid:always,issuer
   basicConstraints        = critical,CA:FALSE
   extendedKeyUsage        = codesigning,1.3.6.1.4.1.311.10.3.6,1.3.6.1.4.1.2312.16.1.2
   nsComment               = "OpenSSL Generated Certificate"
   

3. Generate the private (MOK.priv) and public (MOK.der) keys using OpenSSL:

   sudo openssl req -config ./openssl.cnf -new -x509 -newkey rsa:2048 -nodes -days 36500 -outform DER -keyout "MOK.priv"
   -out "MOK.der"
   

4. Enroll the key in Linux system using mokutil. Make sure to memorize the password you enter as it is also used for MOK key enroll in BIOS:

   sudo mokutil --import MOK.der
   

Sign the Driver Module

1. Verify the installed DKMS version (e.g. habanalabs-dkms-1.20.0-543):

   sudo dpkg -l | grep habana
   

2. Check the driver path to verify the location of the installed modules:

   sudo modinfo -n habanalabs
   

3. Copy the habanalabs*.ko module to the ~/secure_boot directory and sign them with the MOK key created earlier:

   cp /lib/modules/5.15.0--generic/updates/dkms/habanalabs*.ko ~/secure_boot/
   

4. Sign the habanalabs*.ko files. The file size should increase after signing:

   cd ~/secure_boot/
   sudo kmodsign sha512 MOK.priv MOK.der habanalabs.ko
   sudo kmodsign sha512 MOK.priv MOK.der habanalabs_cn.ko
   sudo kmodsign sha512 MOK.priv MOK.der habanalabs_en.ko
   sudo kmodsign sha512 MOK.priv MOK.der habanalabs_ib.ko
   

5. Verify that the signature is appended:

   hexdump -Cv habanalabs.ko | tail -n 5
   

   Expected output:

   0021ce20  49 25 ce 79 70 d3 de b3  0c 20 a2 54 99 ee c1 ef  |I%.yp.... .T....|
   0021ce30  00 00 02 00 00 00 00 00  00 00 01 ff 7e 4d 6f 64  |............~Mod|
   0021ce40  75 6c 65 20 73 69 67 6e  61 74 75 72 65 20 61 70  |ule signature ap|
   0021ce50  70 65 6e 64 65 64 7e 0a                           |pended~.|
   

6. Copy the signed modules back to the DKMS folder where the modules are stored:

   sudo cp habanalabs*.ko /lib/modules/`uname -r` /updates/dkms/
   

7. Load the signed module. The modules should be loaded successfully when the key is already enrolled. If the key is not enrolled, the modules load fails. In this case, reboot the system and proceed to the next section:

   sudo modprobe habanalabs_en &&
   sudo modprobe habanalabs_ib &&
   sudo modprobe habanalabs_cn &&
   sudo modprobe habanalabs
   

Enroll the Key in BIOS

BIOS opens the MOK (Machine Owner Key) Management page automatically. Once opened, perform the following steps:

1. Press any key to continue:

   

2. Select “Enroll MOK”:

   

3. Select “View Key 0”:

   

4. Verify the signing name as specified in the openssl.cnf file and press Enter:

   

5. Select “Continue” to proceed to the enrollment:

   

6. Select “Yes” to enroll the key:

   

7. Enter the password created in for the key enrollment in Linux:

   

8. Select “Reboot”:

   

Verify Functionality

1. Check the Secure Boot status:

   sudo mokutil --sb-state
   

   Expected output:

   SecureBoot enabled
   

2. Run hl-smi to verify the driver status. The output should look similar to the below:

   

Known Limitations

hl-fw-loader

The hl-fw-loader does not function once Secure Boot is enabled. This includes the FW hash and the FW update features:

• In-band FW updates are not supported in Secure Boot mode, which minimizes the risk of unauthorized modifications.

• Since the hl-fw-loader operates without a driver, it can access the PCIe BAR directly. Secure Boot effectively prevents this behavior.

Workaround:

• Load the FW with the BMC using OOB protocol. For more details, refer to Gaudi 3 OOB Management Specification available the Intel Gaudi vault and Intel RDC.

• Do not enable Secure Boot on systems that utilize IPMI and I2C direct protocols as they do not support OOB FW updates.

hl_qual

hl_qual is unable to access debugfs when Secure Boot is enabled. As a result, Memory bandwidth test cannot run.

Workaround:

• Disable Secure Boot for investigations.

• Alternatively, coverage is provided by the following tests:

  • PCIe test

  • HBM_TPC_STRESS and HBM_DMA_STRESS tests

hl-smi

hl-smi daemon mode does not function once Secure Boot is enabled resulting in blocking of the virtual UART debug: hl-smi dmon -i <bus_id>.

Workaround:

Disable Secure Boot for investigations.

HCL

Habana Communications Library (HCL) is unable to bring up network interfaces due to lack of debugfs access.

Hypervisor Tools Package

Hypervisor tools package (hl-smi-async, Memory Scrub Verification) does not function once Secure Boot is enabled.