はじめに
この記事は MySQL Advent Calendar 2025 6日目の記事です。
MySQL キーリングプラグインからコンポーネントへの移行
今年、対応した作業で個人的に多かったな、と感じたのがこれでした。
移行したいけど、よくわからん！っていうのが多くて、んじゃ俺も試してみるか、
「うーん、確かにわかりづれえ！」
ってポイントが多かったんで、放流して参考にしてもらうのが正しいかと思って。
ら、楽したいとかそういうんじゃないんだからね！
MySQL キーリングって？
そもそもキーリングって何？っていう人のために、簡単に説明すると、データ暗号化（Transparent Data Encryption 略してTDE）を行うためのプラグインまたはコンポーネントです。
よーわからん、っていう人は、まあ、データ暗号化したかったらそれ設定せえ、っちゅうことで覚えてください。
ちゃんと知りたいって人は個別にMySQL セミナーのセキュリティ関連の資料読んだり、それこそキーリングのドキュメントを読んでくださいね。
プラグインからコンポーネントへ
さて、色んな前情報は各自自分で調べて読んでもらうとして、ここからは本題の移行作業へ
ただ、ここでは気軽に試してみたいっていう人のために、キーリングプラグインのインストールから書いてみる
1 MySQL Serverを用意する
適当なMySQL Serverを1台ご用意ください
2 my.cnf|my.iniの編集
MySQL コンフィグファイルを編集します。
$ vim my.cnf
以下を追加してください。
### keyring early-plugin-load=keyring_file.so plugin-load=keyring_udf.so keyring_file_data=/home/takiida/mysql-keyring/keyring-encrypted ### エラー表示時にNoteも出力するようにしておく log_error_verbosity=3
log_error_verbosity=3は、キーリングとは関係ないんですが、作業の可視化のためです。
キーリング管理用関数を設定するためにプラグイン（keyring_udf.so）もここで入れてます。
keyring_file_dataの/home/takiida/mysql-keyringはファイルの作成場所として自分で作った場所です。
指定しないとデフォルトがありますが、何度も行き来するので、分かりやすいところに作っておきましょう。
話はちょっとずれますが、エラーログのローテーションをしているところはこの設定がおススメです。
クライアント周りのエラーをつかむのや、今回のような作業の成功時のメッセージが見れるので便利ですし、安心感が違います。
3 再起動してプラグインが読み込まれる
keyring_file プラグインとkeyring_udf プラグインが読み込まれます。
keyring_udf はSQLでキーリング管理（ランダムキー作成など）をするためのプラグインです。
今回はSQLでちゃちゃっと試すために入れてます。
再起動後に確認して以下のようになってればOKです。
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'keyring%'; +------------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +------------------------+---------------+ | keyring_file | ACTIVE | | keyring_udf | ACTIVE | +------------------------+---------------+ 2 rows in set (0.00 sec)
ランダムキー作成
ここに手順が全て書かれていますが、サラッと記載しておきます。
キーリング管理用関数をこしらえます。
-- INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so'; <-- これは既にmy.cnfで読み込んだのでスキップ CREATE FUNCTION keyring_key_generate RETURNS INTEGER SONAME 'keyring_udf.so'; CREATE FUNCTION keyring_key_fetch RETURNS STRING SONAME 'keyring_udf.so'; CREATE FUNCTION keyring_key_length_fetch RETURNS INTEGER SONAME 'keyring_udf.so'; CREATE FUNCTION keyring_key_type_fetch RETURNS STRING SONAME 'keyring_udf.so'; CREATE FUNCTION keyring_key_store RETURNS INTEGER SONAME 'keyring_udf.so'; CREATE FUNCTION keyring_key_remove RETURNS INTEGER SONAME 'keyring_udf.so';
keyring_key_generate関数でランダムキーを作成します。
以下の例はMyKey という名前の 2,048-bit DSA 暗号化キーを作成しています。
mysql> SELECT keyring_key_generate('MyKey', 'DSA', 256);
5 キーリングプラグインでTDE設定
mysql> SELECT SPACE, NAME, SPACE_TYPE, ENCRYPTION FROM INFORMATION_SCHEMA.INNODB_TABLESPACES WHERE ENCRYPTION='Y' ; Empty set (0.00 sec) mysql> SELECT TABLE_SCHEMA, TABLE_NAME, CREATE_OPTIONS FROM INFORMATION_SCHEMA.TABLES WHERE CREATE_OPTIONS LIKE '%ENCRYPTION%'; Empty set (0.01 sec) mysql> SELECT * FROM performance_schema.keyring_keys; Empty set (0.00 sec) mysql> create database testdb; Query OK, 1 row affected (0.03 sec) mysql> use testdb; Database changed mysql> CREATE TABLE testdb.A1(ID INT AUTO_INCREMENT PRIMARY KEY, NAME VARCHAR(20)) ENCRYPTION = 'Y'; Query OK, 0 rows affected (0.11 sec) mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'keyring%'; +------------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +------------------------+---------------+ | keyring_file | ACTIVE | | keyring_udf | ACTIVE | +------------------------+---------------+ 2 rows in set (0.00 sec) mysql> SELECT SPACE, NAME, SPACE_TYPE, ENCRYPTION FROM INFORMATION_SCHEMA.INNODB_TABLESPACES WHERE ENCRYPTION='Y' ; +-------+-----------+------------+------------+ | SPACE | NAME | SPACE_TYPE | ENCRYPTION | +-------+-----------+------------+------------+ | 2 | testdb/A1 | Single | Y | +-------+-----------+------------+------------+ 1 row in set (0.00 sec) mysql> SELECT TABLE_SCHEMA, TABLE_NAME, CREATE_OPTIONS FROM INFORMATION_SCHEMA.TABLES WHERE CREATE_OPTIONS LIKE '%ENCRYPTION%'; +--------------+------------+----------------+ | TABLE_SCHEMA | TABLE_NAME | CREATE_OPTIONS | +--------------+------------+----------------+ | testdb | A1 | ENCRYPTION='Y' | +--------------+------------+----------------+ 1 row in set (0.01 sec) mysql> SELECT * FROM performance_schema.keyring_keys; +--------------------------------------------------+-----------+----------------+ | KEY_ID | KEY_OWNER | BACKEND_KEY_ID | +--------------------------------------------------+-----------+----------------+ | INNODBKey-00008040-0000-0000-0000-000000008040-1 | | | +--------------------------------------------------+-----------+----------------+ 1 row in set (0.00 sec)
ってな感じで準備ができました。
さて、したごしらえができたので、ここからが移行作業です。
6 キーリングコンポーネント移行前確認
コンポーネントはまだ表示されないことを確認
mysql> SELECT * FROM performance_schema.keyring_component_status; Empty set (0.00 sec)
keyring-encrypted fileを確認
$ ll mysql-keyring/ total 12 drwxr-x--- 2 takiida takiida 4096 Feb 20 10:28 ./ drwxr-xr-x 29 takiida takiida 4096 Feb 20 09:34 ../ -rw-r----- 1 takiida takiida 229 Feb 20 10:28 keyring-encrypted
もしkeyring-encryptedファイルが0バイトだと、そもそもキーリングプラグインの設定が失敗してるのでやり直してください。
7 component_keyring_file の設定ファイルを作成する
mysql> SHOW GLOBAL VARIABLES LIKE 'plugin_dir';
+---------------+-----------------+
| Variable_name | Value |
+---------------+-----------------+
| plugin_dir | {path1}/plugin/ |
+---------------+-----------------+
ここで表示された {path1}/plugin/ 配下にcomponent_keyring_file.cnfファイルを作る必要があります。
$ vim {path1}/plugin/component_keyring_file.cnf
$ cat {path1}/plugin/component_keyring_file.cnf
{
"path": "/home/takiida/mysql-keyring/component_keyring_file",
"read_only": false
}
この設定ファイル内のpathはkeyring_file_dataと同じがいいでしょう。
このcomponent_keyring_file.cnfファイルを作成する手順がドキュメントだと無いんですよね…。
インストール関係として別ページにあるから厄介
あと、グローバルとローカルっていうのがありますが、ここではグローバルオンリーにしてます。
8 キーリングプラグインからコンポーネントへの移行です
移行方法としてオフラインとオンラインの方法があります。
昔はオフラインしかできなかったんですが、今はオンラインでできるってことで、オンラインでやっちゃいましょう。
$ /home/takiida/opt/mysql/8.0.40/bin/mysqld \ --keyring-file-data=/home/takiida/mysql-keyring/keyring-encrypted \ --keyring-migration-to-component \ --keyring-migration-source=keyring_file.so \ --keyring-migration-destination=component_keyring_file.so \ --keyring-migration-host=<ip> \ --keyring-migration-user=root \ --keyring-migration-password=<password> \ --keyring-migration-port=<port> \ --log-error-verbosity=3
キモはlog-error-verbosity=3です。なぜかというと、以下のような表示が出力されるのを確認するためです。
[Note] [MY-013713] [Server] Component component_keyring_file reported: 'Keyring component initialized successfully.' [Note] [MY-011085] [Server] Keyring migration successful. [Note] [MY-010120] [Server] Binlog end [Note] [MY-010733] [Server] Shutting down plugin 'keyring_file' [System] [MY-010910] [Server] /home/takiida/opt/mysql/8.0.40/bin/mysqld: Shutdown complete (mysqld 8.0.40-commercial) MySQL Enterprise Server - Commercial.
Noteとしてメッセージが表示されるので、ここでlog-error-verbosity=3にしとかないと成功したのかどうか不安になります。
オフラインでマイグレーションした場合はさっきのmy.cnfに設定したやつが利きます。
9 component_keyring_file fileの確認
component_keyring_fileファイルが０バイトじゃなければ移行は成功しています。
$ ll mysql-keyring/ total 36 drwxr-x--- 2 takiida takiida 4096 Nov 26 10:32 ./ drwxr-xr-x 30 takiida takiida 20480 Nov 26 10:27 ../ -rw-r----- 1 takiida takiida 210 Nov 26 10:32 component_keyring_file -rw-r----- 1 takiida takiida 187 Nov 26 10:20 keyring-encrypted
10 マニフェストの作成
実はまだ完了ではありません。
マニフェストファイルというものを作成し、どのキーリングコンポーネントをロードするかを設定する必要があります。
ファイルは起動時に使用するmysqldインストールディレクトリ配下に作成します。
$ vim {basedir}/bin/mysqld.my
$ cat {basedir}/bin/mysqld.my
{
"read_local_manifest":false,
"components": "file://component_keyring_file"
}
この話も移行のドキュメント上に無くて、コンポーネントインストールのドキュメントにあるんで、そこが不便なんですよね…
ここでも、グローバルとローカルっていうのがありますが、ここではやはりグローバルオンリーにしてます。
11 MySQL Server を再起動します
再起動して、キーリングコンポーネントが使われることを確認します。
ちなみに、再起動前にキーリングプラグイン関連のパラメータをコメントアウトしておくとより分かりやすいと思います。
# early-plugin-load=keyring_file.so plugin-load=keyring_udf.so # keyring_file_data=/home/takiida/mysql-keyring/keyring-encrypted
12 エラーログを確認します
以下のようなメッセージが表示されていればOKです。
[Note] [MY-013713] [Server] Component component_keyring_file reported: 'Keyring component initialized successfully.'
13 performance_schema.keyring_component_statusテーブルで確認
以下のような結果が確認できれば移行は終了です。
mysql> SELECT * FROM performance_schema.keyring_component_status; +---------------------+-------------------------------------------------+ | STATUS_KEY | STATUS_VALUE | +---------------------+-------------------------------------------------+ | Component_name | component_keyring_file | | Author | Oracle Corporation | | License | GPL | | Implementation_name | component_keyring_file | | Version | 1.0 | | Component_status | Active | | Data_file | /usr/local/mysql/keyring/component_keyring_file | | Read_only | No | +---------------------+-------------------------------------------------+
おわりに
キーリング関連のドキュメント、充実してるけど導線が微妙でわかりづらいので、流れをまとめてみました。
誰かの参考になれば幸いです。
明日は@yoku0825さんの「ConoHaとクロスポストでビルドの話」です。
