MySQL 8.0.31
Source Code Documentation
keyring_writer.h
Go to the documentation of this file.
1/* Copyright (c) 2021, 2022, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is also distributed with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have included with MySQL.
13
14This program is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17GNU General Public License, version 2.0, for more details.
18
19You should have received a copy of the GNU General Public License
20along with this program; if not, write to the Free Software
21Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef KEYRING_WRITER_INCLUDED
24#define KEYRING_WRITER_INCLUDED
25
27
28/**
29 @ingroup group_keyring_component_services_inventory
30
31 Keyring writer service provides APIs to add/remove
32 sensitive data to/from keyring backend.
33
34 Data stored within keyring should be uniquely identified using:
35 1. Data ID
36 An identifier associated with data - supplied by keyring APIs' callers
37 2. Auth ID
38 An identifier associated with owner of the data - suppled by keyring
39 APIs' callers. If Auth ID is not provided, key is treated as an internal
40 key. Such a key shalll not be accessible to database users using
41 SQL interface
42
43 @code
44 bool write_key(const char *data_id, const char *auth_id,
45 const unsigned char *data_buffer, size_t data_length,
46 const char *data_type) {
47 my_service<SERVICE_TYPE(keyring_writer)> keyring_writer("keyring_writer",
48 m_reg_srv);
49 if (!keyring_writer.is_valid()) {
50 return true;
51 }
52
53 return keyring_writer->store(data_id, auth_id, data_buffer, data_length,
54 data_type);
55 }
56
57 bool remove_key(const char *data_id, const char *auth_id) {
58 my_service<SERVICE_TYPE(keyring_writer)> keyring_writer("keyring_writer",
59 m_reg_srv);
60 if (!keyring_writer.is_valid()) {
61 return true;
62 }
63
64 return keyring_writer->remove(data_id, auth_id);
65 }
66 @endcode
67*/
68
70
71/**
72 Store data identified with (data_id, auth_id) in keyring backend
73
74 Data_type value is implementation specific. It associates type
75 label with data which may be an important indicator for certain
76 backends.
77
78 Examples: AES, SECRET
79
80 Note: If components want to support aes_encryption service,
81 it must support storing data of type AES.
82
83 A success status implies that data is stored persistently on
84 keyring backend and shall always be available for access unless
85 removed explicitly.
86
87 @note Implementation can restrict type and/or size of data that can be
88 stored in keyring.
89
90 @param [in] data_id Data Identifier. Byte string.
91 @param [in] auth_id Authorization ID. Byte string.
92 @param [in] data Data to be stored. Byte string.
93 @param [in] data_size Size of data to be stored
94 @param [in] data_type Type of data. ASCII. Null terminated.
95
96 @returns status of the operation
97 @retval false Success - Data is stored successfully in backend
98 @retval true Failure
99*/
100
101DECLARE_BOOL_METHOD(store, (const char *data_id, const char *auth_id,
102 const unsigned char *data, size_t data_size,
103 const char *data_type));
104
105/**
106 Remove data identified by (data_id, auth_id) from keyring backend
107 if present.
108
109 Data_type value is implementation specific. It associates type
110 label with data which may be an important indicator for certain
111 backends.
112
113 Examples: AES, SECRET
114
115 Once removed, data should not be accessible through keyring implementation.
116 Based on keyring backend, implementor may decide to either destroy the data
117 completely or change the state of the data to make in unavailable.
118
119 @param [in] data_id Data Identifier. Byte string.
120 @param [in] auth_id Authorization ID. Byte string.
121
122 @returns status of the operation
123 @retval false Success - Key removed successfully or key not present.
124 @retval true Failure
125*/
126
127DECLARE_BOOL_METHOD(remove, (const char *data_id, const char *auth_id));
128
130
131#endif // !KEYRING_WRITER_INCLUDED
bool store(THD *thd, const Table *tp)
Stores the SDI for a table.
Definition: sdi.cc:606
static mysql_service_status_t remove(reference_caching_channel channel, const char *implementation_name) noexcept
Definition: component.cc:144
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:111