Documentation/ABI/testing/securityfs-secrets-coco

   1 What:           security/secrets/coco
   2 Date:           February 2022
   3 Contact:        Dov Murik <dovmurik@linux.ibm.com>
   4 Description:
   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".