> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/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>