Installation 

Requirements 

Before installing nr-vault, ensure your system meets these requirements:

  • TYPO3 v13.4 LTS or v14.3 LTS.
  • PHP 8.2 or higher.
  • PHP sodium extension (usually included in PHP 8.2+).
  • Composer-based TYPO3 installation.

Installation via Composer 

Install the extension using Composer:

Install via Composer 
composer require netresearch/nr-vault
Copied!

Activate the extension 

After installation, activate the extension in the TYPO3 backend:

  1. Go to Admin Tools > Extensions.
  2. Find "nr-vault" in the list.
  3. Click the activation icon.

Or use the command line:

Activate extension via CLI 
vendor/bin/typo3 extension:activate nr_vault
Copied!

Database schema 

Update the database schema to create the required tables:

Update database schema 
vendor/bin/typo3 database:updateschema
Copied!

This creates the following tables:

  • tx_nrvault_secret - Stores encrypted secrets with metadata.
  • tx_nrvault_secret_begroups_mm - Read-tier group relations.
  • tx_nrvault_secret_writegroups_mm - Write-tier group relations.
  • tx_nrvault_audit_log - Stores audit log entries with hash chain.

The chain tip anchor, the break-glass session and the per-sink delivery state live in core's sys_registry rather than in a table of their own.

Master key setup 

nr-vault requires a master encryption key to protect your secrets. There are four options, from simplest to most configurable:

Option 1: TYPO3 encryption key (default, zero configuration) 

This is the recommended default. nr-vault automatically derives a master key from TYPO3's built-in encryption key ( $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'] ).

No configuration required - nr-vault works immediately after installation.

Benefits:

  • Zero setup - works out of the box
  • Unique per TYPO3 installation
  • Already secured by TYPO3's configuration protection

Option 2: Environment variable 

For containerized deployments or when you need explicit control:

  1. Generate a master key:

    Generate master key 
    openssl rand -base64 32
    Copied!

  2. Set the environment variable:

    Set environment variable 
    export NR_VAULT_MASTER_KEY="your-generated-key"
    Copied!

  3. Configure the extension in Admin Tools > Settings > Extension Configuration:

Option 3: Key file 

For maximum security, store the key in a file outside the web root:

Create secure key file 
openssl rand -base64 32 > /secure/path/vault.key
chmod 0400 /secure/path/vault.key
Copied!

Configure the extension:

Option 4: HashiCorp Vault Transit 

Where a Vault deployment already exists, the master key can be kept wrapped by Vault's transit engine so only ciphertext is stored locally, and custody, rotation and audit move into Vault. Setup (transit engine, policy, token) is described in HashiCorp Vault Transit provider.

See Master key providers for detailed information on each provider.

Verify installation 

Verify the installation by listing secrets (should return empty if newly installed):

List vault secrets 
vendor/bin/typo3 vault:list
Copied!

If the command executes without errors, the extension is properly configured.

You can also test by storing and retrieving a test secret. Note that this probe needs CLI access that is off by default: allowCliAccess must be on, and secret.reveal and secret.delete must be added to cliAllowedOperations, which excludes both. If you would rather not widen that for a smoke test, create and reveal a secret in the backend module instead — it exercises the same encrypt and decrypt path.

Test vault functionality 
# Store a test secret (needs allowCliAccess; secret.create is in the default allowlist)
vendor/bin/typo3 vault:store test_secret --value="test-value"

# Retrieve it (additionally needs secret.reveal in cliAllowedOperations)
vendor/bin/typo3 vault:retrieve test_secret

# Clean up (additionally needs secret.delete in cliAllowedOperations)
vendor/bin/typo3 vault:delete test_secret --force
Copied!