1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==============================
4 Confidential Computing secrets
5 ==============================
6
7 This document describes how Confidential Compu
8 from the firmware to the operating system, in
9 kernel module.
10
11
12 Introduction
13 ============
14
15 Confidential Computing (coco) hardware such as
16 Virtualization) allows guest owners to inject
17 memory without the host/hypervisor being able
18 secret injection is performed early in the VM
19 guest starts running.
20
21 The efi_secret kernel module allows userspace
22 secrets via securityfs.
23
24
25 Secret data flow
26 ================
27
28 The guest firmware may reserve a designated me
29 and publish its location (base GPA and length)
30 under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` en
31 (``adf956ad-e98c-484c-ae11-b51c7d336447``). T
32 by the firmware as ``EFI_RESERVED_TYPE``, and
33 be use it for its own purposes.
34
35 During the VM's launch, the virtual machine ma
36 area. In AMD SEV and SEV-ES this is performed
37 ``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_)
38 Guest Owner secret data should be a GUIDed tab
39 format is described in ``drivers/virt/coco/efi
40 "Structure of the EFI secret area".
41
42 On kernel start, the kernel's EFI driver saves
43 (taken from the EFI configuration table) in th
44 Later it checks if the secret area is populate
45 whether its content begins with ``EFI_SECRET_T
46 (``1e74f542-71dd-4d66-963e-ef4287ff173b``). I
47 the EFI driver will autoload the efi_secret ke
48 secrets to userspace applications via security
49 efi_secret filesystem interface are in [secret
50
51
52 Application usage example
53 =========================
54
55 Consider a guest performing computations on en
56 provides the decryption key (= secret) using t
57 The guest application reads the secret from th
58 proceeds to decrypt the files into memory and
59 computations on the content.
60
61 In this example, the host can't read the files
62 because they are encrypted. Host can't read t
63 it is passed using the secret injection mechan
64 Host can't read the decrypted content from mem
65 confidential (memory-encrypted) guest.
66
67 Here is a simple example for usage of the efi_
68 to which an EFI secret area with 4 secrets was
69
70 # ls -la /sys/kernel/security/secrets/
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
75 -r--r----- 1 root root 0 Jun 28 11:54
76 -r--r----- 1 root root 0 Jun 28 11:54
77 -r--r----- 1 root root 0 Jun 28 11:54
78
79 # hd /sys/kernel/security/secrets/coco
80 00000000 74 68 65 73 65 2d 61 72 65
81 00000010 74 61 2d 73 65 63 72 65 74
82 00000020 06 07
83 00000022
84
85 # rm /sys/kernel/security/secrets/coco
86
87 # ls -la /sys/kernel/security/secrets/
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
92 -r--r----- 1 root root 0 Jun 28 11:54
93 -r--r----- 1 root root 0 Jun 28 11:54
94
95
96 References
97 ==========
98
99 See [sev-api-spec]_ for more info regarding SE
100
101 .. [sev] Documentation/virt/kvm/x86/amd-memory
102 .. [secrets-coco-abi] Documentation/ABI/testin
103 .. [sev-api-spec] https://www.amd.com/system/f
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.