MySQL 9.0.0
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
 
bool encrypt_log_block (byte *src_ptr, byte *dst_ptr) const noexcept
 Encrypt the redo log block (OS_FILE_LOG_BLOCK_SIZE bytes). More...
 
bool encrypt_log (byte *src, size_t src_len, byte *dst) const noexcept
 Encrypt the redo log data blocks. More...
 
byteencrypt (const IORequest &type, byte *src, ulint src_len, byte *dst, ulint *dst_len) const noexcept
 Encrypt the page data contents. More...
 
dberr_t decrypt_log_block (byte *buf) const noexcept
 Decrypt the log block (OS_FILE_LOG_BLOCK_SIZE bytes) in place. More...
 
dberr_t decrypt_log (byte *buf, size_t buf_len) const noexcept
 Decrypt the redo log data blocks in place. More...
 
dberr_t decrypt (const IORequest &type, byte *src, ulint src_len, byte *tmp, ulint tmp_len) const noexcept
 Decrypt the page data contents in place. 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...
 
void set (const struct Encryption_metadata &metadata) noexcept
 Uses metadata to configure this instance. 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) const 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 tmp,
ulint  tmp_len 
) const
noexcept

Decrypt the page data contents in place.

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]tmpscratch area to use for decrypt
[in]tmp_lensize of the scratch area in bytes
Returns
DB_SUCCESS or error code

◆ decrypt_log()

dberr_t Encryption::decrypt_log ( byte buf,
size_t  buf_len 
) const
noexcept

Decrypt the redo log data blocks in place.

Parameters
[in,out]bufpointer to the first block to decrypt in place
[in]buf_lenlenght of the buffer in bytes, must be a multiple of OS_FILE_LOG_BLOCK_SIZE
Returns
DB_SUCCESS or error code

◆ decrypt_log_block()

dberr_t Encryption::decrypt_log_block ( byte buf) const
noexcept

Decrypt the log block (OS_FILE_LOG_BLOCK_SIZE bytes) in place.

Parameters
[in,out]bufa buffer which contains a single redo log block to be decrypted in place
Returns
DB_SUCCESS or error code

◆ encrypt()

byte * Encryption::encrypt ( const IORequest type,
byte src,
ulint  src_len,
byte dst,
ulint dst_len 
) const
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 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()

bool Encryption::encrypt_log ( byte src,
size_t  src_len,
byte dst 
) const
noexcept

Encrypt the redo log data blocks.

On success the buffer provided by caller as dst will contain src_len bytes of encrypted redo log.

Parameters
[in,out]srcpointer to the first block to encrypt
[in]src_lensize of the source in bytes, must be a multiple of OS_FILE_LOG_BLOCK_SIZE
[in,out]dstdestination area. Must be at least src_len bytes long. Must not overlap with src.
Returns
true on success

◆ encrypt_log_block()

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

Encrypt the redo log block (OS_FILE_LOG_BLOCK_SIZE bytes).

Parameters
[in,out]src_ptrredo log block to encrypt
[in,out]dst_ptrdestination area, must not overlap with src_ptr
Returns
true if success.

◆ encrypt_low()

bool Encryption::encrypt_low ( byte src,
ulint  src_len,
byte dst,
ulint dst_len 
) const
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 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 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 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()

void Encryption::set ( const struct Encryption_metadata metadata)
noexcept

Uses metadata to configure this instance.

Caller must ensure that the metadata is not freed before this instance, because iv and key will reference those inside metadata object. The key_len and type are copied by value.

◆ 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:123
static constexpr size_t KEY_LEN
Encryption key length.
Definition: os0enc.h:117
static constexpr size_t SERVER_UUID_LEN
UUID of server instance, it's needed for composing master key name.
Definition: os0enc.h:132
uint32_t uint32
Definition: my_inttypes.h:67

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: