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_encryption &	operator= (const Rpl_encryption &)=delete

Rpl_encryption &	operator= (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_string >	get_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_string >	get_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

enum class Rpl_encryption::Key_rotation_step

strong

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] thd the 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] thd the thd object of the session.

Return values

false	Success.
true	Error. 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_id	ID of the key to be returned.
[in]	key_type	Expected 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] seqno The sequence number of the master key.

Return values

false	Success.
true	Error.

◆ 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_id	ID of the key to be returned.
[in]	key_type	Expected 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_id	ID of the key to be returned.
[in]	key_type	Expected type of the key to be returned.
[in]	key_size	Expected 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_id ID 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

false	Success.
true	Error.

◆ is_enabled()

bool Rpl_encryption::is_enabled ( )

Return is the replication logs encryption feature is enabled.

Return values

false	The feature is disabled.
true	The 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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_id ID of the key to be removed from keyring.

Return values

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

error The 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

error	The Keyring_status to be reported.
key_id	The 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] thd The 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

step	Step to start the process (it might be recovering).
new_master_key_seqno	When recovering, this is the new master key sequence number detected by recovery process.

Return values

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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

false	Success.
true	Error.

◆ 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_id	ID of the key to set the sequence number.
[in]	seqno	The sequence number to be set.

Return values

false	Success.
true	Error.

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:

sql/rpl_log_encryption.h
sql/rpl_log_encryption.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Key_rotation_step

◆ Keyring_status

Constructor & Destructor Documentation

◆ Rpl_encryption() [1/3]

◆ Rpl_encryption() [2/3]

◆ Rpl_encryption() [3/3]

Member Function Documentation

◆ disable()

◆ enable()

◆ fetch_key_from_keyring()

◆ generate_master_key_on_keyring()

◆ get_enabled_var()

◆ get_key() [1/2]

◆ get_key() [2/2]

◆ get_last_purged_master_key_seqno_from_keyring()

◆ get_last_purged_master_key_seqno_key_id()

◆ get_master_key()

◆ get_master_key_rotation_at_startup_var()

◆ get_master_key_seqno_from_keyring()

◆ get_master_key_seqno_key_id()

◆ get_new_master_key_seqno_from_keyring()

◆ get_new_master_key_seqno_key_id()

◆ get_old_master_key_seqno_from_keyring()

◆ get_old_master_key_seqno_key_id()

◆ get_seqno_from_keyring()

◆ initialize()

◆ is_enabled()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ purge_unused_keys()

◆ recover_master_key()

◆ remove_key_from_keyring()

◆ remove_last_purged_master_key_seqno_from_keyring()

◆ remove_master_key_seqno_from_keyring()

◆ remove_new_master_key_seqno_from_keyring()

◆ remove_old_master_key_seqno_from_keyring()

◆ remove_remaining_seqnos_from_keyring()

◆ report_keyring_error() [1/2]

◆ report_keyring_error() [2/2]

◆ rotate_logs()

◆ rotate_master_key()

◆ set_last_purged_master_key_seqno_on_keyring()

◆ set_master_key_seqno_on_keyring()

◆ set_new_master_key_seqno_on_keyring()

◆ set_old_master_key_seqno_on_keyring()

◆ set_seqno_on_keyring()

Member Data Documentation

◆ m_enabled

◆ m_initialized

◆ m_master_key

◆ m_master_key_recovered

◆ m_master_key_seqno

◆ m_rotate_at_startup

◆ m_skip_logs_rotation

◆ SEQNO_KEY_LENGTH

◆ SEQNO_KEY_TYPE