Chapter 7. Automatically provisioning and onboarding RHEL for Edge devices with FDO

You can build a RHEL for Edge Simplified Installer image, and provision it to a RHEL for Edge image. The FIDO device onboarding (FDO) process automatically provision and onboard your Edge devices, and exchange data with other devices and systems connected on the networks.

Important

Red Hat provides the FDO process as a Technology Preview feature and should run on secure networks. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

7.1. The FIDO device onboarding (FDO) process

Device onboarding is the process that:

  • Provisions and onboards a physical device.
  • Automatically configures credentials for this device.
  • Enables this device to securely connect and interact on the network.

With FIDO device onboarding (FDO), you can perform a secure device onboarding by adding new devices into your IOT architecture. This includes the specified device configuration that needs to be trusted and integrated with the rest of the running systems and to deploy new systems that are ready to be used. The FDO authentication is an automatic onboarding process that is triggered by the installation of a new device to securely onboard a device. The FDO protocol solves the trust and chain of ownership along with the automation needed to securely onboard a device at scale. It performs device initialization at the manufacturing stage and late device binding for its actual use. This means that actual binding of the device to a management system happens on the first boot of the device without requiring manual configuration on the device. By using the FDO protocol, you have support for automated secure devices onboarding, that is, zero touch installation and onboarding that does not need any specialized person at the edge location. After the device is onboarded, you can connect to it and apply patches, updates, and rollbacks.

With FDO, you can benefit from the following:

  • FDO is a secure and simple way to enroll a device to a management platform. Instead of embedding a Kickstart configuration to the image, FDO applies the customization, such as inclusion of sensitive data as credentials, keys or certificates directly to the ISO image.
  • FDO solves the issue of late binding to a device, enabling any sensitive data to be shared over a secure FDO channel.
  • FDO cryptographically identifies the system identity and ownership before enrolling and passing the configuration and other secrets to the system. That enables non-technical users to power-on the system.

To build a RHEL for Edge Simplified Installer image and automatically onboard it, provide an existing OSTree commit. The resulting simplified image contains a raw image that has the OSTree commit deployed. After you boot the Simplified installer ISO image, it provisions a RHEL for Edge system that you can use on a hard disk or as a boot image in a virtual machine.

The RHEL for Edge Simplified Installer image is optimized for unattended installation to a device and supports both network-base deployment and non-network-based deployments. However, for network-based deployment, it supports only UEFI HTTP boot.

The FDO protocol is based on the following servers:

  • Manufacturing server

    This server is at the manufacturer server location. The manufacturing server:

    1. Signs the device.
    2. Creates a voucher that is used to set the ownership of the device, later in the process.
    3. Binds the device to a specific management platform.
  • Rendezvous server

    This server is at the owner server location or at the platform where the Device management system will be located, for example a cloud. The Rendezvous server:

    1. Gets the voucher generated by the manufacturing server during the first device boot.
    2. Matches the device UUID with a target platform and provides information to the device about which Owner server endpoint this device must use.
  • Owner management server

    This server is at the owner server location or at the platform where the Device will be deployed. The Owner management server:

    1. Creates a secure channel between the device and the Owner server after the device authentication.
    2. Uses the secure channel to send the required information, such as files and scripts for the onboarding automation to the device.
  • Device client

    This is the server installed on the device. The Device client

    1. Starts the queries to the multiple servers where the onboarding automation will be executed.
    2. Uses TCP/IP protocols to communicate with the servers.

The following diagram represents the FIDO device onboarding workflow:

Figure 7.1. Deploying RHEL for Edge in non-network environment

FDO device onboarding

At the Manufacturer server, the device gets the FDO credentials, a set of certificates and keys to be installed on the operating system, and the Rendezvous server endpoint (URL). It also gets the Ownership Voucher, that is maintained separately in case you need to change the owner assignment.

  1. Device client reads device credential
  2. Device client connects to network
  3. At an early point, the Owner management system informs the Manufacturer Rendezvous server about the location of the Owner management system
  4. After connecting to the network, the Device client contacts the Rendezvous Server
  5. The Rendezvous Server sends the owner endpoint URL to the Device Client, and registers the device. This action connects and boots the device.
  6. The Device client connects to the Owner management system shared by the Rendezvous Server, proves that it is the correct device by signing a statement with a device key
  7. The Owner management system prove itself by signing a statement with the last key of the Owner Voucher
  8. The Owner management system provides the configuration for the device, which the Device client stores for example, in an SSH key
  9. The Device client receives and verify the Ownership voucher
  10. Then, the Device client retrieves its device credentials
  11. After that, the Owner management system reports the Device client as onboarded

    The entire FDO process is done and no longer in use in this device.

7.2. Automatically provisioning and onboarding RHEL for Edge devices

Automatically provisioning and onboarding a RHEL for Edge device involves the following high-level steps:

  1. Install and register a RHEL system
  2. Install image builder
  3. Using image builder, create a blueprint with customizations for RHEL for Edge Container image
  4. Import the RHEL for Edge blueprint in image builder
  5. Create a RHEL for Edge image embed in an OCI container with a webserver ready to deploy the commit as an OSTree repository
  6. Create a blueprint for edge-simplified-installer with customizations for storage device path and FDO customizations

    name = "fdo"
    description = "FDO blueprint"
    version = "0.0.1"
    packages = []
    modules = []
    groups = []
    distro = ""
    
    [customizations]
    installation_device = "/dev/vda"
    
    [customizations.fdo]
    manufacturing_server_url = "http://10.0.0.2:8080"
    diun_pub_key_insecure = "true"
  7. Build a simplified installer RHEL for Edge image
  8. Download the RHEL for Edge simplified installer image
  9. Install the simplified installer ISO image to a device. The FIDO FDO client runs on the Simplified Installer ISO and the UEFI directory structure makes the image bootable.
  10. The network configuration enables the device to reach out to the manufacturing server to perform the initial device credential exchange.
  11. After the system reaches the endpoint, the device credentials are created for the device.
  12. The onboard server uses the device credential to authenticate against the onboarding server. .The onboarding server passes the configuration to the device/system: After it connects to the system, it connects to their onboarding server, receives the configuration.
  13. The onboarding server provides the device with an SSH key and installs the system.
  14. Then, it reboots the system and encrypts it with a strong key stored at TPM.
  15. You can login to the system with the credentials from the blueprint you created and check the configuration that was created into the Simplified Installer ISO image.

7.3. Generating key and certificates

To run the FIDO device onboarding (FDO) infrastructure, you need to generate keys and certificates. FDO generates these keys and certificates to configure the manufacturing server. FDO automatically generates the certificates and .yaml configuration files when you install the services, and re-creating them is optional. After you install and start the services, it runs with the default settings.

Important

Red Hat provides the fdo-admin-tool generate-key-and-cert tool as a Technology Preview feature and should run on secure networks. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

Prerequisites

  • You installed the fdo-admin-cli RPM package

Procedure

  1. Create a directory for the keys and certificates:

    $ mkdir /etc/fdo/keys
  2. Generate the keys and certificates in the directory you created:

    $ for i in "diun" "manufacturer" "device_ca" "owner"; do fdo-admin-tool generate-key-and-cert $i; done
    $ ls keys
    device_ca_cert.pem device_ca_key.der diun_cert.pem diun_key.der manufacturer_cert.pem manufacturer_key.der owner_cert.pem owner_key.der
    Note

    If you used the source code and compiled it, the correct path is ./target/debug/fdo-admin-tool or ./target/debug/fdo-admin-tool, depending on your build options.

  3. Check the key and certificates that were created:

    $ tree keys

    You can see the following output:

    – device_ca_cert.pem
    – device_ca_key.der
    – diun_cert.pem
    – diun_key.dre
    – manufacturer_cert.pem
    – manufacturer_key.der
    – owner_cert.pem
    – owner_key.pem

Additional resources

  • The fdo-admin-tool generate-key-and-cert –help

7.4. Installing the manufacturing server package

The manufacturing server RPM package provides the credentials to securely onboard the device. During the device installation, the manufacturing server requests for the Rendezvous server to provide the device credential authentication against the server and install the device credentials to the installed system.

Important

Red Hat provides the fdo-manufacturing-server tool as a Technology Preview feature and should run on secure networks. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

To install the manufacturing server RPM package, complete the following steps:

Procedure

  1. Install the fdo-admin-cli package:

    # yum install -y fdo-admin-cli
  2. Install the manufacturing server RPM package:

    # yum install fdo-manufacturing-server --refresh
  3. Check if the files were correctly installed:

    $ ls /usr/share/doc/fdo

    You can see the following output:

    Output:
    manufacturing server.yml
    Owner-onboarding-server.yml
    rendezvous-server.yml
  4. Optional: Check the content of each file, for example:

    $ cat /usr/share/doc/fdo/manufacturing-server.yml
  5. Configure the manufacturing server. You must provide the following:

    • The manufacturing server URL
    • The IP address or DNS name for the rendezvous server
    • The path to the keys and certificates you generated. See Generating key and certificates section.
  6. After you install the RHEL for Edge network simplified image to your device, ensure that the manufacturer server is running on a Podman container. The manufacturing server takes care of the creating and enabling device credentials on the new device.

    $ cat /usr/share/doc/fdo/manufacturing-server.yml

7.5. Automatically onboarding an RHEL for Edge device by using FDO authentication

To prepare your device to automatically onboard a RHEL for Edge device, complete the following steps:

Prerequisites

  • You built and served an OStree container.
  • Device assembled and provisioned. This example uses a VM machine, but you can use it in a real device.
  • You are running a UEFI HTTP Boot server.
  • You installed the fdo-manufacturing-server RPM package. Run:

    # yum install -y fdo-admin-cli

Procedure

  1. Run the installation using the ISO Simplified image. You can install it from a CD-ROM or from a USB flash drive, for example.

    The installation runs the ISO Simplified Installer image, where the FDO client runs and the UEFI directory structure makes the image bootable, to burn the raw image in the ISO.

  2. Verify through the terminal that the device has reached the manufacturing service to perform the initial device credential exchange and produced an ownership voucher:

    $ ls directory-path/ownership_voucher/

    The output should show the ownership_voucher ID to indicate that the correct device credentials were added to the device.

    The onboarding server uses the device credential to authenticate against the onboarding server. It then passes the configuration to the device. After the device receives the configuration from the onboarding server, it receives an SSH key and installs the operating system on the device. Finally, the system automatically reboots, encrypts it with a strong key stored at TPM.

    After the device automatically reboots, the device contacts the onboarding server to be onboarded and the user credentials are automatically provisioned by FDO.

Verification

After the device automatically reboots, you can log in to the device with the credentials you created for the blueprint.

  1. Log in to the device by providing the username and password you created for the blueprint.
  2. Optional: verify that the configuration that was created into the raw image.