PS-9139 Document new PS Encryption UDFs functionality - 8.0

	modified:   docs/encryption-functions.md

Author: patrickbirch

docs/encryption-functions.md

@@ -1,6 +1,54 @@
-# 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.41 adds the following:
+
+* Support for `pkcs1`, `oaep`, or `no` padding for RSA encrypt and decrypt operations
+
+    <details>
+       <summary> `pkcs1` padding explanation</summary>
+        The `pkcs1` padding 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> `oeap` padding explanation</summary>  
+        The `oeap` (Optimal Asymmetric Encryption Padding) padding adds a randomized mask generation function. This function makes it more difficult for attackers to exploit weaknesses in the encryption algorithm or to recover the original message.
+    </details>
+    
+    <details>
+       <summary> `no` padding explanation</summary>
+       Using `no` padding means that the plaintext message is encrypted without adding an extra layer before performing the RSA encryption operation.
+    </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.
 
@@ -66,6 +114,8 @@ The following are the function’s parameters:
 
 * algorithm - the encryption algorithm supports RSA to decrypt the string.
 
+* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. It is used with the RSA algorithm and supports padding schemes like `no`, `pkcs1`, or `oaep`. If you skip this parameter, the system determines its value based on the `encryption_udf.legacy_padding_scheme` variable.
+
 * key_str - a string in the PEM format. The key string must have the following attributes:
 
   * Valid
@@ -100,6 +150,8 @@ The parameters are the following:
 
 * algorithm - the encryption algorithm supports RSA to encrypt the string.
 
+* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. It is used with the RSA algorithm and supports padding schemes like `no`, `pkcs1`, or `oaep`. If you skip this parameter, the system determines its value based on the `encryption_udf.legacy_padding_scheme` variable.
+
 * str - measured in bytes. The length of the string must not be greater than the key_str modulus length in bytes - 11 (additional bytes used for PKCS1 padding)
 
 * key_str - a key (either private or public) in the PEM format
@@ -116,7 +168,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. 
 
 * digest_str - the digest binary string that is signed. Invoking create_digest generates the digest.
 
@@ -158,7 +210,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 +360,45 @@ 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, 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` value. 
+
+The padding schemes have the following limitations:
+
+| Padding Scheme    | Details                                                                                                                                                        |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `oeap`           | 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()` 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.