Skip to main content
A device’s private key is its identity. By default Omega stores that key in a file in cert_dir; anyone who can read that file can clone the device. A hardware-backed key is generated inside a secure element (TPM, HSM, or Secure Enclave) and never leaves it — the device can sign with the key but can’t export it, so the key can’t be copied to another machine even by someone with full disk access. This page covers the per-OS backends, the OMEGA_KEY_PREFERENCE setting that decides whether hardware is required, and the one rule that keeps them consistent: the build and the preference must agree.

​
Backends (compile-time, per OS)

A hardware backend is a Cargo feature — you compile in the one that matches the device’s OS: A binary with no hardware backend compiled in can only produce software keys. So “can this device use a hardware key?” is answered at build time; “must it?” is answered by the setting below.

​
The preference: OMEGA_KEY_PREFERENCE

Whether Omega requires, prefers, or skips hardware is set by the environment variable OMEGA_KEY_PREFERENCE: Unrecognized values (and a typo) fall back to prefer_hardware with a warning — refusing to start would turn a typo in a deployment script into a bricked fleet, but the warning ensures a misspelled require_hardware doesn’t silently become prefer_hardware, which is the one direction that must never happen quietly.
This is an environment variable, not a profile field — deliberately. The device key is provisioned during enrollment, which runs before the profile’s module sections are loaded. A setting that only existed in the profile couldn’t reach the one decision it needs to influence. Set it in the service environment (the systemd unit, the launchd plist, the Windows service environment).

​
Build and preference must agree

The feature and the env var are two halves of one decision. Get them lined up: The failing row is the important one: asking for require_hardware on a binary built without a backend for that OS is a contradiction, and Omega surfaces it at startup rather than limping along on a software key the policy was meant to forbid.

​
Why loud-at-startup, not silent-fallback

require_hardware fails at boot, not at first authorization, on purpose. A device that quietly enrolls with a software key and is later denied by a hardware-only policy looks like a policy bug from every angle — the device is “online,” its cert is valid, yet every command is refused. Failing at startup, with the reason in the startup log, puts the error where the operator can act on it. The honest key-class reporting is the other side of this: a prefer_hardware device that fell back to software says so, so platform policy can decide what a software key is worth per resource. A fleet can roll out on its weakest platform and tighten later — nothing pretends to be hardware-backed when it isn’t.

​
Rotation and renewal

Hardware keys participate in certificate renewal like any other key — the secure element signs the CSR, the renewed certificate is written to cert_dir, and the private key never moves. A require_hardware device that somehow holds no hardware key won’t silently create a software one to get unstuck; it refuses, because the honest failure is the safer one.

​
Checklist for a hardware-key device

  • Built with the backend for its OS (keystore-cng / keystore-pkcs11 / keystore-secure-enclave).
  • OMEGA_KEY_PREFERENCE=require_hardware in the service environment (or prefer_hardware if a software fallback is acceptable).
  • The service account can reach the secure element (TPM device node / PKCS#11 module / Keychain).
  • Verified at first boot that the key class the device reports is what you expect.

​
See also