Added migration and updates to documentation

Author: tswagger

UPGRADING.md

@@ -1,5 +1,25 @@
 # Upgrade Guide
 
+## Version 1.0.0-beta.8 to 1.0.0-beta.9
+
+### Mandatory Config Changes
+
+#### Config\AuthToken
+
+If you are using the HMAC authentication you need to update the encryption settings in **app/Config/AuthToken.php**.
+You will need to update and set the encryption key `$hmacEncryptionKey`. This should be set using .env and/or system
+environment variables. Instructions on how to do that can be found in the
+[Setting Your Encryption Key](https://codeigniter.com/user_guide/libraries/encryption.html#setting-your-encryption-key)
+section of the CodeIgniter 4 documentation.
+
+You also may wish to adjust the default Driver `$hmacEncryptionDriver` and the default Digest `$hmacEncryptionDigest`,
+these currently default to `'OpenSSL'` and `'SHA512'` respectively.
+
+### Database Migrations
+
+After updating the `$hmacEncryptionKey` value, you will need to run `php spark migrate --all` in order to encrypt any
+existing HMAC tokens.
+
 ## Version 1.0.0-beta.7 to 1.0.0-beta.8
 
 ### Mandatory Config Changes
@@ -45,7 +65,7 @@ protected function redirectToDeniedUrl(): RedirectResponse
 {
     return redirect()->to(config('Auth')->groupDeniedRedirect())
         ->with('error', lang('Auth.notEnoughPrivilege'));
-} 
+}
 ```
 
 ## Version 1.0.0-beta.6 to 1.0.0-beta.7

docs/guides/api_hmac_keys.md

@@ -16,8 +16,8 @@ API. When making requests using HMAC keys, the token should be included in the `
 
 Tokens are issued with the `generateHmacToken()` method on the user. This returns a
 `CodeIgniter\Shield\Entities\AccessToken` instance. These shared keys are saved to the database in plain text. The
-`AccessToken` object returned when you generate it will include a `secret` field which will be the `key` and a `secret2`
-field that will be the `secretKey`. You should display the `secretKey` to your user once, so they have a chance to copy
+`AccessToken` object returned when you generate it will include a `secret` field which will be the '_key_' and a `rawSecretKey`
+field that will be the '_secretKey_'. You should display the '_secretKey_' to your user once, so they have a chance to copy
 it somewhere safe, as this is the only time you should reveal this key.
 
 The `generateHmacToken()` method requires a name for the token. These are free strings and are often used to identify
@@ -27,7 +27,7 @@ the user/device the token was generated from/for, like 'Johns MacBook Air'.
 $routes->get('hmac/token', static function () {
     $token = auth()->user()->generateHmacToken(service('request')->getVar('token_name'));
 
-    return json_encode(['key' => $token->secret, 'secretKey' => $token->secret2]);
+    return json_encode(['key' => $token->secret, 'secretKey' => $token->rawSecretKey]);
 });
 ```
 
@@ -62,7 +62,7 @@ token is granted all access to all scopes. This might be enough for a smaller AP
 
 ```php
 $token = $user->generateHmacToken('token-name', ['users-read']);
-return json_encode(['key' => $token->secret, 'secretKey' => $token->secret2]);
+return json_encode(['key' => $token->secret, 'secretKey' => $token->rawSecretKey]);
 ```
 
 !!! note

docs/references/authentication/hmac.md

@@ -68,18 +68,18 @@ $token = $user->generateHmacToken('Work Laptop');
 
 This creates the keys/tokens using a cryptographically secure random string. The keys operate as shared keys.
 This means they are stored as-is in the database. The method returns an instance of
-`CodeIgniters\Shield\Authentication\Entities\AccessToken`. The field `secret` is the 'key' the field `secret2` is
-the shared 'secretKey'. Both are required to when using this authentication method.
+`CodeIgniters\Shield\Authentication\Entities\AccessToken`. The field `secret` is the '_key_' the field `rawSecretKey` is
+the shared '_secretKey_'. Both are required to when using this authentication method.
 
 **The plain text version of these keys should be displayed to the user immediately, so they can copy it for
-their use.** It is recommended that after that only the 'key' field is displayed to a user.  If a user loses the
-'secretKey', they should be required to generate a new set of keys to use.
+their use.** It is recommended that after that only the '_key_' field is displayed to a user.  If a user loses the
+'_secretKey_', they should be required to generate a new set of keys to use.
 
 ```php
 $token = $user->generateHmacToken('Work Laptop');
 
 echo 'Key: ' . $token->secret;
-echo 'SecretKey: ' . $token->secret2;
+echo 'SecretKey: ' . $token->rawSecretKey;
 ```
 
 ## Revoking HMAC Keys

src/Authentication/Authenticators/HmacSha256.php

@@ -171,8 +171,8 @@ public function check(array $credentials): Result
         $config->digest = $authConfig->hmacEncryptionDigest;
 
         // decrypt secret key so signature can be validated
-        $encrypter = Services::encrypter($config);
-        $secretKey = $encrypter->decrypt(hex2bin($token->secret2));
+        $encryptor = Services::encrypter($config);
+        $secretKey = $encryptor->decrypt(hex2bin($token->secret2));
 
         // Check signature...
         $hash = hash_hmac('sha256', $credentials['body'], $secretKey);

src/Database/Migrations/2023-10-30-222755_EncryptHmacKeys.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Database\Migrations;
+
+use CodeIgniter\Database\Forge;
+use CodeIgniter\Database\Migration;
+use CodeIgniter\Encryption\EncrypterInterface;
+use CodeIgniter\Shield\Config\Auth;
+use CodeIgniter\Shield\Config\AuthToken;
+use CodeIgniter\Shield\Models\UserIdentityModel;
+use Config\Encryption;
+use Config\Services;
+
+class EncryptHmacKeys extends Migration
+{
+    /**
+     * Encryptor Interface object
+     */
+    private EncrypterInterface $encryptor;
+
+    public function __construct(?Forge $forge = null)
+    {
+        /** @var Auth $authConfig */
+        $authConfig = config('Auth');
+
+        if ($authConfig->DBGroup !== null) {
+            $this->DBGroup = $authConfig->DBGroup;
+        }
+
+        parent::__construct($forge);
+
+        /** @var AuthToken $authTokenConfig */
+        $authTokenConfig = config('AuthToken');
+        $config          = new Encryption();
+
+        $config->key    = $authTokenConfig->hmacEncryptionKey;
+        $config->driver = $authTokenConfig->hmacEncryptionDriver;
+        $config->digest = $authTokenConfig->hmacEncryptionDigest;
+
+        // decrypt secret key so signature can be validated
+        $this->encryptor = Services::encrypter($config);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function up(): void
+    {
+        $uIdModel = new UserIdentityModel();
+
+        $updateList     = [];
+        $hmacIdentities = $uIdModel->where('type', 'hmac_sha256')->findAll();
+
+        foreach ($hmacIdentities as $identity) {
+            $identity->secret2 = bin2hex($this->encryptor->encrypt($identity->secret2));
+
+            $updateList[] = [
+                'id'      => $identity->id,
+                'secret2' => $identity->secret2,
+            ];
+        }
+
+        if ($updateList !== []) {
+            $uIdModel->updateBatch($updateList, 'id');
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function down(): void
+    {
+        $uIdModel = new UserIdentityModel();
+
+        $updateList     = [];
+        $hmacIdentities = $uIdModel->where('type', 'hmac_sha256')->findAll();
+
+        foreach ($hmacIdentities as $identity) {
+            $identity->secret2 = $this->encryptor->decrypt(hex2bin($identity->secret2));
+
+            $updateList[] = [
+                'id'      => $identity->id,
+                'secret2' => $identity->secret2,
+            ];
+        }
+
+        if ($updateList !== []) {
+            $uIdModel->updateBatch($updateList, 'id');
+        }
+    }
+}

tests/Authentication/Authenticators/HmacAuthenticatorTest.php

@@ -13,7 +13,6 @@
 
 namespace Tests\Authentication\Authenticators;
 
-use CodeIgniter\Encryption\Encryption;
 use CodeIgniter\I18n\Time;
 use CodeIgniter\Shield\Authentication\Authentication;
 use CodeIgniter\Shield\Authentication\AuthenticationException;
@@ -38,9 +37,6 @@ protected function setUp(): void
     {
         parent::setUp();
 
-        $authConfig                    = config('AuthToken');
-        $authConfig->hmacEncryptionKey = Encryption::createKey();
-
         $config = new Auth();
         $auth   = new Authentication($config);
         $auth->setProvider(model(UserModel::class));

tests/Authentication/Filters/HmacFilterTest.php

@@ -13,7 +13,6 @@
 
 namespace Tests\Authentication\Filters;
 
-use CodeIgniter\Encryption\Encryption;
 use CodeIgniter\Shield\Entities\AccessToken;
 use CodeIgniter\Shield\Entities\User;
 use CodeIgniter\Shield\Filters\HmacAuth;
@@ -31,14 +30,6 @@ final class HmacFilterTest extends AbstractFilterTestCase
     protected string $alias     = 'hmacAuth';
     protected string $classname = HmacAuth::class;
 
-    protected function setUp(): void
-    {
-        parent::setUp();
-
-        $authConfig                    = config('AuthToken');
-        $authConfig->hmacEncryptionKey = Encryption::createKey();
-    }
-
     public function testFilterNotAuthorized(): void
     {
         $result = $this->call('get', 'protected-route');

tests/Authentication/HasHmacTokensTest.php

@@ -13,7 +13,6 @@
 
 namespace Tests\Authentication;
 
-use CodeIgniter\Encryption\Encryption;
 use CodeIgniter\Shield\Entities\AccessToken;
 use CodeIgniter\Shield\Entities\User;
 use CodeIgniter\Shield\Models\UserIdentityModel;
@@ -31,9 +30,6 @@ protected function setUp(): void
     {
         parent::setUp();
 
-        $authConfig                    = config('AuthToken');
-        $authConfig->hmacEncryptionKey = Encryption::createKey();
-
         $this->user = fake(UserModel::class);
         $this->db->table($this->tables['identities'])->truncate();
     }
@@ -61,12 +57,12 @@ public function testHmacTokens(): void
         // Give the user a couple of access tokens
         $token1 = fake(
             UserIdentityModel::class,
-            ['user_id' => $this->user->id, 'type' => 'hmac_sha256', 'secret' => 'key1', 'secret2' => 'secretKey1']
+            ['user_id' => $this->user->id, 'type' => 'hmac_sha256', 'secret' => 'key1', 'secret2' => 'd862cd9ddc23e960ca6d45a3e0b64c7509f0c0ef0e5f7b64be8910a6a714c89b83fab95251bbf17f6c84b42c26cf460a28ea969591dc64b1f5c4b323f47615d2e8cbe4c62118001d3274e0f25850b0ac2617bc43119af22c99a1a83072002267177da01f9f37225435e1914be004f4d35a49869b737ed10ab232c1ed1048bb96ef6fb70979dc9c981e17134f4356a938']
         );
 
         $token2 = fake(
             UserIdentityModel::class,
-            ['user_id' => $this->user->id, 'type' => 'hmac_sha256', 'secret' => 'key2', 'secret2' => 'secretKey2']
+            ['user_id' => $this->user->id, 'type' => 'hmac_sha256', 'secret' => 'key2', 'secret2' => 'd862cd9ddc23e960ca6d45a3e0b64c7509f0c0ef0e5f7b64be8910a6a714c89b83fab95251bbf17f6c84b42c26cf460a28ea969591dc64b1f5c4b323f47615d2e8cbe4c62118001d3274e0f25850b0ac2617bc43119af22c99a1a83072002267177da01f9f37225435e1914be004f4d35a49869b737ed10ab232c1ed1048bb96ef6fb70979dc9c981e17134f4356a938']
         );
 
         $tokens = $this->user->hmacTokens();

tests/_support/TestCase.php

@@ -25,6 +25,8 @@ abstract class TestCase extends CIUnitTestCase
 {
     protected function setUp(): void
     {
+        $_ENV['authtoken.hmacEncryptionKey'] = 'hex2bin:178ed94fd0b6d57dd31dd6b22fc601fab8ad191efac165a5f3f30a8ac09d813d';
+
         $this->resetServices();
 
         parent::setUp();