PS-9139 Document new PS Encryption UDFs functionality - 8.0

	modified:   docs/encryption-functions.md

Author: patrickbirch

docs/encryption-functions.md

@@ -1,7 +1,28 @@
-# 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.
 
+## 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
+
+
 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.
@@ -64,7 +85,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 +137,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 +179,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 +329,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.