MySQL 8.4.7
Source Code Documentation
keyring_aes.h
Go to the documentation of this file.
1/* Copyright (c) 2021, 2025, 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_AES_INCLUDED
25#define KEYRING_AES_INCLUDED
26
27#include <mysql/components/service.h>
28
29/* clang-format off */
30/**
31 @defgroup group_keyring_component_services_inventory Keyring component services
32 @ingroup group_components_services_inventory
33*/
34
35/* clang-format on */
36
37/**
38 @ingroup group_keyring_component_services_inventory
39
40 Keyring aes encryption service provides APIs to perform AES
41 encryption/decryption operation on given data. These methods
42 make sure that key never leaves keyring component.
43
44 @code
45 my_service<SERVICE_TYPE(keyring_aes)> aes_encryption(
46 "keyring_aes", m_reg_srv);
47 if (!aes_encryption.is_valid()) {
48 return true;
49 }
50
51 std::string mode("cbc");
52 size_t block_size = 256;
53 const unsigned char plaintext[] = "Quick brown fox jumped over the lazy dog.";
54 size_t plaintext_length = strlen(static_cast<const char *>(plaintext));
55 size_t ciphertext_length = 0;
56 if (aes_encryption->get_size(plaintext_length, block_size, mode.c_str,
57 &ciphertext_length) == true) {
58 return true;
59 }
60 std::unique_ptr<unsigned char[]> ciphertext(
61 new unsigned char[ciphertext_length]);
62 if (ciphertext.get() == nullptr) {
63 return true;
64 }
65 const unsigned char iv[] = "abcefgh12345678";
66 size_t out_length = 0;
67 if (aes_encryption->encrypt(
68 "my_aes_key_1", "testuser@localhost", mode.c_str(), block_size,
69 iv, true, plaintext, plaintext_length, ciphertext.get(),
70 ciphertext_length, &out_length) == true) {
71 return true;
72 }
73
74 std::unique_ptr<unsigned char[]> retrieved_plaintext(
75 new unsigned char[plaintext_length]);
76 if (retrieved_plaintext.get() == nullptr) {
77 return true;
78 }
79
80 if (aes_encryption->decrypt(
81 "my_aes_key_1", "testuser@localhost", mode.c_str(), block_size,
82 iv, true, ciphertext.get(), out_length, retrieved_plaintext.get(),
83 plaintext_length, &out_length) == true) {
84 return true;
85 }
86
87 if (plaintext_length != out_length ||
88 memcmp(plaintext, retrieved_plaintext.get(), plaintext_length) != 0) {
89 return true;
90 }
91
92 return false;
93 @endcode
94*/
95
96BEGIN_SERVICE_DEFINITION(keyring_aes)
97
98/**
99 Retrieve required out buffer length information
100
101 Assumption: mode string is in lower case.
102
103 @param [in] input_length Length of input text
104 @param [in] mode AES mode. ASCII string.
105 @param [in] block_size AES block size information
106 @param [out] out_size Size of out buffer
107
108 @returns Output buffer length or error
109 @retval false Success
110 @retval true Error processing given mode and/or block size
111*/
112DECLARE_BOOL_METHOD(get_size, (size_t input_length, const char *mode,
113 size_t block_size, size_t *out_size));
114
115/**
116 Encrypt given piece of plaintext
117
118 Block mode for operation (e.g. "ecb", "cbc", cfb1",...)
119 Block size (e.g. 256)
120
121 Length of out buffer should be sufficient to hold ciphertext
122 data. See get_size() API.
123
124 Encrypted data should be stored in out_buffer with out_length
125 set to actual length of data.
126
127 IV must be provided if block mode of operation requires it.
128
129 It is caller's responsibility to supply same IV for encryption/decryption.
130
131 @param [in] data_id Name of the key. Byte string.
132 @param [in] auth_id Owner of the key. Byte string.
133 @param [in] mode AES mode. ASCII string.
134 @param [in] block_size AES block size information
135 @param [in] iv Initialization vector
136 @param [in] padding padding preference (0 implies no padding)
137 @param [in] data_buffer Input buffer. Byte string.
138 @param [in] data_buffer_length Input buffer length
139 @param [out] out_buffer Output buffer. Byte string.
140 @param [in] out_buffer_length Output buffer length
141 @param [out] out_length Length of encrypted data
142
143 @returns status of the operation
144 @retval false Success
145 @retval true Failure
146
147*/
148DECLARE_BOOL_METHOD(encrypt,
149 (const char *data_id, const char *auth_id, const char *mode,
150 size_t block_size, const unsigned char *iv, int padding,
151 const unsigned char *data_buffer,
152 size_t data_buffer_length, unsigned char *out_buffer,
153 size_t out_buffer_length, size_t *out_length));
154
155/**
156 Decrypt given piece ciphertext
157
158 Block mode for operation (e.g. "ecb", "cbc", cfb1",...)
159 Block size (e.g. 256)
160
161 Length of out buffer should be sufficient to hold ciphertext
162 data. See get_size() API.
163
164
165 If block mode requires IV, same should be provided by caller.
166 This should same IV that was used for encryption operation.
167
168 @param [in] data_id Name of the key. Byte string.
169 @param [in] auth_id Owner of the key. Byte string.
170 @param [in] mode AES mode. ASCII string.
171 @param [in] block_size AES block size information
172 @param [in] iv Initialization vector
173 @param [in] padding padding preference (0 implies no padding)
174 @param [in] data_buffer Input buffer. Byte string.
175 @param [in] data_buffer_length Input buffer length
176 @param [out] out_buffer Output buffer. Byte string.
177 @param [in] out_buffer_length Output buffer length
178 @param [out] out_length Length of decrypted data
179
180 @returns status of the operation
181 @retval false Success
182 @retval true Failure
183
184*/
185DECLARE_BOOL_METHOD(decrypt,
186 (const char *data_id, const char *auth_id, const char *mode,
187 size_t block_size, const unsigned char *iv, int padding,
188 const unsigned char *data_buffer,
189 size_t data_buffer_length, unsigned char *out_buffer,
190 size_t out_buffer_length, size_t *out_length));
191
192END_SERVICE_DEFINITION(keyring_aes)
193
194#endif // KEYRING_AES_INCLUDED
stdx::io::mode
mode
Definition: file_handle.h:61
END_SERVICE_DEFINITION
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:91
BEGIN_SERVICE_DEFINITION
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:86
DECLARE_BOOL_METHOD
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:112