MySQL 8.0.31
Source Code Documentation
Encryption Class Reference

Encryption algorithm. More...

#include <os0enc.h>

Public Types

enum  Type { NONE = 0 , AES = 1 }
 Algorithm types supported. More...
 
enum  Version { VERSION_1 = 0 , VERSION_2 = 1 , VERSION_3 = 2 }
 Encryption information format version. More...
 
enum class  Progress { ENCRYPTION , DECRYPTION , NONE }
 Encryption progress type. More...
 
enum class  Resume_point { INIT , PROCESS , END , DONE }
 Encryption operation resume point after server restart. More...
 

Public Member Functions

 Encryption () noexcept
 Default constructor. More...
 
 Encryption (Type type) noexcept
 Specific constructor. More...
 
 Encryption (const Encryption &other) noexcept=default
 Copy constructor. More...
 
Encryptionoperator= (const Encryption &)=default
 
dberr_t set_algorithm (const char *option, Encryption *type) noexcept
 Check the encryption option and set it. More...
 
bool encrypt_log_block (const IORequest &type, byte *src_ptr, byte *dst_ptr) noexcept
 Encrypt the redo log block. More...
 
byteencrypt_log (const IORequest &type, byte *src, ulint src_len, byte *dst, ulint *dst_len) noexcept
 Encrypt the redo log data contents. More...
 
byteencrypt (const IORequest &type, byte *src, ulint src_len, byte *dst, ulint *dst_len) noexcept
 Encrypt the page data contents. More...
 
dberr_t decrypt_log_block (const IORequest &type, byte *src, byte *dst) noexcept
 Decrypt the log block. More...
 
dberr_t decrypt_log (const IORequest &type, byte *src, ulint src_len, byte *dst) noexcept
 Decrypt the log data contents. More...
 
dberr_t decrypt (const IORequest &type, byte *src, ulint src_len, byte *dst, ulint dst_len) noexcept
 Decrypt the page data contents. More...
 
Type get_type () const
 Get encryption type. More...
 
bool is_none () const noexcept
 Check if the encryption algorithm is NONE. More...
 
void set_type (Type type)
 Set encryption type. More...
 
void set_key (const byte *key)
 Set encryption key. More...
 
ulint get_key_length () const
 Get key length. More...
 
void set_key_length (ulint klen)
 Set key length. More...
 
void set_initial_vector (const byte *iv)
 Set initial vector. More...
 

Static Public Member Functions

static bool is_encrypted_page (const byte *page) noexcept
 Check if page is encrypted page or not. More...
 
static bool is_encrypted_log (const byte *block) noexcept
 Check if a log block is encrypted or not. More...
 
static dberr_t validate (const char *option) noexcept
 Validate the algorithm string. More...
 
static const char * to_string (Type type) noexcept
 Convert to a "string". More...
 
static bool is_none (const char *algorithm) noexcept
 Check if the string is "empty" or "none". More...
 
static void random_value (byte *value) noexcept
 Generate random encryption value for key and iv. More...
 
static void set_or_generate (Type type, byte *key, byte *iv, Encryption_metadata &metadata)
 Copy the given encryption metadata to the given Encryption_metadata object, if both key != nullptr and iv != nullptr. More...
 
static void create_master_key (byte **master_key) noexcept
 Create new master key for key rotation. More...
 
static void get_master_key (uint32_t master_key_id, char *srv_uuid, byte **master_key) noexcept
 Get master key by key id. More...
 
static void get_master_key (uint32_t *master_key_id, byte **master_key) noexcept
 Get current master key and key id. More...
 
static bool fill_encryption_info (const Encryption_metadata &encryption_metadata, bool encrypt_key, byte *encrypt_info) noexcept
 Fill the encryption information. More...
 
static const byteget_master_key_from_info (const byte *encrypt_info, Version version, uint32_t *m_key_id, char *srv_uuid, byte **master_key) noexcept
 Get master key from encryption information. More...
 
static bool is_encrypted_with_version (const byte *encryption_info, const char *version_magic_bytes) noexcept
 Checks if encryption info bytes represent data encrypted by the given version of the encryption mechanism. More...
 
static bool is_encrypted_with_v3 (const byte *encryption_info) noexcept
 Checks if encryption info bytes represent data encrypted by version V3 of the encryption mechanism. More...
 
static bool is_encrypted (const byte *encryption_info) noexcept
 Checks if encryption info bytes represent data encrypted by any of known versions of the encryption mechanism. More...
 
static bool decode_encryption_info (Encryption_metadata &encryption_metadata, const byte *encryption_info, bool decrypt_key) noexcept
 Decoding the encryption info from the given array of bytes, which are assumed not to be related to any particular tablespace. More...
 
static bool decode_encryption_info (space_id_t space_id, Encryption_key &e_key, const byte *encryption_info, bool decrypt_key) noexcept
 Decoding the encryption info from the given array of bytes, which are assumed to be related to a given tablespace (unless space_id == dict_sys_t::s_invalid_space_id). More...
 
static bool check_keyring () noexcept
 Check if keyring plugin loaded. More...
 
static uint32_t get_master_key_id ()
 Get master key id. More...
 

Static Public Attributes

static constexpr char KEY_MAGIC_V1 [] = "lCA"
 Encryption magic bytes for 5.7.11, it's for checking the encryption information version. More...
 
static constexpr char KEY_MAGIC_V2 [] = "lCB"
 Encryption magic bytes for 5.7.12+, it's for checking the encryption information version. More...
 
static constexpr char KEY_MAGIC_V3 [] = "lCC"
 Encryption magic bytes for 8.0.5+, it's for checking the encryption information version. More...
 
static constexpr char MASTER_KEY_PREFIX [] = "INNODBKey"
 Encryption master key prifix. More...
 
static constexpr size_t KEY_LEN = 32
 Encryption key length. More...
 
static constexpr char DEFAULT_MASTER_KEY [] = "DefaultMasterKey"
 Default master key for bootstrap. More...
 
static constexpr size_t MAGIC_SIZE = 3
 Encryption magic bytes size. More...
 
static constexpr size_t MASTER_KEY_PRIFIX_LEN = 9
 Encryption master key prifix size. More...
 
static constexpr size_t MASTER_KEY_NAME_MAX_LEN = 100
 Encryption master key prifix size. More...
 
static constexpr size_t SERVER_UUID_LEN = 36
 UUID of server instance, it's needed for composing master key name. More...
 
static constexpr size_t INFO_SIZE
 Encryption information total size: magic number + master_key_id + key + iv + server_uuid + checksum. More...
 
static constexpr size_t INFO_MAX_SIZE = INFO_SIZE + sizeof(uint32)
 Maximum size of Encryption information considering all formats v1, v2 & v3. More...
 
static constexpr uint32_t DEFAULT_MASTER_KEY_ID = 0
 Default master key id for bootstrap. More...
 
static constexpr size_t OPERATION_INFO_SIZE = 1
 (De)Encryption Operation information size More...
 
static constexpr size_t PROGRESS_INFO_SIZE = sizeof(uint)
 Encryption Progress information size. More...
 
static constexpr size_t ENCRYPT_IN_PROGRESS = 1 << 0
 Flag bit to indicate if Encryption/Decryption is in progress. More...
 
static constexpr size_t DECRYPT_IN_PROGRESS = 1 << 1
 Decryption in progress. More...
 
static std::vector< space_id_ts_tablespaces_to_reencrypt
 Tablespaces whose key needs to be reencrypted. More...
 

Private Member Functions

bool encrypt_low (byte *src, ulint src_len, byte *dst, ulint *dst_len) noexcept
 Encrypt the page data contents. More...
 

Private Attributes

Type m_type
 Encrypt type. More...
 
const bytem_key
 Encrypt key. More...
 
ulint m_klen
 Encrypt key length. More...
 
const bytem_iv
 Encrypt initial vector. More...
 

Static Private Attributes

static uint32_t s_master_key_id = Encryption::DEFAULT_MASTER_KEY_ID
 Current master key id. More...
 
static char s_uuid [SERVER_UUID_LEN+1] = {0}
 Current uuid of server instance. More...
 

Detailed Description

Encryption algorithm.

Member Enumeration Documentation

◆ Progress

enum class Encryption::Progress
strong

Encryption progress type.

Enumerator
ENCRYPTION 
DECRYPTION 
NONE 

◆ Resume_point

enum class Encryption::Resume_point
strong

Encryption operation resume point after server restart.

Enumerator
INIT 
PROCESS 
END 
DONE 

◆ Type

Algorithm types supported.

Enumerator
NONE 

No encryption.

AES 

Use AES.

◆ Version

Encryption information format version.

Enumerator
VERSION_1 

Version in 5.7.11.

VERSION_2 

Version in > 5.7.11.

VERSION_3 

Version in > 8.0.4.

Constructor & Destructor Documentation

◆ Encryption() [1/3]

Encryption::Encryption ( )
inlinenoexcept

Default constructor.

◆ Encryption() [2/3]

Encryption::Encryption ( Type  type)
inlineexplicitnoexcept

Specific constructor.

Parameters
[in]typeAlgorithm type

◆ Encryption() [3/3]

Encryption::Encryption ( const Encryption other)
defaultnoexcept

Copy constructor.

Member Function Documentation

◆ check_keyring()

bool Encryption::check_keyring ( )
staticnoexcept

Check if keyring plugin loaded.

◆ create_master_key()

void Encryption::create_master_key ( byte **  master_key)
staticnoexcept

Create new master key for key rotation.

Parameters
[in,out]master_keymaster key

◆ decode_encryption_info() [1/2]

bool Encryption::decode_encryption_info ( Encryption_metadata encryption_metadata,
const byte encryption_info,
bool  decrypt_key 
)
staticnoexcept

Decoding the encryption info from the given array of bytes, which are assumed not to be related to any particular tablespace.

Parameters
[out]encryption_metadatadecoded encryption metadata
[in]encryption_infoencryption info to decode
[in]decrypt_keydecrypt key using master key
Returns
true if success

◆ decode_encryption_info() [2/2]

bool Encryption::decode_encryption_info ( space_id_t  space_id,
Encryption_key e_key,
const byte encryption_info,
bool  decrypt_key 
)
staticnoexcept

Decoding the encryption info from the given array of bytes, which are assumed to be related to a given tablespace (unless space_id == dict_sys_t::s_invalid_space_id).

The given tablespace is noted down in s_tablespaces_to_reencrypt if the encryption info became successfully decrypted using the master key and the space_id is not dict_sys_t::s_invalid_space_id. For such tablespaces the encryption info is later re-encrypted using the rotated master key in innobase_dict_recover().

Parameters
[in]space_idTablespace id
[in,out]e_keykey, iv
[in]encryption_infoencryption info to decode
[in]decrypt_keydecrypt key using master key
Returns
true if success

◆ decrypt()

dberr_t Encryption::decrypt ( const IORequest type,
byte src,
ulint  src_len,
byte dst,
ulint  dst_len 
)
noexcept

Decrypt the page data contents.

Page type must be FIL_PAGE_ENCRYPTED, FIL_PAGE_COMPRESSED_AND_ENCRYPTED, FIL_PAGE_ENCRYPTED_RTREE, if not then the source contents are left unchanged and DB_SUCCESS is returned.

Parameters
[in]typeIORequest
[in,out]srcdata read from disk, decrypt data will be copied to this page
[in]src_lensource data length
[in,out]dstscratch area to use for decrypt
[in]dst_lensize of the scratch area in bytes
Returns
DB_SUCCESS or error code

◆ decrypt_log()

dberr_t Encryption::decrypt_log ( const IORequest type,
byte src,
ulint  src_len,
byte dst 
)
noexcept

Decrypt the log data contents.

Parameters
[in]typeIORequest
[in,out]srcdata read from disk, decrypted data will be copied to this page
[in]src_lensource data length
[in,out]dstscratch area to use for decryption
Returns
DB_SUCCESS or error code

◆ decrypt_log_block()

dberr_t Encryption::decrypt_log_block ( const IORequest type,
byte src,
byte dst 
)
noexcept

Decrypt the log block.

Parameters
[in]typeIORequest
[in,out]srcdata read from disk, decrypted data will be copied to this page
[in,out]dstscratch area to use for decryption
Returns
DB_SUCCESS or error code

◆ encrypt()

byte * Encryption::encrypt ( const IORequest type,
byte src,
ulint  src_len,
byte dst,
ulint dst_len 
)
noexcept

Encrypt the page data contents.

Page type can't be FIL_PAGE_ENCRYPTED, FIL_PAGE_COMPRESSED_AND_ENCRYPTED, FIL_PAGE_ENCRYPTED_RTREE.

Parameters
[in]typeIORequest
[in,out]srcpage data which need to encrypt
[in]src_lensize of the source in bytes
[in,out]dstdestination area
[in,out]dst_lensize of the destination in bytes
Returns
buffer data, dst_len will have the length of the data

◆ encrypt_log()

byte * Encryption::encrypt_log ( const IORequest type,
byte src,
ulint  src_len,
byte dst,
ulint dst_len 
)
noexcept

Encrypt the redo log data contents.

Parameters
[in]typeIORequest
[in,out]srcpage data which need to encrypt
[in]src_lensize of the source in bytes
[in,out]dstdestination area
[in,out]dst_lensize of the destination in bytes
Returns
buffer data, dst_len will have the length of the data

◆ encrypt_log_block()

bool Encryption::encrypt_log_block ( const IORequest type,
byte src_ptr,
byte dst_ptr 
)
noexcept

Encrypt the redo log block.

Parameters
[in]typeIORequest
[in,out]src_ptrlog block which need to encrypt
[in,out]dst_ptrdestination area
Returns
true if success.

◆ encrypt_low()

bool Encryption::encrypt_low ( byte src,
ulint  src_len,
byte dst,
ulint dst_len 
)
privatenoexcept

Encrypt the page data contents.

Page type can't be FIL_PAGE_ENCRYPTED, FIL_PAGE_COMPRESSED_AND_ENCRYPTED, FIL_PAGE_ENCRYPTED_RTREE.

Parameters
[in]srcpage data which need to encrypt
[in]src_lensize of the source in bytes
[in,out]dstdestination area
[in,out]dst_lensize of the destination in bytes
Returns
true if operation successful, false otherwise.

◆ fill_encryption_info()

bool Encryption::fill_encryption_info ( const Encryption_metadata encryption_metadata,
bool  encrypt_key,
byte encrypt_info 
)
staticnoexcept

Fill the encryption information.

Parameters
[in]encryption_metadataencryption metadata (key,iv)
[in]encrypt_keyencrypt with master key
[out]encrypt_infoencryption information
Returns
true if success.

◆ get_key_length()

ulint Encryption::get_key_length ( ) const

Get key length.

Returns
key length

◆ get_master_key() [1/2]

void Encryption::get_master_key ( uint32_t *  master_key_id,
byte **  master_key 
)
staticnoexcept

Get current master key and key id.

Parameters
[in,out]master_key_idmaster key id
[in,out]master_keymaster key

◆ get_master_key() [2/2]

void Encryption::get_master_key ( uint32_t  master_key_id,
char *  srv_uuid,
byte **  master_key 
)
staticnoexcept

Get master key by key id.

Parameters
[in]master_key_idmaster key id
[in]srv_uuiduuid of server instance
[in,out]master_keymaster key

◆ get_master_key_from_info()

const byte * Encryption::get_master_key_from_info ( const byte encrypt_info,
Version  version,
uint32_t *  m_key_id,
char *  srv_uuid,
byte **  master_key 
)
staticnoexcept

Get master key from encryption information.

Parameters
[in]encrypt_infoencryption information
[in]versionversion of encryption information
[in,out]m_key_idmaster key id
[in,out]srv_uuidserver uuid
[in,out]master_keymaster key
Returns
position after master key id or uuid, or the old position if can't get the master key.

◆ get_master_key_id()

uint32_t Encryption::get_master_key_id ( )
static

Get master key id.

Returns
master key id

◆ get_type()

Encryption::Type Encryption::get_type ( ) const

Get encryption type.

Returns
encryption type

◆ is_encrypted()

bool Encryption::is_encrypted ( const byte encryption_info)
staticnoexcept

Checks if encryption info bytes represent data encrypted by any of known versions of the encryption mechanism.

Note, that if the encryption_info is read from file created by a newer MySQL version, it could be considered to be unknown for this MySQL version, and this function would return false.

Parameters
[in]encryption_infoencryption info bytes
Returns
result of the check

◆ is_encrypted_log()

bool Encryption::is_encrypted_log ( const byte block)
staticnoexcept

Check if a log block is encrypted or not.

Parameters
[in]blockblock which need to check
Returns
true if it is an encrypted block

◆ is_encrypted_page()

bool Encryption::is_encrypted_page ( const byte page)
staticnoexcept

Check if page is encrypted page or not.

Parameters
[in]pagepage which need to check
Returns
true if it is an encrypted page

◆ is_encrypted_with_v3()

bool Encryption::is_encrypted_with_v3 ( const byte encryption_info)
staticnoexcept

Checks if encryption info bytes represent data encrypted by version V3 of the encryption mechanism.

Parameters
[in]encryption_infoencryption info bytes
Returns
result of the check

◆ is_encrypted_with_version()

bool Encryption::is_encrypted_with_version ( const byte encryption_info,
const char *  version_magic_bytes 
)
staticnoexcept

Checks if encryption info bytes represent data encrypted by the given version of the encryption mechanism.

Parameters
[in]encryption_infoencryption info bytes
[in]version_magic_bytesmagic bytes which represent version of the encryption mechanism, for example: Encryption::KEY_MAGIC_V3
Returns
result of the check

◆ is_none() [1/2]

bool Encryption::is_none ( ) const
inlinenoexcept

Check if the encryption algorithm is NONE.

Returns
true if no algorithm is set, false otherwise.

◆ is_none() [2/2]

bool Encryption::is_none ( const char *  algorithm)
staticnoexcept

Check if the string is "empty" or "none".

Parameters
[in]algorithmEncryption algorithm to check
Returns
true if no algorithm requested

◆ operator=()

Encryption & Encryption::operator= ( const Encryption )
default

◆ random_value()

void Encryption::random_value ( byte value)
staticnoexcept

Generate random encryption value for key and iv.

Parameters
[in,out]valueEncryption value

◆ set_algorithm()

dberr_t Encryption::set_algorithm ( const char *  option,
Encryption type 
)
noexcept

Check the encryption option and set it.

Parameters
[in]optionencryption option
[in,out]typeThe encryption type
Returns
DB_SUCCESS or DB_UNSUPPORTED

◆ set_initial_vector()

void Encryption::set_initial_vector ( const byte iv)

Set initial vector.

Parameters
[in]ivinitial_vector

◆ set_key()

void Encryption::set_key ( const byte key)

Set encryption key.

Parameters
[in]keyencryption key

◆ set_key_length()

void Encryption::set_key_length ( ulint  klen)

Set key length.

Parameters
[in]klenkey length

◆ set_or_generate()

void Encryption::set_or_generate ( Type  type,
byte key,
byte iv,
Encryption_metadata metadata 
)
static

Copy the given encryption metadata to the given Encryption_metadata object, if both key != nullptr and iv != nullptr.

Generate randomly the new metadata, if both key == nullptr and iv == nullptr, and store it to the given Encryption_metadata object. Cannot be called with key, iv such that: (key == nullptr) != (iv == nullptr).

Parameters
[in]typeencryption algorithm type to store
[in]keyencryption key to copy or nullptr to generate
[in]ivencryption iv to copy or nullptr to generate
[out]metadatafilled Encryption_metadata object

◆ set_type()

void Encryption::set_type ( Encryption::Type  type)

Set encryption type.

Parameters
[in]typeencryption type

◆ to_string()

const char * Encryption::to_string ( Type  type)
staticnoexcept

Convert to a "string".

Parameters
[in]typeThe encryption type
Returns
the string representation

◆ validate()

dberr_t Encryption::validate ( const char *  option)
staticnoexcept

Validate the algorithm string.

Parameters
[in]optionEncryption option
Returns
DB_SUCCESS or error code

Member Data Documentation

◆ DECRYPT_IN_PROGRESS

constexpr size_t Encryption::DECRYPT_IN_PROGRESS = 1 << 1
staticconstexpr

Decryption in progress.

◆ DEFAULT_MASTER_KEY

constexpr char Encryption::DEFAULT_MASTER_KEY = "DefaultMasterKey"
staticconstexpr

Default master key for bootstrap.

◆ DEFAULT_MASTER_KEY_ID

constexpr uint32_t Encryption::DEFAULT_MASTER_KEY_ID = 0
staticconstexpr

Default master key id for bootstrap.

◆ ENCRYPT_IN_PROGRESS

constexpr size_t Encryption::ENCRYPT_IN_PROGRESS = 1 << 0
staticconstexpr

Flag bit to indicate if Encryption/Decryption is in progress.

◆ INFO_MAX_SIZE

constexpr size_t Encryption::INFO_MAX_SIZE = INFO_SIZE + sizeof(uint32)
staticconstexpr

Maximum size of Encryption information considering all formats v1, v2 & v3.

◆ INFO_SIZE

constexpr size_t Encryption::INFO_SIZE
staticconstexpr
Initial value:
=
(MAGIC_SIZE + sizeof(uint32) + (KEY_LEN * 2) + SERVER_UUID_LEN +
sizeof(uint32))
static constexpr size_t MAGIC_SIZE
Encryption magic bytes size.
Definition: os0enc.h:122
static constexpr size_t KEY_LEN
Encryption key length.
Definition: os0enc.h:116
static constexpr size_t SERVER_UUID_LEN
UUID of server instance, it's needed for composing master key name.
Definition: os0enc.h:131
uint32_t uint32
Definition: my_inttypes.h:66

Encryption information total size: magic number + master_key_id + key + iv + server_uuid + checksum.

◆ KEY_LEN

constexpr size_t Encryption::KEY_LEN = 32
staticconstexpr

Encryption key length.

◆ KEY_MAGIC_V1

constexpr char Encryption::KEY_MAGIC_V1 = "lCA"
staticconstexpr

Encryption magic bytes for 5.7.11, it's for checking the encryption information version.

◆ KEY_MAGIC_V2

constexpr char Encryption::KEY_MAGIC_V2 = "lCB"
staticconstexpr

Encryption magic bytes for 5.7.12+, it's for checking the encryption information version.

◆ KEY_MAGIC_V3

constexpr char Encryption::KEY_MAGIC_V3 = "lCC"
staticconstexpr

Encryption magic bytes for 8.0.5+, it's for checking the encryption information version.

◆ m_iv

const byte* Encryption::m_iv
private

Encrypt initial vector.

◆ m_key

const byte* Encryption::m_key
private

Encrypt key.

◆ m_klen

ulint Encryption::m_klen
private

Encrypt key length.

◆ m_type

Type Encryption::m_type
private

Encrypt type.

◆ MAGIC_SIZE

constexpr size_t Encryption::MAGIC_SIZE = 3
staticconstexpr

Encryption magic bytes size.

◆ MASTER_KEY_NAME_MAX_LEN

constexpr size_t Encryption::MASTER_KEY_NAME_MAX_LEN = 100
staticconstexpr

Encryption master key prifix size.

◆ MASTER_KEY_PREFIX

constexpr char Encryption::MASTER_KEY_PREFIX = "INNODBKey"
staticconstexpr

Encryption master key prifix.

◆ MASTER_KEY_PRIFIX_LEN

constexpr size_t Encryption::MASTER_KEY_PRIFIX_LEN = 9
staticconstexpr

Encryption master key prifix size.

◆ OPERATION_INFO_SIZE

constexpr size_t Encryption::OPERATION_INFO_SIZE = 1
staticconstexpr

(De)Encryption Operation information size

◆ PROGRESS_INFO_SIZE

constexpr size_t Encryption::PROGRESS_INFO_SIZE = sizeof(uint)
staticconstexpr

Encryption Progress information size.

◆ s_master_key_id

uint32_t Encryption::s_master_key_id = Encryption::DEFAULT_MASTER_KEY_ID
staticprivate

Current master key id.

◆ s_tablespaces_to_reencrypt

std::vector< space_id_t > Encryption::s_tablespaces_to_reencrypt
static

Tablespaces whose key needs to be reencrypted.

◆ s_uuid

char Encryption::s_uuid = {0}
staticprivate

Current uuid of server instance.

◆ SERVER_UUID_LEN

constexpr size_t Encryption::SERVER_UUID_LEN = 36
staticconstexpr

UUID of server instance, it's needed for composing master key name.


The documentation for this class was generated from the following files: