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