diff --git a/docs/ai-docs.md b/docs/ai-docs.md index 4c060a86550..1351337d586 100644 --- a/docs/ai-docs.md +++ b/docs/ai-docs.md @@ -1,7 +1,7 @@ # How we use artificial intelligence -The technical writer oversees the integration of AI-driven tools and platforms into the documentation workflow, ensuring that AI-generated text meets the standards for clarity, coherence, and accuracy. While AI assists in tasks such as content generation, language enhancement, and formatting optimization, the technical writer is responsible for validating and refining the output to ensure its suitability for the intended audience. +The technical writer manages how AI tools and platforms are used in the documentation process. They ensure that the text created by AI is clear, logical, and accurate. Although AI helps with generating content, improving language, and formatting, it is the technical writer who checks and improves the output to make sure it suits the audience. -Throughout the documentation process, the technical writer reviews the quality and relevance of AI-generated content in detail and with critical judgment. By leveraging their expertise in language, communication, and subject matter knowledge, the technical writer collaborates with AI systems to refine and tailor the documentation to meet the specific needs and preferences of the audience. +During the documentation process, the technical writer carefully reviews the AI-generated content for quality and relevance. Using their knowledge of language, communication, and the subject matter, they work with AI systems to adjust and improve the documentation based on what the audience needs. -While AI accelerates the documentation process and enhances productivity, the technical writer verifies the information's accuracy and maintains consistency in terminology, style, and tone. The technical writer ensures that the final document reflects the company's commitment to excellence. +Even though AI speeds up the process and boosts productivity, the technical writer makes sure that the information is correct and keeps the style, tone, and terminology consistent. They ensure that the final document meets the company's high standards. diff --git a/docs/digest-encryption.md b/docs/digest-encryption.md new file mode 100644 index 00000000000..47fd4bbd4c5 --- /dev/null +++ b/docs/digest-encryption.md @@ -0,0 +1,45 @@ +# Cryptographic digest functions vs. encryption + +These two fundamental cryptographic technologies serve different security purposes and should not be confused in implementation: + +* Cryptographic Digest Functions (hashes): + + * Generate a fixed-length unique data representation that serves as a cryptographic fingerprint + + * Provide data integrity verification by detecting modifications at the bit level + + * Can be digitally signed to verify data origin and authenticate the source + + * Implement mathematically irreversible one-way functions by design + + * Common implementation error: Attempting to retrieve original data from digest values, which is mathematically impossible + +* Encryption: + + * Implements reversible transformation of data using cryptographic algorithms + + * Renders data unreadable without the appropriate decryption key + + * Ensures complete data recovery with the correct cryptographic key + + * Common implementation error: Inadequate key management leading to permanent data loss + + +## When to use which + +Use digests when: + +* You need to verify data hasn't changed + +* You want to store passwords (never store actual passwords, ever!) + +* You need to create a digital signature + +Use encryption when: + +* You need to keep data secret but retrieve it later + +* You're storing sensitive information that must remain recoverable + +* You need to securely transmit data over insecure channels + diff --git a/docs/encryption-functions-overview.md b/docs/encryption-functions-overview.md new file mode 100644 index 00000000000..929faa2d7cb --- /dev/null +++ b/docs/encryption-functions-overview.md @@ -0,0 +1,188 @@ +## Encryption functions overview + +This document provides comprehensive information about encryption functions that transform plaintext data into encrypted ciphertext. These functions provide robust security measures that require proper documentation to implement and maintain effectively. This guide offers the necessary information for successful implementation. + + + +## Overview of capabilities + +This documentation will guide you through: + +* Implementing data encryption protocols + +* Executing data decryption procedures + +* Implementing digital signature authentication + +* Avoiding common implementation pitfalls + + + + +First, let's review some key terms you'll encounter throughout this guide. + + +## Glossary of terms + +Here's a quick reference guide to the cryptographic terms used in this document: + +* **Encryption**: The process of converting readable data into a coded format that can only be decoded with the correct key. + +* **Decryption**: The reverse process of encryption, converting coded data back to its original readable form. + +* **Symmetric Encryption**: A type of encryption where the same key is used for both encryption and decryption, like a single key that locks and unlocks the same door. + +* **Asymmetric Encryption**: A type of encryption that uses a pair of keys - a public key for encryption and a private key for decryption, or vice versa. + +* **RSA** (Rivest-Shamir-Adleman): One of the most widely used asymmetric encryption algorithms, named after its creators. + +* **DSA** (Digital Signature Algorithm): An algorithm specifically designed for creating digital signatures. + +* **DH** (Diffie-Hellman): A method that allows two parties to establish a shared secret key over an insecure channel without sharing any secret information beforehand. + +* **Digest/Hash**: A fixed-size string of bytes generated from input data of any size, functioning like a digital fingerprint of the data. + +* **Digital Signature**: An electronic equivalent of a handwritten signature that uses asymmetric cryptography to verify authenticity. + +* **Padding**: Additional data added to a message before encryption to enhance security and prevent pattern analysis. + +* **PEM Format**: Privacy Enhanced Mail format, a common format for storing and sending cryptographic keys, certificates, and other data. + +Now, let's examine common implementation challenges in encryption systems. + +## Implementation challenges + +> ⚠️ **Common encryption mistakes** +> +> Key management is a critical aspect of encryption systems that requires rigorous planning and careful implementation. +> + +Here are the most common implementation issues: + +* Key loss: When decryption keys are lost, data becomes permanently inaccessible, even to authorized personnel. + +*Algorithm-key mismatch: Using incompatible keys and algorithms results in decryption failures. + +* Exceeding size limitations: Attempting to encrypt data larger than algorithm constraints can cause failures in both encryption and decryption processes. + +* Insufficient documentation: Failing to properly document the encryption process and key management procedures can lead to system failures. + +## Version updates + +Percona Server for MySQL 8.0.41 introduces several important new features that enhance security capabilities while requiring careful implementation. + +### Padding options for RSA encryption + +| Padding type | Security level | Application | Characteristics | +|--------------|----------------|------------------------|------------------------------------------------| +| `pkcs1` | Basic | Legacy compatibility | Standard protection with known limitations | +| `oaep` | High | Modern applications | Enhanced protection with additional security layers | +| `no` | None | Specialized cases only | No protection, vulnerable to multiple attack vectors | + +#### Detailed padding explanations + +
+ `pkcs1` padding: The nostalgic option + + Think of `pkcs1` padding as the security equivalent of a 90s-era car alarm. It adds random stuffing to your message to stop pattern analysis, making your message look different each time. It's decent protection against casual thieves but not against determined professionals with modern tools. It's like putting your valuables in a safe that shouts "HEY! I'M A SAFE!" when touched. +
+ +
+ `oaep` padding: The recommended secure option + + `oaep` padding (Optimal Asymmetric Encryption Padding) implements a mathematically robust random mask that significantly increases resistance to cryptanalysis (the science of breaking encryption). This method applies multiple layers of protection to the encrypted data, making it the recommended option for systems requiring high security standards. The additional computational overhead is justified by the enhanced security protections it provides. +
+ +
+ `no` padding: Non-secure implementation option + + The unpadded encryption implementation provides no additional cryptographic protection for the message content. This approach eliminates randomization elements, exposing the encrypted data to various cryptanalytic attacks including pattern analysis. This option should only be implemented in specialized circumstances where compatibility with specific systems is required or where separate security controls are implemented at another layer. Not recommended for standard security implementations. +
+ + +### Signature padding options + +| Padding Type | Security Level | Characteristics | Best For | +|-------------|---------------|-----------------|----------| +| `pkcs1` | Standard | Consistent signatures | Compatibility with older systems | +| `pkcs1_pss` | High | Unique signature every time | Modern security needs | + +
+ `pkcs1` padding: The basic signature + + `pkcs1` padding for signatures is like signing your name the same way every time. It takes your message, creates a fingerprint, adds some standard framing, and locks it with your private key. It works fine until someone figures out how to copy your signature style, at which point your security is compromised. It's simple and compatible with older systems, but not the strongest option available. +
+ +
+ `pkcs1_pss` padding: The signature with flair + + `pkcs1_pss` padding is like adding a unique flourish to your signature every single time. Even when signing the exact same document twice, the signatures will look completely different - yet both will verify correctly. This makes signature forgery dramatically harder, as there's no consistent pattern to copy. If you're serious about security (and if you're reading this, you should be), this is your go-to option. +
+ + +### Other new features + +* [`encryption_udf.legacy_padding_scheme`](#encryption_udflegacy_padding_scheme) system variable - provides compatibility with legacy systems and previous implementations + +* Character set awareness - ensures proper handling of different character encodings during encryption operations + +Percona Server for MySQL 8.0.28-20 introduces tools for selective data encryption, allowing precise control over which data elements receive encryption protections. + +## Character sets and component encryption UDFs + +> 🏭 **Automated feature** +> +> These functions automatically manage character sets, eliminating the need for manual character encoding management during encryption operations. + +The implementation handles complex character set conversions internally, allowing developers to focus on encryption logic rather than encoding issues. + +### What happens to your input + +| Input Type | What Happens | Why It Matters | +|------------|--------------|----------------| +| Algorithms, digest names, keys | Automatically converted to ASCII | Prevents character encoding mismatches between encryption and decryption operations | +| Messages and signatures | Transformed into raw binary | Computers process binary, not human-readable formats | + + +### What you get back + +| Output Type | Format | What to Expect | +|------------|--------|----------------| +| Key files | Human-readable ASCII text | Viewable without terminal issues | +| Encrypted messages & signatures | Binary data | Looks like gibberish (this is correct!) | + +## External key management + +> 🔒 **External Key Management** +> +> For enhanced security, cryptographic keys can be generated outside the database server using dedicated cryptographic tools and hardware. + +Keys can be generated externally with OpenSSL and imported into the system. This approach separates key generation from the database environment, reducing the attack surface and allowing for specialized key generation hardware if required. + + +### External key generation + +| Tool | Command Example | What It Creates | +|------|----------------|-----------------| +| OpenSSL | `openssl genrsa -out private.pem 2048` | RSA private key | +| OpenSSL | `openssl rsa -in private.pem -pubout -out public.pem` | RSA public key from private key | +| OpenSSL | `openssl dsaparam -genkey 2048 -out dsaprivate.pem` | DSA private key | + +Your OpenSSL-generated keys work seamlessly with these functions - just read the PEM file and pass its content to the encryption functions. + + +### How you might break this + +⚠️ **Common Mistakes With External Keys:** + +* Importing a key in the wrong format + +* Using a key type incompatible with your chosen algorithm + +* Forgetting to remove newlines from PEM files when storing in variables + +* Storing keys directly in your database without proper protection + +If you encounter any of these issues, you may receive a non-descriptive error message. Ensure that your keys are correctly formatted and stored securely. + + diff --git a/docs/encryption-functions.md b/docs/encryption-functions.md index 20eb09a3909..8d6ca6cd7e4 100644 --- a/docs/encryption-functions.md +++ b/docs/encryption-functions.md @@ -1,311 +1,604 @@ -# Encryption user-defined functions +# Encryption functions + +## Quick start guide + +> ⚡ **Get Started in 5 Minutes** +> +> ```sql +> -- Install the encryption component +> INSTALL COMPONENT 'file://component_encryption_udf'; +> +> -- Create keys +> SET @private_key = create_asymmetric_priv_key('RSA', 3072); +> SET @public_key = create_asymmetric_pub_key('RSA', @private_key); +> +> -- Encrypt data +> SET @ciphertext = asymmetric_encrypt('RSA', 'Secret message', @public_key); +> +> -- Decrypt data +> SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @private_key); +> ``` +> +> See [complete examples](#examples-you-can-try) for more detailed use cases. + +## Functions + +> 🧰 **Cryptographic function library** +> +> The following section documents each cryptographic function available in the library. Each function is categorized by purpose with detailed implementation specifications. + + +### Function quick reference + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryFunctionWhat It DoesCommon Use Case
Encryptionasymmetric_encrypt()Puts your data in a math lockboxProtecting sensitive data
asymmetric_decrypt()Opens the lockbox and gets your data backRetrieving protected data
Key Managementcreate_asymmetric_priv_key()Makes your secret keyCreating your private key
create_asymmetric_pub_key()Creates a shareable public keyGenerating keys to distribute
Digital Signaturesasymmetric_sign()Stamps your message with your secret keyProving a message is from you
asymmetric_verify()Checks if a signature is real or fakeVerifying message authenticity
+ +### Asymmetric encryption functions + +These functions implement public key cryptography utilizing key pairs. The encryption and decryption operations require different keys from the same key pair. + +| Function Name | Purpose | +| --- | --- | +| [asymmetric_encrypt](#asymmetric_encrypt) | Encrypts plaintext data using asymmetric cryptography. Only the corresponding key can decrypt. | +| [asymmetric_decrypt](#asymmetric_decrypt) | Decrypts ciphertext that was encrypted with the corresponding asymmetric key. | + + +### Asymmetric key management functions + +These functions facilitate the generation and management of asymmetric cryptographic key pairs: + +| Function Name | Description | +| --- | --- | +| [create_asymmetric_priv_key](#create_asymmetric_priv_key) | Generates a private key with specified algorithm and security parameters | +| [create_asymmetric_pub_key](#create_asymmetric_pub_key) | Derives the corresponding public key from a private key for distribution | + + +### Digital Signature functions + +These functions implement digital signature operations for message authentication and verification: + +| Function Name | Description | +| --- | --- | +| [asymmetric_sign](#asymmetric_sign) | Applies a cryptographic signature to a message digest using a private key | +| [asymmetric_verify](#asymmetric_verify) | Validates the authenticity of a digital signature using the corresponding public key | + +### Diffie-Hellman functions + +> 🤝 **Shared secret generation** +> +> These functions facilitate secure key exchange between parties through the Diffie-Hellman protocol without transmitting sensitive key material. + +| Function Name | Description | Application | +| --- | --- | --- | +| [asymmetric_derive](#asymmetric_derive) | Generates a shared cryptographic secret through asymmetric key combination | When implementing secure communication channels between parties | +| [create_dh_parameters](#create_dh_parameters) | Generates the prime numbers and parameters required for Diffie-Hellman key exchange | As a prerequisite for Diffie-Hellman key generation | -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 +### Encryption threshold variables -Percona Server for MySQL 8.0.41 adds the following: +> ⚙️ **System configuration** +> +> These settings let you control how strong your encryption can be. They're like speed limits for your security system. + +Keys that are too strong might slow down your system. It's like having a super-heavy padlock that takes forever to open. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Setting NameWhat It DoesDefaultRangePerformance Impact
encryption_udf.dh_bits_thresholdSets how strong Diffie-Hellman keys can be100001024-10000Higher values significantly increase key generation time
encryption_udf.dsa_bits_thresholdSets how strong DSA keys can be99841024-9984Higher values increase key generation time
encryption_udf.rsa_bits_thresholdSets how strong RSA keys can be163841024-16384Higher values increase key generation and encryption/decryption time
encryption_udf.legacy_paddingTurns old-style padding on or offOFFON/OFFMinor impact on encryption speed, major impact on security
+--- -* Support for `pkcs1`, `oaep`, or `no` padding for RSA encrypt and decrypt operations -
- `pkcs1` padding explanation - [`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. -
- -
- `oaep` padding explanation - 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. -
- -
- `no` padding explanation - Using `no` padding means the plaintext message is encrypted without adding an extra layer before performing the RSA encryption operation. -
+## Install component_encryption_udf -* Support for `pkcs1` or `pkcs1_pss` padding for RSA sign and verify operations +> 📦 **Installation Guide** +> +> Before you can lock up your data, you need to install your security tools. -
- `pkcs1` padding explanation - 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. -
-
- `pkcs1_pss` padding explanation - 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. -
-* [`encryption_udf.legacy_paddding_scheme`](#encryption_udflegacy_paddding_scheme) system variable +### Quick installation steps -* Character set awareness +1. Use a simple command to add the encryption tools +2. Once you run the command, all the tools are ready right away +3. Best part: You don't need to run any complex setup commands! -Percona Server for MySQL 8.0.28-20 adds encryption functions and variables to manage the encryption range. +You'll need the `INSERT` permission on the `mysql.component` table to install this. The system just adds one row to this table to remember the tools are installed. -## Charset Awareness +```sql +-- Install the encryption component +INSTALL COMPONENT 'file://component_encryption_udf'; -All component_encryption_udf functions now handle character sets intelligently: +-- Verify installation +SELECT * FROM mysql.component; +``` -• 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. +!!! note -• 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. + If you're building Percona Server for MySQL from scratch, the encryption UDF component can be enabled or disabled using the `-DWITH_ENCRYPTION_UDF` CMake flag. By default, this flag is set to `ON`, meaning the encryption UDF component is built and included in the installation. If you want to build Percona Server without this component, you can disable it by setting `-DWITH_ENCRYPTION_UDF=OFF` during the CMake configuration stage of the build process. -• Function return values in PEM format: Assigned the ASCII charset. +## User-defined functions described -• 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. +## Asymmetric_decrypt(*algorithm, crypt_str, key_str*){asymmetric_decrypt} -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. +> 🔓 **Data Decryption Function** +> +> This function decrypts ciphertext to recover the original plaintext using asymmetric cryptography. -When choosing key lengths, consider the following: -* Encryption strength increases with the key size and also the key generation time. +### Quick reference -* 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. +| Parameter | Required | Description | +|-----------|----------|-------------| +| algorithm | Yes | Cryptographic algorithm identifier (currently only 'RSA') | +| crypt_str | Yes | The encrypted data (ciphertext) to be decrypted | +| key_str | Yes | The decryption key in PEM format | +| padding | No | Padding scheme: 'no', 'pkcs1', or 'oaep' | -The following table and sections describe the functions. For examples, see function examples. -| Function Name | -|----------------------------------------------------------------------------------------------------------------------------------| -| [asymmetric_decrypt(algorithm, crypt_str, key_str)](#asymmetric_decryptalgorithm-crypt_str-key_str) | -| [asymmetric_derive(pub_key_str, priv_key_str)](#asymmetric_derivepub_key_str-priv_key_str) | -| [asymmetric_encrypt(algorithm, str, key_str)](#asymmetric_encryptalgorithm-str-key_str) | -| [asymmetric_sign(algorithm, digest_str, priv_key_str, digest_type)](#asymmetric_signalgorithm-digest_str-priv_key_str-digest_type) | -| [asymmetric_verify(algorithm, digest_str, sig_str, pub_key_str, digest_type)](#asymmetric_verifyalgorithm-digest_str-sig_str-pub_key_str-digest_type) | -| [create_asymmetric_priv_key(algorithm, (key_len | dh_parameters))](#create_asymmetric_priv_keyalgorithm-key_len--dh_parameters) | -| [create_asymmetric_pub_key(algorithm, priv_key_str)](#create_asymmetric_pub_keyalgorithm-priv_key_str) | -| [create_dh_parameters(key_len)](#create_dh_parameterskey_len) | -| [create_digest(digest_type, str)](#create_digestdigest_type-str) | +### Return value -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. +The function returns the original plaintext message decoded from the ciphertext. -| Variable Name | -|-----------------------------------| -| [encryption_udf.dh_bits_threshold](#encryption_udfdh_bits_threshold) | -| [encryption_udf.dsa_bits_threshold](#encryption_udfdsa_bits_threshold) | -| [encryption_udf.rsa_bits_threshold](#encryption_udfrsa_bits_threshold) | -## Install component_encryption_udf +### Parameter details -Use the [Install Component Statement](https://dev.mysql.com/doc/refman/8.0/en/install-component.html) 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 ...`. +* **algorithm** - Specifies the cryptographic algorithm to be used for decryption (currently only RSA is supported) -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. +* **key_str** - The decryption key in PEM format. Requirements: + * Must be properly formatted and valid + * Must correspond to the encryption key used (public key if encrypted with private key, or private key if encrypted with public key) -The following is an example of the installation command: +* **crypt_str** - The encrypted binary data to be decrypted -```{.bash data-prompt="mysql>"} -mysql> INSTALL COMPONENT 'file://component_encryption_udf'; -``` +* **padding** - Specifies the padding scheme implemented in version 8.0.41: + * `no` - No padding (requires exact-size messages) + * `pkcs1` - PKCS#1 v1.5 padding scheme + * `oaep` - Optimal Asymmetric Encryption Padding (more secure) + + If not specified, the system uses the value from the encryption_udf.legacy_padding_scheme variable. -!!! note +
+ Example usage + + ```sql + -- Decrypt data using a private key + SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @private_key, 'oaep'); + + -- Verify the decrypted result + SELECT @plaintext; + ``` +
+--- - 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. -## User-defined functions described +## Asymmetric_derive(*pub_key_str, priv_key_str*){asymmetric_derive} -## asymmetric_decrypt(*algorithm, crypt_str, key_str*) +> 🤝 **Shared secret generation** +> +> This function implements the Diffie-Hellman key exchange protocol to establish a shared cryptographic secret between two parties without transmitting sensitive key material. -Decrypts an encrypted string using the algorithm and a key string. -### Returns +### Quick reference -A plaintext as a string. +| Parameter | Required | Description | +|-----------|----------|-------------| +| pub_key_str | Yes | The recipient's public key | +| priv_key_str | Yes | The initiator's private key | -### Parameters -The following are the function’s parameters: +### Required parameters -* algorithm - the encryption algorithm supports RSA in decrypting the string. +* **pub_key_str** - The recipient party's public key in PEM format -* key_str - a string in the PEM format. The key string must have the following attributes: +* **priv_key_str** - The initiator's private key in PEM format - * Valid - * Public or private key string corresponding with the private or public key string used with the asymmetric_encrypt function. - - * `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. - -* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. It is used with the RSA algorithm and supports RSA encryption 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`](#encryption_udf.legacy_padding_scheme) variable. +### Return value -## asymmetric_derive(*pub_key_str, priv_key_str*) +* Returns a cryptographic key value that will be identical for both parties when they perform their respective calculations -Derives a symmetric key using a public key generated on one side and a private key generated on another. +* The function enables secure symmetric key establishment without transmitting the actual secret key -### asymmetric_derive output +
+ Example usage + + ```sql + -- Generate a shared secret + SET @shared_secret = asymmetric_derive(@their_public_key, @my_private_key); + + -- Use the shared secret for symmetric encryption + -- Both parties will have the same shared secret + ``` +
+--- -A key as a binary string. -### asymmetric_derive parameters +## Asymmetric_encrypt(*algorithm, str, key_str*){asymmetric_encrypt} -The `pub_key_str` must be a public key in the PEM format and generated using the Diffie-Hellman (DH) algorithm. +> 🔒 **Data Encryption Function** +> +> This function transforms plaintext data into encrypted format using asymmetric cryptography. The encrypted data can only be decrypted with the corresponding key. -The `priv_key_str` must be a private key in the PEM format and generated using the Diffie-Hellman (DH) algorithm. -## asymmetric_encrypt(*algorithm, str, key_str*) +### Quick reference -Encrypts a string using the algorithm and a key string. +| Parameter | Required | Description | +|-----------|----------|-------------| +| algorithm | Yes | Cryptographic algorithm identifier (currently only 'RSA') | +| str | Yes | The plaintext message to encrypt | +| key_str | Yes | The encryption key (public or private) in PEM format | +| padding | No | Padding scheme: 'no', 'pkcs1', or 'oaep' | -### asymmetric_encrypt output -A ciphertext as a binary string. +### Return value -### asymmetric_encrypt parameters +The function returns the encrypted ciphertext as binary data. -The parameters are the following: -* algorithm - the encryption algorithm supports RSA in encrypting the string. +### Parameter details -* 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) +* **algorithm** - Specifies the cryptographic algorithm to be used for encryption (currently only RSA is supported) -* key_str - a key (either private or public) in the PEM format +* **str** - The plaintext data to be encrypted. Note that message length is constrained by the key size and padding scheme selected. Maximum message length must not exceed the key size minus padding overhead. -* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. It is used with the RSA algorithm and supports RSA encryption 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`](#encryption_udf.legacy_padding_scheme) variable. +* **key_str** - The encryption key in PEM format (can be either a public or private key depending on implementation requirements) -## asymmetric_sign(*algorithm, digest_str, priv_key_str, digest_type*) +* **padding** - A parameter added in version 8.0.41 that specifies the padding scheme: + * `no` - No padding (requires exact-size messages, not recommended for production) + * `pkcs1` - PKCS#1 v1.5 padding scheme (standard protection) + * `oaep` - Optimal Asymmetric Encryption Padding (enhanced security) + + If not specified, the system uses the value from the encryption_udf.legacy_padding_scheme variable. -Signs a digest string using a private key string. +
+ Example usage + + ```sql + -- Encrypt sensitive data using a public key + SET @ciphertext = asymmetric_encrypt('RSA', 'Secret message', @public_key, 'oaep'); + + -- Store or transmit the encrypted data + INSERT INTO secure_messages VALUES (@ciphertext); + ``` +
-### asymmetric_sign output +⚠️ **Size Limits**: Remember that your message size is limited by your key size and padding method. For a 2048-bit key with OAEP padding, your message must be smaller than (2048/8)-42 = 214 bytes. +--- -A signature is a binary string. -### asymmetric_sign parameters +## Asymmetric_sign(*algorithm, digest_str, priv_key_str, digest_type, [padding]*){asymmetric_sign} -The parameters are the following: +> ✍️ **Digital Signature Function** +> +> This function applies a cryptographic signature to a message digest using a private key. The signature provides authentication, non-repudiation, and integrity verification capabilities. Each signature is unique even when signing the same content multiple times. -* algorithm - the encryption algorithm supports RSA or DSA in encrypting the string. -* digest_str - the digest binary string that is signed. Invoking create_digest generates the digest. +### Quick reference -* priv_key_str - the private key used to sign the digest string. The key must be in the PEM format. +| Parameter | Required | Description | +|-----------|----------|-------------| +| algorithm | Yes | Signature algorithm ('RSA' or 'DSA') | +| digest_str | Yes | The message digest (hash value) | +| priv_key_str | Yes | The signer's private key in PEM format | +| digest_type | Yes | The hash algorithm identifier (e.g., 'SHA256') | +| padding | No | For RSA only: 'pkcs1' or 'pkcs1_pss' | -* digest_type - the OpenSSL version installed on your system determines the available hash functions. The following table lists these functions: - | OpenSSL 1.0.2 | OpenSSL 1.1.0 | OpenSSL 1.1.1 | OpenSSL 3.0.x | - |---|---|---|---| - | md5 | md5 | md5 | md5 | - | sha1 | sha1 | sha1 | sha1 | - | sha224 | sha224 | sha224 | sha224 | - | sha384 | sha384 | sha384 | sha384 | - | sha512 | sha512 | sha512 | sha512 | - | md4 | md4 | md4 | md4 | - | sha | md5-sha1 | md5-sha1 | md5-sha1 | - | ripemd160 | ripemd160 | ripemd160 | sha512-224 | - | whirlpool | whirlpool | sha512-224 | sha512-256 | - | | blake2b512 | sha512-256 | sha3-224 | - | | blake2s256 | whirlpool | sha3-256 | - | | | sm3 | sha3-384 | - | | | blake2b512 | sha3-512 | - | | | blake2s256 | | - | | | sha3-224 | | - | | | sha3-384 | | - | | | sha3-512 | | - | | | shake128 | | - | | | shake256 | | +### Security considerations +⚠️ **Implementation Risks**: +* Using public key instead of private key for signing operations +* Signing raw message data instead of message digest +* Inconsistent algorithm selection across systems +* Inadequate private key protection and backup procedures -* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. 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_scheme`](#encryption_udf.legacy_padding_scheme) variable. -## asymmetric_verify(*algorithm, digest_str, sig_str, pub_key_str, digest_type*) +### Return value -Verifies whether the signature string matches the digest string. +The function returns a digital signature as binary data that cryptographically proves the authenticity of the message. -### asymmetric_verify output -A `1` (success) or a `0` (failure). +### Parameter details -### asymmetric_verify parameters +1. **algorithm** - Specifies the signature algorithm: + * 'RSA' - RSA signature algorithm (widely implemented) + * 'DSA' - Digital Signature Algorithm (alternative implementation) -The parameters are the following: +2. **digest_str** - The cryptographic hash of the message + * Generate using the create_digest function + * Always sign the digest rather than the raw message for security and performance -* algorithm - supports either ‘RSA’ or ‘DSA’. +3. **priv_key_str** - The signer's private key + * Requires secure storage and access controls + * Must be in PEM format (standard key encoding format) -* digest_str - invoking create_digest generates this digest binary string. +4. **digest_type** - The hash algorithm identifier + * Common implementations include 'SHA256', 'SHA512', etc. + * Reference the digest type table for all supported algorithms -* sig_str - the signature binary string. Invoking asymmetric_sign generates this string. +5. **padding** - Signature padding scheme (for RSA algorithm only) + * Options: 'pkcs1' or 'pkcs1_pss' + * Default is determined by the encryption_udf.legacy_padding_scheme setting -* pub_key_str - the signer’s public key string. This string must correspond to the private key passed to asymmetric_sign to generate the signature string. The string must be in the PEM format. +
+ Example usage + + ```sql + -- Generate a message digest + SET @digest = create_digest('SHA256', 'Important message'); + + -- Sign the digest + SET @signature = asymmetric_sign('RSA', @digest, @private_key, 'SHA256', 'pkcs1_pss'); + + -- Store the signature with the message + INSERT INTO signed_messages VALUES ('Important message', @signature); + ``` +
-* digest_type - the supported values are listed in the digest type table of create_digest +--- -* padding - An optional parameter introduced in Percona Server for MySQL 8.0.41. 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_scheme`](#encryption_udf.legacy_padding_scheme) variable. -## create_asymmetric_priv_key(*algorithm, (key_len | dh_parameters)*) +## Asymmetric_verify(*algorithm, digest_str, sig_str, pub_key_str, digest_type, [padding]*){asymmetric_verify} -Generates a private key using the given algorithm and key length for DH's RSA, DSA -, or Diffie-Hellman parameters. For RSA or DSA, if needed, execute `KILL -[QUERY|CONNECTION] ` to terminate a long-lasting key generation. The -DH key generation from existing parameters is a quick operation. Therefore, it -does not make sense to terminate that operation with `KILL`. +> 🔍 **Signature verification function** +> +> This function validates the authenticity of a digital signature by verifying it against the original message digest using the signer's public key. It provides cryptographic proof of message integrity and sender identity. -### create_asymmetric_priv_key output -The key as a string in the PEM format. +### Quick reference -### create_asymmetric_priv_key parameters +| Parameter | Required | Description | +|-----------|----------|-------------| +| algorithm | Yes | Signature algorithm ('RSA' or 'DSA') | +| digest_str | Yes | The message digest (hash value) | +| sig_str | Yes | The digital signature to verify | +| pub_key_str | Yes | The signer's public key in PEM format | +| digest_type | Yes | The hash algorithm identifier (e.g., 'SHA256') | +| padding | No | For RSA only: 'pkcs1' or 'pkcs1_pss' | -The parameters are the following: -* algorithm - the supported values are ‘RSA’, ‘DSA’, or ‘DH’. +### Return value -* key_len - the supported key length values are the following: +The function returns a binary verification result: +* `1` - Signature verified successfully (authentic) +* `0` - Signature verification failed (inauthentic or corrupted) - * RSA - the minimum length is 1,024. The maximum length is 16,384. - * DSA - the minimum length is 1,024. The maximum length is 9,984. +### Parameter details - !!! note - - OpenSSL defines the key length limits. To change the maximum key length, use either encryption_udf.rsa_bits_threshold or encryption_udf.dsa_bits_threshold. +1. **algorithm** - Specifies the signature algorithm for verification + * Must match the algorithm used during signature creation + * Supported values: 'RSA' or 'DSA' -* dh_parameters - Diffie-Hellman (DH) parameters. Invoking create_dh_parameter creates the DH parameters. +2. **digest_str** - The cryptographic hash of the message + * Generate using the create_digest function + * Must use identical hashing algorithm as used during signing -## create_asymmetric_pub_key(*algorithm, priv_key_str*) +3. **sig_str** - The digital signature to be verified + * Generated by the asymmetric_sign function + * Binary data containing cryptographic validation information -Derives a public key from the given private key using the given algorithm. +4. **pub_key_str** - The signer's public key + * Must correspond to the private key used for signature creation + * Required in PEM format -### create_asymmetric_pub_key output +5. **digest_type** - The hash algorithm identifier + * Must match the algorithm used during signature creation + * Reference the algorithm table for supported options -The key as a string in the PEM format. +6. **padding** - The signature padding scheme + * Applicable only for RSA signatures + * Must match the padding scheme used during signature creation + * Default is determined by [`encryption_udf.legacy_padding_scheme`](#encryption_udflegacy_padding_scheme) -### create_asymmetric_pub_key parameters -The parameters are the following: +### ⚠️ Common Verification Pitfalls -* algorithm - the supported values are ‘RSA’, ‘DSA’, or ‘DH’. +| Mistake | What Happens | How to Avoid | +|---------|-------------|--------------| +| Using wrong public key | Verification always fails | Double-check key ownership | +| Verifying tampered message | Verification correctly fails | Don't change the message after signing | +| Using wrong digest type | Verification fails mysteriously | Use same digest type as signing | +| Mismatched padding | Verification fails with no clear reason | Use same padding as signing | + +
+ Example usage + + ```sql + -- Retrieve a signed message and its signature + SELECT message, signature INTO @message, @signature FROM signed_messages LIMIT 1; + + -- Generate the message digest + SET @digest = create_digest('SHA256', @message); + + -- Verify the signature (1 = valid, 0 = invalid) + SET @is_valid = asymmetric_verify('RSA', @digest, @signature, @public_key, 'SHA256', 'pkcs1_pss'); + + -- Check the result + SELECT IF(@is_valid = 1, 'Signature is valid', 'Signature is forged or corrupted') AS verification_result; + ``` +
+ +--- +## Create_asymmetric_priv_key(*algorithm, key_len*){create_asymmetric_priv_key} + +> 🔑 **Private key generation function** +> +> This function generates a cryptographic private key using the specified algorithm and security parameters. The private key serves as the foundation for asymmet + +| Mistake | Consequence | Better Approach | +|---------|-------------|-----------------| +| Too small key | Vulnerable to attacks | Use at least 2048 bits for RSA | +| Too large key | Extremely slow operations | Balance security with performance | +| Unsecured storage | Key theft | Store keys in secure, restricted locations | +| No backup | Permanent data loss | Backup keys with proper security | -* priv_key_str - must be a valid key string in the PEM format. +### Taking too long? -## create_dh_parameters(*key_len*) +Some keys (especially strong ones) take a while to create. If you're getting impatient: -Creates parameters for generating a Diffie-Hellman (DH) private/public key pair. -If needed, execute `KILL [QUERY|CONNECTION] ` to terminate the generation of long-lasting parameters. +```sql +KILL QUERY ; +-- or +KILL CONNECTION ; +``` -Generating the DH parameters can take more time than generating the RSA keys or -the DSA keys. -OpenSSL defines the parameter length limits. To change the -maximum parameter length, use encryption_udf.dh_bits_threshold. +This works for RSA and DSA keys. DH keys are quick, so no worries there. -### create_dh_parameters output +
+ Example usage + + ```sql + -- Create a 3072-bit RSA private key + SET @private_key = create_asymmetric_priv_key('RSA', 3072); + + -- Create a 2048-bit DSA private key + SET @dsa_key = create_asymmetric_priv_key('DSA', 2048); + + -- Create DH parameters and then a DH key + SET @dh_params = create_dh_parameters(2048); + SET @dh_key = create_asymmetric_priv_key('DH', 2048, @dh_params); + + -- Save your key for future use + INSERT INTO secure_keys (key_id, key_content) VALUES ('my_primary_key', @private_key); + ``` +
-A string in the PEM format can be passed to create_asymmetric_private_key. +--- -### create_dh_parameters parameters +## Create_asymmetric_pub_key(*algorithm, priv_key_str*){create_asymmetric_pub_key} -The parameters are the following: +> 🔓 **Public key extraction function** +> +> This function extracts a public key from your private key. Think of it as creating a deposit-only ATM card - people can put money in, but they can't take any out. + +### Quick reference + +| Parameter | Required | Description | +|-----------|----------|-------------| +| algorithm | Yes | Key algorithm ('RSA', 'DSA', or 'DH') | +| priv_key_str | Yes | Your private key in PEM format | + +### What you get back + +A public key in PEM format - another block of garbled text you can freely share. + +### What you need to extract your public key + +1. **algorithm** - What kind of key are we working with? + * Must match the private key type: 'RSA', 'DSA', or 'DH' + * Get this wrong and you'll get errors -* key_len - the range for the key length is from 1024 to 10,000. The default value is 10,000. +2. **priv_key_str** - Your secret private key + * Must be in PEM -## create_digest(*digest_type, str*) +## Create_dh_parameters(*key_len*){create_dh_parameters} + +This function creates the special math values for Diffie-Hellman keys. It's like creating a recipe that two people will follow to create identical secret sauces without ever sharing their individual ingredients. + +### Warning: Patience required! +This can take a LONG time - much longer than making regular keys. Cancel with: +``` +KILL [QUERY|CONNECTION] +``` + +Think of it like the difference between: +* Making regular keys = making a sandwich +* Creating DH parameters = baking bread from scratch + +### What you get back +A block of special values in PEM format. You'll use these later when creating DH keys. + +### What you need to create parameters + +**key_len** - How mathematically strong should these be? +* Choose between 1,024 and 10,000 bits +* Default is 10,000 (strongest but slowest) +* Admins can adjust the maximum with encryption_udf.dh_bits_threshold +## Create_digest(*digest_type, str*){create_digest} Creates a digest from the given string using the given digest type. The digest string can be used with asymmetric_sign and asymmetric_verify. -### create_digest output +### Create_digest output The digest of the given string as a binary string -### create_digest parameters +### Create_digest parameters The parameters are the following: @@ -371,10 +664,12 @@ The variable sets the threshold limits for the create_asymmetric_priv_key user-d The range for this variable is from 1,024 to 9,984. The default value is 9,984. -### encryption_udf.legacy_paddding_scheme +### Encryption_udf.legacy_padding_scheme The variable enables or disables the legacy padding scheme for certain encryption operations. +895| + | Option | Description | |--------------|------------------| | command-line | Yes | @@ -386,60 +681,86 @@ 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: +### Understanding padding schemes - • asymmetric_encrypt() and asymmetric_decrypt() use OAEP encryption padding. +Think of padding like packing a box: +* `oaep` is like using a big box with lots of bubble wrap +* `no` padding is like using an exact-size box with no padding +* `pkcs1` is like using a box with just a thin layer of protection - • asymmetric_sign() and asymmetric_verify() use PKCS1_PSS signature padding. +When `encryption_udf.legacy_padding_scheme` is OFF (default): -• When encryption_udf.legacy_padding_scheme is ON: +* For locking data: Functions use `oaep` padding (the big box with lots of bubble wrap) +* For signing data: Functions use `pkcs1_pss` padding (the fancy signature style) - • asymmetric_encrypt() and asymmetric_decrypt() use PKCS1 encryption padding. +When `encryption_udf.legacy_padding_scheme` is ON: - • asymmetric_sign() and asymmetric_verify() use PKCS1 signature padding. +* For locking data: Functions use `pkcs1` padding (the box with thin protection) +* For signing data: Functions use `pkcs1` padding (the basic signature style) -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`](#encryption_udf.legacy_padding_scheme) value. +You can also pick a padding style yourself in the `asymmetric_encrypt()` and `asymmetric_decrypt()` functions with RSA encryption. Just add `'no'`, `'pkcs1'`, or `'oaep'` as the last parameter. If you don't pick one, the system uses whatever `encryption_udf.legacy_padding_scheme` is set to. -The padding schemes have the following limitations: +### Size limits for each padding style -| Padding Scheme | Details | -|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `oaep` | 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.| +| Padding Box | How much can fit inside | +|-------------|-------------------------| +| `oaep` | Your key size minus 42 bytes (less room, but most secure) | +| `no` | Must be EXACTLY your key size (like a perfect-fit box) | +| `pkcs1` | Your key size minus 11 bytes (more room than oaep) | -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. +#### Example: How much fits in a pkcs1 box -#### Additional resources +Let's say you have a 1024-bit RSA key: - 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/) +1. First, convert bits to bytes: + * 1024 bits ÷ 8 = 128 bytes -### encryption_udf.rsa_bits_threshold +2. Then, subtract the padding space: + * 128 bytes - 11 bytes = 117 bytes -The variable sets the threshold limits for the create_asymmetric_priv_key user-defined function when invoked with the RSA parameter and takes precedence over the OpenSSL maximum length value. +3. Result: Your message must be 117 bytes or less -| Option | Description | -|--------------|------------------| -| command-line | Yes | -| scope | Global | -| data type | unsigned integer | -| default | 16384 | +If your message is bigger than what fits, you'll need: +* A bigger key size, or +* A different padding style + +### Padding for signatures + +When you sign data with `asymmetric_sign()` or verify with `asymmetric_verify()`, you can choose a padding style too: +* `pkcs1` - the basic style +* `pkcs1_pss` - the extra-secure style + +If you don't pick one, the system checks the `encryption_udf.legacy_padding_scheme` setting. You can only use padding with RSA algorithms. + +#### Want to learn more? -The range for this variable is from 1,024 to 16,384. The default value is 16,384. +Check out this article: [`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/) -### Examples +### Encryption_udf.rsa_bits_threshold -Code examples for the following operations: +This setting controls how strong RSA keys can be when you create them with the create_asymmetric_priv_key function. Think of it as setting a limit on how big of a padlock you can make. -* Set the threshold variables +| Option | What it means | +|--------------|-------------------| +| command-line | You can set it when starting MySQL | +| scope | Affects the whole server | +| data type | A number without decimals | +| default | 16384 (strongest possible) | -* Create a private key +You can choose any number between 1,024 (good) and 16,384 (extremely strong). The default is set to the maximum of 16,384. -* Create a public key +## Examples you can try -* Encrypt data +Here are some simple examples to help you get started: -* Decrypt data +### Example 1: Setting limits and working with keys + +This example shows how to: +* Set how strong keys can be +* Create your private key (your secret key) +* Create your public key (the key you can share) +* Lock (encrypt) some text +* Unlock (decrypt) it again ```{.bash data-prompt="mysql>"} -- Set Global variable @@ -464,13 +785,12 @@ mysql> SET @ciphertext = asymmetric_encrypt('RSA', 'This text is secret', @priva mysql> SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @public_key); ``` -Code examples for the following operations: - -* generate a digest string +### Example 2: Creating digital signatures -* generate a digest signature - -* verify the signature against the digest +This example shows how to: +* Create a fingerprint (digest) of your message +* Sign that fingerprint with your private key +* Check if the signature is real ```{.bash data-prompt="mysql>"} -- Generate a digest string @@ -484,15 +804,16 @@ mysql> SET @signature = asymmetric_sign('RSA', @digest, @private_key, 'SHA256'); mysql> SET @verify_signature = asymmetric_verify('RSA', @digest, @signature, @public_key, 'SHA256'); ``` -Code examples for the following operations: - -* Generate a DH parameter +### Example 3: Creating a shared secret -* Generate two DH key pairs +This example shows how two people can create the same secret key without ever sharing their private keys: -* Generate a symmetric key using the public_1 and the private_2 +* Create the recipe (DH parameter) for making the shared secret +* Make two sets of keys (one for each person) +* Person 1 creates the shared secret using their private key and Person 2's public key +* Person 2 creates the SAME shared secret using their private key and Person 1's public key -* Generate a symmetric key using the public_2 and the private_1 +This is like two people who each have half of a recipe - when combined, they both end up with the same final dish! ```{.bash data-prompt="mysql>"} -- Generate a DH parameter @@ -513,13 +834,12 @@ mysql> SET symmetric_1 = asymmetric_derive(@public_1, @private_2); mysql> SET symmetric_2 = asymmetric_derive(@public_2, @private_1); ``` -Code examples for the following operations: +### Example 4: Different ways to create keys -* Create a private key using a `SET` statement - -* Create a private key using a `SELECT` statement - -* Create a private key using an `INSERT` statement +Here are three different ways to create and save your keys: +* Using a simple variable with `SET` +* Using a query with `SELECT INTO` +* Saving directly to a table with `INSERT` ```{.bash data-prompt="mysql>"} mysql> SET @private_key1 = create_asymmetric_priv_key('RSA', 3072); @@ -527,10 +847,14 @@ mysql> SELECT create_asymmetric_priv_key('RSA', 3072) INTO @private_key2; mysql> INSERT INTO key_table VALUES(create_asymmetric_priv_key('RSA', 3072)); ``` -## Uninstall component_encryption_udf +## Removing the encryption toolbox -You can deactivate and uninstall the component using the [Uninstall Component statement](https://dev.mysql.com/doc/refman/8.0/en/uninstall-component.html). +When you're done using these tools, you can remove them from your system. Think of it like uninstalling an app when you no longer need it. + +Use this simple command: ```{.bash data-prompt="mysql>"} mysql> UNINSTALL COMPONENT 'file://component_encryption_udf'; ``` + +This removes all the encryption functions from your MySQL server. diff --git a/docs/glossary.md b/docs/glossary.md index 31766a0b9e4..0c7c79ba994 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -4,6 +4,10 @@ Set of properties that guarantee database transactions are processed reliably. Stands for [Atomicity](#atomicity), [Consistency](#consistency), [Isolation](#isolation), [Durability](#durability). +## Asymmetric key + +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. + ## Atomicity 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 Consistency means that each transaction that modifies the database takes it from one consistent state to another. +## Digest + +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. + +## Digest string +The string representation of a digest, often in hexadecimal format. + +## Digital signature + +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. + +## Diffie-Hellman key exchange + +A cryptographic protocol that allows two parties to establish a shared secret key over an insecure communication channel without actually exchanging the key. + ## Durability 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 A finalized version of the product which is made available to the general public. It is the final stage in the software release cycle. +## Hash function + +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. + ## Isolation The Isolation requirement means that no transaction can interfere with another. @@ -86,10 +109,22 @@ Non-Uniform Memory Access ([NUMA](https://en.wikipedia.org/wiki/Non-Uniform_Memo The Percona branch of [MySQL](#mysql) with performance and management improvements. +## Private key + +A secret key used in asymmetric cryptography for decrypting or signing data. It is typically kept secure and not shared with others. + +## Public key + +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. + ## Storage Engine 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). +## Symmetric key + +A single key used for both encrypting and decrypting data in symmetric cryptography. Symmetric keys are typically kept secret and shared between parties. + ## Tech Preview 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. diff --git a/docs/key-length-considerations.md b/docs/key-length-considerations.md new file mode 100644 index 00000000000..9ad6b6dcb18 --- /dev/null +++ b/docs/key-length-considerations.md @@ -0,0 +1,41 @@ +# Key length considerations + +Selecting appropriate cryptographic key lengths requires balancing security requirements with computational overhead. The following considerations should guide implementation decisions: + +* Key length security characteristics: + + * Security strength increases exponentially with bit length - a 2048-bit RSA key provides significantly higher security than a 1024-bit key + + * Computational requirements increase proportionally with key length, affecting system performance + + * Security margin increases logarithmically - doubling key length provides exponentially more possible combinations + + * Common implementation error: Implementing maximum key lengths for all applications without considering performance implications + +* Two types of cryptographic relationships: + + * Symmetric: Same key locks and unlocks (AES, etc.) + + * Like having one key that works on both sides of your door + + * Blazingly fast compared to asymmetric encryption + + * The problem: How do you securely share that key with other parties without exposing it during transmission + + * Asymmetric: Different keys for locking and unlocking (RSA, DSA, etc.) + + * Like a safety deposit box where you have one key and the bank has another + + * Significantly slower (think 1000x or more) than symmetric encryption + + * But solves the key distribution problem brilliantly + + * This is what we're focusing on in this document + +* Size limits that will bite you: + + * RSA can only encrypt messages smaller than your key size (minus padding) + + * A 2048-bit key can't encrypt a 2048-bit message - more on this particular trap later + + * If you try to encrypt something too large, you'll get an error that explains absolutely nothing. \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index ae51f626b95..2ed1dcb0f32 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -319,7 +319,11 @@ nav: - install-data-masking-plugin.md - data-masking-plugin-functions.md - fido-authentication-plugin.md - - encryption-functions.md + - Encryption functions: + - encryption-functions-overview.md + - digest-encryption.md + - key-length-considerations.md + - encryption-functions.md - pam-plugin.md - ssl-improvement.md - secure-log-path-variable.md