0001 What: security/secrets/coco
0002 Date: February 2022
0003 Contact: Dov Murik <dovmurik@linux.ibm.com>
0004 Description:
0005 Exposes confidential computing (coco) EFI secrets to
0006 userspace via securityfs.
0007
0008 EFI can declare memory area used by confidential computing
0009 platforms (such as AMD SEV and SEV-ES) for secret injection by
0010 the Guest Owner during VM's launch. The secrets are encrypted
0011 by the Guest Owner and decrypted inside the trusted enclave,
0012 and therefore are not readable by the untrusted host.
0013
0014 The efi_secret module exposes the secrets to userspace. Each
0015 secret appears as a file under <securityfs>/secrets/coco,
0016 where the filename is the GUID of the entry in the secrets
0017 table. This module is loaded automatically by the EFI driver
0018 if the EFI secret area is populated.
0019
0020 Two operations are supported for the files: read and unlink.
0021 Reading the file returns the content of secret entry.
0022 Unlinking the file overwrites the secret data with zeroes and
0023 removes the entry from the filesystem. A secret cannot be read
0024 after it has been unlinked.
0025
0026 For example, listing the available secrets::
0027
0028 # modprobe efi_secret
0029 # ls -l /sys/kernel/security/secrets/coco
0030 -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
0031 -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
0032 -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
0033 -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910
0034
0035 Reading the secret data by reading a file::
0036
0037 # cat /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
0038 the-content-of-the-secret-data
0039
0040 Wiping a secret by unlinking a file::
0041
0042 # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
0043 # ls -l /sys/kernel/security/secrets/coco
0044 -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
0045 -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
0046 -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
0047
0048 Note: The binary format of the secrets table injected by the
0049 Guest Owner is described in
0050 drivers/virt/coco/efi_secret/efi_secret.c under "Structure of
0051 the EFI secret area".
