Enhance Vault with AAD and key rotation

Author: JoshuaEstes

ROADMAP.md

@@ -121,35 +121,6 @@ This roadmap outlines planned libraries and updates for the Sons of PHP monorepo
     - Release notes highlight Symfony 7 support.
     - Implementation meets the Global DoD.
 
-### Epic: Introduce Vault Component
-**Description:** Provide secure secret storage with pluggable backends.
-
-- [ ] Add filesystem storage adapter.
-  - **Acceptance Criteria**
-    - All Global DoR items are satisfied before implementation begins.
-    - Filesystem adapter encrypts and retrieves secrets reliably.
-    - Implementation meets the Global DoD.
-- [ ] Add database storage adapter.
-  - **Acceptance Criteria**
-    - All Global DoR items are satisfied before implementation begins.
-    - Database adapter persists encrypted secrets.
-    - Implementation meets the Global DoD.
-- [ ] Add Redis storage adapter.
-  - **Acceptance Criteria**
-    - All Global DoR items are satisfied before implementation begins.
-    - Redis adapter stores encrypted secrets and respects expirations.
-    - Implementation meets the Global DoD.
-- [ ] Support key rotation and secret versioning.
-  - **Acceptance Criteria**
-    - All Global DoR items are satisfied before implementation begins.
-    - Secrets can be rotated without loss using new keys.
-    - Implementation meets the Global DoD.
-- [ ] Provide CLI tools for managing secrets.
-  - **Acceptance Criteria**
-    - All Global DoR items are satisfied before implementation begins.
-    - CLI allows setting, retrieving, and rotating secrets.
-    - Implementation meets the Global DoD.
-
 ## Suggestions
 
 - Automate dependency updates with a scheduled tool (e.g., Renovate or Dependabot).

docs/components/vault.md

@@ -1,6 +1,6 @@
 # Vault
 
-The Vault component securely stores secrets using pluggable storage backends and encryption.
+The Vault component securely stores secrets using pluggable storage backends and encryption with key rotation and support for additional authenticated data (AAD).
 
 ## Basic Usage
 
@@ -9,7 +9,15 @@ use SonsOfPHP\Component\Vault\Cipher\OpenSSLCipher;
 use SonsOfPHP\Component\Vault\Storage\InMemoryStorage;
 use SonsOfPHP\Component\Vault\Vault;
 
-$vault = new Vault(new InMemoryStorage(), new OpenSSLCipher(), 'encryption-key');
-$vault->set('db_password', 'secret');
-$secret = $vault->get('db_password');
+$keys  = ['v1' => '32_byte_master_key_example!!'];
+$vault = new Vault(new InMemoryStorage(), new OpenSSLCipher(), $keys, 'v1');
+$vault->set('db_password', 'secret', 'app');
+$secret = $vault->get('db_password', 'app');
+
+// Rotate the master key
+$vault->rotateKey('v2', 'another_32_byte_master_key!!');
+
+// Store non-string data
+$vault->set('config', ['user' => 'root']);
+$config = $vault->get('config');
 ```

src/SonsOfPHP/Component/Vault/Cipher/CipherInterface.php

@@ -10,12 +10,12 @@
 interface CipherInterface
 {
     /**
-     * Encrypts plaintext using the provided key.
+     * Encrypts plaintext using the provided key and optional authenticated data.
      */
-    public function encrypt(string $plaintext, string $key): string;
+    public function encrypt(string $plaintext, string $key, string $aad = ''): string;
 
     /**
-     * Decrypts ciphertext using the provided key.
+     * Decrypts ciphertext using the provided key and optional authenticated data.
      */
-    public function decrypt(string $ciphertext, string $key): string;
+    public function decrypt(string $ciphertext, string $key, string $aad = ''): string;
 }

src/SonsOfPHP/Component/Vault/Cipher/OpenSSLCipher.php

@@ -11,29 +11,37 @@
  */
 class OpenSSLCipher implements CipherInterface
 {
-    public function __construct(private readonly string $cipherMethod = 'aes-256-ctr')
-    {
-    }
+    /**
+     * @param string $cipherMethod OpenSSL cipher method supporting AEAD.
+     */
+    public function __construct(private readonly string $cipherMethod = 'aes-256-gcm') {}
 
-    public function encrypt(string $plaintext, string $key): string
+    public function encrypt(string $plaintext, string $key, string $aad = ''): string
     {
         $ivLength = openssl_cipher_iv_length($this->cipherMethod);
         $iv       = random_bytes($ivLength);
-        $encrypted = openssl_encrypt($plaintext, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv);
+        $tag      = '';
+        $encrypted = openssl_encrypt($plaintext, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $aad, 16);
         if (false === $encrypted) {
             throw new RuntimeException('Unable to encrypt secret.');
         }
 
-        return base64_encode($iv . $encrypted);
+        return base64_encode($iv . $tag . $encrypted);
     }
 
-    public function decrypt(string $ciphertext, string $key): string
+    public function decrypt(string $ciphertext, string $key, string $aad = ''): string
     {
-        $data     = base64_decode($ciphertext, true);
-        $ivLength = openssl_cipher_iv_length($this->cipherMethod);
-        $iv       = substr($data, 0, $ivLength);
-        $payload  = substr($data, $ivLength);
-        $decrypted = openssl_decrypt($payload, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv);
+        $data = base64_decode($ciphertext, true);
+        if (false === $data) {
+            throw new RuntimeException('Invalid ciphertext.');
+        }
+
+        $ivLength  = openssl_cipher_iv_length($this->cipherMethod);
+        $tagLength = 16;
+        $iv        = substr($data, 0, $ivLength);
+        $tag       = substr($data, $ivLength, $tagLength);
+        $payload   = substr($data, $ivLength + $tagLength);
+        $decrypted = openssl_decrypt($payload, $this->cipherMethod, $key, OPENSSL_RAW_DATA, $iv, $tag, $aad);
         if (false === $decrypted) {
             throw new RuntimeException('Unable to decrypt secret.');
         }

src/SonsOfPHP/Component/Vault/README.md

@@ -1,6 +1,8 @@
 Sons of PHP - Vault
 ===================
 
+Secure secret storage with pluggable backends, key rotation, and support for additional authenticated data.
+
 ## Learn More
 
 * [Documentation][docs]

src/SonsOfPHP/Component/Vault/ROADMAP.md

@@ -23,11 +23,11 @@
   - Redis adapter encrypts secrets and handles expirations.
   - Implementation meets the Global DoD.
 
-### Support key rotation and secret versioning
-- [ ] Provide APIs to rotate encryption keys and maintain secret history.
+### Add secret versioning
+- [ ] Provide APIs to maintain secret history across updates.
 - **Acceptance Criteria**
   - All Global DoR items are satisfied before implementation begins.
-  - Secrets can be re-encrypted with new keys without loss.
+  - Previous versions of a secret remain accessible.
   - Implementation meets the Global DoD.
 
 ### Provide CLI tools for managing secrets

src/SonsOfPHP/Component/Vault/Tests/VaultTest.php

@@ -5,6 +5,7 @@
 namespace SonsOfPHP\Component\Vault\Tests;
 
 use PHPUnit\Framework\TestCase;
+use RuntimeException;
 use SonsOfPHP\Component\Vault\Cipher\OpenSSLCipher;
 use SonsOfPHP\Component\Vault\Storage\InMemoryStorage;
 use SonsOfPHP\Component\Vault\Vault;
@@ -18,13 +19,13 @@ class VaultTest extends TestCase
     /**
      * Creates a vault instance for testing.
      */
-    private function createVault(): Vault
+    private function createVault(?InMemoryStorage &$storage = null): Vault
     {
-        $storage = new InMemoryStorage();
+        $storage ??= new InMemoryStorage();
         $cipher  = new OpenSSLCipher();
-        $key     = 'test_encryption_key_32_bytes!';
+        $keys    = ['v1' => 'test_encryption_key_32_bytes!'];
 
-        return new Vault($storage, $cipher, $key);
+        return new Vault($storage, $cipher, $keys, 'v1');
     }
 
     public function testSecretCanBeRetrieved(): void
@@ -50,4 +51,48 @@ public function testSecretCanBeDeleted(): void
 
         $this->assertNull($vault->get('api_key'));
     }
+
+    public function testSetAndGetWithArray(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('config', ['user' => 'root']);
+
+        $this->assertSame(['user' => 'root'], $vault->get('config'));
+    }
+
+    public function testSetAndGetWithAad(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('token', 'secret', 'aad');
+
+        $this->assertSame('secret', $vault->get('token', 'aad'));
+    }
+
+    public function testGetThrowsWhenAadDoesNotMatch(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('token', 'secret', 'aad');
+
+        $this->expectException(RuntimeException::class);
+        $vault->get('token', 'bad');
+    }
+
+    public function testSecretsEncryptedBeforeRotationAreStillAccessible(): void
+    {
+        $vault = $this->createVault();
+        $vault->set('legacy', 'secret');
+        $vault->rotateKey('v2', 'another_32_byte_encryption_key!!');
+
+        $this->assertSame('secret', $vault->get('legacy'));
+    }
+
+    public function testRotateKeyChangesActiveKey(): void
+    {
+        $storage = new InMemoryStorage();
+        $vault   = $this->createVault($storage);
+        $vault->rotateKey('v2', 'another_32_byte_encryption_key!!');
+        $vault->set('current', 'secret');
+
+        $this->assertStringStartsWith('v2:', $storage->get('current'));
+    }
 }

src/SonsOfPHP/Component/Vault/Vault.php

@@ -4,43 +4,70 @@
 
 namespace SonsOfPHP\Component\Vault;
 
+use RuntimeException;
 use SonsOfPHP\Component\Vault\Cipher\CipherInterface;
 use SonsOfPHP\Component\Vault\Storage\StorageInterface;
 
 /**
- * Vault stores encrypted secrets using a pluggable storage backend.
+ * Vault stores encrypted secrets using a pluggable storage backend with
+ * support for additional authenticated data and key rotation.
  */
 class Vault
 {
     /**
-     * @param StorageInterface $storage The storage backend.
-     * @param CipherInterface $cipher  The cipher used for encryption.
-     * @param string $encryptionKey The encryption key.
+     * @param StorageInterface       $storage       The storage backend.
+     * @param CipherInterface        $cipher        The cipher used for encryption.
+     * @param array<string,string>   $keys          Map of key IDs to encryption keys.
+     * @param string                 $currentKeyId  Identifier of the active key.
      */
-    public function __construct(private readonly StorageInterface $storage, private readonly CipherInterface $cipher, private readonly string $encryptionKey)
+    public function __construct(private readonly StorageInterface $storage, private readonly CipherInterface $cipher, private array $keys, private string $currentKeyId)
     {
     }
 
     /**
      * Stores a secret in the vault.
+     *
+     * @param string $name  Identifier of the secret.
+     * @param mixed  $secret The secret to store.
+     * @param string $aad   Additional authenticated data.
      */
-    public function set(string $name, string $secret): void
+    public function set(string $name, mixed $secret, string $aad = ''): void
     {
-        $encrypted = $this->cipher->encrypt($secret, $this->encryptionKey);
-        $this->storage->set($name, $encrypted);
+        $serialized = serialize($secret);
+        $key        = $this->keys[$this->currentKeyId];
+        $encrypted  = $this->cipher->encrypt($serialized, $key, $aad);
+        $this->storage->set($name, $this->currentKeyId . ':' . $encrypted);
     }
 
     /**
      * Retrieves a secret from the vault or null if it does not exist.
+     *
+     * @param string $name Identifier of the secret.
+     * @param string $aad  Additional authenticated data.
+     *
+     * @return mixed|null
      */
-    public function get(string $name): ?string
+    public function get(string $name, string $aad = ''): mixed
     {
-        $encrypted = $this->storage->get($name);
-        if (null === $encrypted) {
+        $record = $this->storage->get($name);
+        if (null === $record) {
             return null;
         }
 
-        return $this->cipher->decrypt($encrypted, $this->encryptionKey);
+        [$keyId, $ciphertext] = explode(':', $record, 2);
+        $key = $this->keys[$keyId] ?? null;
+        if (null === $key) {
+            throw new RuntimeException('Unknown key identifier.');
+        }
+
+        $serialized = $this->cipher->decrypt($ciphertext, $key, $aad);
+
+        $secret = @unserialize($serialized, ['allowed_classes' => false]);
+        if (false === $secret && 'b:0;' !== $serialized) {
+            throw new RuntimeException('Unable to unserialize secret.');
+        }
+
+        return $secret;
     }
 
     /**
@@ -50,4 +77,16 @@ public function delete(string $name): void
     {
         $this->storage->delete($name);
     }
+
+    /**
+     * Rotates the active encryption key.
+     *
+     * @param string $keyId Identifier for the new key.
+     * @param string $key   The new encryption key.
+     */
+    public function rotateKey(string $keyId, string $key): void
+    {
+        $this->keys[$keyId] = $key;
+        $this->currentKeyId = $keyId;
+    }
 }