Details
-
Bug
-
Status: Confirmed (View Workflow)
-
Critical
-
Resolution: Unresolved
-
N/A
-
Notable changes
Description
After the encryption manual updates (ref MDEV-36434) the manual now has various inconsitencies, and the page needs work. For example,
1) The openssl enc command refers to /tmp which is not used earlier in the page.
2) The manual uses -pass pass:secret instead of -pass file:/etc/mysql/encryption/keyfile.key or similar to match text earlier in the page and general setup methods.
3) (Background: when one uses "file:" in openssl, one expects to be able to use "file:" in MariaDB.) This is not the case, and "FILE:" (uppercase) needs to be used instead. When one uses 'file:' it simply gives a cryptic error:
2025-12-10 10:26:51 0 [Note] mariadbd: Read from ../key.enc, read bytes: 96, max key file size: 1048576 bytes
|
2025-12-10 10:26:51 0 [ERROR] mariadbd: Cannot decrypt ../key.enc. Wrong key?
|
2025-12-10 10:26:51 0 [ERROR] Plugin 'file_key_management' init function returned error.
|
2025-12-10 10:26:51 0 [ERROR] Plugin 'file_key_management' registration as a ENCRYPTION failed.
|
Let's add a special warning box for this to ensure users use 'FILE:' even if it's already in the example.
4) It makes sense to use -iter when using -pbkdf2 to specify a higher number than the openssl default 10k (as the manual already alludes to here). This could be put in as part of the example.
5) Whenever -pbkdf2 is used the number of iterations should be specified on the MariaDB server side as well, or key decryption will fail.
6) It will be necessary to have both the original setup (as it was before any updates) as well as the new SHA2 setup specified, as MDEV-34712 was implemented only in 12.0.1. IOW, the current syntax will not work for older versions.
7) The digest needs to be specified, or key decryption will fail.
etc.
To update this page, one will have to understand well how encryption in MariaDB works. To aid this, here is working example code (for both after 12.0.1 and before):
if check_for_version $MYSQL_VERSION "12.0.1"; then # https://jira.mariadb.org/browse/MDEV-34712 was implemented in 12.0.1 |
# For use with: --plugin_load_add=file_key_management [--file-key-management=FORCE_PLUS_PERMANENT] --file-key-management-filekey=FILE:../key.pass --file_key_management_use_pbkdf2=11000 --file-key-management-filename=../key.enc --file_key_management_digest=sha256 --file-key-management-encryption-algorithm=AES_CBC [--aria-encrypt-tables=ON --innodb-encrypt-log=ON --innodb_encrypt_tables=ON ...] |
# Generate a 256-bit (32-byte) key for use with file_key_management_filekey |
echo "$(echo -n '1;' ; openssl rand -hex 32)" > key.key |
# Generate an plain-text hex password to encrypt the key.key file with |
openssl rand -hex 128 > key.pass
|
# Encrypt the file_key key.key with the password provided in key.pass |
openssl enc -aes-256-cbc -md sha256 -pbkdf2 -iter 11000 -pass file:key.pass -in key.key -out key.enc |
# Remove the unencrypted key |
rm -f key.key |
else # i.e. prior to 12.0.1 |
# For use with: --plugin_load_add=file_key_management [--file-key-management=FORCE_PLUS_PERMANENT] --file-key-management-filekey=FILE:../key.pass --file-key-management-filename=../key.enc --file-key-management-encryption-algorithm=AES_CBC [--aria-encrypt-tables=ON --innodb-encrypt-log=ON --innodb_encrypt_tables=ON ...] |
# Generate a 256-bit (32-byte) key for use with file_key_management_filekey |
echo "$(echo -n '1;' ; openssl rand -hex 32)" > key.key |
# Generate an plain-text hex password to encrypt the key.key file with |
openssl rand -hex 128 > key.pass
|
# Encrypt the file_key key.key with the password provided in key.pass |
openssl enc -aes-256-cbc -md sha1 -pass file:key.pass -in key.key -out key.enc |
# Remove the unencrypted key |
rm -f key.key |
fi |
(Except the check_for_version function, can provide if of interest, basically it checks if the version >=12.0.1).
Note the intricacies like the need to use 'FILE:' in the mariadbd startup command, the need to specify 10000 (the default number of iterations as set in openssl), the need to specify the digest, if --iter was used in openssl, a matching value needs to be used for mariadbd, etc.
Attachments
Issue Links
- is caused by
-
MDEV-36434 SHA2 support for the file_key_management.so plugin (TDE) documentation
-
- Closed
-
- relates to
-
MDEV-34712 Implement SHA2 support for file_key_management.so plugin (TDE)
-
- Closed
-