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