These docs are under active development and cover the v0.20 Kobicha security model.
Peios Learn
Back to specification

psd-002 — Specification

Binary Identifiers

Binary identifier types — GUID and LUID formats, comparison, generation, and allocation.

v0.20 Draft 2026-04-25

Contents

1Introduction

2Guid

3Luid

Section

1 Introduction

§1.1 1 Introduction

Scope

This specification defines the binary identifier types used across Peios subsystems: the Globally Unique Identifier (GUID) and the Locally Unique Identifier (LUID).

This specification covers:

  • GUID -- binary format, string representation, comparison semantics, and generation requirements
  • LUID -- binary format, comparison semantics, and allocation model

This specification does not cover:

  • Security Identifiers (SIDs) -- defined in PSD-004
  • Well-known GUID or LUID values -- defined in the specifications of the subsystems that declare them
  • Application-specific identifier namespaces
§1.2 1 Introduction

Terminology

  • GUID (Globally Unique Identifier): A 128-bit identifier with global uniqueness guarantees. Used to identify registry hives, layers, object types, and other entities that require stable identity across systems and reboots.

  • LUID (Locally Unique Identifier): A 64-bit identifier with boot-scoped local uniqueness. Used to identify transient entities such as logon sessions and privilege instances that do not persist across reboots.

  • Nil GUID: The GUID with all 128 bits set to zero. A sentinel value meaning "no GUID" or "unset."

  • Nil LUID: The LUID with all 64 bits set to zero. A sentinel value meaning "no LUID" or "unset."

§1.3 1 Introduction

Conventions

This specification conforms to PSD-001.

§1.3.1 Normative keywords

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this specification are to be interpreted as described in RFC 2119.

§1.3.2 Byte order

All multi-byte integer fields in this specification are little-endian unless explicitly stated otherwise.

§1.3.3 Notation

Byte offsets and sizes in format tables are in bytes. Hex values use the 0x prefix. Byte sequences are written as space-separated hex pairs: 0a 0b 0c.

§1.4 1 Introduction

Prior Art

§1.4.1 MS-DTYP

The GUID and LUID types defined in this specification derive from the Microsoft Data Types specification (MS-DTYP), §2.3.4 (GUID) and §2.3.7 (LUID).

The Peios GUID binary format is identical to the MS-DTYP GUID. The Peios GUID string format follows the same hyphenated hex convention but normalises to lowercase hex digits on output, where Microsoft implementations typically produce uppercase.

The Peios LUID binary format diverges from MS-DTYP in one detail: HighPart is an unsigned 32-bit integer (uint32) rather than the signed 32-bit integer (LONG) used in MS-DTYP. The signed type in MS-DTYP is a Win32 API convention with no semantic purpose -- LUID values are never negative. Making the field unsigned simplifies comparison and eliminates a class of sign-extension bugs.

§1.4.2 RFC 4122

RFC 4122 ("A Universally Unique IDentifier (UUID) URN Namespace") defines the UUID format and generation algorithms. The GUID binary layout used by Microsoft and adopted by Peios is the mixed-endian variant of the RFC 4122 UUID: the first three fields are little-endian integers and the last field is a raw byte array. This differs from the RFC 4122 network byte order representation where all fields are big-endian.

Peios generates version 4 (random) GUIDs as defined in RFC 4122 §4.4.

§1.4.3 DCE RPC

The GUID structure originates from the DCE 1.1 RPC specification, which defined the uuid_t type with the same field layout. The mixed-endian encoding reflects the DCE convention of encoding integer fields in the sender's native byte order (little-endian on x86).

Section

2 Guid

§2.1 2 Guid

Binary Format

A GUID is a 128-bit (16-byte) value with the following binary layout:

Offset Size Field Type
0 4 Data1 uint32, little-endian
4 2 Data2 uint16, little-endian
6 2 Data3 uint16, little-endian
8 8 Data4 uint8[8]

The total size of a GUID MUST be exactly 16 bytes with no padding.

Data1, Data2, and Data3 MUST be stored in little-endian byte order.

Data4 is a raw byte array with no endianness interpretation.

ⓘ Informative
This is the mixed-endian layout inherited from DCE RPC and MS-DTYP. The first three fields follow the platform's native byte order (little-endian on x86), while Data4 is a byte sequence with no integer interpretation.

§2.1.1 Nil GUID

The nil GUID is the GUID with all 16 bytes set to zero.

The nil GUID is a valid GUID value. Specifications that require a non-nil GUID MUST state this requirement explicitly.

The nil GUID MUST NOT be produced by the generation algorithm defined in §2.4.

§2.2 2 Guid

String Format

§2.2.1 Canonical form

The canonical string representation of a GUID MUST use the following format:

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

The string MUST be exactly 38 characters: an opening brace, 32 hex digits arranged in 8-4-4-4-12 groups separated by hyphens, and a closing brace.

The fields map to the string as follows:

Group Digits Source
1 8 Data1, most significant nibble first
2 4 Data2, most significant nibble first
3 4 Data3, most significant nibble first
4 4 Data4[0] and Data4[1], in byte order
5 12 Data4[2] through Data4[7], in byte order

For Data1, Data2, and Data3, the hex representation is of the numeric value (most significant nibble first), not of the stored byte order. For Data4, each byte is encoded in sequence with the high nibble before the low nibble.

[!INFORMATIVE] Example. Given the 16 bytes (in storage order):

04 03 02 01  06 05  08 07  09 0a  0b 0c 0d 0e 0f 10

Data1 = 0x01020304 (little-endian), Data2 = 0x0506, Data3 = 0x0708. The string representation is:

{01020304-0506-0708-090a-0b0c0d0e0f10}

§2.2.2 Case

Canonical output MUST use lowercase hex digits (a–f).

§2.2.3 Parsing

Parsers MUST accept both uppercase and lowercase hex digits.

Parsers MUST accept the braced form {...} and SHOULD accept the unbraced form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Parsers MUST reject strings that do not have exactly the right number of hex digits in each group.

§2.3 2 Guid

Comparison

§2.3.1 Equality

Two GUIDs are equal if and only if their 16-byte binary representations are identical.

GUID comparison MUST be performed on the binary representation, not on string representations.

ⓘ Informative
Byte-for-byte comparison of the binary form avoids case sensitivity and brace-presence issues that would arise from comparing string representations.

§2.3.2 Ordering

This specification does not define a total ordering for GUIDs. Specifications that require an ordered GUID collection MUST define their ordering convention explicitly.

§2.4 2 Guid

Generation

GUIDs generated by Peios MUST be version 4 (random) as defined in RFC 4122 §4.4.

§2.4.1 Algorithm

To generate a version 4 GUID:

  1. Fill all 16 bytes with cryptographically random data.
  2. Set the four most significant bits of Data3 to 0100 (version 4).
  3. Set the two most significant bits of Data4[0] to 10 (RFC 4122 variant).

The resulting GUID has 122 random bits, 4 version bits, and 2 variant bits.

[!INFORMATIVE] In terms of bit manipulation on the binary layout:

Data3 = (Data3 & 0x0fff) | 0x4000
Data4[0] = (Data4[0] & 0x3f) | 0x80

§2.4.2 Randomness source

The random data MUST be obtained from a cryptographically secure source.

In the kernel, this MUST be get_random_bytes() or equivalent.

In userspace, this MUST be getrandom(2) with no flags (blocking until the entropy pool is initialised) or equivalent.

GUIDs MUST NOT be generated using a pseudorandom number generator seeded from a predictable source.

Section

3 Luid

§3.1 3 Luid

Binary Format

An LUID is a 64-bit (8-byte) value with the following binary layout:

Offset Size Field Type
0 4 LowPart uint32, little-endian
4 4 HighPart uint32, little-endian

The total size of an LUID MUST be exactly 8 bytes with no padding.

Both fields MUST be stored in little-endian byte order.

ⓘ Informative
MS-DTYP defines HighPart as a signed 32-bit integer (LONG). Peios uses unsigned uint32 for both fields. The signed type in MS-DTYP is a Win32 API convention with no semantic purpose -- LUID values are never negative. See §1.4.1 for the full divergence rationale.

§3.1.1 Nil LUID

The nil LUID is the LUID with all 8 bytes set to zero (LowPart = 0, HighPart = 0).

The nil LUID is a valid LUID value. The nil LUID MUST NOT be assigned by the allocation algorithm defined in §3.3.

Specifications that require a non-nil LUID MUST state this requirement explicitly.

§3.2 3 Luid

Comparison

§3.2.1 Equality

Two LUIDs are equal if and only if both their LowPart and HighPart fields are identical.

§3.2.2 Ordering

This specification does not define a total ordering for LUIDs. Although LUIDs are allocated monotonically within a boot session (see §3.3), consumers MUST NOT rely on numeric ordering to infer temporal relationships between LUIDs obtained from different contexts.

§3.3 3 Luid

Allocation

LUIDs MUST be allocated by the kernel.

§3.3.1 Uniqueness scope

Each LUID MUST be unique within a single boot session.

LUID values MUST NOT be assumed unique across reboots. A value allocated in one boot session MAY be reused in a subsequent boot session.

§3.3.2 Monotonicity

The kernel MUST allocate LUIDs in strictly monotonically increasing order within a boot session, treating the two fields as a single unsigned 64-bit integer (HighPart << 32 | LowPart).

The starting value of the allocation sequence after each boot is implementation-defined.

ⓘ Informative
Subsystems that define well-known LUID values (such as privilege identifiers) typically reserve values below the allocation starting point. The starting value should be chosen to leave room for current and future well-known values.

§3.3.3 Fabrication prohibition

Userspace code MUST NOT fabricate LUID values. All LUIDs MUST be obtained through the kernel allocation interface or from well-known constants defined in a Peios specification.