Botan 3.7.1
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 118 of file ffi_cipher.cpp.

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

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 114 of file ffi_cipher.cpp.

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

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 302 of file ffi_cipher.cpp.

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

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 310 of file ffi_cipher.cpp.

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

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 141 of file ffi_cipher.cpp.

144 {
145 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
146 if(out_minimum_keylength) {
147 *out_minimum_keylength = c.key_spec().minimum_keylength();
148 }
149 if(out_maximum_keylength) {
150 *out_maximum_keylength = c.key_spec().maximum_keylength();
151 }
152 if(out_keylength_modulo) {
153 *out_keylength_modulo = c.key_spec().keylength_multiple();
154 }
155 });
156}

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 314 of file ffi_cipher.cpp.

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

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 306 of file ffi_cipher.cpp.

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

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 *cipher = new botan_cipher_struct(std::move(mode), update_size, ideal_update_size);
110 return BOTAN_FFI_SUCCESS;
111 });
112}
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:541
#define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
Definition ffi.h:540
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition ffi.h:135
@ BOTAN_FFI_SUCCESS
Definition ffi.h:114
Flags flags(Flag flags)
Definition p11.h:838
int ffi_guard_thunk(const char *func_name, const std::function< int()> &thunk)
Definition ffi.cpp:128

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

◆ 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 318 of file ffi_cipher.cpp.

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

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 326 of file ffi_cipher.cpp.

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

References BOTAN_FFI_VISIT, name, 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 126 of file ffi_cipher.cpp.

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

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 134 of file ffi_cipher.cpp.

134 {
135 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
136 *out_minimum_keylength = c.key_spec().minimum_keylength();
137 *out_maximum_keylength = c.key_spec().maximum_keylength();
138 });
139}

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 322 of file ffi_cipher.cpp.

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

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 122 of file ffi_cipher.cpp.

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

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 288 of file ffi_cipher.cpp.

288 {
289 return BOTAN_FFI_VISIT(cipher, [=](auto& c) {
290 if(Botan::AEAD_Mode* aead = dynamic_cast<Botan::AEAD_Mode*>(&c)) {
291 aead->set_associated_data(ad, ad_len);
292 return BOTAN_FFI_SUCCESS;
293 }
295 });
296}
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition ffi.h:130

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 158 of file ffi_cipher.cpp.

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

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 162 of file ffi_cipher.cpp.

162 {
163 return ffi_guard_thunk(__func__, [=]() -> int {
164 Botan::Cipher_Mode& cipher = safe_get(cipher_obj);
165 cipher.start(nonce, nonce_len);
166 return BOTAN_FFI_SUCCESS;
167 });
168}
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:97
T & safe_get(botan_struct< T, M > *p)
Definition ffi_util.h:63

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 170 of file ffi_cipher.cpp.

177 {
178 return ffi_guard_thunk(__func__, [=]() -> int {
179 using namespace Botan;
180 Cipher_Mode& cipher = safe_get(cipher_obj);
181 secure_vector<uint8_t>& mbuf = cipher_obj->buf();
182
183 // If the cipher object's internal buffer contains residual data from
184 // a previous invocation, we can be sure that botan_cipher_update() was
185 // called with the final flag set but not enough buffer space was provided
186 // to accommodate the final output.
187 const bool was_finished_before = !mbuf.empty();
188 const bool final_input = (flags & BOTAN_CIPHER_UPDATE_FLAG_FINAL);
189
190 // Bring the output variables into a defined state.
191 *output_written = 0;
192 *input_consumed = 0;
193
194 // Once the final flag was set once, it must always be set for
195 // consecutive invocations.
196 if(was_finished_before && !final_input) {
198 }
199
200 // If the final flag was set in a previous invocation, no more input
201 // data can be processed.
202 if(was_finished_before && input_size > 0) {
204 }
205
206 // Make sure that we always clear the internal buffer before returning
207 // or aborting this invocation due to an exception.
208 auto clean_buffer = scoped_cleanup([&mbuf] { mbuf.clear(); });
209
210 if(final_input) {
211 // If the final flag is set for the first time, we need to process the
212 // remaining input data and then finalize the cipher object.
213 if(!was_finished_before) {
214 *input_consumed = input_size;
215 mbuf.resize(input_size);
216 copy_mem(mbuf, std::span(input, input_size));
217
218 try {
219 cipher.finish(mbuf);
222 }
223 }
224
225 // At this point, the cipher object is finalized (potentially in a
226 // previous invocation) and we can copy the final output to the caller.
227 *output_written = mbuf.size();
228
229 // Not enough space to copy the final output out to the caller.
230 // Inform them how much space we need for a successful operation.
231 if(output_size < mbuf.size()) {
232 // This is the only place where mbuf is not cleared before returning.
233 clean_buffer.disengage();
235 }
236
237 // Copy the final output to the caller, mbuf is cleared afterwards.
238 copy_mem(std::span(output, mbuf.size()), mbuf);
239 } else {
240 // Process data in a streamed fashion without finalizing. No data is
241 // ever retained in the cipher object's internal buffer. If we run out
242 // of either input data or output capacity, we stop and report that not
243 // all bytes were processed via *output_written and *input_consumed.
244
245 BufferSlicer in({input, input_size});
246 BufferStuffer out({output, output_size});
247
248 // Helper function to do blockwise processing of data.
249 auto blockwise_update = [&](const size_t granularity) {
250 if(granularity == 0) {
251 return;
252 }
253
254 const size_t expected_output_per_iteration = cipher.requires_entire_message() ? 0 : granularity;
255 mbuf.resize(granularity);
256
257 while(in.remaining() >= granularity && out.remaining_capacity() >= expected_output_per_iteration) {
258 copy_mem(mbuf, in.take(granularity));
259 const auto written_bytes = cipher.process(mbuf);
260 BOTAN_DEBUG_ASSERT(written_bytes == expected_output_per_iteration);
261 if(written_bytes > 0) {
262 BOTAN_ASSERT_NOMSG(written_bytes <= granularity);
263 copy_mem(out.next(written_bytes), std::span(mbuf).first(written_bytes));
264 }
265 }
266 };
267
268 // First, process as much data as possible in chunks of ideal granularity
269 blockwise_update(cipher_obj->ideal_update_size());
270
271 // Then process the remaining bytes in chunks of update_size() or, in one go
272 // if update_size() is equal to 1 --> i.e. likely a stream cipher.
273 const bool is_stream_cipher = (cipher_obj->update_size() == 1);
274 const size_t tail_granularity =
275 is_stream_cipher ? std::min(in.remaining(), out.remaining_capacity()) : cipher_obj->update_size();
276 BOTAN_DEBUG_ASSERT(tail_granularity < cipher_obj->ideal_update_size());
277 blockwise_update(tail_granularity);
278
279 // Inform the caller about the amount of data processed.
280 *output_written = output_size - out.remaining_capacity();
281 *input_consumed = input_size - in.remaining();
282 }
283
284 return BOTAN_FFI_SUCCESS;
285 });
286}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:59
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:98
Helper class to ease in-place marshalling of concatenated fixed-length values.
Definition stl_util.h:142
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:354
#define BOTAN_CIPHER_UPDATE_FLAG_FINAL
Definition ffi.h:635
@ BOTAN_FFI_ERROR_INVALID_OBJECT_STATE
Definition ffi.h:133
@ BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE
Definition ffi.h:120
@ BOTAN_FFI_ERROR_BAD_MAC
Definition ffi.h:118
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:147

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_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 298 of file ffi_cipher.cpp.

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

References BOTAN_FFI_VISIT.