1 /* Copyright (c) 2016, 2021, 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 also distributed 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 included with MySQL. 13 14 This program is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU General Public License, version 2.0, for more details. 18 19 You should have received a copy of the GNU General Public License 20 along with this program; if not, write to the Free Software 21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ 22 23 #ifndef MYSQL_PLUGIN_KEYRING_INCLUDED 24 #define MYSQL_PLUGIN_KEYRING_INCLUDED 25 26 /** 27 API for keyring plugin. (MYSQL_KEYRING_PLUGIN) 28 */ 29 30 #include "plugin.h" 31 #define MYSQL_KEYRING_INTERFACE_VERSION 0x0101 32 33 /** 34 The descriptor structure for the plugin, that is referred from 35 st_mysql_plugin. 36 */ 37 38 struct st_mysql_keyring 39 { 40 int interface_version; 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 my_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 my_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 my_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 my_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 @return VOID 161 */ 162 void (*mysql_key_iterator_init)(void** key_iterator); 163 164 /** 165 Deinitialize an iterator. 166 167 @param[in] key_iterator Iterator used to fetch individual keys 168 from key_container. 169 170 @return VOID 171 */ 172 void (*mysql_key_iterator_deinit)(void* key_iterator); 173 174 /** 175 Get details of key. Every call to this service will change 176 internal pointers to advance to next position, so that the next call 177 will fetch the next key. In case iterator moves to the end, this service 178 will return error. 179 180 @param[in] key_iterator Iterator used to fetch individual keys 181 from key_container. 182 @param[out] key_id id of the key 183 @param[out] user_id id of the owner 184 185 @return Operation status 186 @retval 0 OK 187 @retval 1 ERROR 188 */ 189 bool (*mysql_key_iterator_get_key)(void* key_iterator, char *key_id, char *user_id); 190 }; 191 #endif 192