Botan 3.9.0
Crypto and TLS for C&
ffi_cipher.cpp File Reference
#include <botan/ffi.h>
#include <botan/aead.h>
#include <botan/internal/bit_ops.h>
#include <botan/internal/ffi_util.h>
#include <botan/internal/stl_util.h>
#include <limits>

Go to the source code of this file.

Functions

int botan_cipher_clear (botan_cipher_t cipher)
int botan_cipher_destroy (botan_cipher_t cipher)
int botan_cipher_get_default_nonce_length (botan_cipher_t cipher, size_t *nl)
int botan_cipher_get_ideal_update_granularity (botan_cipher_t cipher, size_t *ug)
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_get_tag_length (botan_cipher_t cipher, size_t *tl)
int botan_cipher_get_update_granularity (botan_cipher_t cipher, size_t *ug)
int botan_cipher_init (botan_cipher_t *cipher, const char *cipher_name, uint32_t flags)
int botan_cipher_is_authenticated (botan_cipher_t cipher)
int botan_cipher_name (botan_cipher_t cipher, char *name, size_t *name_len)
int botan_cipher_output_length (botan_cipher_t cipher, size_t in_len, size_t *out_len)
int botan_cipher_query_keylen (botan_cipher_t cipher, size_t *out_minimum_keylength, size_t *out_maximum_keylength)
int botan_cipher_requires_entire_message (botan_cipher_t cipher)
int botan_cipher_reset (botan_cipher_t cipher)
int botan_cipher_set_associated_data (botan_cipher_t cipher, const uint8_t *ad, size_t ad_len)
int botan_cipher_set_key (botan_cipher_t cipher, const uint8_t *key, size_t key_len)
int botan_cipher_start (botan_cipher_t cipher_obj, const uint8_t *nonce, size_t nonce_len)
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_valid_nonce_length (botan_cipher_t cipher, size_t nl)

Function Documentation

◆ botan_cipher_clear()

int botan_cipher_clear ( botan_cipher_t hash)

Reset the key, nonce, AD and all other state on this cipher object

Definition at line 117 of file ffi_cipher.cpp.

117 {
118 return BOTAN_FFI_VISIT(cipher, [](auto& c) { c.clear(); });
119}
#define BOTAN_FFI_VISIT(obj, lambda)
Definition ffi_util.h:158

References BOTAN_FFI_VISIT.

◆ botan_cipher_destroy()

int botan_cipher_destroy ( botan_cipher_t cipher)

Destroy the cipher object

Returns
0 if success, error if invalid object handle

Definition at line 113 of file ffi_cipher.cpp.

113 {
114 return BOTAN_FFI_CHECKED_DELETE(cipher);
115}
#define BOTAN_FFI_CHECKED_DELETE(o)
Definition ffi_util.h:185

References BOTAN_FFI_CHECKED_DELETE.

◆ botan_cipher_get_default_nonce_length()

int botan_cipher_get_default_nonce_length ( botan_cipher_t cipher,
size_t * nl )

Get the default nonce length of this cipher

Definition at line 301 of file ffi_cipher.cpp.

301 {
302 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *nl = c.default_nonce_length(); });
303}

References BOTAN_FFI_VISIT.

◆ botan_cipher_get_ideal_update_granularity()

int botan_cipher_get_ideal_update_granularity ( botan_cipher_t cipher,
size_t * ug )

Return the ideal update granularity of the cipher. This is some multiple of the update granularity, reflecting possibilities for optimization.

Definition at line 309 of file ffi_cipher.cpp.

309 {
310 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *ug = c.ideal_granularity(); });
311}

References BOTAN_FFI_VISIT.

◆ botan_cipher_get_keyspec()

int botan_cipher_get_keyspec ( botan_cipher_t cipher,
size_t * min_keylen,
size_t * max_keylen,
size_t * mod_keylen )

Get information about the supported key lengths.

Definition at line 140 of file ffi_cipher.cpp.

143 {
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}

References BOTAN_FFI_VISIT.

◆ botan_cipher_get_tag_length()

int botan_cipher_get_tag_length ( botan_cipher_t cipher,
size_t * tag_size )

Get the tag length of the cipher (0 for non-AEAD modes)

Definition at line 313 of file ffi_cipher.cpp.

313 {
314 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *tl = c.tag_size(); });
315}

References BOTAN_FFI_VISIT.

◆ botan_cipher_get_update_granularity()

int botan_cipher_get_update_granularity ( botan_cipher_t cipher,
size_t * ug )

Return the update granularity of the cipher; botan_cipher_update must be called with blocks of this size, except for the final.

Definition at line 305 of file ffi_cipher.cpp.

305 {
306 return BOTAN_FFI_VISIT(cipher, [=](const auto& /*c*/) { *ug = cipher->update_size(); });
307}

References BOTAN_FFI_VISIT.

◆ botan_cipher_init()

int botan_cipher_init ( botan_cipher_t * cipher,
const char * name,
uint32_t flags )

Initialize a cipher object

Definition at line 96 of file ffi_cipher.cpp.

96 {
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}
static std::unique_ptr< Cipher_Mode > create(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
#define BOTAN_CIPHER_INIT_FLAG_ENCRYPT
Definition ffi.h:560
#define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
Definition ffi.h:559
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition ffi.h:138
Flags flags(Flag flags)
Definition p11.h:848
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

References BOTAN_CIPHER_INIT_FLAG_ENCRYPT, BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, Botan::Cipher_Mode::create(), Botan::Decryption, Botan::Encryption, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

◆ botan_cipher_is_authenticated()

int botan_cipher_is_authenticated ( botan_cipher_t cipher)

Returns 1 iff the cipher provides authentication as well as confidentiality.

Definition at line 317 of file ffi_cipher.cpp.

317 {
318 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.authenticated() ? 1 : 0; });
319}

References BOTAN_FFI_VISIT.

◆ botan_cipher_name()

int botan_cipher_name ( botan_cipher_t cipher,
char * name,
size_t * name_len )

Return the name of the cipher object

Definition at line 325 of file ffi_cipher.cpp.

325 {
326 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return write_str_output(name, name_len, c.name()); });
327}
int write_str_output(char out[], size_t *out_len, const std::string &str)
Definition ffi_util.h:251

References BOTAN_FFI_VISIT, and Botan_FFI::write_str_output().

◆ botan_cipher_output_length()

int botan_cipher_output_length ( botan_cipher_t cipher,
size_t in_len,
size_t * out_len )

Return the output length of this cipher, for a particular input length.

Definition at line 125 of file ffi_cipher.cpp.

125 {
126 if(out_len == nullptr) {
128 }
129
130 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *out_len = c.output_length(in_len); });
131}
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition ffi.h:132

References BOTAN_FFI_ERROR_NULL_POINTER, and BOTAN_FFI_VISIT.

◆ botan_cipher_query_keylen()

int botan_cipher_query_keylen ( botan_cipher_t cipher,
size_t * out_minimum_keylength,
size_t * out_maximum_keylength )

Get information about the key lengths. Prefer botan_cipher_get_keyspec

Definition at line 133 of file ffi_cipher.cpp.

133 {
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}

References BOTAN_FFI_VISIT.

◆ botan_cipher_requires_entire_message()

int botan_cipher_requires_entire_message ( botan_cipher_t cipher)

Returns 1 iff the cipher requires the entire message before any encryption or decryption can be performed. No output data will be produced in botan_cipher_update() until the final flag is set.

Definition at line 321 of file ffi_cipher.cpp.

321 {
322 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.requires_entire_message() ? 1 : 0; });
323}

References BOTAN_FFI_VISIT.

◆ botan_cipher_reset()

int botan_cipher_reset ( botan_cipher_t cipher)

Reset the message specific state for this cipher. Without resetting the keys, this resets the nonce, and any state associated with any message bits that have been processed so far.

It is conceptually equivalent to calling botan_cipher_clear followed by botan_cipher_set_key with the original key.

Definition at line 121 of file ffi_cipher.cpp.

121 {
122 return BOTAN_FFI_VISIT(cipher, [](auto& c) { c.reset(); });
123}

References BOTAN_FFI_VISIT.

◆ botan_cipher_set_associated_data()

int botan_cipher_set_associated_data ( botan_cipher_t cipher,
const uint8_t * ad,
size_t ad_len )

Set the associated data. Will fail if cipher is not an AEAD

Definition at line 287 of file ffi_cipher.cpp.

287 {
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}
@ BOTAN_FFI_SUCCESS
Definition ffi.h:115
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition ffi.h:133

References BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_SUCCESS, and BOTAN_FFI_VISIT.

◆ botan_cipher_set_key()

int botan_cipher_set_key ( botan_cipher_t cipher,
const uint8_t * key,
size_t key_len )

Set the key for this cipher object

Definition at line 157 of file ffi_cipher.cpp.

157 {
158 return BOTAN_FFI_VISIT(cipher, [=](auto& c) { c.set_key(key, key_len); });
159}

References BOTAN_FFI_VISIT.

◆ botan_cipher_start()

int botan_cipher_start ( botan_cipher_t cipher,
const uint8_t * nonce,
size_t nonce_len )

Begin processing a new message using the provided nonce

Definition at line 161 of file ffi_cipher.cpp.

161 {
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}
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:98
T & safe_get(botan_struct< T, M > *p)
Definition ffi_util.h:79

References BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), Botan_FFI::safe_get(), and Botan::Cipher_Mode::start().

◆ botan_cipher_update()

int botan_cipher_update ( botan_cipher_t cipher,
uint32_t flags,
uint8_t output[],
size_t output_size,
size_t * output_written,
const uint8_t input_bytes[],
size_t input_size,
size_t * input_consumed )

Encrypt/Decrypt some data and/or finalize the encryption/decryption.

This encrypts as many bytes from input_bytes into output_bytes as possible. Unless BOTAN_CIPHER_UPDATE_FLAG_FINAL is set, this function will consume bytes in multiples of botan_cipher_get_update_granularity(). input_consumed and output_written will be set accordingly and it is the caller's responsibility to adapt their buffers accordingly before calling this function again. Note that, unless BOTAN_CIPHER_UPDATE_FLAG_FINAL is set, the cipher will at most generate input_size output bytes.

Eventually, the caller must set the BOTAN_CIPHER_UPDATE_FLAG_FINAL flag to indicate that no more input will be provided. This will cause the cipher to consume all given input bytes and produce the final output; or return a BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE error if the given output buffer was too small. In the latter case, output_written will be set to the required buffer size. Calling again with BOTAN_CIPHER_UPDATE_FLAG_FINAL, a big enough buffer and no further input will then produce the final output.

Note that some ciphers require the entire message to be provided before any output is produced.

See also
botan_cipher_requires_entire_message().

Definition at line 169 of file ffi_cipher.cpp.

176 {
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}
#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
void finish(secure_vector< uint8_t > &final_block, size_t offset=0)
virtual bool requires_entire_message() const
size_t process(std::span< uint8_t > msg)
Helper class to create a RAII-style cleanup callback.
Definition stl_util.h:346
#define BOTAN_CIPHER_UPDATE_FLAG_FINAL
Definition ffi.h:654
@ 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
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:145
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69

References BOTAN_ASSERT_NOMSG, BOTAN_CIPHER_UPDATE_FLAG_FINAL, BOTAN_DEBUG_ASSERT, BOTAN_FFI_ERROR_BAD_MAC, BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE, BOTAN_FFI_ERROR_INVALID_OBJECT_STATE, BOTAN_FFI_SUCCESS, Botan::copy_mem(), Botan_FFI::ffi_guard_thunk(), Botan::Cipher_Mode::finish(), Botan::Cipher_Mode::process(), Botan::Cipher_Mode::requires_entire_message(), and Botan_FFI::safe_get().

◆ botan_cipher_valid_nonce_length()

int botan_cipher_valid_nonce_length ( botan_cipher_t cipher,
size_t nl )

Return if the specified nonce length is valid for this cipher

Definition at line 297 of file ffi_cipher.cpp.

297 {
298 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return c.valid_nonce_length(nl) ? 1 : 0; });
299}

References BOTAN_FFI_VISIT.