mirror of
https://github.com/agentrhq/authsome.git
synced 2026-09-19 01:34:19 +08:00
Manoj Bajaj
84 lines
3.4 KiB
Plaintext
84 lines
3.4 KiB
Plaintext
---
|
|
title: "Encryption at rest"
|
|
sidebarTitle: "Encryption at rest"
|
|
description: "How Authsome encrypts credentials in the local vault. Argon2id KEK/DEK model and AES-256-GCM."
|
|
icon: "lock"
|
|
keywords: ["authsome encryption", "AES-256-GCM credentials", "credential vault encryption", "Argon2id KEK"]
|
|
---
|
|
|
|
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](/security/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
|
|
|
|
<Columns cols={2}>
|
|
<Card title="Threat model" icon="shield-halved" href="/security/threat-model">
|
|
What authsome protects against and what it doesn't.
|
|
</Card>
|
|
<Card title="Credential storage" icon="database" href="/concepts/credential-storage">
|
|
Storage layout, key namespace, and the three states.
|
|
</Card>
|
|
</Columns>
|
|
|