Configuration

Extension configuration

Configure nr-vault in Admin Tools > Settings > Extension Configuration.

storageAdapter

Type: string
Default: local
Options: local

Where secrets are stored.

local: Store secrets in the TYPO3 database (default). Secrets are encrypted with envelope encryption before storage.

Note

External vault adapters (HashiCorp Vault, AWS Secrets Manager) are planned for future releases. The adapter architecture is designed to support external backends, but currently only the local database adapter is implemented. See Custom storage adapters for information on implementing custom adapters.

masterKeyProvider

Type: string
Default: typo3
Options: typo3, file, env

How to retrieve the master encryption key.

typo3: Derive from TYPO3's encryption key. This is the recommended default as it requires no additional configuration and works out of the box.
file: Read from a file on the filesystem.
env: Read from an environment variable.

masterKeySource

Type: string
Default: NR_VAULT_MASTER_KEY

Source location for the master key. Interpretation depends on the provider:

file: Path to the key file (e.g., /secure/path/vault.key).
env: Environment variable name (e.g., NR_VAULT_MASTER_KEY).
typo3: Not used (key derived from TYPO3's encryption key).

allowCliAccess

Type: boolean
Default: false

Allow CLI commands to access secrets without a backend user session.

cliAccessGroups

Type: string
Default: empty

Comma-separated list of backend user group UIDs that CLI can access. Empty means all secrets are accessible when CLI access is enabled.

auditLogRetention

Type: integer
Default: 365

Number of days to retain audit log entries. Set to 0 for unlimited retention.

preferXChaCha20

Type: boolean
Default: false

Prefer XChaCha20-Poly1305 over AES-256-GCM. XChaCha20 is recommended when hardware AES acceleration is not available.

Master key providers

TYPO3 provider (default)

Uses TYPO3's built-in encryption key to derive the master key. This is the recommended default because:

Zero configuration: Works immediately after installation.
No server access required: Ideal for users without shell access.
Unique per installation: Each TYPO3 instance has its own key.
Already secured: TYPO3's encryption key is already protected.

The master key is derived from the encryption key using HKDF-SHA256 with a nr-vault-specific context, ensuring it cannot be used to compromise other TYPO3 functionality.

Master key derivation (internal)

// How it works internally
$masterKey = hash_hkdf(
    'sha256',
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'],
    32,
    'nr-vault-master-key'
);

Note

If you rotate TYPO3's encryption key, all secrets will need to be re-encrypted. Use the key rotation command before changing the encryption key.

File provider

Store the master key in a file with restrictive permissions:

Create master key file

# Generate a new key
openssl rand -base64 32 > /secure/path/vault-master.key
chmod 0400 /secure/path/vault-master.key

Configure in extension settings:

masterKeyProvider: file
masterKeySource: /secure/path/vault-master.key

Warning

The key file must be:

Outside the web root.
Readable only by the web server user.
Not in version control.
Backed up separately from the database.

Environment provider

Store the master key in an environment variable:

Set master key via environment

export NR_VAULT_MASTER_KEY="base64-encoded-key"

Configure in extension settings:

masterKeyProvider: env
masterKeySource: NR_VAULT_MASTER_KEY

This is ideal for containerized deployments where secrets are injected via environment variables.

Access control

Access to secrets is controlled by:

Ownership: The user who created the secret has full access.
Group membership: Secrets can be shared with backend user groups.
Admin access: Backend administrators have access to all secrets.
CLI access: Configurable via allowCliAccess.

Context-based scoping

Organize secrets by context for easier management:

payment - Payment gateway credentials.
email - Email service API keys.
api - Third-party API tokens.
database - External database credentials.

Contexts are user-defined strings that help organize and filter secrets.

Site configuration integration

Use the %vault(identifier)% syntax in site configuration files:

config/sites/main/config.yaml

settings:
  payment:
    stripeSecretKey: '%vault(stripe_api_key)%'
  email:
    mailchimpKey: '%vault(mailchimp_key)%'

Secrets are resolved when the site configuration is loaded. This keeps sensitive values out of version control while allowing configuration through the standard TYPO3 site settings.

Frontend-accessible secrets

By default, secrets cannot be resolved in frontend context (TypoScript). To allow a secret to be used in TypoScript:

Create the secret with frontend_accessible metadata.
Use the %vault(identifier)% syntax in TypoScript.

Store frontend-accessible secret

$this->vaultService->store(
    'google_maps_key',
    $apiKey,
    [
        'metadata' => [
            'frontend_accessible' => true,
        ],
    ],
);

Warning

Frontend-accessible secrets may be exposed in rendered HTML output. Only use this for secrets that are intended to be public (like client-side API keys).