1What:		security/secrets/coco
2Date:		February 2022
3Contact:	Dov Murik <dovmurik@linux.ibm.com>
4Description:
5		Exposes confidential computing (coco) EFI secrets to
6		userspace via securityfs.
7
8		EFI can declare memory area used by confidential computing
9		platforms (such as AMD SEV and SEV-ES) for secret injection by
10		the Guest Owner during VM's launch.  The secrets are encrypted
11		by the Guest Owner and decrypted inside the trusted enclave,
12		and therefore are not readable by the untrusted host.
13
14		The efi_secret module exposes the secrets to userspace.  Each
15		secret appears as a file under <securityfs>/secrets/coco,
16		where the filename is the GUID of the entry in the secrets
17		table.  This module is loaded automatically by the EFI driver
18		if the EFI secret area is populated.
19
20		Two operations are supported for the files: read and unlink.
21		Reading the file returns the content of secret entry.
22		Unlinking the file overwrites the secret data with zeroes and
23		removes the entry from the filesystem.  A secret cannot be read
24		after it has been unlinked.
25
26		For example, listing the available secrets::
27
28		  # modprobe efi_secret
29		  # ls -l /sys/kernel/security/secrets/coco
30		  -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
31		  -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
32		  -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
33		  -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910
34
35		Reading the secret data by reading a file::
36
37		  # cat /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
38		  the-content-of-the-secret-data
39
40		Wiping a secret by unlinking a file::
41
42		  # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
43		  # ls -l /sys/kernel/security/secrets/coco
44		  -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
45		  -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
46		  -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
47
48		Note: The binary format of the secrets table injected by the
49		Guest Owner is described in
50		drivers/virt/coco/efi_secret/efi_secret.c under "Structure of
51		the EFI secret area".
52