You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/encryption-functions.md
+178-58
Original file line number
Diff line number
Diff line change
@@ -12,33 +12,69 @@ When choosing key lengths, consider the following:
12
12
13
13
* 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.
14
14
15
-
The following table and sections describe the functions. For examples, see function examples.
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.
17
+
Percona Server for MySQL 8.4.4 adds the following:
* Support for `pkcs1`, `oaep`, or `no` padding for RSA encrypt and decrypt operations
20
+
21
+
<details>
22
+
<summary> `pkcs1` padding explanation</summary>
23
+
[`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.
24
+
</details>
25
+
<details>
26
+
<summary> `oaep` padding explanation</summary>
27
+
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.
28
+
</details>
29
+
<details>
30
+
<summary> `no` padding explanation</summary>
31
+
Using `no` padding means the plaintext message is encrypted without adding an extra layer before performing the RSA encryption operation.
32
+
</details>
33
+
34
+
* Support for `pkcs1` or `pkcs1_pss` padding for RSA sign and verify operations
35
+
36
+
<details>
37
+
<summary> `pkcs1` padding explanation</summary>
38
+
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.
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.
43
+
</details>
44
+
45
+
*[`encryption_udf.legacy_paddding`](#legacy_padding) system variable
46
+
47
+
* Character set awareness
48
+
49
+
## Charset Awareness
50
+
51
+
All component_encryption_udf functions now handle character sets intelligently:
52
+
53
+
• 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.
54
+
55
+
• 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.
56
+
57
+
• Function return values in PEM format: Assigned the ASCII charset.
58
+
59
+
• Function return values for operations like digest calculation, encryption, decryption, and signing: Assigned the binary charset.
60
+
61
+
## Use user-defined functions
62
+
63
+
You can also use the user-defined functions with the PEM format keys generated externally by the OpenSSL utility.
64
+
65
+
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.
66
+
67
+
When choosing key lengths, consider the following:
68
+
69
+
* Encryption strength increases with the key size and generation time.
70
+
71
+
* 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.
36
72
37
73
## Install component_encryption_udf
38
74
39
75
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 ...`.
40
76
41
-
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.
77
+
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.
42
78
43
79
The following is an example of the installation command:
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.
87
+
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.
88
+
89
+
90
+
91
+
## Functions
92
+
93
+
The following table and sections describe the functions. For examples, see function examples.
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.
Decrypts an encrypted string using the algorithm and a key string.
58
124
@@ -64,15 +130,19 @@ A plaintext as a string.
64
130
65
131
The following are the function’s parameters:
66
132
67
-
* algorithm - the encryption algorithm supports RSA to decrypt the string.
133
+
* algorithm - the encryption algorithm supports RSA in decrypting the string.
134
+
135
+
*`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.
68
136
69
137
* key_str - a string in the PEM format. The key string must have the following attributes:
70
138
71
139
* Valid
72
140
73
-
* Public or private key string that corresponds with the private or public key string used with the asymmetric_encrypt function.
141
+
* Public or private key string corresponding with the private or public key string used with the [`asymmetric_encrypt`](#asymmetric_encrypt()) function.
142
+
143
+
* 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`](#legacy_padding) variable.
* 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`](#legacy_padding) variable.
* 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`](#legacy_padding) variable.
* 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`](#legacy_padding) variable.
Creates a digest from the given string using the given digest type. The digest string can be used with asymmetric_sign and asymmetric_verify.
315
+
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()).
240
316
241
317
### create_digest output
242
318
@@ -282,9 +358,9 @@ The variables are automatically registered when component_encryption_udf is inst
The variable sets the maximum limit for the create_dh_parameters user-defined function and takes precedence over the OpenSSL maximum length value.
363
+
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.
288
364
289
365
| Option | Description |
290
366
|--------------|------------------|
@@ -295,9 +371,9 @@ The variable sets the maximum limit for the create_dh_parameters user-defined fu
295
371
296
372
The range for this variable is from 1024 to 10,000. The default value is 10,000.
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.
376
+
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.
301
377
302
378
| Option | Description |
303
379
|--------------|------------------|
@@ -308,9 +384,53 @@ The variable sets the threshold limits for create_asymmetric_priv_key user-defin
308
384
309
385
The range for this variable is from 1,024 to 9,984. The default value is 9,984.
The variable enables or disables the legacy padding scheme for certain encryption operations.
390
+
391
+
| Option | Description |
392
+
|--------------|------------------|
393
+
| command-line | Yes |
394
+
| scope | Global |
395
+
| data type | Boolean |
396
+
| default | OFF |
397
+
398
+
This system variable is a BOOLEAN type and set to `OFF` by default.
399
+
400
+
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.
401
+
402
+
• When encryption_udf.legacy_padding is OFF:
403
+
404
+
• [asymmetric_encrypt()](#asymmetric_encrypt()) and [asymmetric_decrypt()](#asymmetric_decrypt()) use OAEP encryption padding.
405
+
406
+
• [asymmetric_sign()](#asymmetric_sign()) and [asymmetric_verify()](#asymmetric_verify()) use PKCS1_PSS signature padding.
407
+
408
+
• When encryption_udf.legacy_padding is ON:
409
+
410
+
• [`asymmetric_encrypt()`](#asymmetric_encrypt()) and [`asymmetric_decrypt()`](#asymmetric_decrypt()) use PKCS1 encryption padding.
411
+
412
+
• [`asymmetric_sign()`](#asymmetric_sign()) and [`asymmetric_verify()`](#asymmetric_verify()) use PKCS1 signature padding.
413
+
414
+
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`](#legacy_padding) value.
415
+
416
+
The padding schemes have the following limitations:
|`oaep`| The message you encrypt can be as long as your RSA key size in bytes - 42 bytes.|
421
+
|`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. |
422
+
|`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.|
423
+
424
+
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`](#legacy_padding). You can only use the padding parameter with RSA algorithms.
425
+
426
+
#### Additional resources
427
+
428
+
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/)
429
+
312
430
313
-
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`](#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.
314
434
315
435
| Option | Description |
316
436
|--------------|------------------|
@@ -325,15 +445,15 @@ The range for this variable is from 1,024 to 16,384. The default value is 16,384
0 commit comments