loader/_docs/02_document/modules/hardware_service.md

Module: hardware_service

Purpose

Collects a hardware fingerprint string from the host OS (CPU, GPU, memory, drive serial) for use in hardware-bound encryption key derivation.

Public Interface

Classes

HardwareService (cdef class)

Method	Signature	Description
get_hardware_info	@staticmethod cdef str ()	Returns cached hardware fingerprint string

Module-level State

Name	Type	Description
_CACHED_HW_INFO	str	Cached result (computed once)

Internal Logic

get_hardware_info

1. If cached (_CACHED_HW_INFO is not None), return cached value immediately
2. Detect OS via os.name:
   • Windows (nt): PowerShell command querying WMI (Win32_Processor, Win32_VideoController, Win32_OperatingSystem, Disk serial)
   • Linux/other: shell commands (lscpu, lspci, free, block device serial)
3. Parse output lines → extract CPU, GPU, memory, drive serial
4. Format: "CPU: {cpu}. GPU: {gpu}. Memory: {memory}. DriveSerial: {serial}"
5. Cache result in _CACHED_HW_INFO

The function uses subprocess.check_output(shell=True) — platform-specific shell commands.

Dependencies

• Internal: constants (for log())
• External: os, subprocess (stdlib)

Consumers

• api_client — load_bytes() and check_resource() call HardwareService.get_hardware_info()

Data Models

None.

Configuration

None. Hardware detection commands are hardcoded per platform.

External Integrations

• OS commands: Windows PowerShell (Get-CimInstance, Get-Disk) or Linux shell (lscpu, lspci, free, /sys/block)

Security

Produces a hardware fingerprint used to bind encryption keys to specific machines. The fingerprint includes drive serial number, which acts as a machine-unique identifier.

Tests

No tests found.