MySQL 8.3.0
Source Code Documentation
s_mysql_keyring_reader_with_status Struct Reference

Keyring reader with status service provides APIs to fetch sensitive data from keyring backend. More...

#include <keyring_reader_with_status.h>

Public Attributes

mysql_service_status_t(* init )(const char *data_id, const char *auth_id, my_h_keyring_reader_object *reader_object)
 Initialize reader. More...
 
mysql_service_status_t(* deinit )(my_h_keyring_reader_object reader_object)
 Deinitialize reader. More...
 
mysql_service_status_t(* fetch_length )(my_h_keyring_reader_object reader_object, size_t *data_size, size_t *data_type_size)
 Fetch length of the data if it exists data_size and data_type_size must not be nullptr. More...
 
mysql_service_status_t(* fetch )(my_h_keyring_reader_object reader_object, unsigned char *data_buffer, size_t data_buffer_length, size_t *data_size, char *data_type, size_t data_type_buffer_length, size_t *data_type_size)
 Fetches data if it exists. More...
 

Detailed Description

Keyring reader with status service provides APIs to fetch sensitive data from keyring backend.

It is designed to be compatible with corresponding plugin method which returns state of the keyring as well.

Data stored within keyring should be uniquely identified using:

  1. Data ID An identifier associated with data - supplied by keyring APIs' callers
  2. Auth ID An identifier associated with owner of the data - suppled by keyring APIs' callers. If Auth ID is not provided, key is treated as an internal key. Such a key shalll not be accessible to database users using SQL interface

fetch and fetch_length APIs return a value indicating one of the 3 possible states.

  1. An error in keyring component
  2. Key is missing or there is a problem performing the operation
  3. Key is found and returned
bool read_key(const char *data_id, const char *auth_id, char **out_key_buffer,
size_t *out_key_length, char **out_key_type) {
*out_key_buffer = nullptr;
*out_key_type = nullptr;
*out_key_length = 0;
my_service<SERVICE_TYPE(keyring_reader_with_status)> keyring_reader(
"keyring_reader_with_status", m_reg_srv);
if (!keyring_reader.is_valid()) {
return true;
}
my_h_keyring_reader_object reader_object = nullptr;
int key_exists = 0;
bool retval = keyring_reader->init(data_id, auth_id, &reader_object,
&key_exists); if (retval) return true;
if (key_exists == 0)
return true;
auto cleanup_object = create_scope_guard([&]{
if (reader_object != nullptr) keyring_reader->deinit(reader_object);
reader_object = nullptr;
});
size_t key_length, key_type_length;
if (keyring_reader->fetch_length(data_id, auth_id, &key_length,
&key_type_length) == true) {
return true;
}
std::unique_ptr<char[]> key_buffer(new char[key_length]);
std::unique_ptr<char[]> key_type_buffer(new char[key_type_length + 1]);
if (key_buffer.get() == nullptr || key_type_buffer.get() == nullptr) {
return true;
}
memset(key_buffer.get(), 0, key_length);
memset(key_type_buffer.get(), 0, key_type_length + 1);
size t fetched_key_length = 0, fetched_key_type_length = 0;
if( keyring_reader->fetch(data_id, auth_id, key_buffer.get(),
key_length, &fetched_key_length,
key_type_buffer, key_type_length,
&fetched_key_type_length) == true)
return true;
*out_key_buffer = new char[](fetched_key_length);
*out_key_type = new char[](fetched_key_type_length + 1);
if (*out_key_buffer == nullptr || *out_key_type == nullptr) {
return true;
}
memset(*out_key_buffer, 0, fetched_key_length);
memset(*out_key_type, 0, fetched_key_type_length + 1);
memcpy(*out_key_buffer, key_buffer.get(), fetched_key_length);
memcpy(*out_key_type, key_type_buffer.get(), fetched_key_type_length);
*out_key_length = fetched_key_length;
return false;
}
Wraps my_h_service struct conforming ABI into RAII C++ object with ability to cast to desired service...
Definition: my_service.h:34
struct my_h_keyring_reader_object_imp * my_h_keyring_reader_object
Definition: keyring_reader_with_status.h:28
void read_key(PSI_key_reader *, PSI_plugin_key_bigint *, int) noexcept
Definition: pfs_plugin_column_bigint_v1_all_empty.cc:36
Scope_guard< TLambda > create_scope_guard(const TLambda rollback_lambda)
Definition: scope_guard.h:60
#define SERVICE_TYPE(name)
Generates the standard Service type name.
Definition: service.h:75

Implementor can choose to: A. Read data from backend on each request B. Cache data in memory and server read requests from the cache

In case of B, care should be taken to keep cached data in sync with backend.

To go one step further, implementation may let user choose behavior (cached or otherwise) for read operation through configuration options.

Member Data Documentation

◆ deinit

mysql_service_status_t(* s_mysql_keyring_reader_with_status::deinit) (my_h_keyring_reader_object reader_object)

Deinitialize reader.

Parameters
[in]reader_objectReader object
Returns
status of the operation
Return values
falseSuccess
trueFailure

◆ fetch

mysql_service_status_t(* s_mysql_keyring_reader_with_status::fetch) (my_h_keyring_reader_object reader_object, unsigned char *data_buffer, size_t data_buffer_length, size_t *data_size, char *data_type, size_t data_type_buffer_length, size_t *data_type_size)

Fetches data if it exists.

All pointer parameters must be non-null.

Data_type value is implementation specific. It associates type label with data which may be an important indicator for certain backends.

Minimum expectation: AES, SECRET

data_buffer size must be enough to hold data data_type size must be enough to hold datatype and a null-terminating character

See also
fetch_length - To fetch length information about sensitive data
Parameters
[in]reader_objectReader object
[out]data_bufferOut buffer for data. Byte string.
[in]data_buffer_lengthLength of out buffer
[out]data_sizeSize of fetched data
[out]data_typeType of data. ASCII. Null terminated.
[in]data_type_buffer_lengthLength of data type buffer
[out]data_type_sizeSize of fetched datatype
Returns
status of the operation
Return values
falsesuccess
truefailure

◆ fetch_length

mysql_service_status_t(* s_mysql_keyring_reader_with_status::fetch_length) (my_h_keyring_reader_object reader_object, size_t *data_size, size_t *data_type_size)

Fetch length of the data if it exists data_size and data_type_size must not be nullptr.

Data_type value is implementation specific. It associates type label with data which may be an important indicator for certain backends.

Minimum expectation: AES, SECRET

Parameters
[in]reader_objectReader object
[out]data_sizeSize of fetched data in bytes
[out]data_type_sizeSize of data type
Returns
status of the operation
Return values
falsesuccess
truefailure

◆ init

mysql_service_status_t(* s_mysql_keyring_reader_with_status::init) (const char *data_id, const char *auth_id, my_h_keyring_reader_object *reader_object)

Initialize reader.

Parameters
[in]data_idData Identifier. Byte string.
[in]auth_idAuthorization ID. Byte string.
[out]reader_objectReader object

If return value is false, here is how value of reader_object is interpreted: reader_object == nullptr implies key does not exist reader_object != nullptr implies key exists

Returns
status of the operation
Return values
falseSuccess - Does not mean that key is found.
trueFailure

The documentation for this struct was generated from the following file: