Botan 3.9.0
Crypto and TLS for C&
ffi_cipher.cpp
Go to the documentation of this file.
1/*
2* (C) 2015,2017 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#include <botan/ffi.h>
8
9#include <botan/aead.h>
10#include <botan/internal/bit_ops.h>
11#include <botan/internal/ffi_util.h>
12#include <botan/internal/stl_util.h>
13
14#include <limits>
15
16extern "C" {
17
18using namespace Botan_FFI;
19
20struct botan_cipher_struct final : public botan_struct<Botan::Cipher_Mode, 0xB4A2BF9C> {
21 public:
22 explicit botan_cipher_struct(std::unique_ptr<Botan::Cipher_Mode> x,
23 size_t update_size,
24 size_t ideal_update_size) :
25 botan_struct(std::move(x)), m_update_size(update_size), m_ideal_update_size(ideal_update_size) {
26 BOTAN_DEBUG_ASSERT(ideal_update_size >= update_size);
27 m_buf.reserve(m_ideal_update_size);
28 }
29
30 Botan::secure_vector<uint8_t>& buf() { return m_buf; }
31
32 size_t update_size() const { return m_update_size; }
33
34 size_t ideal_update_size() const { return m_ideal_update_size; }
35
36 private:
38 size_t m_update_size;
39 size_t m_ideal_update_size;
40};
41
42namespace {
43
44/**
45 * Select an update size so that the following constraints are satisfies:
46 *
47 * - greater than or equal to the mode's update granularity
48 * - greater than the mode's minimum final size
49 * - the mode's ideal update granularity is a multiple of this size
50 * - (optional) a power of 2
51 *
52 * Note that this is necessary mostly for backward-compatibility with previous
53 * versions of the FFI (prior to Botan 3.5.0). For Botan 4.0.0 we should just
54 * directly return the update granularity of the cipher mode and instruct users
55 * to switch to botan_cipher_get_ideal_update_granularity() instead. See also
56 * the discussion in GitHub Issue #4090.
57 */
58size_t ffi_choose_update_size(Botan::Cipher_Mode& mode) {
59 const size_t update_granularity = mode.update_granularity();
60 const size_t ideal_update_granularity = mode.ideal_granularity();
61 const size_t minimum_final_size = mode.minimum_final_size();
62
63 // If the minimum final size is zero, or the update_granularity is
64 // already greater, just use that.
65 if(minimum_final_size == 0 || update_granularity > minimum_final_size) {
66 BOTAN_ASSERT_NOMSG(update_granularity > 0);
67 return update_granularity;
68 }
69
70 // If the ideal granularity is a multiple of the minimum final size, we
71 // might be able to use that if it stays within the ideal granularity.
72 if(ideal_update_granularity % minimum_final_size == 0 && minimum_final_size * 2 <= ideal_update_granularity) {
73 return minimum_final_size * 2;
74 }
75
76 // Otherwise, try to use the next power of two greater than the minimum
77 // final size, if the ideal granularity is a multiple of that.
78 BOTAN_ASSERT_NOMSG(minimum_final_size <= std::numeric_limits<uint16_t>::max());
79 const size_t b1 = size_t(1) << Botan::ceil_log2(static_cast<uint16_t>(minimum_final_size));
80 if(ideal_update_granularity % b1 == 0) {
81 return b1;
82 }
83
84 // Last resort: Find the next integer greater than the minimum final size
85 // for which the ideal granularity is a multiple of.
86 // Most sensible cipher modes should never reach this point.
87 BOTAN_ASSERT_NOMSG(minimum_final_size < ideal_update_granularity);
88 size_t b2 = minimum_final_size + 1;
89 for(; b2 < ideal_update_granularity && ideal_update_granularity % b2 != 0; ++b2) {}
90
91 return b2;
92}
93
94} // namespace
95
96int botan_cipher_init(botan_cipher_t* cipher, const char* cipher_name, uint32_t flags) {
97 return ffi_guard_thunk(__func__, [=]() -> int {
100
101 std::unique_ptr<Botan::Cipher_Mode> mode(Botan::Cipher_Mode::create(cipher_name, dir));
102 if(!mode) {
104 }
105
106 const size_t update_size = ffi_choose_update_size(*mode);
107 const size_t ideal_update_size = std::max(mode->ideal_granularity(), update_size);
108
109 return ffi_new_object(cipher, std::move(mode), update_size, ideal_update_size);
110 });
111}
112
114 return BOTAN_FFI_CHECKED_DELETE(cipher);
115}
116
118 return BOTAN_FFI_VISIT(cipher, [](auto& c) { c.clear(); });
119}
120
122 return BOTAN_FFI_VISIT(cipher, [](auto& c) { c.reset(); });
123}
124
125int botan_cipher_output_length(botan_cipher_t cipher, size_t in_len, size_t* out_len) {
126 if(out_len == nullptr) {
128 }
129
130 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *out_len = c.output_length(in_len); });
131}
132
133int botan_cipher_query_keylen(botan_cipher_t cipher, size_t* out_minimum_keylength, size_t* out_maximum_keylength) {
134 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
135 *out_minimum_keylength = c.key_spec().minimum_keylength();
136 *out_maximum_keylength = c.key_spec().maximum_keylength();
137 });
138}
139
141 size_t* out_minimum_keylength,
142 size_t* out_maximum_keylength,
143 size_t* out_keylength_modulo) {
144 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
145 if(out_minimum_keylength) {
146 *out_minimum_keylength = c.key_spec().minimum_keylength();
147 }
148 if(out_maximum_keylength) {
149 *out_maximum_keylength = c.key_spec().maximum_keylength();
150 }
151 if(out_keylength_modulo) {
152 *out_keylength_modulo = c.key_spec().keylength_multiple();
153 }
154 });
155}
156
157int botan_cipher_set_key(botan_cipher_t cipher, const uint8_t* key, size_t key_len) {
158 return BOTAN_FFI_VISIT(cipher, [=](auto& c) { c.set_key(key, key_len); });
159}
160
161int botan_cipher_start(botan_cipher_t cipher_obj, const uint8_t* nonce, size_t nonce_len) {
162 return ffi_guard_thunk(__func__, [=]() -> int {
163 Botan::Cipher_Mode& cipher = safe_get(cipher_obj);
164 cipher.start(nonce, nonce_len);
165 return BOTAN_FFI_SUCCESS;
166 });
167}
168
170 uint32_t flags,
171 uint8_t output[],
172 size_t output_size,
173 size_t* output_written,
174 const uint8_t input[],
175 size_t input_size,
176 size_t* input_consumed) {
177 return ffi_guard_thunk(__func__, [=]() -> int {
178 using namespace Botan;
179 Cipher_Mode& cipher = safe_get(cipher_obj);
180 secure_vector<uint8_t>& mbuf = cipher_obj->buf();
181
182 // If the cipher object's internal buffer contains residual data from
183 // a previous invocation, we can be sure that botan_cipher_update() was
184 // called with the final flag set but not enough buffer space was provided
185 // to accommodate the final output.
186 const bool was_finished_before = !mbuf.empty();
187 const bool final_input = (flags & BOTAN_CIPHER_UPDATE_FLAG_FINAL) != 0;
188
189 // Bring the output variables into a defined state.
190 *output_written = 0;
191 *input_consumed = 0;
192
193 // Once the final flag was set once, it must always be set for
194 // consecutive invocations.
195 if(was_finished_before && !final_input) {
197 }
198
199 // If the final flag was set in a previous invocation, no more input
200 // data can be processed.
201 if(was_finished_before && input_size > 0) {
203 }
204
205 // Make sure that we always clear the internal buffer before returning
206 // or aborting this invocation due to an exception.
207 auto clean_buffer = scoped_cleanup([&mbuf] { mbuf.clear(); });
208
209 if(final_input) {
210 // If the final flag is set for the first time, we need to process the
211 // remaining input data and then finalize the cipher object.
212 if(!was_finished_before) {
213 *input_consumed = input_size;
214 mbuf.resize(input_size);
215 copy_mem(mbuf, std::span(input, input_size));
216
217 try {
218 cipher.finish(mbuf);
221 }
222 }
223
224 // At this point, the cipher object is finalized (potentially in a
225 // previous invocation) and we can copy the final output to the caller.
226 *output_written = mbuf.size();
227
228 // Not enough space to copy the final output out to the caller.
229 // Inform them how much space we need for a successful operation.
230 if(output_size < mbuf.size()) {
231 // This is the only place where mbuf is not cleared before returning.
232 clean_buffer.disengage();
234 }
235
236 // Copy the final output to the caller, mbuf is cleared afterwards.
237 copy_mem(std::span(output, mbuf.size()), mbuf);
238 } else {
239 // Process data in a streamed fashion without finalizing. No data is
240 // ever retained in the cipher object's internal buffer. If we run out
241 // of either input data or output capacity, we stop and report that not
242 // all bytes were processed via *output_written and *input_consumed.
243
244 BufferSlicer in({input, input_size});
245 BufferStuffer out({output, output_size});
246
247 // Helper function to do blockwise processing of data.
248 auto blockwise_update = [&](const size_t granularity) {
249 if(granularity == 0) {
250 return;
251 }
252
253 const size_t expected_output_per_iteration = cipher.requires_entire_message() ? 0 : granularity;
254 mbuf.resize(granularity);
255
256 while(in.remaining() >= granularity && out.remaining_capacity() >= expected_output_per_iteration) {
257 copy_mem(mbuf, in.take(granularity));
258 const auto written_bytes = cipher.process(mbuf);
259 BOTAN_DEBUG_ASSERT(written_bytes == expected_output_per_iteration);
260 if(written_bytes > 0) {
261 BOTAN_ASSERT_NOMSG(written_bytes <= granularity);
262 copy_mem(out.next(written_bytes), std::span(mbuf).first(written_bytes));
263 }
264 }
265 };
266
267 // First, process as much data as possible in chunks of ideal granularity
268 blockwise_update(cipher_obj->ideal_update_size());
269
270 // Then process the remaining bytes in chunks of update_size() or, in one go
271 // if update_size() is equal to 1 --> i.e. likely a stream cipher.
272 const bool is_stream_cipher = (cipher_obj->update_size() == 1);
273 const size_t tail_granularity =
274 is_stream_cipher ? std::min(in.remaining(), out.remaining_capacity()) : cipher_obj->update_size();
275 BOTAN_DEBUG_ASSERT(tail_granularity < cipher_obj->ideal_update_size());
276 blockwise_update(tail_granularity);
277
278 // Inform the caller about the amount of data processed.
279 *output_written = output_size - out.remaining_capacity();
280 *input_consumed = input_size - in.remaining();
281 }
282
283 return BOTAN_FFI_SUCCESS;
284 });
285}
286
287int botan_cipher_set_associated_data(botan_cipher_t cipher, const uint8_t* ad, size_t ad_len) {
288 return BOTAN_FFI_VISIT(cipher, [=](auto& c) {
289 if(Botan::AEAD_Mode* aead = dynamic_cast<Botan::AEAD_Mode*>(&c)) {
290 aead->set_associated_data(ad, ad_len);
291 return BOTAN_FFI_SUCCESS;
292 }
294 });
295}
296
298 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.valid_nonce_length(nl) ? 1 : 0; });
299}
300
302 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *nl = c.default_nonce_length(); });
303}
304
306 return BOTAN_FFI_VISIT(cipher, [=](const auto& /*c*/) { *ug = cipher->update_size(); });
307}
308
310 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *ug = c.ideal_granularity(); });
311}
312
314 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *tl = c.tag_size(); });
315}
316
318 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.authenticated() ? 1 : 0; });
319}
320
322 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.requires_entire_message() ? 1 : 0; });
323}
324
325int botan_cipher_name(botan_cipher_t cipher, char* name, size_t* name_len) {
326 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return write_str_output(name, name_len, c.name()); });
327}
328}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:75
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:129
Helper class to ease in-place marshalling of concatenated fixed-length values.
Definition stl_util.h:134
static std::unique_ptr< Cipher_Mode > create(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:98
void finish(secure_vector< uint8_t > &final_block, size_t offset=0)
virtual bool requires_entire_message() const
virtual size_t ideal_granularity() const =0
size_t process(std::span< uint8_t > msg)
virtual size_t minimum_final_size() const =0
virtual size_t update_granularity() const =0
Helper class to create a RAII-style cleanup callback.
Definition stl_util.h:346
#define BOTAN_CIPHER_INIT_FLAG_ENCRYPT
Definition ffi.h:560
#define BOTAN_CIPHER_UPDATE_FLAG_FINAL
Definition ffi.h:654
#define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
Definition ffi.h:559
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition ffi.h:138
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition ffi.h:132
@ BOTAN_FFI_SUCCESS
Definition ffi.h:115
@ BOTAN_FFI_ERROR_INVALID_OBJECT_STATE
Definition ffi.h:136
@ BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE
Definition ffi.h:123
@ BOTAN_FFI_ERROR_BAD_MAC
Definition ffi.h:120
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition ffi.h:133
struct botan_cipher_struct * botan_cipher_t
Definition ffi.h:557
int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl)
int botan_cipher_requires_entire_message(botan_cipher_t cipher)
int botan_cipher_output_length(botan_cipher_t cipher, size_t in_len, size_t *out_len)
int botan_cipher_reset(botan_cipher_t cipher)
int botan_cipher_destroy(botan_cipher_t cipher)
int botan_cipher_name(botan_cipher_t cipher, char *name, size_t *name_len)
int botan_cipher_set_associated_data(botan_cipher_t cipher, const uint8_t *ad, size_t ad_len)
int botan_cipher_start(botan_cipher_t cipher_obj, const uint8_t *nonce, size_t nonce_len)
int botan_cipher_get_tag_length(botan_cipher_t cipher, size_t *tl)
int botan_cipher_update(botan_cipher_t cipher_obj, uint32_t flags, uint8_t output[], size_t output_size, size_t *output_written, const uint8_t input[], size_t input_size, size_t *input_consumed)
Encrypt/Decrypt some data and/or finalize the encryption/decryption.
int botan_cipher_get_keyspec(botan_cipher_t cipher, size_t *out_minimum_keylength, size_t *out_maximum_keylength, size_t *out_keylength_modulo)
int botan_cipher_set_key(botan_cipher_t cipher, const uint8_t *key, size_t key_len)
int botan_cipher_get_ideal_update_granularity(botan_cipher_t cipher, size_t *ug)
int botan_cipher_is_authenticated(botan_cipher_t cipher)
int botan_cipher_clear(botan_cipher_t cipher)
int botan_cipher_get_default_nonce_length(botan_cipher_t cipher, size_t *nl)
int botan_cipher_init(botan_cipher_t *cipher, const char *cipher_name, uint32_t flags)
int botan_cipher_query_keylen(botan_cipher_t cipher, size_t *out_minimum_keylength, size_t *out_maximum_keylength)
int botan_cipher_get_update_granularity(botan_cipher_t cipher, size_t *ug)
#define BOTAN_FFI_VISIT(obj, lambda)
Definition ffi_util.h:158
#define BOTAN_FFI_CHECKED_DELETE(o)
Definition ffi_util.h:185
T & safe_get(botan_struct< T, M > *p)
Definition ffi_util.h:79
BOTAN_FFI_ERROR ffi_new_object(T *obj, Args &&... args)
Definition ffi_util.h:178
int ffi_guard_thunk(const char *func_name, T thunk)
Definition ffi_util.h:95
int write_str_output(char out[], size_t *out_len, const std::string &str)
Definition ffi_util.h:251
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:145
constexpr uint8_t ceil_log2(T x)
Definition bit_ops.h:120
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69
botan_struct(std::unique_ptr< Botan::Cipher_Mode > obj)
Definition ffi_util.h:38