MySQL 8.4.3
Source Code Documentation
plugin_keyring.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef MYSQL_PLUGIN_KEYRING_INCLUDED
25#define MYSQL_PLUGIN_KEYRING_INCLUDED
26
27/**
28 API for keyring plugin. (MYSQL_KEYRING_PLUGIN)
29*/
30
31#include "plugin.h"
32#define MYSQL_KEYRING_INTERFACE_VERSION 0x0101
33
34/**
35 The descriptor structure for the plugin, that is referred from
36 st_mysql_plugin.
37*/
38
41 /*!
42 Add key to the keyring.
43
44 Obfuscates and adds the key to the keyring. The key is associated with
45 key_id and user_id (unique key identifier).
46
47 @param[in] key_id id of the key to store
48 @param[in] key_type type of the key to store
49 @param[in] user_id id of the owner of the key
50 @param[in] key the key itself to be stored. The memory of the key is
51 copied by the keyring, thus the key itself can be freed
52 after it was stored in the keyring.
53 @param[in] key_len the length of the key to be stored
54
55 @return Operation status
56 @retval 0 OK
57 @retval 1 ERROR
58 */
59 bool (*mysql_key_store)(const char *key_id, const char *key_type,
60 const char *user_id, const void *key, size_t key_len);
61 /*!
62 Fetches key from the keyring.
63
64 De-obfuscates and retrieves key associated with key_id and user_id from the
65 keyring.
66
67 @param[in] key_id id of the key to fetch
68 @param[out] key_type type of the fetched key
69 @param[in] user_id id of the owner of the key
70 @param[out] key the fetched key itself. The memory for this key is
71 allocated by the keyring and needs to be freed by the
72 user when no longer needed. Prior to freeing the memory
73 it needs to be obfuscated or zeroed.
74 @param[out] key_len the length of the fetched key
75
76 @return Operation status
77 @retval 0 OK
78 @retval 1 ERROR
79 */
80 bool (*mysql_key_fetch)(const char *key_id, char **key_type,
81 const char *user_id, void **key, size_t *key_len);
82
83 /*!
84 Removes key from the keyring.
85
86 Removes the key associated with key_id and user_id from the
87 keyring.
88
89 @param[in] key_id id of the key to remove
90 @param[in] user_id id of the owner of the key to remove
91
92 @return Operation status
93 @retval 0 OK
94 @retval 1 ERROR
95 */
96 bool (*mysql_key_remove)(const char *key_id, const char *user_id);
97
98 /*!
99 Generates and stores the key.
100
101 Generates a random key of length key_len, associates it with key_id, user_id
102 and stores it in the keyring.
103
104 @param[in] key_id id of the key to generate
105 @param[in] key_type type of the key to generate
106 @param[in] user_id id of the owner of the generated key
107 @param[in] key_len length of the key to generate
108
109 @return Operation status
110 @retval 0 OK
111 @retval 1 ERROR
112 */
113 bool (*mysql_key_generate)(const char *key_id, const char *key_type,
114 const char *user_id, size_t key_len);
115
116 /**
117 Keys_iterator object refers to an iterator which is used to iterate
118 on a list which refers to Key_metadata. Key_metadata hold information
119 about individual keys keyd_id and user_id. Keys_iterator should be used
120 in following sequence only.
121
122 void* iterator_ptr;
123 char key_id[64]= { 0 };
124 char user_id[64]= { 0 };
125
126 plugin_handle->mysql_key_iterator_init(&iterator_ptr);
127
128 if (iterator_ptr == NULL)
129 report error;
130
131 while (!(plugin_handle->mysql_key_iterator_get_key(iterator_ptr,
132 key_id, user_id)))
133 {
134 Fetch the keys.
135 Perform operations on the fetched keys.
136 ..
137 }
138 plugin_handle->mysql_key_iterator_deinit(iterator_ptr);
139
140 init() method accepts a void pointer which is the made to point to
141 Keys_iterator instance. Keys_iterator instance internal pointer points
142 to Key_metadata list. This list holds information about all keys stored
143 in the backed end data store of keyring plugin. After call to init()
144 please check iterator_ptr.
145
146 get_key() method accepts the above iterator_ptr as IN param and then
147 fills the passes in key_id and user_id with valid values. This can be
148 used to fetch actual key information. Every call to this method will
149 change internal pointers to advance to next position, so that the next
150 call will fetch the next key.
151
152 deinit() method frees all internal pointers along with iterator_ptr.
153 */
154 /**
155 Initialize an iterator.
156
157 @param[out] key_iterator Iterator used to fetch individual keys
158 from key_container.
159 */
160 void (*mysql_key_iterator_init)(void **key_iterator);
161
162 /**
163 Deinitialize an iterator.
164
165 @param[in] key_iterator Iterator used to fetch individual keys
166 from key_container.
167 */
168 void (*mysql_key_iterator_deinit)(void *key_iterator);
169
170 /**
171 Get details of key. Every call to this service will change
172 internal pointers to advance to next position, so that the next call
173 will fetch the next key. In case iterator moves to the end, this service
174 will return error.
175
176 @param[in] key_iterator Iterator used to fetch individual keys
177 from key_container.
178 @param[out] key_id id of the key
179 @param[out] user_id id of the owner
180
181 @return Operation status
182 @retval 0 OK
183 @retval 1 ERROR
184 */
185 bool (*mysql_key_iterator_get_key)(void *key_iterator, char *key_id,
186 char *user_id);
187};
188#endif
int key_type
Definition: method.h:38
required string key
Definition: replication_asynchronous_connection_failover.proto:60
The descriptor structure for the plugin, that is referred from st_mysql_plugin.
Definition: plugin_keyring.h:39
void(* mysql_key_iterator_init)(void **key_iterator)
Keys_iterator object refers to an iterator which is used to iterate on a list which refers to Key_met...
Definition: plugin_keyring.h:160
bool(* mysql_key_remove)(const char *key_id, const char *user_id)
Removes key from the keyring.
Definition: plugin_keyring.h:96
bool(* mysql_key_fetch)(const char *key_id, char **key_type, const char *user_id, void **key, size_t *key_len)
Fetches key from the keyring.
Definition: plugin_keyring.h:80
void(* mysql_key_iterator_deinit)(void *key_iterator)
Deinitialize an iterator.
Definition: plugin_keyring.h:168
bool(* mysql_key_store)(const char *key_id, const char *key_type, const char *user_id, const void *key, size_t key_len)
Add key to the keyring.
Definition: plugin_keyring.h:59
bool(* mysql_key_iterator_get_key)(void *key_iterator, char *key_id, char *user_id)
Get details of key.
Definition: plugin_keyring.h:185
int interface_version
Definition: plugin_keyring.h:40
bool(* mysql_key_generate)(const char *key_id, const char *key_type, const char *user_id, size_t key_len)
Generates and stores the key.
Definition: plugin_keyring.h:113