---
title: "Integrity & trust"
manual: "T3Vault"
version: "main"
permalink: "https://docs.typo3.org/permalink/codemacher/t3vault:integrity@main"
source: "Integrity/Index.rst"
rendered: "2026-10-01T12:10:44+00:00"
---

# Integrity & trust {#integrity}

-   [Verify with T3Vault CLI](https://docs.typo3.org/permalink/codemacher/t3vault:verify-with-t3vault-cli@main)
-   [Manual verification with the OpenTimestamps client](https://docs.typo3.org/permalink/codemacher/t3vault:manual-verification-with-the-opentimestamps-client@main)

## Overview {#integrity-overview}

When a backup finishes, T3Vault seals it with `BackupIntegrityService`:

1.  Hash artefacts (`*.zip` incl. `database.zip`, legacy `database.sql.gz` / `database.sql`,
    `MANIFEST.json`) with SHA-256.
1.  Write `integrity.json` (algorithm, `createdAt`, file digests).
1.  Optionally write `integrity.json.hmac` (HMAC-SHA256 bound to the site
    `secret`).
1.  Submit the digest of `integrity.json` to OpenTimestamps calendars and
    store the proof as `integrity.json.ots`.
1.  Write `integrity-meta.json` (stamp outcome metadata — **not** a trust
    anchor).

Trust model:

-   Changing backup files without a new seal breaks the hash check.
-   Forging a new seal requires a new OpenTimestamps proof.
-   Final time-stamp time comes from the Bitcoin blockchain, not this server.
-   A large gap between `createdAt` and that blockchain time is treated as
    suspicious (T3Vault allows up to 72 hours for calendar → chain confirmation).
-   Until the proof is fully attested, status stays `pending`.
-   HMAC is only checked when the site secret is available; on foreign hosts it is
    skipped so cross-system restore still works.

## How to verify a backup (recommended) {#integrity-how-to-verify}

The goal is to detect whether the backup was **modified after sealing**.

**Recommended:** re-hash artefacts against `integrity.json` with the
bundled verifier (no Bitcoin node required):

```bash
php t3vault-verify.phar /path/to/backup_YYYYMMDD_HHMMSS_<id>
```

Exit code `0` / state `ok` (or `pending` with matching hashes) means the
listed files still match the seal. State `tampered` means do **not** restore.

**Optional:** confirm the seal via [Manual verification with the OpenTimestamps client](https://docs.typo3.org/permalink/codemacher/t3vault:opentimestamps-manual@main) — either in the
browser on [opentimestamps.org](https://opentimestamps.org/) or with the
`ots` CLI. The hash check above already answers the “was it changed?”
question for the archive files.

You can also verify from the T3Vault UI (**Integrity** / verify action).

Always keep `integrity.json` and `integrity.json.ots` together in
the backup directory.

## Verification states {#integrity-states}

| State | Meaning |
| --- | --- |
| `ok` | Hashes match and OTS proof is attested within the time window |
| `pending` | Hashes OK; calendar proof not yet upgraded to Bitcoin |
| `missing` | Integrity files incomplete |
| `stamp_failed` | Stamping failed earlier; hashes may still be OK |
| `tampered` | Hash or OTS digest mismatch / attestation skew |
| `checking` | Transient UI state while a check runs |