tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: security: Add secrets/coco documentation
Add documentation for the efi_secret module which allows access
to Confidential Computing injected secrets.
Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>
Link: https://lore.kernel.org/r/20220412212127.154182-5-dovmurik@linux.ibm.com
Signed-off-by: Ard Biesheuvel <ardb@kernel.org>
authored by
Dov Murik
and committed by
Ard Biesheuvel
7419995a
20ffd920
+113
+1
Documentation/security/index.rst
+1
Documentation/security/index.rst
+103
Documentation/security/secrets/coco.rst
+103
Documentation/security/secrets/coco.rst
···
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 strucutre 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/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