| 1 | |
| 2 |
|
| 3 | ==============================
|
| 4 | Confidential Computing secrets
|
| 5 | ==============================
|
| 6 |
|
| 7 | This document describes how Confidential Computing secret injection is handled
|
| 8 | from the firmware to the operating system, in the EFI driver and the efi_secret
|
| 9 | kernel module.
|
| 10 |
|
| 11 |
|
| 12 | Introduction
|
| 13 | ============
|
| 14 |
|
| 15 | Confidential Computing (coco) hardware such as AMD SEV (Secure Encrypted
|
| 16 | Virtualization) allows guest owners to inject secrets into the VMs
|
| 17 | memory without the host/hypervisor being able to read them. In SEV,
|
| 18 | secret injection is performed early in the VM launch process, before the
|
| 19 | guest starts running.
|
| 20 |
|
| 21 | The efi_secret kernel module allows userspace applications to access these
|
| 22 | secrets via securityfs.
|
| 23 |
|
| 24 |
|
| 25 | Secret data flow
|
| 26 | ================
|
| 27 |
|
| 28 | The guest firmware may reserve a designated memory area for secret injection,
|
| 29 | and publish its location (base GPA and length) in the EFI configuration table
|
| 30 | under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` entry
|
| 31 | (``adf956ad-e98c-484c-ae11-b51c7d336447``). This memory area should be marked
|
| 32 | by the firmware as ``EFI_RESERVED_TYPE``, and therefore the kernel should not
|
| 33 | be use it for its own purposes.
|
| 34 |
|
| 35 | During the VM's launch, the virtual machine manager may inject a secret to that
|
| 36 | area. In AMD SEV and SEV-ES this is performed using the
|
| 37 | ``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_). The structure of the injected
|
| 38 | Guest Owner secret data should be a GUIDed table of secret values; the binary
|
| 39 | format is described in ``drivers/virt/coco/efi_secret/efi_secret.c`` under
|
| 40 | "Structure of the EFI secret area".
|
| 41 |
|
| 42 | On kernel start, the kernel's EFI driver saves the location of the secret area
|
| 43 | (taken from the EFI configuration table) in the ``efi.coco_secret`` field.
|
| 44 | Later it checks if the secret area is populated: it maps the area and checks
|
| 45 | whether its content begins with ``EFI_SECRET_TABLE_HEADER_GUID``
|
| 46 | (``1e74f542-71dd-4d66-963e-ef4287ff173b``). If the secret area is populated,
|
| 47 | the EFI driver will autoload the efi_secret kernel module, which exposes the
|
| 48 | secrets to userspace applications via securityfs. The details of the
|
| 49 | efi_secret filesystem interface are in [secrets-coco-abi]_.
|
| 50 |
|
| 51 |
|
| 52 | Application usage example
|
| 53 | =========================
|
| 54 |
|
| 55 | Consider a guest performing computations on encrypted files. The Guest Owner
|
| 56 | provides the decryption key (= secret) using the secret injection mechanism.
|
| 57 | The guest application reads the secret from the efi_secret filesystem and
|
| 58 | proceeds to decrypt the files into memory and then performs the needed
|
| 59 | computations on the content.
|
| 60 |
|
| 61 | In this example, the host can't read the files from the disk image
|
| 62 | because they are encrypted. Host can't read the decryption key because
|
| 63 | it is passed using the secret injection mechanism (= secure channel).
|
| 64 | Host can't read the decrypted content from memory because it's a
|
| 65 | confidential (memory-encrypted) guest.
|
| 66 |
|
| 67 | Here is a simple example for usage of the efi_secret module in a guest
|
| 68 | to which an EFI secret area with 4 secrets was injected during launch::
|
| 69 |
|
| 70 | # ls -la /sys/kernel/security/secrets/coco
|
| 71 | total 0
|
| 72 | drwxr-xr-x 2 root root 0 Jun 28 11:54 .
|
| 73 | drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
|
| 74 | -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
|
| 75 | -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
|
| 76 | -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
|
| 77 | -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910
|
| 78 |
|
| 79 | # hd /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
|
| 80 | 00000000 74 68 65 73 65 2d 61 72 65 2d 74 68 65 2d 6b 61 |these-are-the-ka|
|
| 81 | 00000010 74 61 2d 73 65 63 72 65 74 73 00 01 02 03 04 05 |ta-secrets......|
|
| 82 | 00000020 06 07 |..|
|
| 83 | 00000022
|
| 84 |
|
| 85 | # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
|
| 86 |
|
| 87 | # ls -la /sys/kernel/security/secrets/coco
|
| 88 | total 0
|
| 89 | drwxr-xr-x 2 root root 0 Jun 28 11:55 .
|
| 90 | drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
|
| 91 | -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
|
| 92 | -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
|
| 93 | -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
|
| 94 |
|
| 95 |
|
| 96 | References
|
| 97 | ==========
|
| 98 |
|
| 99 | See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation.
|
| 100 |
|
| 101 |
|
| 102 |
|
| 103 |
|