From: Dov Murik <dovmurik@linux.ibm.com>
To: linux-efi@vger.kernel.org
Cc: Dov Murik <dovmurik@linux.ibm.com>, Borislav Petkov <bp@suse.de>,
Ashish Kalra <ashish.kalra@amd.com>,
Brijesh Singh <brijesh.singh@amd.com>,
Tom Lendacky <thomas.lendacky@amd.com>,
Ard Biesheuvel <ardb@kernel.org>,
James Morris <jmorris@namei.org>,
"Serge E. Hallyn" <serge@hallyn.com>,
Andi Kleen <ak@linux.intel.com>,
Greg KH <gregkh@linuxfoundation.org>,
Andrew Scull <ascull@google.com>,
Dave Hansen <dave.hansen@intel.com>,
"Dr. David Alan Gilbert" <dgilbert@redhat.com>,
Gerd Hoffmann <kraxel@redhat.com>,
Lenny Szubowicz <lszubowi@redhat.com>,
Peter Gonda <pgonda@google.com>,
James Bottomley <jejb@linux.ibm.com>,
Tobin Feldman-Fitzthum <tobin@linux.ibm.com>,
Jim Cadden <jcadden@ibm.com>,
Daniele Buono <dbuono@linux.vnet.ibm.com>,
linux-coco@lists.linux.dev,
linux-security-module@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: [PATCH v7 5/5] docs: security: Add coco/efi_secret documentation
Date: Tue, 1 Feb 2022 12:44:13 +0000 [thread overview]
Message-ID: <20220201124413.1093099-6-dovmurik@linux.ibm.com> (raw)
In-Reply-To: <20220201124413.1093099-1-dovmurik@linux.ibm.com>
Add documentation for the efi_secret module which allows access
to Confidential Computing injected secrets.
Signed-off-by: Dov Murik <dovmurik@linux.ibm.com>
---
Documentation/security/coco/efi_secret.rst | 102 +++++++++++++++++++++
Documentation/security/coco/index.rst | 9 ++
Documentation/security/index.rst | 1 +
3 files changed, 112 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..fa74899b68a3
--- /dev/null
+++ b/Documentation/security/coco/efi_secret.rst
@@ -0,0 +1,102 @@
+.. 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, in the EFI driver and the efi_secret
+kernel module.
+
+
+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 [sev]_). 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 area
+(taken from the EFI configuration table) in the ``efi.coco_secret`` field.
+Later it checks if the secret area is populated: it maps the area and checks
+whether its content begins with ``EFI_SECRET_TABLE_HEADER_GUID``
+(``1e74f542-71dd-4d66-963e-ef4287ff173b``). If the secret area is populated,
+the EFI driver will autoload the efi_secret kernel module, which exposes the
+secretes to userspace applications 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::
+
+ # 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.
+
+.. [sev] Documentation/virt/kvm/amd-memory-encryption.rst
+.. [efi-secret-abi] Documentation/ABI/testing/securityfs-coco-efi_secret
+.. [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..3662e93a3eba 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -17,3 +17,4 @@ Security Documentation
tpm/index
digsig
landlock
+ coco/index
--
2.25.1
next prev parent reply other threads:[~2022-02-01 12:45 UTC|newest]
Thread overview: 37+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-02-01 12:44 [PATCH v7 0/5] Allow guest access to EFI confidential computing secret area Dov Murik
2022-02-01 12:44 ` [PATCH v7 1/5] efi: Save location of EFI confidential computing area Dov Murik
2022-02-02 8:38 ` Gerd Hoffmann
2022-02-01 12:44 ` [PATCH v7 2/5] efi/libstub: Reserve confidential computing secret area Dov Murik
2022-02-02 8:41 ` Gerd Hoffmann
2022-02-02 11:13 ` Dov Murik
2022-02-01 12:44 ` [PATCH v7 3/5] virt: Add efi_secret module to expose confidential computing secrets Dov Murik
2022-02-02 8:45 ` Gerd Hoffmann
2022-02-02 10:55 ` Dov Murik
2022-02-01 12:44 ` [PATCH v7 4/5] efi: Load efi_secret module if EFI secret area is populated Dov Murik
2022-02-02 8:47 ` Gerd Hoffmann
2022-02-02 11:08 ` Dov Murik
2022-02-02 14:31 ` Gerd Hoffmann
2022-02-02 15:09 ` Dov Murik
2022-02-03 6:16 ` Gerd Hoffmann
2022-02-03 11:03 ` Dov Murik
2022-02-03 12:11 ` Gerd Hoffmann
2022-02-01 12:44 ` Dov Murik [this message]
2022-02-02 8:49 ` [PATCH v7 5/5] docs: security: Add coco/efi_secret documentation Gerd Hoffmann
2022-02-02 11:19 ` Dov Murik
2022-02-01 13:50 ` [PATCH v7 0/5] Allow guest access to EFI confidential computing secret area Greg KH
2022-02-01 14:24 ` James Bottomley
2022-02-01 14:41 ` Greg KH
2022-02-01 15:05 ` James Bottomley
2022-02-01 18:07 ` Dr. David Alan Gilbert
2022-02-02 4:01 ` Matthew Garrett
2022-02-02 6:10 ` Greg KH
2022-02-02 6:54 ` Matthew Garrett
2022-02-02 7:05 ` Greg KH
2022-02-02 7:10 ` Matthew Garrett
2022-02-02 7:22 ` Ard Biesheuvel
2022-02-02 8:04 ` Matthew Garrett
2022-02-02 8:25 ` Greg KH
2022-02-09 0:25 ` Nayna
2022-02-02 8:36 ` Gerd Hoffmann
2022-02-02 8:45 ` Matthew Garrett
2022-02-07 18:50 ` Dov Murik
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220201124413.1093099-6-dovmurik@linux.ibm.com \
--to=dovmurik@linux.ibm.com \
--cc=ak@linux.intel.com \
--cc=ardb@kernel.org \
--cc=ascull@google.com \
--cc=ashish.kalra@amd.com \
--cc=bp@suse.de \
--cc=brijesh.singh@amd.com \
--cc=dave.hansen@intel.com \
--cc=dbuono@linux.vnet.ibm.com \
--cc=dgilbert@redhat.com \
--cc=gregkh@linuxfoundation.org \
--cc=jcadden@ibm.com \
--cc=jejb@linux.ibm.com \
--cc=jmorris@namei.org \
--cc=kraxel@redhat.com \
--cc=linux-coco@lists.linux.dev \
--cc=linux-efi@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=lszubowi@redhat.com \
--cc=pgonda@google.com \
--cc=serge@hallyn.com \
--cc=thomas.lendacky@amd.com \
--cc=tobin@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).