Botan 3.5.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 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 299 of file ffi_cipher.cpp.

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

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

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

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 if(out_maximum_keylength)
149 *out_maximum_keylength = c.key_spec().maximum_keylength();
150 if(out_keylength_modulo)
151 *out_keylength_modulo = c.key_spec().keylength_multiple();
152 });
153}

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

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

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

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

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:527
#define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
Definition ffi.h:526
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition ffi.h:124
@ BOTAN_FFI_SUCCESS
Definition ffi.h:103
Flags flags(Flag flags)
Definition p11.h:838
int ffi_guard_thunk(const char *func_name, const std::function< int()> &thunk)
Definition ffi.cpp:116

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

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

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

323 {
324 return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return write_str_output(name, name_len, c.name()); });
325}
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:118

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

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

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

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

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

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

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

159 {
160 return ffi_guard_thunk(__func__, [=]() -> int {
161 Botan::Cipher_Mode& cipher = safe_get(cipher_obj);
162 cipher.start(nonce, nonce_len);
163 return BOTAN_FFI_SUCCESS;
164 });
165}
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:89
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 167 of file ffi_cipher.cpp.

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

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

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

References BOTAN_FFI_VISIT.