| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <20211118113359.642571-5-dovmurik@linux.ibm.com>
Date: Thu, 18 Nov 2021 11:33:59 +0000
From: Dov Murik <dovmurik@...ux.ibm.com>
To: linux-efi@...r.kernel.org
Cc: Dov Murik <dovmurik@...ux.ibm.com>, Borislav Petkov <bp@...e.de>,
Ashish Kalra <ashish.kalra@....com>,
Brijesh Singh <brijesh.singh@....com>,
Tom Lendacky <thomas.lendacky@....com>,
Ard Biesheuvel <ardb@...nel.org>,
James Morris <jmorris@...ei.org>,
"Serge E. Hallyn" <serge@...lyn.com>,
Andi Kleen <ak@...ux.intel.com>,
Greg KH <gregkh@...uxfoundation.org>,
Andrew Scull <ascull@...gle.com>,
Dave Hansen <dave.hansen@...el.com>,
"Dr. David Alan Gilbert" <dgilbert@...hat.com>,
James Bottomley <jejb@...ux.ibm.com>,
Tobin Feldman-Fitzthum <tobin@...ux.ibm.com>,
Jim Cadden <jcadden@....com>,
Daniele Buono <dbuono@...ux.vnet.ibm.com>,
linux-coco@...ts.linux.dev, linux-security-module@...r.kernel.org,
linux-kernel@...r.kernel.org
Subject: [PATCH v5 4/4] docs: security: Add coco/efi_secret documentation
Add documentation for the efi_secret module which allows access
to Confidential Computing injected secrets.
Signed-off-by: Dov Murik <dovmurik@...ux.ibm.com>
---
Documentation/security/coco/efi_secret.rst | 103 +++++++++++++++++++++
Documentation/security/coco/index.rst | 9 ++
Documentation/security/index.rst | 1 +
3 files changed, 113 insertions(+)
create mode 100644 Documentation/security/coco/efi_secret.rst
create mode 100644 Documentation/security/coco/index.rst
diff --git a/Documentation/security/coco/efi_secret.rst b/Documentation/security/coco/efi_secret.rst
new file mode 100644
index 000000000000..bb7acae22e90
--- /dev/null
+++ b/Documentation/security/coco/efi_secret.rst
@@ -0,0 +1,103 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========
+efi_secret
+==========
+
+This document describes how Confidential Computing secret injection is handled
+from the firmware to the operating system.
+
+
+Introduction
+============
+
+Confidential Computing (coco) hardware such as AMD SEV (Secure Encrypted
+Virtualization) allows guest owners to inject secrets into the VMs
+memory without the host/hypervisor being able to read them. In SEV,
+secret injection is performed early in the VM launch process, before the
+guest starts running.
+
+The efi_secret kernel module allows userspace applications to access these
+secrets via securityfs.
+
+
+Secret data flow
+================
+
+The guest firmware may reserve a designated memory area for secret injection,
+and publish its location (base GPA and length) in the EFI configuration table
+under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` entry
+(``adf956ad-e98c-484c-ae11-b51c7d336447``). This memory area should be marked
+by the firmware as ``EFI_RESERVED_TYPE``, and therefore the kernel should not
+be use it for its own purposes.
+
+During the VM's launch, the virtual machine manager may inject a secret to that
+area. In AMD SEV and SEV-ES this is performed using the
+``KVM_SEV_LAUNCH_SECRET`` command (see [amd-mem-enc]_). The strucutre of the
+injected Guest Owner secret data should be a GUIDed table of secret values; the
+binary format is described in ``drivers/virt/coco/efi_secret/efi_secret.c``
+under "Structure of the EFI secret area".
+
+On kernel start, the kernel's EFI driver saves the location of the secret
+memory (taken from the EFI configuration table) in the ``efi.coco_secret``
+field.
+
+When a userspace application needs to access the secrets inside the guest VM,
+it loads the efi_secret kernel module (``CONFIG_EFI_SECRET=m``) which exposes
+the secrets via securityfs. The details of the efi_secret filesystem interface
+are in [efi-secret-abi]_.
+
+
+
+Application usage example
+=========================
+
+Consider a guest performing computations on encrypted files. The Guest Owner
+provides the decryption key (= secret) using the secret injection mechanism.
+The guest application reads the secret from the efi_secret filesystem and
+proceeds to decrypt the files into memory and then performs the needed
+computations on the content.
+
+In this example, the host can't read the files from the disk image
+because they are encrypted. Host can't read the decryption key because
+it is passed using the secret injection mechanism (= secure channel).
+Host can't read the decrypted content from memory because it's a
+confidential (memory-encrypted) guest.
+
+Here is a simple example for usage of the efi_secret module in a guest
+to which an EFI secret area with 4 secrets was injected during launch::
+
+ # modprobe efi_secret
+ # ls -la /sys/kernel/security/coco/efi_secret
+ total 0
+ drwxr-xr-x 2 root root 0 Jun 28 11:54 .
+ drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
+ -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
+
+ # xxd /sys/kernel/security/coco/efi_secret/e6f5a162-d67f-4750-a67c-5d065f2a9910
+ 00000000: 7468 6573 652d 6172 652d 7468 652d 6b61 these-are-the-ka
+ 00000010: 7461 2d73 6563 7265 7473 0001 0203 0405 ta-secrets......
+ 00000020: 0607 ..
+
+ # rm /sys/kernel/security/coco/efi_secret/e6f5a162-d67f-4750-a67c-5d065f2a9910
+
+ # ls -la /sys/kernel/security/coco/efi_secret
+ total 0
+ drwxr-xr-x 2 root root 0 Jun 28 11:55 .
+ drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
+ -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
+
+
+References
+==========
+
+See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation.
+
+.. [amd-mem-enc] :ref:`Documentation/virt/kvm/amd-memory-encryption <amdmemenc>`
+.. [efi-secret-abi] :ref:`Documentation/ABI/testing/securityfs-coco-efi_secret <efisecret>`
+.. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
diff --git a/Documentation/security/coco/index.rst b/Documentation/security/coco/index.rst
new file mode 100644
index 000000000000..56b803d4b33e
--- /dev/null
+++ b/Documentation/security/coco/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Confidential Computing documentation
+====================================
+
+.. toctree::
+
+ efi_secret
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 16335de04e8c..d4ef543825a7 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -17,3 +17,4 @@ Security Documentation
tpm/index
digsig
landlock
+ coco
--
2.25.1
Powered by blists - more mailing lists