From 5297853fe5c0101809d1d338bf06c126b2d475b1 Mon Sep 17 00:00:00 2001 From: "Daniel P. Smith" Date: Sun, 29 Mar 2026 15:49:48 -0400 Subject: [PATCH] specification: updating for latest linux changes Update the specification to align with the changes made for the Linux maintainers. Signed-off-by: Daniel P. Smith --- .../secure-launch-specification.rst | 124 +++++++++++++++--- 1 file changed, 109 insertions(+), 15 deletions(-) diff --git a/specifications/secure-launch-specification.rst b/specifications/secure-launch-specification.rst index a4233a8..89ed2cd 100644 --- a/specifications/secure-launch-specification.rst +++ b/specifications/secure-launch-specification.rst @@ -7,7 +7,7 @@ Secure Launch Specification .. class:: center -**Version:** 0.6.0-draft +**Version:** 0.7.0-draft .. class:: center @@ -18,6 +18,7 @@ Secure Launch Specification **Daniel P. Smith** (Apertus Solutions) **Ross Philipson** (Oracle) **Krystian Hebel** (3mdeb) + **Sergii Dmytruk** (3mdeb) .. sectnum:: @@ -99,6 +100,13 @@ Handler to be implemented by each platform supported by TrenchBoot. The specification provides a well-defined interface for DLE Handler and bootloader implementors to follow to ensure interoperability between implementations. +Dynamic Lauch Measured Environment Header +----------------------------------------- + +The DLME Header is a platform agnositic header structure that a Secure +Launch-complaint kernel must implement. It is derived from Intel's MLE Header, +but generalized to allow it to be compatible with other platforms. + Secure Launch Resource Table ---------------------------- @@ -173,8 +181,55 @@ Sequence Secure Launch Interfaces ======================== -There are two interfaces to be defined here, the DLE Handler Specifications and -the SLRT Specification. +Secure Launch Interfaces consist of three interfaces, the DLME Header, the DLE +Handler Specifications, and the SLRT Specification. + +DLME Header +----------- + +Detailed below is the header structure that a Secure Launch-compatible kernel +must provide and is discoverable. The information provides details to the DLE +Handler to facilitate it in launching the kernel. + + +DLME Header Structure +~~~~~~~~~~~~~~~~~~~~~ + +A descripton of the DLME for the DLE Handler. + +:uuid0: Chunk 0 of UUID, 9082AC5A +:uuid1: Chunk 1 of UUID, 74A7476F +:uuid2: Chunk 2 of UUID, A2555C0F +:uuid3: Chunk 3 of UUID, 42B651CB +:header_len: Length of the header. +:version: Header version. +:entry_point: Address of the DLME entry point. +:first_valid_page: Address to first valid page of DLME. +:start: Offset to first byte of DLME within page space. +:end: Offset to last byte + 1 of DLME within page space. +:capabilities: Bitfield of DLME supported capabilities. +:cmdline_start: Starting address of command line buffer. +:cmdline_end: Ending address of command line buffer. + +.. code-block:: c + :linenos: 1 + + struct slr_dlme_header { + u32 uuid0; + u32 uuid1; + u32 uuid2; + u32 uuid3; + u32 header_len; + u32 version; + u32 entry_point; + u32 first_valid_page; + u32 start; + u32 end; + u32 capabilities; + u32 cmdline_start; + u32 cmdline_end; + }; + DLE Handler Specification ------------------------- @@ -184,19 +239,56 @@ The DLE Handler Specification defines the invocation interface for the DLE Handl Platform Requirements ~~~~~~~~~~~~~~~~~~~~~ -| **1** - x86 Platforms -| **1.1** - The DLE Handler **MAY** be invoked with the CPU in either 32bit +| **1** - General Requirements +| **1.1** - The DLME **SHALL** provide a DLME Header +| **1.2** - The DLME **SHALL** provide a mechanism to discover the DLME Header +| +| **2** - x86 Non-EFI Platforms +| **2.1** - The DLE Handler **MAY** be invoked with the CPU in either 32bit | protected mode or 64bit long mode -| **1.2** - The SLRT **SHALL** be passed to the DLE Handler in the EDI/RDI CPU +| **2.2** - The SLRT **SHALL** be passed to the DLE Handler in the EDI/RDI CPU | register -| **1.3** - All other registers besides EDI/RDI are not guarenteed -| **1.4** - The invoking code **SHALL** use a long jump to the DLE Handler -| **1.5** - The DLE Handler **SHALL NOT** return control on error +| **2.3** - All other registers besides EDI/RDI are not guarenteed +| **2.4** - The invoking code **SHALL** use a long jump to the DLE Handler +| **2.5** - The DLE Handler **SHALL NOT** return control on error +| +| **3** - x86 EFI Platforms +| **3.1** - The DLE Handler **SHALL** implement the Secure Launch EFI Protocol. | | **2** - Arm Platforms | **2.1** - *Reserved* +EFI SLaunch Protocol +~~~~~~~~~~~~~~~~~~~~ + +On EFI platforms the DLE Handler must implement the EFI_SLAUNCH_PROTOCOL that provides the following methods. + +* **EFI_SLAUNCH_REGISTER_DLME**: Registers the DLME with the DLE Handler +* **EFI_SLAUNCH_LAUNCH**: Invokes the DLE Handler + +The interface definition for the protocol is as follows, + +.. code-block:: c + :linenos: 1 + + typedef struct tdEFI_SLAUNCH_PROTOCOL { + EFI_SLAUNCH_SLRT_UPDATE_REGISTER_DLME RegisterDlme; + EFI_SLAUNCH_LAUNCH Launch; + } EFI_SLAUNCH_PROTOCOL + + typedef EFI_STATUS (EFIAPI *EFI_SLAUNCH_REGISTER_DLME) ( + IN EFI_SLAUNCH_PROTOCOL *This, + IN EFI_PHYSICAL_ADDRESS *DlmeBase + IN EFI_PHYSICAL_ADDRESS *DlmeHeader + IN EFI_PHYSICAL_ADDRESS *DlmeConfigTable + ); + + typedef EFI_STATUS (EFIAPI *EFI_SLAUNCH_LAUNCH) ( + IN EFI_SLAUNCH_PROTOCOL *This + ); + + SLRT Specification ------------------ @@ -213,7 +305,7 @@ able to meet. The supplemental sections will cover any idiosyncrasies for the various platforms and environments supported. Platform Requirements ---------------------- +~~~~~~~~~~~~~~~~~~~~~ | **1** - General Requirements | **1.1** - The SLRT **MUST** begin with the magic value `0x4452544d`. @@ -359,6 +451,8 @@ invoke the DLE Handler and for the DLE Handler to invoke the DL. :dlme_size: The size of the DLME. :dlme_base: The base address where the DLME is located. :dlme_entry: The offset into the DLME of the entry point. +:dlme_header_offset: The offest into the DLME of the DLME Header. +:dlme_config_table: The offsee into the DLME of the DLME Config Table. :bl_context: Allows the bootloader to provide a reference to a context object. :dl_handler: The address to the entry point for the DLE Handler. @@ -372,6 +466,8 @@ invoke the DLE Handler and for the DLE Handler to invoke the DL. u64 dlme_size; u64 dlme_base; u64 dlme_entry; + u64 dlme_header_offset; + u64 dlme_config_table; struct slr_bl_context bl_context; u64 dl_handler; }; @@ -888,8 +984,7 @@ it in the TXT Heap definition. This area is referred to as the OS2MLE structure. The OS2MLE structure for Secure Launch is defined as follows, :version: Revision of the os2mle table -:boot_params_addr: - Physical address of boot parameters, format depends on target kernel +:reserved: Reserved field :slrt: Physical address of the SLRT :txt_info: Physical address of TXT info, located in SLRT (simply a convenience to avoid @@ -906,12 +1001,11 @@ The OS2MLE structure for Secure Launch is defined as follows, struct os2mle { u32 version; u32 reserved; - u64 boot_params_addr; u64 slrt; - u64 txt_info; + u64 txt_info; u32 ap_wake_block; u32 ap_wake_block_size; - u8 mle_scratch[64]; + u8 mle_scratch[64]; }; [1] https://www.kernel.org/doc/html/v6.12/arch/x86/boot.html#details-of-header-fields