Struct MasterKey 

pub struct MasterKey(/* private fields */);

The master key: a 256-bit CSPRNG random value.

It is the only long-lived secret of the application

OTP seeds, device identities and sync payloads are all derived from it or encrypted under it. With no central server and no account, there is no recovery path: a lost key is lost. The key is meant to be held by the platform hardware key store (Windows TPM).

Boundaries of secret protection

• No Clone (which would silently copy the plaintext) and no plaintext in Debug output.
• Erased on Drop (guaranteed by SecretBytes).
• The plaintext is not protected from being copied into registers, stack copies or the swap file; forbid(unsafe_code) rules out mlock to prevent paging.
• Malicious code in the same process is not defended against. Reading the plaintext requires an explicit call to MasterKey::expose, which keeps every use site visible in code review.

Implementations

impl MasterKey

pub fn generate() -> Result<Self>

Generates a new random master key.

Errors

Returns Error::RandomnessUnavailable when the OS random source is unavailable, and there is no fallback to a user-space PRNG: a predictable master key would let an attacker decrypt every entry, and such a failure would be silent. The key bytes are handed to SecretBytes, which owns the buffer and erases it on drop.

pub fn from_bytes(bytes: SecretBytes) -> Result<Self>

Restores the master key from existing bytes.

Security contract: the caller must ensure that bytes come from a trusted source and are erased afterwards. Device login is the only consumer: the master key is recovered from the platform key store or from an out-of-band channel (a QR code). This is not a way to keep a master key in an ordinary file.

Errors

Returns Error::MasterKeyWrongLength when the length is not MASTER_KEY_LEN. A wrong length is rejected rather than padded or truncated: padding would silently weaken the key, and truncation would make two devices derive different subkeys.

pub fn expose(&self) -> &[u8]

Explicitly reads the master key plaintext.

Deref and AsRef are deliberately not implemented: they would read the plaintext silently in many places, whereas an explicit method name keeps every use site visible to grep and code review.

pub fn matches(&self, other: &Self) -> bool

Constant-time equality.

Used where two independently recovered keys are compared — for example “the password wrap and the platform wrap must yield the same master key”. A short-circuiting == would leak how many leading bytes matched.

Trait Implementations

impl Debug for MasterKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Prints the type name only, not even the length.

The length carries no diagnostic value here, since it is a constant.