PROJECT TRANSITION NOTICE

MyKey was an experimental prototype that is being refocused in a new direction. MyKey remains available as research history and implementation reference and should not be installed. MyKey will no longer be receiving any more updates, features, or fixes and is officially considered abandoned. ALL documentation reflects the state of the project at the time development stopped. For more information please see platform-auth

MyKey

Windows Hello–inspired platform authentication for Linux.
Trusted local authentication, TPM-backed secrets, and Linux-native platform security built around PAM, session trust, and real hardware-backed protection.

---

👋 What Is MyKey?

MyKey is an experimental Linux security platform focused on building a more cohesive platform-authentication experience for Linux desktops.

The project combines:

• 🔐 TPM-backed secret protection
• 🧠 trusted local authentication
• 🗝️ a hardware-aware Secret Service provider
• 🧩 PAM-integrated authentication orchestration
• 🧭 daemon-tracked trusted login sessions
• 🚪 explicit session step-up authentication
• 🧑‍💻 a user-session agent foundation for future step-up UX
• 🔎 diagnostics and Secret Service validation tooling
• 🔢 Windows Hello–style local PIN workflows
• 🧰 display-manager-aware PAM integration
• 🧭 future platform-authentication and authenticator foundations

The long-term goal is not only to replace traditional software-only keyrings, but to help create a Linux-native authentication layer that applications, desktops, and services can reliably build upon.

Inspired philosophically by the experience of Windows Hello, but designed around Linux tooling, Linux workflows, and explicit trust boundaries.

---

📚 Want To Dig Deeper?

If you want the more technical breakdown of how MyKey is designed, how the pieces fit together, and where the project is headed, start in docs/.

---

🚧 Project Status

MyKey currently includes active foundations for:

• session trust
• PAM ownership
• display-manager-aware login integration
• Secret Service enforcement
• vault v2 storage and recovery groundwork
• explicit session step-up
• user-session agent registration and request visibility
• platform-authentication groundwork

Development is moving quickly and internal authentication behavior may change between development builds.

At this stage:

• mykey-git is the only supported package
• development builds should be treated as experimental
• PAM/session/auth behavior is actively evolving
• recovery flows are scaffolded but not yet live
• third-party keyring import is intentionally unsupported
• v1-to-v2 storage migration is intentionally unsupported during this experimental refactor
• WebAuthn/FIDO/passkey behavior is not live yet

Current focus areas include:

• trusted login sessions
• TPM-backed vault v2 Secret Service storage
• trusted-session-gated Secret Service enforcement
• explicit mykey auth step-up trust promotion
• mykey-agent as the future user-session step-up UX foundation
• platform trust evaluation
• PAM-integrated authentication ownership
• future Linux-native platform authentication flows

---

✨ Why MyKey?

Linux already has strong security building blocks.

The problem is that they are often fragmented across:

• desktop environments
• keyrings
• PAM modules
• authentication workflows
• local unlock systems
• hardware security tooling

MyKey tries to make those pieces feel more coherent.

The goal is not to hide how security works. The goal is to make trusted local authentication and hardware-backed protection feel more modern, understandable, and integrated without turning them into mystery boxes.

If Windows Hello made local authentication feel straightforward and platform-aware, MyKey is trying to bring that same spirit to Linux using native Linux tooling and explicit trust boundaries.

---

🧩 Components

MyKey is made up of focused modules that work together.

• mykey
• mykey-auth
• mykey-authenticator
• mykey-daemon
• mykey-secrets
• mykey-tray
• mykey-vault

🧭 MyKey

mykey is the top-level terminal control surface with navigation and diagnostics.

• mykey top-level CLI control surface
• mykey help Use it first when you want to discover or route into installed MyKey tools
• mykey status Aggregates platform trust, services, auth/PAM state, session trust, Secret Service, and agent status.
• mykey doctor A read-only system, packaging, auth, and trust-state diagnostic surface.

🧑‍💻 MyKey Agent

mykey-agent is a user-session broker foundation for future step-up UX.

It currently supports:

• mykey-agent --check for safe local session-context diagnostics
• mykey-agent --register for daemon-verified agent availability
• heartbeat and stale-agent visibility
• polling-only attention output for daemon-owned step-up requests

🧩 MyKey Authentication

mykey-auth is the local authentication subtree that groups MyKey’s authentication and PAM-management pieces.

It contains:

• mykey-pam
• mykey-pin
• mykey-biometrics
• mykey-security-key The guided setup path applies MyKey-managed PAM blocks to supported login and unlock targets with auth step-up so unsupported systems stay inside MyKey’s authentication flow. Supported display-manager/login surfaces currently include:
• GDM
• SDDM
• greetd
• LightDM
• LXDM
• Plasma Login Manager Unsupported display managers are left unpatched and should use explicit post-login step-up when needed.

mykey-pam

PAM-facing authentication and trusted-session integration layer. It currently handles:

• pam_mykey.so runtime authentication entrypoint
• MyKey-managed PAM placement for supported login, unlock, sudo, and polkit paths
• daemon-backed local-auth policy enforcement for PIN, biometrics, security keys, and password fallback
• trusted login-session registration and close-session cleanup
• safe PAM failure mapping so infrastructure errors fall back instead of locking users out

mykey-pin

An optional local PIN-based authentication path. The long-term goal is a Windows Hello–style local authenticator for Linux:

• device-bound
• TPM-aware
• local-only
• separate from the Linux account password

mykey-biometrics

Biometric enrollment and policy-management surface. It manages:

• fprintd and Howdy enrollments
• TPM-sealed biometric metadata
• biometric provider status
• biometric provider removal
• daemon-owned biometric policy updates

mykey-security-key

Security-key management command. It currently handles:

• security-key enrollment through pam_u2f
• TPM-sealed MyKey metadata for enrolled keys
• MyKey-managed security-key authentication paths
• dedicated verification and policy flows

🔐 MyKey Authenticator

mykey-authenticator is MyKey’s future WebAuthn, FIDO, and passkey protocol layer.

It is intended to handle:

• platform-authenticator credential creation and assertion flows
• user-presence and user-verification requests through daemon-owned policy
• vault-backed credential material access through defined storage boundaries
• relying-party and origin-aware authenticator decisions
• future browser and application platform-authentication integration

⚙️ MyKey Daemon

mykey-daemon is the security core of the project.

It handles:

• TPM interaction
• trust-state evaluation
• authentication decisions
• caller validation
• trusted login session tracking
• agent registration and heartbeat summaries
• daemon-owned step-up request lifecycle
• final trust promotion for auth step-up
• Secret Service trust enforcement
• privileged operations used by the rest of MyKey

🗝️ MyKey Secrets

mykey-secrets is a Secret Service provider backed by MyKey’s hardware-centered trust model.

It handles:

• stores new secrets through the vault v2 model and gates plaintext reads
• protected mutations on daemon-tracked trusted MyKey login sessions.
• local Secret Service protocol validation client for MyKey's provider.

🖥️ MyKey System Tray

mykey-tray is an optional tray app.

It provides:

• component status visibility
• trust-state visibility
• future quick interactions and notifications

🧱 MyKey Vault

mykey-vault is a shared internal crate for vault storage format, crypto helpers, and recovery scaffolding.

It contains:

• vault v2 metadata and item format structures
• vault and item crypto helpers
• recovery wrapping primitives
• dormant recovery unlock, rotation, and re-enrollment scaffolding

---

🛡️ Security Model

MyKey is designed around a few core ideas.

Hardware should matter

Secrets and security-sensitive operations should be tied to the machine through TPM2 wherever possible.

Local authentication should stay local

MyKey PIN is intended to be a local device authenticator, not a network password and not something that should leave the machine.

Session trust matters

MyKey tracks trusted login sessions through daemon-owned state and uses that state to gate MyKey-protected services and future platform-authentication flows.

For sessions that did not enter through a trusted MyKey-managed login path, mykey auth step-up provides an explicit post-login verification path.

Platform trust matters

MyKey separates Standard Mode from Verified Mode through explicit trust-state evaluation.

Convenience and recovery are not the same thing

Convenient daily authentication and elevated security actions are different categories.

MyKey follows this model:

• 👆 Normal local auth: biometrics, security key, or MyKey PIN
• 🔐 Elevated actions: Linux account password through dedicated password-auth flows

Fail closed where trust cannot be verified

If trust state cannot be verified:

• MyKey secrets remain locked
• degraded states are reported
• hardware-backed guarantees are preserved

---

🖥️ Supported System

MyKey is currently designed around a TPM-first Linux security model with explicit trust modes.

🔩 Required Hardware

• TPM 2.0

🛡️ Verified Mode Requirements

• UEFI firmware
• Secure Boot enabled and enforcing

⚙️ Required System Stack

• systemd
• PAM
• D-Bus
• polkit

⚙️ Recommended and Tested Boot Model

• systemd-boot
• sbctl
• UKI-based boot image

❗ Why the requirements matter

For a deeper explanation, see the threat model.

---

🧪 Testing

Current real-world testing has focused on:

🗝️ Secret management

• Secret Service secret storage and recall
• vault v2 live storage
• trusted-session-gated Secret Service reads and writes
• mykey secrets check provider validation
• mykey doctor system and trust diagnostics
• unsupported legacy v1 storage reporting
• no third-party keyring import or migration

🔢 Local authentication

• daemon-backed PIN flows
• PAM-integrated authentication
• biometric provider integration
• security-key flows
• trusted login-session tracking
• PAM-integrated login ownership
• display-manager-aware PAM profiles

🔐 Session trust

• trusted login-session registration
• PAM-integrated session tracking
• daemon-owned trust-state evaluation
• explicit mykey auth step-up
• mykey-agent registration and heartbeat visibility
• Secret Service plaintext-read gating
• Secret Service protected mutation gating

Testing coverage is improving, but this is still an active architecture-heavy project and not a completed security product.

---

🤖 AI Disclosure

Parts of this project were developed with the help of AI tools.

Architecture direction, review, validation, testing decisions, and all final security and implementation decisions remain human.

---

📜 License

MIT — JamesFromFL, 2026