diff --git a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/_index.md b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/_index.md index 306d47b171..a2e2fbd538 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/_index.md @@ -1,30 +1,71 @@ --- -title: Arm CCA BootSync -description: Learn how Arm CCA BootSync transfers boot-time configuration and secret data to a Realm while launching CCA Realms on an FVP with RME support. +title: Secure Realms during boot using Arm Confidential Compute Architecture (CCA) BootSync +description: Use Arm CCA BootSync on an RME-enabled FVP to inject UEFI variables and secrets to unlock the disk during boot, then verify Secure Boot and encrypted root file system startup. -draft: true -cascade: - draft: true - minutes_to_complete: 60 who_is_this_for: This Learning Path is for developers who want to understand how Arm CCA BootSync supports early Realm boot workflows such as UEFI Secure Boot and encrypted disk boot. learning_objectives: - - Explain why BootSync is needed before the Realm guest operating system has networking. - - Describe how the Boot Injection Protocol uses key exchange, attestation, and Boot Information Blocks to support the BootSync workflow. + - Understand why BootSync is needed before the Realm guest operating system has networking. + - Understand how the Boot Injection Protocol uses key exchange, attestation, and Boot Information Blocks to support the BootSync workflow. - Use BootSync to inject UEFI variables and secret data into an Arm CCA Realm. - - Launch Arm CCA Realms with UEFI Secure Boot and an encrypted root file system on an Armv9-A AEM Base FVP with RME support. + - Launch Arm CCA Realms with UEFI Secure Boot and an encrypted root file system on an Armv9-A AEM Base Fixed Virtual Platform (FVP) with Realm Management Extension (RME) support. prerequisites: - - An AArch64 or x86_64 computer running Linux or macOS. Cloud-based instances can also be used; see the [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/) + - A cloud-based instance or an AArch64 or x86_64 computer running Linux. For more information about using cloud-based instances, see the [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/) Learning Path. - Completion of the [Run an application in a Realm using the Arm Confidential Compute Architecture (CCA)](/learning-paths/servers-and-cloud-computing/cca-container/) Learning Path +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-07-17T18:27:39Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 5b4a562e119669be2adcee1e0f304ca8cd2032cc5b6056ad01a88251019c010c + summary_generated_at: '2026-07-17T18:27:39Z' + summary_source_hash: 5b4a562e119669be2adcee1e0f304ca8cd2032cc5b6056ad01a88251019c010c + faq_generated_at: '2026-07-17T18:27:39Z' + faq_source_hash: 5b4a562e119669be2adcee1e0f304ca8cd2032cc5b6056ad01a88251019c010c + summary: >- + You'll use Arm CCA BootSync on an RME-enabled Armv9-A AEM Base FVP + to deliver UEFI variables and secrets to a Realm during early boot, then validate Secure Boot + and encrypted disk startup. First, you'll launch a Realm without injected data to observe + firmware attestation. Next, you'll provide variable data for BootSync to complete and verify that Secure Boot rejects the unsigned kernel. After signing the kernel, you'll verify that Secure Boot is active. Finally, you'll encrypt the Realm root file system, inject the file system decryption secret through + BootSync, and confirm that the disk unlocks during boot. + faqs: + - question: Do I need networking inside the Realm to deliver boot data? + answer: >- + No. BootSync operates before the guest operating system has networking and uses the Boot Injection protocol to provide early boot data. + - question: How do I know BootSync requested variable data? + answer: >- + In the User Context service log, you'll see `BIB Variable Data Requested` + and the expected `_VAR.dat` file name. If the file is missing, + BootSync reports `BootSyncNotDone`, and the Realm boots without Secure + Boot enabled. + - question: What result should I expect when Secure Boot is configured but the kernel is unsigned? + answer: >- + The unsigned kernel is rejected. This confirms that UEFI Secure Boot is enforcing signature + verification. + - question: After I sign the kernel, how do I verify that Secure Boot is enabled? + answer: >- + The signed kernel boots successfully and the Secure Boot UEFI variable reports `1`. Check + that value to confirm the state. + - question: How do I confirm the encrypted root file system unlocks correctly? + answer: >- + After BootSync supplies the correct passphrase, the boot log reports + `LUKS partition unlocked, switching root`. Run `df -h` and verify that + `/dev/mapper/cryptroot` is mounted at `/`. +# END generated_summary_faq + author: - Anton Antonov - Pareena Verma -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false @@ -36,7 +77,6 @@ armips: - Cortex-A operatingsystems: - Linux - - macOS tools_software_languages: - FVP - RME @@ -77,3 +117,4 @@ weight: 1 # _index.md always has weight of 1 to order corr layout: "learningpathall" # All files under learning paths have this same wrapper learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. --- + diff --git a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/cca-bootsync.md b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/cca-bootsync.md index bd61e6f726..631dc8e7bd 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/cca-bootsync.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/cca-bootsync.md @@ -1,6 +1,7 @@ --- # User change -title: "Overview of Arm CCA BootSync and the Boot Injection Protocol" +title: Understand Arm CCA BootSync and the Boot Injection protocol +description: Understand how Arm CCA BootSync uses key exchange, attestation, and Boot Information Blocks to deliver trusted configuration and secret data during Realm boot. weight: 2 # 1 is first, 2 is second, etc. @@ -8,45 +9,40 @@ weight: 2 # 1 is first, 2 is second, etc. layout: "learningpathall" --- -## Design overview +## What Arm CCA BootSync is -Arm CCA BootSync is a boot-time synchronization mechanism for Arm CCA Realms. It lets Realm guest firmware obtain configuration and secret data before the guest operating system is running. This matters because early firmware does not have a network stack, but workflows such as UEFI Secure Boot and encrypted disk boot still need trusted inputs during that early boot window. +Arm Confidential Compute Architecture (CCA) BootSync is a boot-time synchronization mechanism for Arm CCA Realms. The mechanism lets Realm guest firmware obtain configuration and secret data before the guest operating system is running. This matters because early firmware doesn't have a network stack, but workflows such as UEFI Secure Boot and encrypted disk boot still need trusted inputs during that early boot window. -The reference implementation uses the *Boot Injection Protocol*, named the BIB protocol in the Boot Injection appendix of the Realm Host Interface (RHI) specification. In this Learning Path, you use BootSync to provide two kinds of data to a Realm: +The reference implementation uses the *Boot Injection protocol*. The Boot Injection appendix of the [Realm Host Interface (RHI) specification](https://developer.arm.com/documentation/den0148/latest/) refers to the protocol as the BIB protocol. + +You'll use BootSync to provide two kinds of data to a Realm: - Variable data, such as UEFI variables used to configure Secure Boot. - Secret data, such as a disk unlock passphrase or other boot-time secret. -The data is not just copied into the Realm. BootSync first establishes a protected exchange between the Realm guest firmware and a *User Context* service controlled by the Realm initiator. The User Context service runs outside the Realm, but it represents the party that decides whether the Realm should receive the requested boot information. +Before data is copied into the Realm, BootSync establishes a protected exchange between the Realm guest firmware and a *User Context* service controlled by the Realm initiator. The User Context service runs outside the Realm, but it decides whether the Realm should receive the requested boot information. -## Component roles +## Components of the BootSync flow The BootSync flow spans both the Normal World host and the Realm World guest: - The *Realm guest firmware* starts BootSync early in boot and requests boot information. - The *Realm Management Monitor* (RMM) exposes Realm services and creates attestation reports for the Realm. -- The *Virtual Machine Manager* (VMM), `lkvm-bootsync` in this Learning Path, forwards Realm Host Interface calls between the Realm and host user space. +- The *Virtual Machine Manager* (VMM), in this case `lkvm-bootsync`, forwards Realm Host Interface calls between the Realm and host user space. - The *User Context* service receives BootSync requests, verifies attestation evidence, and returns encrypted boot information when the Realm is allowed to receive it. The practical result is that the Realm firmware can get boot-time data without needing direct networking. The host can carry the request, but the release decision belongs to the User Context after the Realm has provided attestation evidence. -## Boot Injection Protocol stages +## Stages of the Boot Injection protocol -The Boot Injection Protocol has three logical stages: +The Boot Injection protocol has three logical stages: 1. Key exchange establishes a secure session between the Realm guest firmware and the User Context service. The reference implementation uses ECDH over the P-384 curve, derives keys with HKDF-SHA512, and encrypts protocol data with AES-GCM. 2. Attestation lets the Realm guest firmware request an attestation report from the RMM. The binding key from the secure session is used as challenge data, so the User Context can bind the attestation evidence to this BootSync exchange. 3. Boot Information Blocks carry the requested boot data after attestation succeeds. -## What you will validate - -The exercises intentionally show both failure and success cases: - -- First, you launch a Realm without injection of any boot data. This demonstrates that the firmware can run successful attestation and ask for BootSync data. -- Next, you add the variable data file. BootSync completes, UEFI Secure Boot is enabled, and the unsigned kernel is rejected. -- Then, you sign the Realm kernel. The Realm boots with UEFI Secure Boot enabled, and the Secure Boot UEFI variable reports `1`. -- Finally, you encrypt the Realm root file system and use BootSync secret data to provide the unlock passphrase during boot. +## What you've learned and what's next -For more detail, see the [ArmCcaBootSync README](https://gitlab.arm.com/linux-arm/edk2-cca/-/blob/cca/4441_measured_boot_v1/ArmVirtPkg/ArmCcaBootSync/Readme.md), the [Realm Management Monitor specification](https://developer.arm.com/documentation/den0137/latest/), and the [Realm Host Interface specification](https://developer.arm.com/documentation/den0148/latest/). +You’ve learned how Arm CCA BootSync uses key exchange, attestation, and Boot Information Blocks to provide trusted data during Realm boot. -In the next section, you will launch Realms and see how Arm CCA BootSync can inject UEFI variables and secret data during early boot. +Next, you'll launch Realms and see how Arm CCA BootSync can inject UEFI variables and secret data during early boot. diff --git a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/flow.md b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/flow.md index 34f9849017..3a6fb44775 100644 --- a/content/learning-paths/servers-and-cloud-computing/cca-bootsync/flow.md +++ b/content/learning-paths/servers-and-cloud-computing/cca-bootsync/flow.md @@ -1,26 +1,32 @@ --- # User change -title: "Arm CCA BootSync" +title: Configure UEFI Secure Boot and disk encryption in Arm CCA Realms +description: Configure Arm CCA BootSync on an FVP, verify UEFI Secure Boot with a signed kernel, and unlock an encrypted Realm root file system. weight: 3 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -## Overview +## What you will configure and validate -In this section, you will run the **User Context** service in a Docker container, launch a **CCA Realm** on **Arm FVP** in a separate Docker container, and use Arm CCA BootSync to provide Realm UEFI variables and secret data during early boot. +You'll configure and validate both failure and success cases: -The flow uses two terminals: +- First, you'll launch a Realm without injecting any boot data to see that the firmware can run successful attestation and ask for BootSync data. +- Next, you'll add the variable data file. BootSync completes, UEFI Secure Boot is enabled, and the unsigned kernel is rejected. +- Then, you'll sign the Realm kernel and validate Secure Boot. The Realm boots with UEFI Secure Boot enabled, and the Secure Boot UEFI variable reports `1`. +- Finally, you'll encrypt the Realm root file system and use BootSync secret data to provide UEFI variables and the unlock passphrase during early boot. You'll unlock the encrypted file system. -- Terminal 1 runs the User Context service. This service represents the Realm initiator and decides whether to release BootSync data. -- Terminal 2 runs the Arm CCA FVP and launches Realm VMs using `lkvm-bootsync`. +You'll run the User Context service in a Docker container and launch CCA Realms on an Arm Fixed Virtual Platform (FVP) in a separate Docker container. -You will first observe a BootSync failure when required data is missing, then fix the flow and validate UEFI Secure Boot. Finally, you will use BootSync secret data to unlock an encrypted root file system. +You'll use two terminals: + +- In the User Context terminal, you'll run the User Context service. This service represents the Realm initiator and decides whether to release BootSync data. +- In the FVP terminal, you'll run the Arm CCA FVP and launch Realm virtual machines using `lkvm-bootsync`. ## Install dependencies -Start by installing Docker. On Ubuntu 24.04 LTS, set up Docker's APT repository so you can pull and run the pre-built Learning Path containers: +Set up Docker's `apt` repository so you can pull and run the pre-built containers: ```bash # Add Docker's official GPG key: @@ -38,24 +44,23 @@ echo \ sudo apt-get update ``` -Install Git and Docker packages. `git` is useful for inspecting linked source files, and the Docker packages provide the runtime used by both the User Context and FVP containers: +Install Docker packages for the runtime used by both the User Context and FVP containers, and optionally install `git` for inspecting linked source files: ```bash sudo apt-get install -y git docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` -Add your user name to the Docker group so you can run Docker without `sudo`. The group change applies to new shells; `newgrp docker` updates the current terminal: +Add your user name to the Docker group so you can run Docker without `sudo`: ```bash sudo usermod -aG docker $USER newgrp docker ``` +The group change applies to new shells; `newgrp docker` updates the current shell. -## Start User Context service - -First, pull the Docker image with the pre-built User Context service, and then run the container. +## Start the User Context service -The `cca-trustee` Docker network is important. It lets the FVP container resolve the User Context service by container name, `user-context`, when `lkvm-bootsync` later uses `--service-ip user-context`. +In the User Context terminal, pull the Docker image with the pre-built User Context service. Then, run the container: ```bash docker pull armswdev/cca-learning-path:cca-key-broker-v4 @@ -63,25 +68,27 @@ docker network create cca-trustee docker run --rm -it --network cca-trustee --name user-context armswdev/cca-learning-path:cca-key-broker-v4 ``` -Now within your running Docker container, start the User Context service using the `run-user-context-service.sh` script. -The User Context service in this Learning Path is part of the [EDK2](https://gitlab.arm.com/linux-arm/edk2-cca/-/tree/cca/4441_measured_boot_v1/ArmVirtPkg/ArmCcaBootSync/UserContext) project. -It has been created specifically for POC purposes, so is intentionally small and simple to understand, and is not designed for production use. +The `cca-trustee` Docker network is important. It lets the FVP container resolve the User Context service by container name, `user-context`, when `lkvm-bootsync` later uses `--service-ip user-context`. + +In the User Context terminal, start the User Context service inside the running container using the `run-user-context-service.sh` script. +The User Context service is part of the [EDK2](https://gitlab.arm.com/linux-arm/edk2-cca/-/tree/cca/4441_measured_boot_v1/ArmVirtPkg/ArmCcaBootSync/UserContext) project. +Created specifically as a proof of concept, it's intentionally small and not designed for production use. When the script starts for the first time, it generates Secure Boot signing certificates and creates a Provisioning Data file. The Provisioning Data is a binary file generated by [GenPd.py](https://gitlab.arm.com/linux-arm/edk2-cca/-/blob/cca/4441_measured_boot_v1/ArmVirtPkg/ArmCcaBootSync/Scripts/GenPd.py) script. The file contains EFI variable definitions required for enabling UEFI Secure Boot. -You will be asked for a passphrase for the Secure Boot signing certificates. Remember it because you will use it again when signing the Realm kernel. +You'll be asked for a passphrase for the Secure Boot signing certificates. Remember it because you'll use it again when signing the Realm kernel. ```bash ./run-user-context-service.sh ``` -## Launch a CCA Realm without Secure Boot enabled +## Validate BootSync failure without boot data -With the User Context service running in one terminal, open up a new terminal in which you will run CCA realms. +With the User Context service running in the User Context terminal, open the FVP terminal. -Pull the Docker image with the pre-built FVP and CCA reference software stack, and then run the container connected to the same Docker network: +Pull the Docker image with the pre-built FVP and CCA reference software stack. Then, run the container connected to the same Docker network: ```bash docker pull armswdev/cca-learning-path:cca-simulation-v4 @@ -106,13 +113,7 @@ host login: root (host) # ``` -Change directory to `/cca` and use `lkvm-bootsync` to launch a guest Linux in a Realm. - -The BootSync-specific parameters are: - -- `--service-ip user-context` points the VMM to the User Context container on the Docker network. -- `--service-port 1080` uses the default User Context service port. -- `--realm-pv ARMCCA01` sets the Realm Personalization Value (RPV). The User Context uses this value as a file-name prefix when looking for BootSync data, such as `ARMCCA01_VAR.dat` and `ARMCCA01_SEC.dat`. +Change directory to `/cca` and use `lkvm-bootsync` to launch a guest Linux in a Realm: ```bash cd /cca @@ -124,10 +125,16 @@ cd /cca --service-port 1080 \ --realm-pv ARMCCA01 ``` +The BootSync-specific parameters are: + +- `--service-ip user-context` points the VMM to the User Context container on the Docker network. +- `--service-port 1080` uses the default User Context service port. +- `--realm-pv ARMCCA01` sets the Realm Personalization Value (RPV). The User Context uses this value as a file-name prefix when looking for BootSync data, such as `ARMCCA01_VAR.dat` and `ARMCCA01_SEC.dat`. -You should see the realm boot. +After running the command, you'll see the Realm boot. + +The output is similar to: -In the realm boot output, UEFI Secure Boot is not mentioned in EFI messages. This is expected because you have not yet provided the UEFI variable data that enables Secure Boot: ```output Shell> bootaa64.efi root=/dev/vda2 acpi=force ip=on EFI stub: Booting Linux Kernel... @@ -135,7 +142,9 @@ EFI stub: Generating empty DTB EFI stub: Exiting boot services... ``` -After the realm boots, log in, using the root again as the username: +UEFI Secure Boot isn't mentioned in the EFI messages. This is expected because you've not yet provided the UEFI variable data that enables Secure Boot. + +After the Realm boots, log in using the root again as the username: ```output Welcome to the CCA realm @@ -151,13 +160,13 @@ efivar -p -d -n {global}-SecureBoot 0 ``` -Stop the realm: +Stop the Realm: ```bash poweroff ``` -On the terminal with the User Context service, you can see that the Realm firmware requested a Variable Data file, but the file is missing. This is the intentional failure in this step: BootSync completed enough of the protocol to request boot information, but the User Context had no `ARMCCA01_VAR.dat` file to release. +In the User Context terminal, you can see that the Realm firmware requested a Variable Data file, but the file is missing: ```output INFO: BIB Variable Data Requested @@ -168,34 +177,36 @@ Info: Session State: ConnectionEstablished Info: Attestation State: AttSuccess Info: BootSync State: BootSyncNotDone ``` +This is an intentional failure: BootSync completed enough of the protocol to request boot information, but the User Context had no `ARMCCA01_VAR.dat` file to release. -In the next step, you will add the missing Boot Information Block data and repeat the launch. +Next, you'll add the missing Boot Information Block data and repeat the launch. -## Launch a CCA Realm with Secure Boot enabled +## Pass UEFI variable data and validate unsigned kernel rejection -On the terminal with the User Context service stop the service by pressing `Ctrl-C`. +In the User Context terminal, stop the service by pressing `Ctrl-C`. -The RPV and file names used here are details of this Learning Path's reference implementation. One User Context service can support multiple Realms by using the RPV as a file-name prefix. A Realm launched with `--realm-pv ARMCCA01` requests files that start with `ARMCCA01`. If the matching files are missing, BootSync can establish a session and complete attestation, but the User Context cannot provide the requested boot information. +The RPV and file names used here are details of this Learning Path's reference implementation. One User Context service can support multiple Realms by using the RPV as a file-name prefix. A Realm launched with `--realm-pv ARMCCA01` requests files that start with `ARMCCA01`. If the matching files are missing, BootSync can establish a session and complete attestation, but the User Context can't provide the requested boot information. -Copy the generated Provisioning Data file to a Realm variable data file with the name `_VAR.dat`. Because you launched the Realm with `--realm-pv ARMCCA01`, the User Context service looks for `ARMCCA01_VAR.dat`: +Copy the generated Provisioning Data file to a Realm variable data file with the name `_VAR.dat`: ```bash cp SecureBoot/SecBootCert/pd.bin SecureBoot/ARMCCA01_VAR.dat ``` +Because you launched the Realm with `--realm-pv ARMCCA01`, the User Context service looks for `ARMCCA01_VAR.dat`. -Create a Secret Data file with data that will be shared with a Realm using the same RPV. This first secret is just a visible test string so you can prove that the data reaches the Realm: +Create a Secret Data file with a test string that'll be shared with a Realm using the same RPV: ```bash echo "My Realm secret data" > SecureBoot/ARMCCA01_SEC.dat ``` -Relaunch the User Context service: +In the User Context terminal, relaunch the User Context service: ```bash ./run-user-context-service.sh ``` -On the terminal with FVP, relaunch the Realm with the same RPV. Keeping the same `--realm-pv ARMCCA01` is what links the Realm request to the files you just created: +In the FVP terminal, relaunch the Realm with the same RPV: ```bash cd /cca @@ -208,7 +219,9 @@ cd /cca --realm-pv ARMCCA01 ``` -On the terminal with the User Context service, you can see that attestation succeeded and BootSync completed. This means the User Context released the Boot Information Blocks to the Realm firmware: +Keeping the same `--realm-pv ARMCCA01` is what links the Realm request to the files you created. + +In the User Context terminal, you can see that attestation succeeded and BootSync completed: ```output Info: Received FIN. Disconnecting. @@ -216,6 +229,7 @@ Info: Session State: UnConnected Info: Attestation State: AttSuccess Info: BootSync State: BootSyncCompete ``` +This means the User Context released the Boot Information Blocks to the Realm firmware. The Realm now fails to boot the Linux kernel: @@ -224,17 +238,19 @@ Shell> bootaa64.efi root=/dev/vda2 acpi=force ip=on Script Error Status: Access Denied (line number 1) ``` -Stop the realm by entering "reset" command to EFI shell prompt: +This failure is expected. The same kernel booted before Secure Boot was enabled, but now the firmware enforces the Secure Boot variables injected by BootSync. The kernel image isn't signed yet, so firmware rejects it. + +Stop the realm by running `reset` in the EFI shell prompt: ```bash reset ``` -This failure is expected. The same kernel booted before Secure Boot was enabled, but now the firmware enforces the Secure Boot variables injected by BootSync. The kernel image is not signed yet, so firmware rejects it. You will fix that in the next step. +Next, you'll launch a Realm with a signed kernel image. -## Launch a CCA Realm with Secure Boot enabled and a signed Linux kernel +## Sign the kernel and verify Secure Boot -On the terminal with FVP, use the `sign_guest_kernel.sh` script to sign the Realm Linux kernel with the Secure Boot certificate generated earlier by the User Context setup script. You will be asked for the passphrase you used for the Secure Boot signing certificates. +In the FVP terminal, use the `sign_guest_kernel.sh` script to sign the Realm Linux kernel with the Secure Boot certificate generated earlier by the User Context setup script. When prompted, enter the passphrase you used for the Secure Boot signing certificates: ```bash { output_lines="2-3" } sign_guest_kernel.sh @@ -243,7 +259,7 @@ Enter PEM pass phrase: Signing Unsigned original image ``` -Relaunch the Realm. Use the same User Context service, service port, and RPV so the Realm receives the same Secure Boot variable data: +In the FVP terminal, relaunch the Realm. Use the same User Context service, service port, and RPV so the Realm receives the same Secure Boot variable data: ```bash cd /cca @@ -256,9 +272,8 @@ cd /cca --realm-pv ARMCCA01 ``` -You should see the Realm boot. +The output is similar to: -In the Realm boot output, the EFI messages show that UEFI Secure Boot is enabled: ```output Shell> bootaa64.efi root=/dev/vda2 acpi=force ip=on EFI stub: Booting Linux Kernel... @@ -266,6 +281,7 @@ EFI stub: UEFI Secure Boot is enabled. EFI stub: Generating empty DTB EFI stub: Exiting boot services... ``` +The EFI messages show that UEFI Secure Boot is enabled. After the Realm boots, log in using `root` as the username: @@ -290,8 +306,8 @@ efivar -d -p -n {global}-SetupMode 0 ``` -Via [securityfs](https://www.kernel.org/doc/Documentation/ABI/testing/securityfs-secrets-coco) you can -access the secret data shared with the Realm. In this demo, the data is exposed under the `GRUB_EFI_DISKPASSWD_GUID` entry: +Using [securityfs](https://www.kernel.org/doc/Documentation/ABI/testing/securityfs-secrets-coco), you can +access the secret data shared with the Realm from under the `GRUB_EFI_DISKPASSWD_GUID` entry: ```bash { output_lines="3" } mount -t securityfs none /sys/kernel/security @@ -299,51 +315,53 @@ cat /sys/kernel/security/secrets/coco/736869e5-84f0-4973-92ec-06879ce3da0b My Realm secret data ``` -Stop the realm: +Stop the Realm: ```bash poweroff ``` -You have successfully started a realm with UEFI Secure Boot configured and enabled via Arm CCA BootSync. +You've successfully started a Realm with UEFI Secure Boot configured and enabled using Arm CCA BootSync. -## Launch a CCA Realm with an encrypted root file system +## Encrypt the root file system and update secret data for disk unlock -The secure data shared with a Realm via Arm CCA BootSync can also be used to provide access to encrypted file systems. In this part of the Learning Path, you encrypt the root file system, observe a failed unlock when the wrong secret is available, and then update the BootSync secret so the Realm can unlock the disk during boot. +You can use the secret data shared with a Realm using Arm CCA BootSync to provide access to encrypted file systems. You'll now encrypt the root file system, observe a failed unlock when the wrong secret is available, and update the BootSync secret so the Realm can unlock the disk during boot. -{{% notice Access to encrypted partitions %}} +### Encrypt the root partition + +{{% notice Note %}} There are different ways to provide a Realm with access to encrypted partitions using Arm CCA BootSync. For example: - Use an updated version of [Grub](https://gitlab.arm.com/linux-arm/grub-cca/-/tree/cca/4441_measured_boot_v1) as a boot loader. -This version of Grub uses the secret data to open an encrypted partition and load kernel and initrd images from it. -This is an example grub config file: -```output -echo 'Mounting encrypted disk...' -cryptomount -s efisecret (hd0,gpt2) + This version of Grub uses the secret data to open an encrypted partition and load kernel and `initrd` images from it. -echo 'Loading Kernel...' -linux (crypto0)/bootaa64.efi + The following is an example Grub config file: + ```output + echo 'Mounting encrypted disk...' + cryptomount -s efisecret (hd0,gpt2) -echo 'Loading InitRD...' -initrd (crypto0)/initrd.gz + echo 'Loading Kernel...' + linux (crypto0)/bootaa64.efi -echo 'Booting Linux...' -boot -``` -With the current Grub implementation of Arm CCA BootSync support, the booted operating system has access to the initramfs only. + echo 'Loading InitRD...' + initrd (crypto0)/initrd.gz -- Use an init script in an initrd image to unlock and mount the encrypted partition. You will use this approach in the next steps. + echo 'Booting Linux...' + boot + ``` + With the current Grub implementation of Arm CCA BootSync support, the booted operating system has access to the `initramfs` only. -{{% /notice %}} +- Use an init script in an `initrd` image to unlock and mount the encrypted partition. You'll use this approach in the next step. +{{% /notice %}} -On the terminal with the running FVP, use the `encrypt_rootfs.sh` script to encrypt the root partition in the Realm disk image and add an initrd image to the kernel parameters. +In the FVP terminal, use the `encrypt_rootfs.sh` script to encrypt the root partition in the Realm disk image and add an `initrd` image to the kernel parameters. -You will be asked for a passphrase to encrypt the root partition. Use a memorable test passphrase for this demo and keep it available, because you will later write the same value into `ARMCCA01_SEC.dat` for BootSync to release. +You'll be asked for a passphrase to encrypt the root partition. Use a memorable test passphrase and keep it available, because you'll later write the same value into `ARMCCA01_SEC.dat` for BootSync to release. -You can use maximum of 512 characters of upper/lowercase, numbers and symbols. -You can ignore the warning message because this demo uses small partitions. +You can use a maximum of 512 characters of uppercase or lowercase letters, numbers, and symbols. +Ignore the warning message because you're using small partitions. ```bash { output_lines="2-11" } encrypt_rootfs.sh @@ -359,7 +377,9 @@ WARNING: keyslots area (1015808 bytes) is very small, available LUKS2 keyslot co Enable Initrd image ``` -Relaunch the Realm. At this point, `ARMCCA01_SEC.dat` still contains the test string from the previous Secure Boot step, not the disk encryption passphrase: +### Validate failed disk unlock + +In the FVP terminal, relaunch the Realm. At this point, `ARMCCA01_SEC.dat` still contains the test string from the previous Secure Boot step, not the disk encryption passphrase: ```bash cd /cca @@ -372,7 +392,7 @@ cd /cca --realm-pv ARMCCA01 ``` -In the realm boot log you can see that the Init script failed to unlock the encrypted partition: +In the Realm boot log, you can see that the init script failed to unlock the encrypted partition: ```output [ 32.761651] Run /init as init process @@ -387,8 +407,9 @@ can't run '/etc/init.d/rcS': No such file or directory Please press Enter to activate this console. ``` -Press Enter to get into the Realm shell. -In the shell, check that only the initramfs is mounted and that you cannot mount `/dev/vda2` directly: +Press `Enter` to get into the Realm shell. + +In the shell, check that only `initramfs` is mounted and that you can't mount `/dev/vda2` directly: ```bash { output_lines="2-3" } df -h @@ -401,30 +422,34 @@ mount -t auto /dev/vda2 /cryptroot mount: mounting /dev/vda2 on /cryptroot failed: Invalid argument ``` -Stop the realm: +Stop the Realm: ```bash poweroff ``` -The init script failed to unlock the encrypted partition because the Secret Data file does not contain the encryption passphrase yet. Now update the BootSync secret. +The init script failed to unlock the encrypted partition because the Secret Data file doesn't contain the encryption passphrase yet. + +### Update the BootSync secret and validate successful disk unlock -On the terminal with the User Context service stop the service by pressing `Ctrl-C`. +Now, update the BootSync secret. -Save the encryption passphrase into the Secret Data file. Use `echo -n` so the file contains only the passphrase and no trailing newline character. +In the User Context terminal, stop the service by pressing `Ctrl-C`. + +Save the encryption passphrase into the Secret Data file. Use `echo -n` so the file contains only the passphrase and no trailing newline character: ```bash ROOTFS_PASSPHRASE='replace-with-the-passphrase-you-used-for-encrypt_rootfs' echo -n "$ROOTFS_PASSPHRASE" > SecureBoot/ARMCCA01_SEC.dat ``` -Relaunch the User Context service: +In the User Context terminal, relaunch the User Context service: ```bash ./run-user-context-service.sh ``` -On the terminal with FVP, relaunch the Realm with the same RPV: +In the FVP terminal, relaunch the Realm with the same RPV: ```bash cd /cca @@ -438,6 +463,7 @@ cd /cca ``` In the Realm boot log, you can see that the init script successfully unlocked and mounted the encrypted partition: + ```output [ 233.501627] Run /init as init process Detecting LUKS containers in vda1-2 @@ -468,7 +494,7 @@ tmpfs 194.8M 32.0K 194.8M 0% /run cgroup 194.8M 0 194.8M 0% /sys/fs/cgroup ``` -Stop the realm: +Stop the Realm: ```bash poweroff @@ -480,4 +506,8 @@ Stop the FVP: poweroff ``` -You have successfully tested launching realms with Arm CCA BootSync. +## What you've accomplished + +You’ve now used Arm CCA BootSync to enable UEFI Secure Boot and unlock an encrypted root file system for a Realm. + +You can extend the workflows covered in this Learning Path to provide trusted early-boot data for your own Realm workloads.