| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 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 |
.. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst |
| 102 |
.. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco |
| 103 |
.. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf |