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
+101-32
Original file line number
Diff line number
Diff line change
@@ -40,51 +40,102 @@ Percona Server for MySQL 8.0.41 adds the following:
40
40
41
41
Percona Server for MySQL 8.0.28-20 adds encryption functions and variables to manage the encryption range.
42
42
43
-
## Charset Awareness
43
+
## Character sets and component encryption UDFs
44
44
45
-
All component_encryption_udf functions now handle character sets intelligently:
45
+
The `component_encryption_udf` functions handle character sets automatically, making them easy to use.
46
46
47
-
• 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.
47
+
* Input handling:
48
+
* Algorithms, digest names, padding, keys, and pem parameters are converted to ascii.
49
+
50
+
* Messages, data blocks, and signatures are converted to binary.
51
+
52
+
* Output handling:
53
+
* Pem format results are returned in ascii.
54
+
55
+
* Digest, encryption, decryption, and signing results are returned in binary.
48
56
49
-
• 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.
57
+
## Using external pem keys
50
58
51
-
• Function return values in PEM format: Assigned the ASCII charset.
59
+
You can use keys generated by openssl with these functions, offering greater flexibility.
52
60
53
-
• Function return values for operations like digest calculation, encryption, decryption, and signing: Assigned the binary charset.
61
+
## Digests vs. encryption
54
62
55
-
## Use user-defined functions
63
+
* Digests (hashes):
64
+
65
+
* Used to verify data integrity.
66
+
67
+
* Can be signed for authenticity.
68
+
69
+
* Cannot be used to recover the original data.
70
+
71
+
* Encryption:
72
+
73
+
* Used to make data unreadable without the key.
74
+
75
+
* Can be decrypted to recover the original data.
56
76
57
-
You can also use the user-defined functions with the PEM format keys generated externally by the OpenSSL utility.
77
+
## Key length considerations
58
78
59
-
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.
79
+
Choose key lengths by balancing security and performance:
60
80
61
-
When choosing key lengths, consider the following:
81
+
* Longer keys increase security but slow down key generation.
62
82
63
-
*Encryption strength increases with the key size and also the key generation time.
83
+
*Symmetric encryption is faster than asymmetric.
64
84
65
-
* 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 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.
85
+
* Asymmetric encryption (like rsa) limits message size (for example, rsa: key length in bytes - 11).
86
+
87
+
Choose the right key length based on your application's needs.
88
+
89
+
90
+
## Functions
66
91
67
92
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.
|[asymmetric_encrypt](#asymmetric_encrypt)| Encrypts a string using an algorithm and a key string. |
99
+
|[asymmetric_decrypt](#asymmetric_decrypt)| Decrypts an encrypted string using an algorithm and a key string. |
100
+
101
+
### Asymmetric key management functions
102
+
103
+
| Function Name | Description |
104
+
| --- | --- |
105
+
|[create_asymmetric_priv_key](#create_asymmetric_priv_key)| Generates a private key using a given algorithm and key length. |
106
+
|[create_asymmetric_pub_key](#create_asymmetric_pub_key)| Derives a public key from a given private key using a given algorithm. |
107
+
108
+
### Digital Signature functions
109
+
110
+
| Function Name | Description |
111
+
| --- | --- |
112
+
|[asymmetric_sign](#asymmetric_sign)| Signs a digest string using a private key string. |
113
+
|[asymmetric_verify](#asymmetric_verify)| Verifies whether a signature string matches a digest string. |
114
+
115
+
### Diffie-Hellman functions
116
+
117
+
| Function Name | Description |
118
+
| --- | --- |
119
+
|[create_dh_parameters](#create_dh_parameters)| Creates parameters for generating a Diffie-Hellman private/public key pair. |
120
+
|[asymmetric_derive](#asymmetric_derive)| Derives a symmetric key using a public key and a private key. |
121
+
122
+
### Digest functions
123
+
124
+
| Function Name | Description |
125
+
| --- | --- |
126
+
|[create_digest](#create_digest)| Creates a digest from a given string using a given digest type. |
127
+
128
+
### Encryption threshold variables
129
+
130
+
The encryption threshold variables are used to set the maximum value for a key length based on the type of encryption used. These variables provide a way to control and limit the key length for different encryption algorithms.
131
+
132
+
| Variable Name | Description | Default Value | Range |
133
+
| --- | --- | --- | --- |
134
+
|[encryption_udf.dh_bits_threshold](#encryption_udfdh_bits_threshold)| Sets the maximum limit for Diffie-Hellman key length | 10000 | 1024-10000 |
135
+
|[encryption_udf.dsa_bits_threshold](#encryption_udfdsa_bits_threshold)| Sets the maximum limit for DSA key length | 9984 | 1024-9984 |
136
+
|[encryption_udf.rsa_bits_threshold](#encryption_udfrsa_bits_threshold)| Sets the maximum limit for RSA key length | 16384 | 1024-16384 |
137
+
|[encryption_udf.legacy_padding](#encryption_udflegacy_padding)| Enables or disables the legacy padding scheme for certain encryption operations | OFF | Boolean |
Decrypts an encrypted string using the algorithm and a key string.
110
163
@@ -408,6 +461,22 @@ The padding schemes have the following limitations:
408
461
|`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. |
409
462
|`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.|
410
463
464
+
<details>
465
+
<summary>Length Limitation</summary>
466
+
When using the PKCS#1 padding scheme with an RSA key, it is essential to consider the limitations on the length of the message that can be encrypted. The maximum length of the message is determined by the size of the RSA key, minus a fixed overhead of 11 bytes, which is used to store the padding bytes.
467
+
468
+
To calculate the maximum length of the message, use the following formula:
This means that when using a 1024-bit RSA key with the PKCS#1 padding scheme, the message cannot exceed 117 bytes. If the message is longer, you will need to use a larger RSA key or a different padding scheme.
478
+
</details>
479
+
411
480
Similarly, `asymmetric_sign()` and `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.
Copy file name to clipboardexpand all lines: docs/glossary.md
+35
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,10 @@
4
4
5
5
Set of properties that guarantee database transactions are processed reliably. Stands for [Atomicity](#atomicity), [Consistency](#consistency), [Isolation](#isolation), [Durability](#durability).
6
6
7
+
## Asymmetric key
8
+
9
+
A pair of keys used for cryptographic purposes, consisting of a private key and a corresponding public key. The private key is used for decrypting or signing, while the public key is used for encrypting or verifying.
10
+
7
11
## Atomicity
8
12
9
13
Atomicity means that database operations are applied following a “all or nothing” rule. A transaction is either fully applied or not at all.
@@ -12,6 +16,21 @@ Atomicity means that database operations are applied following a “all or nothi
12
16
13
17
Consistency means that each transaction that modifies the database takes it from one consistent state to another.
14
18
19
+
## Digest
20
+
21
+
A digital fingerprint of a piece of data, such as a string or a file, produced by a hash function. Digests are used to verify the integrity of data and ensure it has not been tampered with or altered.
22
+
23
+
## Digest string
24
+
The string representation of a digest, often in hexadecimal format.
25
+
26
+
## Digital signature
27
+
28
+
A cryptographic mechanism used to verify the authenticity and integrity of a message, software, or document. It ensures that the data comes from the claimed source and has not been altered during transmission.
29
+
30
+
## Diffie-Hellman key exchange
31
+
32
+
A cryptographic protocol that allows two parties to establish a shared secret key over an insecure communication channel without actually exchanging the key.
33
+
15
34
## Durability
16
35
17
36
Once a transaction is committed, it will remain so.
@@ -28,6 +47,10 @@ A referential constraint between two tables. Example: A purchase order in the pu
28
47
29
48
A finalized version of the product which is made available to the general public. It is the final stage in the software release cycle.
30
49
50
+
## Hash function
51
+
52
+
A one-way mathematical function that takes input data of any size and produces a fixed-size string of characters, known as a digest or hash value. Hash functions are used to create digital fingerprints of data.
53
+
31
54
## Isolation
32
55
33
56
The Isolation requirement means that no transaction can interfere with another.
The Percona branch of [MySQL](#mysql) with performance and management improvements.
88
111
112
+
## Private key
113
+
114
+
A secret key used in asymmetric cryptography for decrypting or signing data. It is typically kept secure and not shared with others.
115
+
116
+
## Public key
117
+
118
+
A publicly available key used in asymmetric cryptography for encrypting or verifying data. It is typically shared with others and used in conjunction with a private key.
119
+
89
120
## Storage Engine
90
121
91
122
A storage engine is a piece of software that implements the details of data storage and retrieval for a database system. This term is primarily used within the [MySQL](#mysql) ecosystem due to it being the first widely used relational database to have an abstraction layer around storage. It is analogous to a Virtual File System layer in an Operating System. A VFS layer allows an operating system to read and write multiple file systems (e.g. FAT, NTFS, XFS, ext3) and a Storage Engine layer allows a database server to access tables stored in different engines (for example, [MyISAM](#myisam) or InnoDB).
92
123
124
+
## Symmetric key
125
+
126
+
A single key used for both encrypting and decrypting data in symmetric cryptography. Symmetric keys are typically kept secret and shared between parties.
127
+
93
128
## Tech Preview
94
129
95
130
A tech preview item can be a feature, a variable, or a value within a variable. Before using this feature in production, we recommend that you test restoring production from physical backups in your environment and also use an alternative backup method for redundancy. A tech preview item is included in a release for users to provide feedback. The item is either updated, released as [general availability(GA)](#general-availability-ga), or removed if not useful. The functionality can change from tech preview to GA.
0 commit comments