Encryption at rest

How Authsome encrypts credentials in the local vault. Argon2id KEK/DEK model and AES-256-GCM.

Authsome encrypts every sensitive credential field in the vault before writing it to disk. The encryption is symmetric, using AES-256-GCM, and relies on an Argon2id KEK/DEK model.

Parameters

Algorithm	AES-256-GCM
Vault encryption	Argon2id KEK/DEK model
Nonce	96 bits, generated per encryption
Tag	128 bits (GCM authentication tag)

The choice of AES-256-GCM provides both confidentiality and integrity in one pass. It is the same primitive used by TLS 1.3 and most modern at-rest stores.

What gets encrypted

Every sensitive field on a Connection is encrypted before write:

• access_token
• refresh_token
• api_key
• client_secret
• id_token (when stored)
• Any provider-issued secret bound to the connection

client_id, scopes, expiry timestamps, and account metadata are stored in plaintext. They are not sensitive on their own and need to be queryable.

The Argon2id KEK/DEK Model

Authsome uses a Key Encryption Key (KEK) and Data Encryption Key (DEK) approach.

The Master Key (or KEK) wraps the underlying data key (DEK) used for the actual AES-256-GCM encryption. This model separates the key used for bulk encryption from the key used to authorize access to the Vault.

Master key sources

The daemon resolves the Master Key depending on how the Vault was initialized.

Authsome prefers stronger and more external key sources first:

1. AUTHSOME_MASTER_KEY from the environment. The value must be a base64-encoded 32-byte key.
2. An existing OS keyring entry.
3. An existing ~/.authsome/server/master.key.
4. A newly created OS keyring entry, when the keyring is available.
5. A newly created local ~/.authsome/server/master.key as the final fallback.

authsome whoami shows the effective source chosen at runtime.

Warning: Key loss

There is no recovery if the Master Key is lost. Without master.key (or the respective OS keyring entry), the encrypted records cannot be decrypted. Treat your master.key and store.db backup strategy with the same care you would give raw credentials.

What encryption does not do

Encryption protects against offline disk access. It does not protect against:

• A running process with access to the master key. Once the daemon decrypts a record, the plaintext lives in memory for the duration of the request.
• Memory inspection via ptrace or kernel-level introspection.
• A backup tool that copies master.key and store.db together into an insecure location.

The full trust model is in Threat model.

Key rotation

Replacing the master key without losing records is handled via the authsome admin rekey command or the daemon API. Records are re-wrapped using the new key without losing the underlying Vault items.

What’s next

Threat model

What authsome protects against and what it doesn’t.

Credential storage

Storage layout, key namespace, and the three states.