Documentation/ABI/testing/securityfs-secrets-coco

Source file repositories/reference/linux-study-clean/Documentation/ABI/testing/securityfs-secrets-coco

File Facts

System
Linux kernel
Corpus path
Documentation/ABI/testing/securityfs-secrets-coco
Extension
[no extension]
Size
2258 bytes
Lines
52
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: Documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

What:		security/secrets/coco
Date:		February 2022
Contact:	Dov Murik <dovmurik@linux.ibm.com>
Description:
		Exposes confidential computing (coco) EFI secrets to
		userspace via securityfs.

		EFI can declare memory area used by confidential computing
		platforms (such as AMD SEV and SEV-ES) for secret injection by
		the Guest Owner during VM's launch.  The secrets are encrypted
		by the Guest Owner and decrypted inside the trusted enclave,
		and therefore are not readable by the untrusted host.

		The efi_secret module exposes the secrets to userspace.  Each
		secret appears as a file under <securityfs>/secrets/coco,
		where the filename is the GUID of the entry in the secrets
		table.  This module is loaded automatically by the EFI driver
		if the EFI secret area is populated.

		Two operations are supported for the files: read and unlink.
		Reading the file returns the content of secret entry.
		Unlinking the file overwrites the secret data with zeroes and
		removes the entry from the filesystem.  A secret cannot be read
		after it has been unlinked.

		For example, listing the available secrets::

		  # modprobe efi_secret
		  # ls -l /sys/kernel/security/secrets/coco
		  -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
		  -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
		  -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
		  -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910

		Reading the secret data by reading a file::

		  # cat /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
		  the-content-of-the-secret-data

		Wiping a secret by unlinking a file::

		  # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
		  # ls -l /sys/kernel/security/secrets/coco
		  -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
		  -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
		  -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2

		Note: The binary format of the secrets table injected by the
		Guest Owner is described in
		drivers/virt/coco/efi_secret/efi_secret.c under "Structure of
		the EFI secret area".

Annotation

Implementation Notes