Merge pull request #86 from paragonie/extension-keys

Feature: Extension Keys
paragonie · Apr 26, 2023 · 59ee2e0 · 59ee2e0
2 parents ccb2e1d + 22d05f9
commit 59ee2e0
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 1 deletion.
diff --git a/src/CipherSweet.php b/src/CipherSweet.php
@@ -127,6 +127,40 @@ public function getFieldSymmetricKey(string $tableName, string $fieldName): Symm
         );
     }
 
+    /**
+     * Get a key for use with CipherSweet extensions
+     *
+     * @param string $extensionUniqueName
+     * @param string ...$extra
+     *
+     * @return SymmetricKey
+     *
+     * @throws CipherSweetException
+     * @throws CryptoOperationException
+     */
+    public function getExtensionKey(string $extensionUniqueName, string ...$extra): SymmetricKey
+    {
+        $info = Constants::DS_EXT . Util::pack([$extensionUniqueName, ...$extra]);
+
+        if ($this->isMultiTenantSupported()) {
+            return new SymmetricKey(
+                Util::HKDF(
+                    $this->getKeyProviderForActiveTenant()->getSymmetricKey(),
+                    '',
+                    $info
+                )
+            );
+        }
+
+        return new SymmetricKey(
+            Util::HKDF(
+                $this->keyProvider->getSymmetricKey(),
+                '',
+                $info
+            )
+        );
+    }
+
     /**
      * Get the key provider for a given tenant
      *

diff --git a/src/Constants.php b/src/Constants.php
@@ -28,6 +28,20 @@ abstract class Constants
      */
     const DS_JSON = "\xD9\xA7\x36\xFF\x8E\xB9\xD8\xCC\x6D\xD2\xF9\x1A\x6E\x55\xE7\x8E\x44\x43\x37\x36\x57\x3B\x4E\xDA\x34\xBB\x23\x46\x09\xC8\xB6\xA5";
 
+    /*
+     * Domain separation constant for CipherSweet extensions
+     *
+     * Calculated as:
+     * SHA256("ciphersweet extensions") xor SHA256("CIPHERSWEET EXTENSIONS")
+     *
+     * 1ce46264e18a7cdc40ead6f379bc1e233d356c5a95f4c48fbd89c6076960338b
+     *                                 xor
+     * 98f0e454e75dddb6108c32294be2db4c2b664b0ad8da1aa072d7493dc0654866
+     * ----------------------------------------------------------------
+     * 8414863006d7a16a5066e4da325ec56f165327504d2ede2fcf5e8f3aa9057bed
+     */
+    const DS_EXT = "\x84\x14\x86\x30\x06\xd7\xa1\x6a\x50\x66\xe4\xda\x32\x5e\xc5\x6f\x16\x53\x27\x50\x4d\x2e\xde\x2f\xcf\x5e\x8f\x3a\xa9\x05\x7b\xed";
+
     const TYPE_JSON = 'json';
     const TYPE_BOOLEAN = 'bool';
     const TYPE_TEXT = 'string';

diff --git a/tests/CipherSweetTest.php b/tests/CipherSweetTest.php
@@ -1,12 +1,16 @@
 <?php
 namespace ParagonIE\CipherSweet\Tests;
 
+use ParagonIE\CipherSweet\Backend\BoringCrypto;
 use ParagonIE\CipherSweet\Backend\FIPSCrypto;
 use ParagonIE\CipherSweet\Backend\ModernCrypto;
 use ParagonIE\CipherSweet\CipherSweet;
+use ParagonIE\CipherSweet\Exception\CipherSweetException;
+use ParagonIE\CipherSweet\Exception\CryptoOperationException;
 use ParagonIE\CipherSweet\KeyProvider\StringProvider;
 use ParagonIE\ConstantTime\Hex;
 use PHPUnit\Framework\TestCase;
+use SodiumException;
 
 /**
  * Class CipherSweetTest
@@ -16,7 +20,7 @@ class CipherSweetTest extends TestCase
 {
     /**
      * @throws \ParagonIE\CipherSweet\Exception\ArrayKeyException
-     * @throws \ParagonIE\CipherSweet\Exception\CryptoOperationException
+     * @throws CryptoOperationException
      */
     public function testBasicAPI()
     {
@@ -72,4 +76,35 @@ public function testBasicAPI()
             }
         }
     }
+
+    public function engineProvider(): array
+    {
+        $random = \random_bytes(32);
+        $provider = new StringProvider($random);
+        return [
+            [new CipherSweet($provider, new FIPSCrypto())],
+            [new CipherSweet($provider, new ModernCrypto())],
+            [new CipherSweet($provider, new BoringCrypto())],
+        ];
+    }
+
+    /**
+     * @dataProvider engineProvider
+     * @param CipherSweet $engine
+     * @return void
+     *
+     * @throws CipherSweetException
+     * @throws CryptoOperationException
+     * @throws SodiumException
+     */
+    public function testExtensionKey(CipherSweet $engine): void
+    {
+        $ext1 = $engine->getExtensionKey('foo', 'bar');
+        $ext2 = $engine->getExtensionKey("foo\x03\x00\x00\x00\x00\x00\x00\x00bar");
+        $this->assertNotSame(
+            sodium_bin2hex($ext1->getRawKey()),
+            sodium_bin2hex($ext2->getRawKey()),
+            'Key derivation is not resistant to canonicalization issues'
+        );
+    }
 }