DOCS-6412 Fix TDE fundamentals instruction steps - #859
Merged
Merged
Conversation
The walkthrough had gaps that made customers fail at it: - The version-specific key file tabs led with the Enterprise Server format, so a 10.6 user picked it and the server refused to start with "Invalid key". Label the tabs by version, put the widely applicable one first, and warn that the wrong format is a startup failure. - The config snippet referenced an encrypted key file that the previous step never created. Point at Encrypting the Key File, and clarify that keyfile.key holds the encryption password, not a key. - innodb_encryption_threads was never set, and it defaults to 0, so existing tables were never converted and both monitoring steps had nothing to report. Set it in the enable step, note it in the disable step, and add the missing "Monitor encryption progress" step. - UNINSTALL SONAME always warns "Plugin is busy and will be uninstalled on shutdown", because the server holds a reference to the active encryption plugin. Document it as expected. - Drop AES_CTR from the walkthrough and warn about it instead: the algorithm can't be changed once data is encrypted, and HashiCorp and AWS Key Management only support AES_CBC, so AES_CTR locks you into File Key Management. See MDEV-40657. Also correct the claim that AES_CTR needs OpenSSL: wolfSSL builds support it as of 11.2 (commit f94d467d326), so the restriction only applies to earlier releases. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mariadb-stefan-hinz
added
the
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes DOCS-6412, reported by Hartmut Holzgraefe after a customer failed to enable TDE by following the page.
What was wrong
1;1;and the server refused to startkeyfile.key(an encrypted key file) that step 1 never createdkeyfile.keyholds the encryption passwordinnodb_encryption_threadswas never set, so existing tables were never converted and the monitoring steps had nothing to showUNINSTALL SONAMEreturnsPlugin is busy and will be uninstalled on shutdown, undocumentedfile_key_management_encryption_algorithm = AES_CTRFact-check notes
Each claim was verified against
mariadb-server@a217e1000f3(13.0.1). Two places where I diverged from the ticket:innodb_encrypt_tables=FORCE— not adopted. The ticket suggestsFORCEinstead ofON"so that existing tables get encrypted in the background already". That isn't whatFORCEdoes.should_encrypt()treats both as truthy for default-mode tablespaces, so background conversion depends on the threads, not onONvsFORCE. WhatFORCEactually adds is rejectingENCRYPTED=NO(ha_innodb.cc:11490) — which would break this page's own Manual Control: Disabling Encryption section further down. So I fixed the real cause (threads) and documentedFORCEas the policy control it is.The wolfSSL restriction is version-specific. Both pages stated unconditionally that
AES_CTRrequires OpenSSL. That flipped in commitf94d467d326("enable AES-CTR with wolfssl"), first released in 11.2.1 —cmake/ssl.cmakesetsHAVE_EncryptAes128Ctr ONfor bundled wolfSSL onmain, versusOFFon10.6-enterprise. So the ticket's version of this claim is right for ES 10.6 but wrong for every current Community Server release. Qualified by version rather than deleted.The plugin lock-in half of the AES_CTR concern is confirmed and was undocumented: HashiCorp and AWS KMS pass
0for all five crypt entry points, so the server falls back to a hard-codedMY_AES_CBCpath (sql/encryption.cc:46). Data written underAES_CTRis unreadable after switching. That's the same trap as MDEV-40657.Checks
doc-lint.sh(codespell + lychee + includes) passes. New heading anchors and relative link targets verified by hand, since lychee doesn't check fragments.🤖 Generated with Claude Code