Security 

How it works 

1. Data Encryption Key (DEK): Each secret gets a unique 256-bit key generated using cryptographically secure random bytes.
2. Value encryption: The secret value is encrypted with its DEK using AES-256-GCM (or XChaCha20-Poly1305).
3. DEK encryption: The DEK is encrypted with the Master Key and stored alongside the encrypted value.
4. Decryption: To read a secret, first decrypt the DEK with the Master Key, then use the DEK to decrypt the value.

Benefits 

• Key rotation: Rotating the master key only requires re-encrypting DEKs, not the actual secret values.
• Blast radius: If a DEK is compromised, only one secret is affected.
• Performance: Bulk operations on secrets don't require the master key for each operation.

Provider security comparison 

TYPO3 provider (default, recommended for most users)

Security depends on TYPO3's encryption key protection. Suitable for environments where the encryption key is properly secured in settings.php. No additional configuration required.

File provider (recommended for high-security environments)

Allows storing the key outside the database and web root with strict permissions. Requires server access to configure.

Environment provider (recommended for containers)

Ideal for containerized deployments where secrets are injected at runtime. Follows 12-factor app methodology.

File storage recommendations 

When using the file provider:

1. Outside web root: Never store in publicly accessible directories.
2. Restrictive permissions: Use 0400 (read-only by owner).
3. Separate backup: Back up the master key separately from the database.
4. Access logging: Monitor access to the key file.
5. Key rotation: Rotate the master key periodically.

Hash chain integrity 

Audit log entries form a hash chain where each entry includes a hash of the previous entry. This provides:

• Tamper detection: Any modification to log entries breaks the chain.
• Completeness: An entry deleted from the middle of the log leaves a UID gap, which the verifier reports as an error even if the surrounding previous_hash values were patched to match.
• Non-repudiation: Actions cannot be denied after logging.

Removing the tail of the log leaves no gap and no broken link, so the chain walk alone cannot see it. That case is covered by the tip anchor below.

Tip anchor (truncation detection) 

The chain proves that what is stored was not altered. It cannot, on its own, prove how much should be stored — any counter kept inside tx_nrvault_audit_log is deleted along with the rows.

nr_vault therefore records one signed assertion outside that table, in the core table sys_registry:

Audit row uid = A still exists and its entry_hash is still H.

The assertion is authenticated with HMAC-SHA256 under a key derived from the master key with its own HKDF context string ("nr-vault-audit-anchor-v1"), which is not stored in the database. It advances on every audit write, inside the same transaction as the audit row, and is re-recorded by master-key rotation and by both HMAC re-seal paths. See ADR-034: Audit chain tip anchor.

What this adds: DELETE FROM tx_nrvault_audit_log WHERE uid > N, deletion of the last row, TRUNCATE, and a truncate followed by refilling the same UIDs with fresh entries are all reported as an invalid chain — by vault:audit --verify, by the backend verification view, and by the gates that guard master-key rotation and the HMAC migration.

What this does not add: an attacker with database write access who deletes the sys_registry row before truncating returns the installation to undetectable truncation. That is reported as a warning (`Tip anchor: NOT ARMED`) rather than an error, because an installation that has not yet written an audit entry since the upgrade is indistinguishable from one whose anchor was deleted.

vendor/bin/typo3 vault:audit --reset-anchor

HMAC-keyed audit chain 

The audit hash chain is authenticated with HMAC-SHA256, using a key derived from the master key via HKDF (see ADR-023: Audit hash chain HMAC consideration). This provides adversarial tamper resistance in addition to tamper detection:

• Adversarial resistance: An attacker with database access but without the master key cannot forge valid HMAC values or recompute the hash chain.
• Cryptographic separation: The HMAC key is derived with a dedicated context string ("nr-vault-audit-hmac-v1"), ensuring independence from encryption key material.
• Backward compatibility: Legacy entries (epoch 0) created before the HMAC migration remain verifiable using the original SHA-256 algorithm. New entries (epoch 1+) use HMAC-SHA256.

Use the vault:audit-migrate-hmac command to migrate existing legacy entries to HMAC-SHA256. See vault:audit-migrate-hmac for details.

Operation permissions 

Each vault operation has its own permission, granted per backend user group in the Backend Users module (field Custom module options, group Vault: operation permissions). They are registered as TYPO3 custom permission options under $GLOBALS['TYPO3_CONF_VARS']['BE']['customPermOptions']['tx_nrvault'] and checked server-side via AccessControlServiceInterface::isGranted().

Notes on the model:

• ``secret.use`` does not imply ``secret.reveal``, and neither implies the other. A non-admin needs both for an end-to-end reveal: the endpoint asserts secret.reveal (displaying plaintext), and the shared read path asserts secret.use (obtaining it at all). An integration account gets secret.use only.
• Non-admin backend users need ``secret.use`` for every plaintext read, including FormEngine vault field widgets and FlexForm / TypoScript placeholder resolution. Grant it to the groups whose editors work with vault-backed fields.
• Mutations are enforced centrally in the service, not only in the module controllers. VaultService::store() requires secret.create (new identifier) or secret.rotate (existing identifier, plus secret.manage_policy when the call also changes owner, group tiers or frontend availability); rotate() requires secret.rotate; delete() requires secret.delete. A direct DataHandler/FormEngine request or a programmatic caller therefore faces the same gates as the secrets module. Editors whose forms write vault-backed TCA fields need secret.create / secret.rotate in addition to secret.use. Creating a tx_nrvault_secret record asserts secret.create even when no value is submitted. That one case cannot go through the service — no value means no store() call — so SecretTcaHook gates it in processDatamap_preProcessFieldArray(), refusing the record before DataHandler inserts it rather than deleting it afterwards.
• Technical actors (TechnicalActorContext::runAs()) hold secret.use implicitly — headless consumption is their purpose — and every other operation permission only if one of their provisioned backend groups grants it via the same tx_nrvault:* custom permission options.
• Admins and system maintainers hold every permission unconditionally, and have full per-secret access to every secret. That override lives in a single seam (AccessControlService::adminBypassActive()) and can be removed — see Disabling the admin override.
• The backend modules are registered ``access => 'user'``. That is deliberate: authorization is asserted by each controller action, not by the module registration, so granular grants are usable by non-admins. The same holds for the vault_reveal / vault_rotate AJAX routes.
• CLI: a trusted CLI operator has no backend user record and thus no group grants. Operation permissions follow the vault's allowCliAccess switch (off by default), narrowed to the cliAllowedOperations allowlist (default: secret.use,secret.create,secret.rotate). High-risk operations are excluded by default: vault:retrieve (needs secret.reveal), vault:delete / the scheduled orphan cleanup (secret.delete), vault:rotate-master-key (master_key.rotate) and the audit export require adding the respective operation to the allowlist — or, preferably, a named technical actor via TechnicalActorContext::runAs().
• Frontend requests never hold operation permissions, regardless of any backend session the visitor carries — frontend visibility remains a property of the secret (frontend_accessible) alone. For %vault(id)% placeholder resolution there is a second gate on top: the identifier must also be in the request's FrontendPlaceholderPolicy allow-set (ADR-035: Per-request allow-set of frontend-resolvable identifiers), which the CLI enforces too unless frontendPlaceholderLegacyCli is set.

Disabling the admin override 

By default a TYPO3 administrator holds every vault permission and full read/write/delete access to every secret. For most installations that is the right answer: an admin already controls settings.php, the master-key provider and the extension configuration, so withholding vault permissions from them would be theatre.

It stops being theatre in two situations: an installation where "TYPO3 administrator" and "may read production credentials" are genuinely different roles, and an audit regime that requires every plaintext access to be attributable to a granted permission rather than to a role. For those, set

securityProfile = hardened
disableAdminOverride = 1

and administrators are treated like every other backend user: they hold exactly the operation permissions their groups were granted, and reach only the secrets they own or share a group with.

$GLOBALS['TYPO3_CONF_VARS']['SYS']['nrVault']['disableAdminOverride'] = true;

Break-glass mode 

A disabled override needs an escape hatch, or the first genuine incident becomes an outage. Break-glass mode is that hatch: a deliberate, justified, time-boxed restoration of the admin override.

# 1. Confirm the state
vendor/bin/typo3 vault:break-glass --status

# 2. Open a window with a justification
vendor/bin/typo3 vault:break-glass --activate --reason="INC-4711 rotate leaked deploy key" --minutes=30

# 3. Do the work in the backend or on the CLI

# 4. Close it — do not wait for the expiry
vendor/bin/typo3 vault:break-glass --deactivate --reason="INC-4711 closed"

Technical actors 

Headless code (messenger workers, scheduler runs) can act as a named technical backend user through the scoped TechnicalActorContext::runAs() API instead of the global CLI switch.

Threat-model notes:

• runAs() is not an authentication boundary: any PHP code with DI access can act as any enabled backend user — the same power that $GLOBALS['BE_USER'] mutation already grants every installed extension. Its security value is validation (deleted/disabled/time-restricted users are refused), guaranteed scope restoration (also on exceptions), and honest audit attribution.
• $GLOBALS['BE_USER'] is never mutated, so a technical identity cannot leak into other code sharing the PHP process.
• Audit entries written inside a scope carry `actor_type = 'technical'` plus the actor's uid and username, sealed into the HMAC hash chain — impersonation is always attributable and tamper-evident.
• Restrict the technical user like any backend account: no admin flag unless required, minimal group membership, and monitor its access_denied events.

Exit-code contract 

The verdict is the worst severity present, never an average, so a long list of passing controls cannot offset one critical finding. And 2 covers "could not check" as well as "checked and found a problem" — a gate that cannot run must never be readable as a gate that found nothing.

Two ways to wire it, and they answer different questions:

vendor/bin/typo3 vault:doctor
test $? -le 1

vendor/bin/typo3 vault:doctor

The stricter form is the one to aim for. Accepting exit 1 indefinitely means a warning nobody ever removes, which is the state in which a new warning goes unnoticed.

Checking a profile you have not adopted yet 

--profile=hardened evaluates the live configuration against the hardened policy without changing anything. That is how to plan the migration described in Disabling the admin override — from the actual finding list, rather than by switching the profile on production and finding out which service stops booting.

The report always states both the profile it checked and the profile in force, so a passing dry run cannot be mistaken for hardening already being live.

What the gate does not cover 

vault:doctor bounds its own cost so it can run in a pipeline and on a backend page load. Two limits matter, and both are stated in the findings themselves:

• the hash-chain pass covers the newest 1000 audit entries, not the whole chain;
• the anchor comparison detects a chain that has shrunk, not one whose anchored row now hashes differently.

vault:audit-verify does both in full and is the authoritative integrity verifier. Schedule it — the gate is a pre-flight check, not a substitute for continuous verification.

Backend surface 

The vault Overview module shows the same controls: the active profile, an "N of M controls passed" ratio, and the open findings with their risk and remediation. The detailed finding list requires the vault.configure permission — it names this installation's concrete weak points and the files to edit. Everyone else sees the profile badge and the ratio, which is enough to escalate.