API Key Encryption at Application Level

Problem statement

TYPO3's TCA type=password field has two modes:

1. Hashed mode (default): Uses bcrypt/argon2 - irreversible, suitable for user passwords

2. Unhashed mode (hashed => false): Stores plaintext - required for API keys that must be retrieved

API keys must be retrievable to authenticate with external services, so hashing is not an option. However, storing them in plaintext exposes them to:

• Database dumps/backups

• SQL injection attacks

• Unauthorized database access

• Accidental exposure in logs

Requirements

1. API keys must be retrievable (not hashed).

2. Keys must be encrypted at rest in the database.

3. Encryption must be transparent to the application.

4. Solution must work without external dependencies (self-contained).

5. Must support key rotation.

6. Backwards compatible with existing plaintext values.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Backend Form                              │
│                    (user enters API key)                         │
└─────────────────────────────┬───────────────────────────────────┘
                              │ plaintext
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Provider::setApiKey()                         │
│              ProviderEncryptionService::encrypt()                │
│                                                                  │
│  1. Generate random nonce (24 bytes)                             │
│  2. Derive key from TYPO3 encryptionKey via SHA-256              │
│  3. Encrypt with XSalsa20-Poly1305                               │
│  4. Prefix with "enc:" marker                                    │
│  5. Base64 encode for storage                                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │ "enc:base64(nonce+ciphertext+tag)"
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Database                                 │
│                   tx_nrllm_provider.api_key                      │
└─────────────────────────────────────────────────────────────────┘

Key derivation

The domain separator :nr_llm_provider_encryption ensures:

• Keys are unique to this use case.

• Same encryptionKey produces different keys for different purposes.

• No collision with other extensions using similar patterns.

Encryption format

enc:{base64(nonce || ciphertext || auth_tag)}

Where:
- "enc:" = 4-byte prefix marker
- nonce = 24 bytes (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES)
- ciphertext = variable length
- auth_tag = 16 bytes (Poly1305 MAC, included by sodium)

Files created/modified

Key methods

Positive

◐ Encryption at rest: Database dumps no longer expose plaintext credentials.

◐ Transparent operation: Encryption/decryption handled automatically.

◐ No external dependencies: Uses PHP's built-in sodium extension.

◐ Authenticated encryption: Tampering is detected (Poly1305 MAC).

◐ Backwards compatible: Unencrypted values work without migration.

◐ Industry standard: XSalsa20-Poly1305 is used by NaCl/libsodium.

Negative

◑ Single point of failure: If encryptionKey is compromised, all keys are exposed.

◑ No key rotation: Changing encryptionKey requires re-encryption of all keys.

◑ In-memory exposure: Decrypted keys exist briefly in memory.

◑ Performance overhead: Encryption/decryption on every save/load (minimal).

Net Score: +4 (Strong positive)