Skip to content

specification: updating for latest linux changes #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dpsmith wants to merge 1 commit into
base: master
Choose a base branch
from
+109 −15
Open

specification: updating for latest linux changes #35

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 109 additions & 15 deletions specifications/secure-launch-specification.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Secure Launch Specification

.. class:: center

**Version:** 0.6.0-draft
**Version:** 0.7.0-draft

.. class:: center

Expand All @@ -18,6 +18,7 @@ Secure Launch Specification
**Daniel P. Smith** (Apertus Solutions)
**Ross Philipson** (Oracle)
**Krystian Hebel** (3mdeb)
**Sergii Dmytruk** (3mdeb)

.. sectnum::

Expand Down Expand Up @@ -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
----------------------------

Expand Down Expand Up @@ -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
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any alignment requirements?

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only requirement from TXT spec is that it must be within the MLE range. If we want to impose alignment, I'm open to that discussion. It may require a slight change to the Linux series, though I don't think it would be difficult.

Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm just thinking of AArch64 and other platforms that don't allow misaligned accesses. If you don't think this will cause problems when storing/reading the structure, then can explicitly say that the structure is 1-byte aligned.

~~~~~~~~~~~~~~~~~~~~~

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
Comment on lines +200 to +203
Copy link
Copy Markdown
Member

@krystian-hebel krystian-hebel Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be unconditionally included in non-TXT binaries as well? It probably makes sense for x86 as vendor can be easily detected, but I'm not so sure about other architectures.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, while it originates from Intel TXT, we want to standardize the dl-stub across architectures and this provides the cleanest, IOW maximize reuse, method to communicate the necessary information to the dl-stub

:header_len: Length of the header.
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be unambiguous since this is not always the case:

Suggested change
:header_len: Length of the header.
:header_len: Length of the header in bytes.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack

:version: Header version.
:entry_point: Address of the DLME entry point.
:first_valid_page: Address to first valid page of DLME.
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:first_valid_page: Address to first valid page of DLME.
:first_valid_page: Address of the first valid 4KiB-page of DLME.

I suppose it also needs to have zeroes in its lowest bits.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not specify 4K, it should be kept platform agnostic. I am good with the other wording change.

Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then could say page of a platform-specific size so a reader doesn't look for the page size specified somewhere else in the specification.

:start: Offset to first byte of DLME within page space.
:end: Offset to last byte + 1 of DLME within page space.
Comment on lines +208 to +209
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The base for the offsets is unspecified.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is how it is defined in MLE guide,

Note: linear addresses start at the beginning of the executable region of the binary,
not the beginning of the file. The offset between the beginning of the binary file and
beginning of the linear address space is ABI-dependent.

I am going to have to think of a good way to say this in relation to this spec. Suggestions are welcome.

: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
-------------------------
Expand All @@ -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
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A typo:

Suggested change
| **2.3** - All other registers besides EDI/RDI are not guarenteed
| **2.3** - All other registers besides EDI/RDI are not guaranteed

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack

| **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
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
} EFI_SLAUNCH_PROTOCOL
} EFI_SLAUNCH_PROTOCOL;

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack


typedef EFI_STATUS (EFIAPI *EFI_SLAUNCH_REGISTER_DLME) (
IN EFI_SLAUNCH_PROTOCOL *This,
IN EFI_PHYSICAL_ADDRESS *DlmeBase
IN EFI_PHYSICAL_ADDRESS *DlmeHeader
Comment on lines +282 to +283
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
IN EFI_PHYSICAL_ADDRESS *DlmeBase
IN EFI_PHYSICAL_ADDRESS *DlmeHeader
IN EFI_PHYSICAL_ADDRESS *DlmeBase,
IN EFI_PHYSICAL_ADDRESS *DlmeHeader,

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack

IN EFI_PHYSICAL_ADDRESS *DlmeConfigTable
);

typedef EFI_STATUS (EFIAPI *EFI_SLAUNCH_LAUNCH) (
IN EFI_SLAUNCH_PROTOCOL *This
);


SLRT Specification
------------------

Expand All @@ -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`.
Expand Down Expand Up @@ -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.
Comment on lines +454 to +455
Copy link
Copy Markdown
Member

@SergiiDmytruk SergiiDmytruk Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: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.
:dlme_header_offset: The offset into the DLME of the DLME Header.
:dlme_config_table: The offset into the DLME of the DLME Config Table.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack

: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.

Expand All @@ -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;
};
Expand Down Expand Up @@ -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
Expand All @@ -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;
Copy link
Copy Markdown
Member

@krystian-hebel krystian-hebel Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove trailing space.

Copy link
Copy Markdown
Contributor Author

@dpsmith dpsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ack.

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
Expand Down