README

Laravel轮换器是一个软件包，用于在您的应用程序加密密钥被泄露的情况下重新加密您的数据。通过运行 php artisan rotation:run，该软件包将生成一个新的应用程序密钥，并使用新密钥重新加密所有配置的数据库列。

为什么选择这个软件包？

尽管有其他密钥轮换软件包可供选择，并且您也可以手动实现密钥轮换功能，但有一些功能可以帮助密钥轮换更顺畅地运行。

• 轮换器将重新加密推送到队列。通过Laravel Horizon或多个队列工作者，这允许重新加密处理比同步运行一切要快得多。由于工作被分批处理，您仍然会知道何时完成重新加密。
• 支持更改加密算法。一些较旧的应用程序可能仍在使用较短的密钥，但轮换器允许您指定旧的和新的加密算法，以便更新密钥。
• 轮换器直接在配置文件中指定的数据库列上运行。它不与模型交互，这提高了性能，并使解决方案更易于使用。虽然您可以编写自己的命令或实现RotatesApplicationKey接口，但无需这样做，并且无需让您的模型实现接口或使用特性。如果您愿意，甚至可以创建一个单独的应用程序来处理重新加密过程，这样就不必触及现有的代码库。
• 生活质量的改进：支持在重新加密完成后发送通知，并自动打开和关闭维护模式。

安装

您可以通过composer安装此软件包。

composer require ivinteractive/laravel-rotation

发布配置文件

php artisan vendor:publish --tag=rotation.config

配置文件将包含以下内容

<?php

use IvInteractive\Rotation;

return [
    /**
     * The columns to be decrypted and re-encrypted. The columns must be
     * an array of string with the format '{TABLENAME}.{PRIMARY_KEY}.{COLUMN_NAME}'.
     */
    'columns' => [
        // 'tablename.primary_key.column',
    ],

    /**
     * The key rotation command creates a job batch and chunks the records into separate
     * jobs. This value controls the number of records processed in each job.
     */
    'chunk_size' => 1000,

    /**
     * The old application key for the key rotater to use in decryption of old encrypted values.
     * This value is set automatically. If your config is cached, the key rotation command will
     * recache your config after appending the OLD_KEY value to your .env file.
     */
    'old_key' => env('OLD_KEY', null),

    /**
     * This class performs decryption and re-encryption while processing records. A valid
     * rotation class must implement `IvInteractive\Rotation\Contracts\RotatesApplicationKey`.
     */
    'rotater_class' => Rotation\Rotater::class,

    /**
     * The class for receiving notifications after the key rotation is completed. The base
     * class includes notification routing for mail and Slack.
     */
    'notifiable' => Rotation\Notifications\Notifiable::class,

    /**
     * The queue connection that will be used for the re-encryption jobs.
     */
    'connection' => 'default',

    /**
     * The queue that re-encryption jobs will be pushed to.
     */
    'queue' => 'default',

    /**
     * The recipient for the notification sent by the default IvInteractive\Rotation|Rotater class.
     */
    'notification' => [
        'recipient' => [
            'mail' => 'jane.doe@example.org',
            // 'slack' => 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
        ],
        'channels' => ['mail'],
    ],

    /**
     * Whether the application should be put in maintenance mode while the re-encryption
     * is running. This is highly recommended, as users may experience errors before
     * all data has been re-encrypted.
     */
    'maintenance' => env('ROTATION_MAINTENANCE', true),

    /**
     * Whether the secret to bypass the maintenance mode should be output. This should
     * not be enabled if the application has functionality that could lead to invalid
     * key errors during the re-encryption process (e.g. encrypted audit logs).
     */
    'maintenance-secret' => env('ROTATION_MAINTENANCE_SECRET', false),

    /**
     * Whether the application should remove the old key from the environment file
     * after the re-encryption process finishes.
     */
    'remove_old_key' => false,

    /**
     * Used when changing the cipher used for the application key. By default, the rotater
     * will use the cipher set in config('app.cipher') for both the old and new keys.
     */
    // 'cipher' => [
    //     'old' => null,
    //     'new' => null,
    // ],
];

用法

密钥轮换命令将生成一个新的应用程序密钥，将现有的应用程序密钥作为配置中的旧密钥，并将批量重新加密作业推送到队列

php artisan rotation:run {--horizon} {--force}

--horizon选项将调用horizon:terminate而不是queue:restart，以确保队列作业使用重新缓存的配置。

--force选项将跳过在更改配置或推送任何作业到队列之前进行的确认步骤。

密钥轮换命令的默认行为是在重新加密处理期间将应用程序置于维护模式。如果应用程序关闭，则必须将queue:work命令或Horizon队列配置中的force选项设置为true，以便处理重新加密作业。

强烈建议使用Horizon，因为重新加密队列配置应该更容易管理。如果使用Horizon并且将remove_old_key设置为true，则应在重新加密完成后运行php artisan horizon:terminate一次以刷新队列工作者中的配置（horizon:terminate命令仅在控制台可用，不能以编程方式执行）。

默认情况下，密钥轮换器将使用config('app.cipher')的值进行解密和重新加密。如果正在更改加密算法，您可以在配置中指定此操作，通过设置config('rotation.cipher')为一个包含old和new键的数组。这对于升级较旧应用程序中用于加密的加密算法非常有用。

事件

当批量作业完成时，将触发IvInteractive\Rotation\Events\ReencryptionFinished事件。

提供了 IvInteractive\Rotation\Listeners\SendFinishedNotification 事件监听器，用于将消息写入日志并发送通知到配置的接收者。

测试

composer test

变更日志

请参阅变更日志获取更多关于最近变更的信息。

贡献

请参阅贡献指南获取详细信息。

安全

如果您发现任何与安全相关的问题，请发送邮件至support@ivinteractive.com，而不是使用问题跟踪器。

致谢

• Craig Spivack
• 所有贡献者

许可

MIT 许可协议 (MIT)。请参阅许可文件获取更多信息。