> For the complete documentation index, see [llms.txt](https://8w6s.gitbook.io/hvpdb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://8w6s.gitbook.io/hvpdb/security/security-model.md).

# Security model

HVPDB focuses on encryption at rest. It also supports optional per-user authentication.

### High-level model

* Main DB file is encrypted.
* WAL file is encrypted.
* The master password derives the File Encryption Key (FEK).
* The FEK is never stored.
* User passwords are stored as KDF hashes.

Encryption primitive:

* AES-256-GCM (AEAD)

Crypto details are in [Cryptography & key derivation](/hvpdb/security/cryptography-and-key-derivation.md).

### Threat model (scope)

In scope:

* offline disk theft
* at-rest data confidentiality
* tamper detection on ciphertext (AEAD)

Out of scope:

* a compromised runtime with the password in memory
* a malicious plugin (plugins are trusted code)
* traffic security if you expose the HTTP server without TLS

### Key management

#### Key creation

* a random salt is generated per DB/WAL header
* the master password derives the FEK via Argon2id or Scrypt

#### Rotation

You can rotate the master password. This decrypts with the old password and rewrites with the new password.

Entry points:

* CLI: `hvpdb passwd <target>`
* HVPShell: `crypt <password>`

#### Backup and recovery

Backups are file-level. Keep backups and passwords protected.

See [Backup & recovery](/hvpdb/operations/backup-and-recovery.md).

{% hint style="warning" %}
Encryption protects data at rest. It does not replace process isolation. Do not run untrusted code in the same process.
{% endhint %}

### Timing-attack resistance

Credential verification does cryptographic work even for unknown users.

This helps prevent timing-based user enumeration.

Implementation detail:

* comparisons use `secrets.compare_digest()` (constant-time)

### TOCTOU-safe lock acquisition

Lock files are created atomically.

This avoids Time-Of-Check-To-Time-Of-Use races during acquisition.

Implementation detail:

* uses `os.open(..., O_CREAT | O_EXCL)` for lock creation

### Passkey / FIDO2 authentication (v1.0.7)

HVPDB supports passwordless auth via WebAuthn/FIDO2.

CLI entry points:

* `hvpdb gen-passkey <user> --native`
* `hvpdb login-passkey <user> --native`

### Access key authentication

Access keys are portable credentials for automation.

CLI entry points:

* `hvpdb gen-key --qr --save access_key.json`
* `hvpdb shell <target> --access-key access_key.json`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://8w6s.gitbook.io/hvpdb/security/security-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.