PS-9139 Document new PS Encryption UDFs functionality - 8.0

	modified:   docs/encryption-functions.md

Author: patrickbirch

docs/encryption-functions.md

@@ -1,6 +1,44 @@
-# Encryption functions
+# Encryption user-defined functions
 
-Percona Server for MySQL 8.0.28-20 adds encryption functions and variables to manage the encryption range. The functions may take an algorithm argument. Encryption converts plaintext into ciphertext using a key and an encryption algorithm.
+The encryption user-defined functions (UDF) let you encrypt and decrypt data. You can choose different encryption algorithms and manage the range of data to encrypt.
+
+## Version updates
+
+Percona Server for MySQL 8.0.40 adds the following:
+
+* Support for `PKCS1 OAEP` padding for RSA encrypt and decrypt operations
+
+    <details>
+       <summary> `PKCS1 OAEP` padding explanation</summary>
+        PKCS1 OAEP (Optimal Asymmetric Encryption Padding) is a cryptographic technique used to add randomness to a message before encryption. This randomness helps to increase the security of the encrypted message. OAEP padding adds a layer of security by making it more difficult for attackers to exploit weaknesses in the encryption algorithm or to recover the original message.
+    </details>
+
+* Support for `PKCS1 PSS` padding for RSA sign and verify operations
+
+    <details>
+       <summary> `PKCS1 PSS` padding explanation</summary>
+        PKCS PSS (Probabilistic Signature Scheme) is a cryptographic algorithm 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 make it more resistant to various attacks. 
+    </details>
+
+* [`encryption_udf.legacy_paddding_scheme`](#encryption_udflegacy_paddding_scheme) system variable
+
+* Character set awareness
+
+Percona Server for MySQL 8.0.28-20 adds encryption functions and variables to manage the encryption range.
+
+## 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.
 
@@ -64,7 +102,7 @@ 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 to decrypt the string. Percona Server for MySQL 8.0.40 added support for PKCS1 OAEP padding for RSA encrypt operations
 
 * key_str - a string in the PEM format. The key string must have the following attributes:
 
@@ -116,7 +154,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 to encrypt the string. Percona Server for MySQL 8.0.40 added support for PKCS1 PSS padding for RSA sign operations.
 
 * digest_str - the digest binary string that is signed. Invoking create_digest generates the digest.
 
@@ -158,7 +196,7 @@ A `1` (success) or a `0` (failure).
 
 The parameters are the following:
 
-* algorithm - supports either ‘RSA’ or ‘DSA’.
+* algorithm - supports either ‘RSA’ or ‘DSA’. Percona Server for MySQL 8.0.40 added support for PKCS1 PSS padding for RSA verify operations.
 
 * digest_str - invoking create_digest generates this digest binary string.
 
@@ -308,6 +346,37 @@ 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_paddding_scheme
+
+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 is set to `OFF` by default. 
+
+This variable controls how the functions `asymmetric_encrypt()`, `asymmetric_decrypt()`, `asymmetric_sign()`, and `asymmetric_verify()` behave when you don’t explicitly set the padding parameter.
+
+•	When encryption_udf.legacy_padding_scheme is OFF:
+
+    • asymmetric_encrypt() and asymmetric_decrypt() use OAEP padding.
+
+    • asymmetric_sign() and asymmetric_verify() use PKCS1_PSS padding.
+
+•	When encryption_udf.legacy_padding_scheme is ON:
+
+    • asymmetric_encrypt() and asymmetric_decrypt() use PKCS1 padding.
+
+    • asymmetric_sign() and asymmetric_verify() use PKCS1 padding.
+
+The `asymmetric_encrypt()` and `asymmetric_decrypt()` functions accept an extra optional parameter, padding. You can set it to `no`, `pkcs1`, or `oaep`. If you don’t specify this parameter, it defaults based on the `encryption_udf.legacy_padding_scheme` value. Note that when using `OAEP` padding, the maximum message length you can encrypt is <key_size_in_bytes> - 42. The padding parameter is only valid with the RSA algorithm.
+
+Similarly, `asymmetric_sign()` and `asymmetric_verify()` also have an optional padding parameter, which can be either `pkcs1` or `pkcs1_pss`. If not explicitly set, it follows the default based on `encryption_udf.legacy_padding_scheme`. You can only use the padding parameter with RSA algorithms.
+
 ### 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.