MySQL 8.0.31
Source Code Documentation
keyring_generator.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_GENERATOR_INCLUDED
24#define KEYRING_GENERATOR_INCLUDED
25
27
28/**
29 @ingroup group_keyring_component_services_inventory
30
31 Key generator service provides a way to generate random data
32 and store it in 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 This service does not return generated data back to user.
44 For that, Keyring reader service should be used.
45
46 @code
47 bool generate_key(const char *data_id, const char *auth_id,
48 const char *data_type, size_t data_size) {
49 my_service<SERVICE_TYPE(keyring_generator)> keyring_generator(
50 "keyring_reader_generator", m_reg_srv);
51 if (!keyring_generator.is_valid()) {
52 return true;
53 }
54
55 if (keyring_generator->generate(data_id, auth_id, data_type, data_size) ==
56 true) {
57 return true;
58 }
59 return false;
60 }
61 @endcode
62*/
63
64BEGIN_SERVICE_DEFINITION(keyring_generator)
65
66/**
67 Generate random data of length data_size and
68 store it in keyring using identifiers as (data_id, auth_id).
69
70 Data_type value is implementation specific. It associates type
71 label with data which may be an important indicator for certain
72 backends.
73
74 Examples: AES, SECRET
75
76 Note: If components want to support aes_encryption service,
77 it must support storing data of type AES.
78
79 If error object is not initialized, the method will initialize it if returns
80 false. Caller will be responsible for freeing error state in such cases.
81 No error object will be created or modified if return value is true.
82
83 The action should be atomic from caller's point of view.
84 As much as possible, deligate data generation to keyring backend.
85
86 @note Implementation can restrict type and/or size of data that can be
87 stored in keyring.
88
89 @param [in] data_id Data Identifier. Byte string.
90 @param [in] auth_id Authorization ID. Byte string.
91 @param [in] data_type Type of data. ASCII. Null terminated.
92 @param [in] data_size Size of the data to be generated
93
94 @returns status of the operation
95 @retval false Success - Key generated and stored in keyring.
96 @retval truen Failure
97*/
98
99DECLARE_BOOL_METHOD(generate, (const char *data_id, const char *auth_id,
100 const char *data_type, size_t data_size));
101
102END_SERVICE_DEFINITION(keyring_generator)
103
104#endif // !KEYRING_GENERATOR_INCLUDED
#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