PS-9713 [DOCS] - Document new PS Encryption UDFs functionality (inspired by upstream 8.4.4)

patrickbirch · patrickbirch · commit b070c25e2c38 · 2025-03-14T19:26:08.000-05:00
modified:   docs/encryption-functions.md
diff --git a/docs/encryption-functions.md b/docs/encryption-functions.md
@@ -12,6 +12,68 @@ When choosing key lengths, consider the following:
 
 * If performance is important and the functions are frequently used, use symmetric encryption. Symmetric encryption functions are faster than asymmetric encryption functions. Moreover, asymmetric encryption has restrictions on the maximum length of a message being encrypted. For example, for RSA the algorithm maximum message size is the key length in bytes (key length in bits / 8) minus 11.
 
+## Version updates
+
+Percona Server for MySQL 8.4.4 adds the following:
+
+* Support for `pkcs1`, `oaep`, or `no` padding for RSA encrypt and decrypt operations
+
+    <details>
+       <summary> `pkcs1` padding explanation</summary>
+        [`RSAES-PKCS1-v1_5`](https://en.wikipedia.org/wiki/PKCS_1) RSA encryption padding scheme prevents patterns that attackers could exploit by including a random sequence of bytes, which ensures that the ciphertext is different no matter how many times it is encrypted.
+    </details>
+    
+    <details>
+       <summary> `oaep` padding explanation</summary>  
+        The [`RSAES-OAEP`](https://en.wikipedia.org/wiki/PKCS_1)  - [`Optimal Asymmetric Encryption Padding`](https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding) RSA encryption padding scheme adds a randomized mask generation function. This function makes it more difficult for attackers to exploit the encryption algorithm's weaknesses or recover the original message.
+    </details>
+    
+    <details>
+       <summary> `no` padding explanation</summary>
+       Using `no` padding means the plaintext message is encrypted without adding an extra layer before performing the RSA encryption operation.
+    </details>
+
+* Support for `pkcs1` or `pkcs1_pss`  padding for RSA sign and verify operations
+
+    <details>
+       <summary> `pkcs1` padding explanation</summary>
+        The [`RSASSA-PKCS1-v1_5`](https://en.wikipedia.org/wiki/PKCS_1) is a deterministic RSA signature padding scheme that hashes a message, pads the hash with a specific structure, and encrypts it with the signer's private key for signature generation. 
+    </details>
+    <details>
+       <summary> `pkcs1_pss` padding explanation</summary>
+        The [`RSASSA-PSS`](https://en.wikipedia.org/wiki/PKCS_1) - [`Probabilistic Signature Scheme'](https://en.wikipedia.org/wiki/Probabilistic_signature_scheme) is an RSA signature padding scheme used to add randomness to a message before signing it with a private key. This randomness helps to increase the security of the signature and makes it more resistant to various attacks. 
+    </details>
+
+* [`encryption_udf.legacy_paddding_scheme`](#encryption_udflegacy_paddding_scheme) system variable
+
+* Character set awareness
+
+## Charset Awareness
+
+All component_encryption_udf functions now handle character sets intelligently:
+
+• Algorithms, digest names, padding schemes, keys, and parameters in PEM format: Automatically converted to the ASCII charset at the MySQL level before passing to the functions.
+
+• Messages, data blocks, and signatures used for digest calculation, encryption, decryption, signing, or verification: Automatically converted to the binary charset at the MySQL level before passing to the functions.
+
+• Function return values in PEM format: Assigned the ASCII charset.
+
+• Function return values for operations like digest calculation, encryption, decryption, and signing: Assigned the binary charset.
+
+## Use user-defined functions
+
+You can also use the user-defined functions with the PEM format keys generated externally by the OpenSSL utility.
+
+A digest uses plaintext and generates a hash value. This hash value can verify if the plaintext is unmodified. You can also sign or verify on digests to ensure that the original plaintext was not modified. You cannot decrypt the original text from the hash value.
+
+When choosing key lengths, consider the following:
+
+* Encryption strength increases with the key size and generation time.
+
+* If performance is essential and the functions are frequently used, use symmetric encryption. Symmetric encryption functions are faster than asymmetric encryption functions. Moreover, asymmetric encryption restricts the maximum length of a message being encrypted. For example, the algorithm's maximum message size for RSA is the key length in bytes (key length in bits / 8) minus 11.
+
+## Functions
+
 The following table and sections describe the functions. For examples, see function examples.
 
 | Function Name                                                                                                                    |
@@ -25,20 +87,24 @@ The following table and sections describe the functions. For examples, see funct
 | [create_asymmetric_pub_key(algorithm, priv_key_str)](#create_asymmetric_pub_keyalgorithm-priv_key_str)  |
 | [create_dh_parameters(key_len)](#create_dh_parameterskey_len)  |
 | [create_digest(digest_type, str)](#create_digestdigest_type-str)  |
+| [create_digest(digest_type, str)](#create_digestdigest_type-str)  |
 
-The following table describes the Encryption threshold variables which can be used to set the maximum value for a key length based on the type of encryption.
+The following table describes the encryption threshold variables which can be used to set the maximum value for a key length based on the type of encryption used.
 
 | Variable Name                     |
 |-----------------------------------|
 | [encryption_udf.dh_bits_threshold](#encryption_udfdh_bits_threshold)  |
 | [encryption_udf.dsa_bits_threshold](#encryption_udfdsa_bits_threshold) |
+| [encryption_udf.legacy_padding](#encryption_udflegacy_padding)|
 | [encryption_udf.rsa_bits_threshold](#encryption_udfrsa_bits_threshold) |
 
+
+
 ## Install component_encryption_udf
 
 Use the [Install Component Statement] to add the component_encryption_udf component. The functions and variables are available. The user-defined functions and the Encryption threshold variables are auto-registered. There is no requirement to invoke `CREATE FUNCTION ... SONAME ...`.
 
-The `INSERT` privilege on the `mysql.component` system table is required to run the `INSTALL COMPONENT` statement. To register the component, the operation adds a row to this table.
+The `INSERT` privilege on the `mysql.component` system table is required to run the `INSTALL COMPONENT` statement. The operation adds a row to this table to register the component.
 
 The following is an example of the installation command:
 
@@ -48,7 +114,7 @@ mysql> INSTALL COMPONENT 'file://component_encryption_udf';
 
 !!! note
 
-    If you are Compiling Percona Server for MySQL from Source, the Encryption UDF component is built by default when Percona Server for MySQL is built. Specify the `-DWITH_ENCRYPTION_UDF=OFF` cmake option to exclude it.
+    When you build Percona Server for MySQL from source code, the Encryption UDF component is included by default. To exclude it, use the `-DWITH_ENCRYPTION_UDF=OFF` option with cmake.
 
 ## User-defined functions described
 
@@ -64,13 +130,17 @@ A plaintext as a string.
 
 The following are the function’s parameters:
 
-* algorithm - the encryption algorithm supports RSA to decrypt the string.
+* algorithm - the encryption algorithm supports RSA in decrypting the string.
+
+  * `crypt_str` - an encrypted string produced by certain encryption functions like AES_ENCRYPT(). This string is typically stored as a binary or blog data type.
 
 * key_str - a string in the PEM format. The key string must have the following attributes:
 
   * Valid
 
-  * Public or private key string that corresponds with the private or public key string used with the asymmetric_encrypt function.
+  * Public or private key string corresponding with the private or public key string used with the [`asymmetric_encrypt`](#asymmetric_encrypt) function.
+  
+  * padding - An optional parameter introduced in Percona Server for MySQL 8.4.4. It is used with the RSA algorithm and supports RSA encryption padding schemes like pkcs1, or oaep. If you skip this parameter, the system determines its value based on the [`encryption_udf.legacy_padding_scheme`](#encryption_udf.legacy_padding_scheme) variable.
 
 ## asymmetric_derive(*pub_key_str, priv_key_str*)
 
@@ -104,6 +174,8 @@ The parameters are the following:
 
 * key_str - a key (either private or public) in the PEM format
 
+* padding - An optional parameter introduced in Percona Server for MySQL 8.4.4. It is used with the RSA algorithm and supports RSA encryption padding schemes like pkcs1, or oaep. If you skip this parameter, the system determines its value based on the [`encryption_udf.legacy_padding_scheme`](#encryption_udf.legacy_padding_scheme) variable.
+
 ## asymmetric_sign(*algorithm, digest_str, priv_key_str, digest_type*)
 
 Signs a digest string using a private key string.
@@ -116,7 +188,7 @@ A signature is a binary string.
 
 The parameters are the following:
 
-* algorithm - the encryption algorithm supports either RSA or DSA to encrypt the string.
+* algorithm - the encryption algorithm supports either RSA or DSA in encrypting the string.
 
 * digest_str - the digest binary string that is signed. Invoking create_digest generates the digest.
 
@@ -146,9 +218,7 @@ The parameters are the following:
     |  |  | shake128 |  |
     |  |  | shake256 |  |
 
-## asymmetric_verify(*algorithm, digest_str, sig_str, pub_key_str, digest_type*)
-
-Verifies whether the signature string matches the digest string.
+* padding - An optional parameter introduced in Percona Server for MySQL 8.4.4. It is used with the RSA algorithm and supports RSA signature padding schemes like `pkcs1`, or `pkcs1_pss`. If you skip this parameter, the system determines its value based on the [`encryption_udf.legacy_padding_scheme`](encryption_udf.legacy_padding_scheme) variable.
 
 ### asymmetric_verify output
 
@@ -168,6 +238,8 @@ The parameters are the following:
 
 * digest_type - the supported values are listed in the digest type table of create_digest
 
+* padding - An optional parameter introduced in Percona Server for MySQL 8.4.4. It is used with the RSA algorithm and supports RSA signature padding schemes like `pkcs1`, or `pkcs1_pss`. If you skip this parameter, the system determines its value based on the [`encryption_udf.legacy_padding_scheme`](#encryption_udf.legacy_padding_scheme) variable.
+
 ## create_asymmetric_priv_key(*algorithm, (key_len | dh_parameters)*)
 
 Generates a private key using the given algorithm and key length for RSA or DSA
@@ -221,12 +293,11 @@ If needed, execute `KILL [QUERY|CONNECTION] <id>` to terminate the generation of
 
 Generating the DH parameters can take more time than generating the RSA keys or
 the DSA keys.
-OpenSSL defines the parameter length limits. To change the
-maximum parameter length, use encryption_udf.dh_bits_threshold.
+OpenSSL defines the parameter length limits. To change the maximum parameter length, use [`encryption_udf.dh_bits_threshold`](#encryption_udf.dh_bits_threshold).
 
 ### create_dh_parameters output
 
-A string in the PEM format and can be passed to create_asymmetric_private_key.
+A string in the PEM format and can be passed to [create_asymmetric_private_key](#create_asymmetric_private_key).
 
 ### create_dh_parameters parameters
 
@@ -236,7 +307,7 @@ The parameters are the following:
 
 ## create_digest(*digest_type, str*)
 
-Creates a digest from the given string using the given digest type. The digest string can be used with asymmetric_sign and asymmetric_verify.
+Creates a digest from the given string using the given digest type. The digest string can be used with [`asymmetric_sign`](#asymmetric_sign) and [`asymmetric_verify`](#asymmetric_verify).
 
 ### create_digest output
 
@@ -284,7 +355,7 @@ The variables are automatically registered when component_encryption_udf is inst
 
 ### `encryption_udf.dh_bits_threshold`
 
-The variable sets the maximum limit for the create_dh_parameters user-defined function and takes precedence over the OpenSSL maximum length value.
+The variable sets the maximum limit for the [`create_dh_parameters`](#create_dh_parameters) user-defined function and takes precedence over the OpenSSL maximum length value.
 
 | Option       | Description      |
 |--------------|------------------|
@@ -297,7 +368,7 @@ The range for this variable is from 1024 to 10,000. The default value is 10,000.
 
 ### encryption_udf.dsa_bits_threshold
 
-The variable sets the threshold limits for create_asymmetric_priv_key user-defined function when the function is invoked with the DSA parameter and takes precedence over the OpenSSL maximum length value.
+The variable sets the threshold limits for [`create_asymmetric_priv_key`](#create_asymmetric_priv_key) user-defined function when the function is invoked with the DSA parameter and takes precedence over the OpenSSL maximum length value.
 
 | Option       | Description      |
 |--------------|------------------|
@@ -308,9 +379,53 @@ The variable sets the threshold limits for create_asymmetric_priv_key user-defin
 
 The range for this variable is from 1,024 to 9,984. The default value is 9,984.
 
+### encryption_udf.legacy_padding
+
+The variable enables or disables the legacy padding scheme for certain encryption operations.
+
+| Option       | Description      |
+|--------------|------------------|
+| command-line | Yes              |
+| scope        | Global           |
+| data type    | Boolean |
+| default      | OFF            |
+
+This system variable is a BOOLEAN type and set to `OFF` by default. 
+
+This variable controls how the functions [`asymmetric_encrypt()`](#asymmetric_encrypt), [`asymmetric_decrypt()`](#asymmetric_decrypt), [`asymmetric_sign()`](#asymmetric_sign), and [`asymmetric_verify()`](#asymmetric_verify) behave when you don’t explicitly set the padding parameter.
+
+•	When [encryption_udf.legacy_padding_scheme](#encryption_udf.legacy_padding_scheme) is OFF:
+
+    • [asymmetric_encrypt()](#asymmetric_encrypt) and [asymmetric_decrypt()](#asymmetric_decrypt) use OAEP encryption padding.
+
+    • [asymmetric_sign()](#asymmetric_sign) and [asymmetric_verify()](#asymmetric_verify) use PKCS1_PSS signature padding.
+
+•	When [encryption_udf.legacy_padding_scheme](#encryption_udf.legacy_padding_scheme) is ON:
+
+    • [`asymmetric_encrypt()`](#asymmetric_encrypt) and [`asymmetric_decrypt()`](#asymmetric_decrypt) use PKCS1 encryption padding.
+
+    • [`asymmetric_sign()`](#asymmetric_sign) and [`asymmetric_verify()`](#asymmetric_verify) use PKCS1 signature padding.
+
+The [`asymmetric_encrypt()`](#asymmetric_encrypt) and [`asymmetric_decrypt()`](#asymmetric_decrypt) functions, when the encryption is `RSA`, can accept an optional parameter, `padding`. You can set this parameter to `no`, `pkcs1`, or `oaep`. If you don’t specify this parameter, it defaults based on the [`encryption_udf.legacy_padding_scheme`](#encryption_udf.legacy_padding_scheme) value. 
+
+The padding schemes have the following limitations:
+
+| Padding Scheme    | Details                                                                                                                                                        |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `oaep`           | The message you encrypt can be as long as your RSA key size in bytes - 42 bytes.|
+| `no`             | The message length must exactly match your RSA key size in bytes. For example, if your key is 1024 bits (128 bytes), the message must also be 128 bytes. If it doesn’t match, it will cause an error. |
+| `pkcs1` | Your message can be equal to or smaller than the RSA key size - 11 bytes. For instance, with a 1024-bit RSA key, your message can’t be longer than 117 bytes.|
+
+Similarly, [`asymmetric_sign()`](#asymmetric_sign) and [`asymmetric_verify()`](#asymmetric_verify) also have an optional `padding` parameter, either `pkcs1` or `pkcs1_pss`. If not explicitly set, it follows the default based on [`encryption_udf.legacy_padding_scheme`](#encryption_udf.legacy_padding_scheme). You can only use the padding parameter with RSA algorithms.
+
+#### Additional resources
+
+  For more information, read [`Digital Signatures: Another layer of Data Protection in Percona Server for MySQL`](https://www.percona.com/blog/digital-signatures-another-layer-of-data-protection-in-percona-server-for-mysql/)
+
+
 ### encryption_udf.rsa_bits_threshold
 
-The variable sets the threshold limits for the create_asymmetric_priv_key user-defined function when the function is invoked with the RSA parameter and takes precedence over the OpenSSL maximum length value.
+The variable sets the threshold limits for the [`create_asymmetric_priv_key`](#encryption_udf.create_asymmetric_priv_key) user-defined function when the function is invoked with the RSA parameter and takes precedence over the OpenSSL maximum length value.
 
 | Option       | Description      |
 |--------------|------------------|
@@ -325,15 +440,15 @@ The range for this variable is from 1,024 to 16,384. The default value is 16,384
 
 Code examples for the following operations:
 
-* set the threshold variables
+* Set the threshold variables
 
-* create a private key
+* Create a private key
 
-* create a public key
+* Create a public key
 
-* encrypt data
+* Encrypt data
 
-* decrypt data
+* Decrypt data
 
 ```{.bash data-prompt="mysql>"}
 -- Set Global variable
@@ -360,11 +475,11 @@ mysql> SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @public_key);
 
 Code examples for the following operations:
 
-* generate a digest string
+* Generate a digest string
 
-* generate a digest signature
+* Generate a digest signature
 
-* verify the signature against the digest
+* Verify the signature against the digest
 
 ```{.bash data-prompt="mysql>"}
 -- Generate a digest string
@@ -380,13 +495,13 @@ mysql> SET @verify_signature = asymmetric_verify('RSA', @digest, @signature, @pu
 
 Code examples for the following operations:
 
-* generate a DH parameter
+* Generate a DH parameter
 
-* generates two DH key pairs
+* Generates two DH key pairs
 
-* generate a symmetric key using the public_1 and the private_2
+* Generate a symmetric key using the public_1 and the private_2
 
-* generate a symmetric key using the public_2 and the private_1
+* Generate a symmetric key using the public_2 and the private_1
 
 ```{.bash data-prompt="mysql>"}
  -- Generate a DH parameter
@@ -409,11 +524,11 @@ mysql> SET symmetric_2 = asymmetric_derive(@public_2, @private_1);
 
 Code examples for the following operations:
 
-* create a private key using a `SET` statement
+* Create a private key using a `SET` statement
 
-* create a private key using a  `SELECT` statement
+* Create a private key using a  `SELECT` statement
 
-* create a private key using an `INSERT` statement
+* Create a private key using an `INSERT` statement
 
 ```{.bash data-prompt="mysql>"}
 mysql> SET @private_key1 = create_asymmetric_priv_key('RSA', 3072);
