0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==============================
0004 Confidential Computing secrets
0005 ==============================
0006
0007 This document describes how Confidential Computing secret injection is handled
0008 from the firmware to the operating system, in the EFI driver and the efi_secret
0009 kernel module.
0010
0011
0012 Introduction
0013 ============
0014
0015 Confidential Computing (coco) hardware such as AMD SEV (Secure Encrypted
0016 Virtualization) allows guest owners to inject secrets into the VMs
0017 memory without the host/hypervisor being able to read them. In SEV,
0018 secret injection is performed early in the VM launch process, before the
0019 guest starts running.
0020
0021 The efi_secret kernel module allows userspace applications to access these
0022 secrets via securityfs.
0023
0024
0025 Secret data flow
0026 ================
0027
0028 The guest firmware may reserve a designated memory area for secret injection,
0029 and publish its location (base GPA and length) in the EFI configuration table
0030 under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` entry
0031 (``adf956ad-e98c-484c-ae11-b51c7d336447``). This memory area should be marked
0032 by the firmware as ``EFI_RESERVED_TYPE``, and therefore the kernel should not
0033 be use it for its own purposes.
0034
0035 During the VM's launch, the virtual machine manager may inject a secret to that
0036 area. In AMD SEV and SEV-ES this is performed using the
0037 ``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_). The strucutre of the injected
0038 Guest Owner secret data should be a GUIDed table of secret values; the binary
0039 format is described in ``drivers/virt/coco/efi_secret/efi_secret.c`` under
0040 "Structure of the EFI secret area".
0041
0042 On kernel start, the kernel's EFI driver saves the location of the secret area
0043 (taken from the EFI configuration table) in the ``efi.coco_secret`` field.
0044 Later it checks if the secret area is populated: it maps the area and checks
0045 whether its content begins with ``EFI_SECRET_TABLE_HEADER_GUID``
0046 (``1e74f542-71dd-4d66-963e-ef4287ff173b``). If the secret area is populated,
0047 the EFI driver will autoload the efi_secret kernel module, which exposes the
0048 secrets to userspace applications via securityfs. The details of the
0049 efi_secret filesystem interface are in [secrets-coco-abi]_.
0050
0051
0052 Application usage example
0053 =========================
0054
0055 Consider a guest performing computations on encrypted files. The Guest Owner
0056 provides the decryption key (= secret) using the secret injection mechanism.
0057 The guest application reads the secret from the efi_secret filesystem and
0058 proceeds to decrypt the files into memory and then performs the needed
0059 computations on the content.
0060
0061 In this example, the host can't read the files from the disk image
0062 because they are encrypted. Host can't read the decryption key because
0063 it is passed using the secret injection mechanism (= secure channel).
0064 Host can't read the decrypted content from memory because it's a
0065 confidential (memory-encrypted) guest.
0066
0067 Here is a simple example for usage of the efi_secret module in a guest
0068 to which an EFI secret area with 4 secrets was injected during launch::
0069
0070 # ls -la /sys/kernel/security/secrets/coco
0071 total 0
0072 drwxr-xr-x 2 root root 0 Jun 28 11:54 .
0073 drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
0074 -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
0075 -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
0076 -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
0077 -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910
0078
0079 # hd /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
0080 00000000 74 68 65 73 65 2d 61 72 65 2d 74 68 65 2d 6b 61 |these-are-the-ka|
0081 00000010 74 61 2d 73 65 63 72 65 74 73 00 01 02 03 04 05 |ta-secrets......|
0082 00000020 06 07 |..|
0083 00000022
0084
0085 # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
0086
0087 # ls -la /sys/kernel/security/secrets/coco
0088 total 0
0089 drwxr-xr-x 2 root root 0 Jun 28 11:55 .
0090 drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
0091 -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
0092 -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
0093 -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
0094
0095
0096 References
0097 ==========
0098
0099 See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation.
0100
0101 .. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst
0102 .. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco
0103 .. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
