MySQL 8.3.0
Source Code Documentation
Rpl_encryption Class Reference

The Rpl_encryption class is the container for the binlog encryption feature generic and server instance functions. More...

#include <rpl_log_encryption.h>

Classes

struct  Rpl_encryption_key
 

Public Types

enum class  Keyring_status {
  SUCCESS = 0 , KEYRING_ERROR_FETCHING = 1 , KEY_NOT_FOUND = 2 , UNEXPECTED_KEY_SIZE = 3 ,
  UNEXPECTED_KEY_TYPE = 4 , KEY_EXISTS_UNEXPECTED = 5 , KEYRING_ERROR_GENERATING = 6 , KEYRING_ERROR_STORING = 7 ,
  KEYRING_ERROR_REMOVING = 8
}
 
enum class  Key_rotation_step {
  START , DETERMINE_NEXT_SEQNO , GENERATE_NEW_MASTER_KEY , REMOVE_MASTER_KEY_INDEX ,
  STORE_MASTER_KEY_INDEX , ROTATE_LOGS , PURGE_UNUSED_ENCRYPTION_KEYS , REMOVE_KEY_ROTATION_TAG
}
 Replication encryption master key rotation process is recoverable. More...
 

Public Member Functions

 Rpl_encryption ()=default
 
 Rpl_encryption (const Rpl_encryption &)=delete
 
 Rpl_encryption (Rpl_encryption &&)=delete
 
Rpl_encryptionoperator= (const Rpl_encryption &)=delete
 
Rpl_encryptionoperator= (Rpl_encryption &&)=delete
 
bool initialize ()
 Initialize the rpl_encryption instance. More...
 
bool remove_remaining_seqnos_from_keyring ()
 Remove remaining old/new master key index in order to cleanup any previous master key rotation. More...
 
bool recover_master_key ()
 Recover the replication encryption master key from keyring. More...
 
const Rpl_encryption_key get_master_key ()
 Return the current replication encryption master key. More...
 
bool enable (THD *thd)
 Enable binlog encryption option. More...
 
void disable (THD *thd)
 Disable binlog encryption option. More...
 
bool is_enabled ()
 Return is the replication logs encryption feature is enabled. More...
 
const bool & get_enabled_var ()
 
const bool & get_master_key_rotation_at_startup_var ()
 
bool purge_unused_keys ()
 Purge unused master keys from Keyring. More...
 
bool rotate_master_key (Key_rotation_step step=Key_rotation_step::START, uint32_t new_master_key_seqno=0)
 Rotate the master key. More...
 

Static Public Member Functions

static void report_keyring_error (Keyring_status error)
 A wrapper function to throw a binlog encryption keyring error. More...
 
static void report_keyring_error (Keyring_status error, const char *key_id)
 A wrapper function to throw a replication logs encryption keyring error, reporting also the key ID. More...
 
static std::pair< Keyring_status, Key_stringget_key (const std::string &key_id, const std::string &key_type)
 Get the key with given key ID. More...
 
static std::pair< Keyring_status, Key_stringget_key (const std::string &key_id, const std::string &key_type, size_t key_size)
 Get the key with given key ID. More...
 

Private Member Functions

void rotate_logs (THD *thd)
 Rotate replication logs excluding relay logs of group replication channels. More...
 
std::pair< Rpl_encryption::Keyring_status, uint32_t > get_seqno_from_keyring (std::string key_id)
 Get a sequence number from the keyring. More...
 
bool set_seqno_on_keyring (std::string key_id, uint32_t seqno)
 Set a sequence number into a key and store it into keyring. More...
 
bool remove_key_from_keyring (std::string key_id)
 Remove a key from the keyring. More...
 
std::string get_master_key_seqno_key_id ()
 Returns the key ID of the keyring key that stores the master key sequence number. More...
 
std::pair< Rpl_encryption::Keyring_status, uint32_t > get_master_key_seqno_from_keyring ()
 Get the master key sequence number from keyring. More...
 
bool set_master_key_seqno_on_keyring (uint32 seqno)
 Set the master key sequence number into a key and store it into keyring. More...
 
bool remove_master_key_seqno_from_keyring ()
 Remove the master key sequence number key from the keyring. More...
 
std::string get_new_master_key_seqno_key_id ()
 Returns the key ID of the keyring key that stores the "new" master key sequence number. More...
 
std::string get_last_purged_master_key_seqno_key_id ()
 Returns the key ID of the keyring key that stores the "last_purged" master key sequence number. More...
 
std::string get_old_master_key_seqno_key_id ()
 Returns the key ID of the keyring key that stores the "old" master key sequence number. More...
 
std::pair< Rpl_encryption::Keyring_status, uint32_t > get_new_master_key_seqno_from_keyring ()
 Get the "new" master key sequence number from keyring. More...
 
std::pair< Rpl_encryption::Keyring_status, uint32_t > get_old_master_key_seqno_from_keyring ()
 Get the "old" master key sequence number from keyring. More...
 
std::pair< Rpl_encryption::Keyring_status, uint32_t > get_last_purged_master_key_seqno_from_keyring ()
 Get the "last_purged" master key sequence number from keyring. More...
 
bool set_new_master_key_seqno_on_keyring (uint32 seqno)
 Set the "new" master key sequence number into a key and store it into keyring. More...
 
bool set_last_purged_master_key_seqno_on_keyring (uint32 seqno)
 Set the "last_purged" master key sequence number into a key and store it into keyring. More...
 
bool set_old_master_key_seqno_on_keyring (uint32 seqno)
 Set the "old" master key sequence number into a key and store it into keyring. More...
 
bool remove_new_master_key_seqno_from_keyring ()
 Remove the "new" master key sequence number key from the keyring. More...
 
bool remove_last_purged_master_key_seqno_from_keyring ()
 Remove the "last_purged" master key sequence number key from the keyring. More...
 
bool remove_old_master_key_seqno_from_keyring ()
 Remove the "old" master key sequence number key from the keyring. More...
 
bool generate_master_key_on_keyring (uint32 seqno)
 Generate a new replication master key on keyring and retrieve it. More...
 

Static Private Member Functions

static std::tuple< Keyring_status, void *, size_t > fetch_key_from_keyring (const std::string &key_id, const std::string &key_type)
 Fetch a key from keyring. More...
 

Private Attributes

bool m_enabled = false
 
bool m_rotate_at_startup = false
 
bool m_initialized = false
 
bool m_master_key_recovered = false
 
uint32_t m_master_key_seqno = 0
 
Rpl_encryption_key m_master_key
 
bool m_skip_logs_rotation = false
 

Static Private Attributes

static const char * SEQNO_KEY_TYPE = "AES"
 
static const int SEQNO_KEY_LENGTH = 16
 

Detailed Description

The Rpl_encryption class is the container for the binlog encryption feature generic and server instance functions.

Member Enumeration Documentation

◆ Key_rotation_step

Replication encryption master key rotation process is recoverable.

The steps defined in the enum class below are the steps from which the rotation process may continue after an unexpected interruption.

Enumerator
START 
DETERMINE_NEXT_SEQNO 
GENERATE_NEW_MASTER_KEY 
REMOVE_MASTER_KEY_INDEX 
STORE_MASTER_KEY_INDEX 
ROTATE_LOGS 
PURGE_UNUSED_ENCRYPTION_KEYS 
REMOVE_KEY_ROTATION_TAG 

◆ Keyring_status

enum class Rpl_encryption::Keyring_status
strong
Enumerator
SUCCESS 
KEYRING_ERROR_FETCHING 
KEY_NOT_FOUND 
UNEXPECTED_KEY_SIZE 
UNEXPECTED_KEY_TYPE 
KEY_EXISTS_UNEXPECTED 
KEYRING_ERROR_GENERATING 
KEYRING_ERROR_STORING 
KEYRING_ERROR_REMOVING 

Constructor & Destructor Documentation

◆ Rpl_encryption() [1/3]

Rpl_encryption::Rpl_encryption ( )
default

◆ Rpl_encryption() [2/3]

Rpl_encryption::Rpl_encryption ( const Rpl_encryption )
delete

◆ Rpl_encryption() [3/3]

Rpl_encryption::Rpl_encryption ( Rpl_encryption &&  )
delete

Member Function Documentation

◆ disable()

void Rpl_encryption::disable ( THD thd)

Disable binlog encryption option.

It rotates replication logs to make encryption ineffective immediately.

Replication logs rotation errors don't fail, but they will throw a warning.

Parameters
[in]thdthe thd object of the session.

◆ enable()

bool Rpl_encryption::enable ( THD thd)

Enable binlog encryption option.

It will generate a new global key if there is no master key yet. Then rotate replication logs to make encryption effective immediately.

Replication logs rotation errors don't fail, but they will throw a warning.

Parameters
[in]thdthe thd object of the session.
Return values
falseSuccess.
trueError. If error happens when generating new key, it will fail.

◆ fetch_key_from_keyring()

std::tuple< Rpl_encryption::Keyring_status, void *, size_t > Rpl_encryption::fetch_key_from_keyring ( const std::string &  key_id,
const std::string &  key_type 
)
staticprivate

Fetch a key from keyring.

When error happens, it either reports an error to user or write an error to log accordingly.

Parameters
[in]key_idID of the key to be returned.
[in]key_typeExpected type of the key to be returned.
Returns
A tuple containing the status of the operation (Keyring_status), a pointer to the fetched key (nullptr if the key was not fetched) and the returned key size. Errors shall be checked by consulting the status.

◆ generate_master_key_on_keyring()

bool Rpl_encryption::generate_master_key_on_keyring ( uint32  seqno)
private

Generate a new replication master key on keyring and retrieve it.

Parameters
[in]seqnoThe sequence number of the master key.
Return values
falseSuccess.
trueError.

◆ get_enabled_var()

const bool & Rpl_encryption::get_enabled_var ( )

◆ get_key() [1/2]

std::pair< Rpl_encryption::Keyring_status, Key_string > Rpl_encryption::get_key ( const std::string &  key_id,
const std::string &  key_type 
)
static

Get the key with given key ID.

The key to be returned will be retrieved from the keyring or from a cached copy in memory.

Parameters
[in]key_idID of the key to be returned.
[in]key_typeExpected type of the key to be returned.
Returns
A pair containing the status of the operation (Keyring_status) and a Key_string. Errors shall be checked by consulting the status.

◆ get_key() [2/2]

std::pair< Rpl_encryption::Keyring_status, Key_string > Rpl_encryption::get_key ( const std::string &  key_id,
const std::string &  key_type,
size_t  key_size 
)
static

Get the key with given key ID.

The key to be returned will be retrieved from the keyring or from a cached copy in memory.

Parameters
[in]key_idID of the key to be returned.
[in]key_typeExpected type of the key to be returned.
[in]key_sizeExpected size of the key to be returned.
Returns
A pair containing the status of the operation (Keyring_status) and a Key_string. Errors shall be checked by consulting the status.

◆ get_last_purged_master_key_seqno_from_keyring()

std::pair< Rpl_encryption::Keyring_status, uint32_t > Rpl_encryption::get_last_purged_master_key_seqno_from_keyring ( )
private

Get the "last_purged" master key sequence number from keyring.

Returns
A pair containing the status of the operation (Keyring_status) and a sequence number. Errors shall be checked by consulting the status.

◆ get_last_purged_master_key_seqno_key_id()

std::string Rpl_encryption::get_last_purged_master_key_seqno_key_id ( )
private

Returns the key ID of the keyring key that stores the "last_purged" master key sequence number.

Returns
The key ID.

◆ get_master_key()

const Rpl_encryption::Rpl_encryption_key Rpl_encryption::get_master_key ( )

Return the current replication encryption master key.

Returns
The current replication encryption master key.

◆ get_master_key_rotation_at_startup_var()

const bool & Rpl_encryption::get_master_key_rotation_at_startup_var ( )

◆ get_master_key_seqno_from_keyring()

std::pair< Rpl_encryption::Keyring_status, uint32_t > Rpl_encryption::get_master_key_seqno_from_keyring ( )
private

Get the master key sequence number from keyring.

Returns
A pair containing the status of the operation (Keyring_status) and a sequence number. Errors shall be checked by consulting the status.

◆ get_master_key_seqno_key_id()

std::string Rpl_encryption::get_master_key_seqno_key_id ( )
private

Returns the key ID of the keyring key that stores the master key sequence number.

Returns
The key ID.

◆ get_new_master_key_seqno_from_keyring()

std::pair< Rpl_encryption::Keyring_status, uint32_t > Rpl_encryption::get_new_master_key_seqno_from_keyring ( )
private

Get the "new" master key sequence number from keyring.

Returns
A pair containing the status of the operation (Keyring_status) and a sequence number. Errors shall be checked by consulting the status.

◆ get_new_master_key_seqno_key_id()

std::string Rpl_encryption::get_new_master_key_seqno_key_id ( )
private

Returns the key ID of the keyring key that stores the "new" master key sequence number.

Returns
The key ID.

◆ get_old_master_key_seqno_from_keyring()

std::pair< Rpl_encryption::Keyring_status, uint32_t > Rpl_encryption::get_old_master_key_seqno_from_keyring ( )
private

Get the "old" master key sequence number from keyring.

Returns
A pair containing the status of the operation (Keyring_status) and a sequence number. Errors shall be checked by consulting the status.

◆ get_old_master_key_seqno_key_id()

std::string Rpl_encryption::get_old_master_key_seqno_key_id ( )
private

Returns the key ID of the keyring key that stores the "old" master key sequence number.

Returns
The key ID.

◆ get_seqno_from_keyring()

std::pair< Rpl_encryption::Keyring_status, uint32_t > Rpl_encryption::get_seqno_from_keyring ( std::string  key_id)
private

Get a sequence number from the keyring.

The sequence number to be returned will be extracted from the key retrieved from the keyring. No caching shall be used for this function.

Parameters
[in]key_idID of the key to extract the sequence number from.
Returns
A pair containing the status of the operation (Keyring_status) and a sequence number. Errors shall be checked by consulting the status.

◆ initialize()

bool Rpl_encryption::initialize ( )

Initialize the rpl_encryption instance.

This initialization shall be called after generating/loading the server UUID and before opening new binary and relay log files for writing.

When the replication_logs_encrypt option is on at server startup, the initialization process will try to recover master key and may generate a new replication master key if needed.

Return values
falseSuccess.
trueError.

◆ is_enabled()

bool Rpl_encryption::is_enabled ( )

Return is the replication logs encryption feature is enabled.

Return values
falseThe feature is disabled.
trueThe feature is enabled.

◆ operator=() [1/2]

Rpl_encryption & Rpl_encryption::operator= ( const Rpl_encryption )
delete

◆ operator=() [2/2]

Rpl_encryption & Rpl_encryption::operator= ( Rpl_encryption &&  )
delete

◆ purge_unused_keys()

bool Rpl_encryption::purge_unused_keys ( )

Purge unused master keys from Keyring.

Return values
falseSuccess.
trueError.

◆ recover_master_key()

bool Rpl_encryption::recover_master_key ( )

Recover the replication encryption master key from keyring.

The recovery of the master key process starts by trying to read the replication master key information from keyring (the master key sequence number, and the master key itself).

Then, if detected that a key rotation did not completed properly, tries to continue the master key rotation.

When recovery is successful, the m_master_key_recovered flag is set true.

Return values
falseSuccess.
trueError.

◆ remove_key_from_keyring()

bool Rpl_encryption::remove_key_from_keyring ( std::string  key_id)
private

Remove a key from the keyring.

Parameters
[in]key_idID of the key to be removed from keyring.
Return values
falseSuccess.
trueError.

◆ remove_last_purged_master_key_seqno_from_keyring()

bool Rpl_encryption::remove_last_purged_master_key_seqno_from_keyring ( )
private

Remove the "last_purged" master key sequence number key from the keyring.

Return values
falseSuccess.
trueError.

◆ remove_master_key_seqno_from_keyring()

bool Rpl_encryption::remove_master_key_seqno_from_keyring ( )
private

Remove the master key sequence number key from the keyring.

Return values
falseSuccess.
trueError.

◆ remove_new_master_key_seqno_from_keyring()

bool Rpl_encryption::remove_new_master_key_seqno_from_keyring ( )
private

Remove the "new" master key sequence number key from the keyring.

Return values
falseSuccess.
trueError.

◆ remove_old_master_key_seqno_from_keyring()

bool Rpl_encryption::remove_old_master_key_seqno_from_keyring ( )
private

Remove the "old" master key sequence number key from the keyring.

Return values
falseSuccess.
trueError.

◆ remove_remaining_seqnos_from_keyring()

bool Rpl_encryption::remove_remaining_seqnos_from_keyring ( )

Remove remaining old/new master key index in order to cleanup any previous master key rotation.

Return values
falseSuccess.
trueError.

◆ report_keyring_error() [1/2]

void Rpl_encryption::report_keyring_error ( Keyring_status  error)
static

A wrapper function to throw a binlog encryption keyring error.

The wrapper will decide if the error will be reported to the client session or to the server error log according to current_thd.

Parameters
errorThe Keyring_status to be reported.

◆ report_keyring_error() [2/2]

void Rpl_encryption::report_keyring_error ( Keyring_status  error,
const char *  key_id 
)
static

A wrapper function to throw a replication logs encryption keyring error, reporting also the key ID.

The wrapper will decide if the error will be reported to the client session or to the server error log according to current_thd.

Parameters
errorThe Keyring_status to be reported.
key_idThe key ID to appear in the error message.

◆ rotate_logs()

void Rpl_encryption::rotate_logs ( THD thd)
private

Rotate replication logs excluding relay logs of group replication channels.

If error happens, it will either report a warning to session user.

Parameters
[in]thdThe thd object of current session.

◆ rotate_master_key()

bool Rpl_encryption::rotate_master_key ( Key_rotation_step  step = Key_rotation_step::START,
uint32_t  new_master_key_seqno = 0 
)

Rotate the master key.

Parameters
stepStep to start the process (it might be recovering).
new_master_key_seqnoWhen recovering, this is the new master key sequence number detected by recovery process.
Return values
falseSuccess.
trueError.

◆ set_last_purged_master_key_seqno_on_keyring()

bool Rpl_encryption::set_last_purged_master_key_seqno_on_keyring ( uint32  seqno)
private

Set the "last_purged" master key sequence number into a key and store it into keyring.

Return values
falseSuccess.
trueError.

◆ set_master_key_seqno_on_keyring()

bool Rpl_encryption::set_master_key_seqno_on_keyring ( uint32  seqno)
private

Set the master key sequence number into a key and store it into keyring.

Return values
falseSuccess.
trueError.

◆ set_new_master_key_seqno_on_keyring()

bool Rpl_encryption::set_new_master_key_seqno_on_keyring ( uint32  seqno)
private

Set the "new" master key sequence number into a key and store it into keyring.

Return values
falseSuccess.
trueError.

◆ set_old_master_key_seqno_on_keyring()

bool Rpl_encryption::set_old_master_key_seqno_on_keyring ( uint32  seqno)
private

Set the "old" master key sequence number into a key and store it into keyring.

Return values
falseSuccess.
trueError.

◆ set_seqno_on_keyring()

bool Rpl_encryption::set_seqno_on_keyring ( std::string  key_id,
uint32_t  seqno 
)
private

Set a sequence number into a key and store it into keyring.

Parameters
[in]key_idID of the key to set the sequence number.
[in]seqnoThe sequence number to be set.
Return values
falseSuccess.
trueError.

Member Data Documentation

◆ m_enabled

bool Rpl_encryption::m_enabled = false
private

◆ m_initialized

bool Rpl_encryption::m_initialized = false
private

◆ m_master_key

Rpl_encryption_key Rpl_encryption::m_master_key
private

◆ m_master_key_recovered

bool Rpl_encryption::m_master_key_recovered = false
private

◆ m_master_key_seqno

uint32_t Rpl_encryption::m_master_key_seqno = 0
private

◆ m_rotate_at_startup

bool Rpl_encryption::m_rotate_at_startup = false
private

◆ m_skip_logs_rotation

bool Rpl_encryption::m_skip_logs_rotation = false
private

◆ SEQNO_KEY_LENGTH

const int Rpl_encryption::SEQNO_KEY_LENGTH = 16
staticprivate

◆ SEQNO_KEY_TYPE

const char * Rpl_encryption::SEQNO_KEY_TYPE = "AES"
staticprivate

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