Installation

Requirements

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

TYPO3 v14.0 or higher.
PHP 8.5 or higher.
PHP sodium extension (usually included in PHP 8.5).
Composer-based TYPO3 installation.

Installation via Composer

Install the extension using Composer:

Install via Composer

composer require netresearch/nr-vault

Activate the extension

After installation, activate the extension in the TYPO3 backend:

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

Or use the command line:

Activate extension via CLI

vendor/bin/typo3 extension:activate nr_vault

Database schema

Update the database schema to create the required tables:

Update database schema

vendor/bin/typo3 database:updateschema

This creates the following tables:

tx_nrvault_secret - Stores encrypted secrets with metadata.
tx_nrvault_audit_log - Stores audit log entries with hash chain.

Master key setup

nr-vault requires a master encryption key to protect your secrets. There are three 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

Note

If you later rotate TYPO3's encryption key, use the vault:rotate-master-key command first to re-encrypt all secrets with the new key.

Option 2: Environment variable

For containerized deployments or when you need explicit control:

Generate a master key:

Generate master key
```
openssl rand -base64 32
```
Copied!
Set the environment variable:

Set environment variable
```
export NR_VAULT_MASTER_KEY="your-generated-key"
```
Copied!
Configure the extension in Admin Tools > Settings > Extension Configuration:
- masterKeyProvider: env
- masterKeySource: NR_VAULT_MASTER_KEY

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

Configure the extension:

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

Warning

For file and environment providers: never commit master keys to version control. Store them securely outside the web root.

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

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

You can also test by storing and retrieving a test secret:

Test vault functionality

# Store a test secret
vendor/bin/typo3 vault:store test_secret --value="test-value"

# Retrieve it
vendor/bin/typo3 vault:retrieve test_secret

# Clean up
vendor/bin/typo3 vault:delete test_secret --force