ffi_cipher.cpp File Reference

#include <botan/ffi.h>
#include <botan/aead.h>
#include <botan/mem_ops.h>
#include <botan/internal/bit_ops.h>
#include <botan/internal/buffer_slicer.h>
#include <botan/internal/buffer_stuffer.h>
#include <botan/internal/ffi_util.h>
#include <botan/internal/scoped_cleanup.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 123 of file ffi_cipher.cpp.

                                              {
   return BOTAN_FFI_VISIT(cipher, [=](auto& c) {
      cipher->buf().clear();
      c.clear();
   });
}

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

                                                {
   return BOTAN_FFI_CHECKED_DELETE(cipher);
}

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

                                                                             {
   if(nl == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *nl = c.default_nonce_length(); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and 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 338 of file ffi_cipher.cpp.

                                                                                 {
   if(ug == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *ug = c.ideal_granularity(); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and 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 156 of file ffi_cipher.cpp.

                                                           {
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
      if(out_minimum_keylength) {
         *out_minimum_keylength = c.key_spec().minimum_keylength();
      }
      if(out_maximum_keylength) {
         *out_maximum_keylength = c.key_spec().maximum_keylength();
      }
      if(out_keylength_modulo) {
         *out_keylength_modulo = c.key_spec().keylength_multiple();
      }
   });
}

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

                                                                   {
   if(tl == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *tl = c.tag_size(); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and 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 331 of file ffi_cipher.cpp.

                                                                           {
   if(ug == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(cipher, [=](const auto& /*c*/) { *ug = cipher->update_size(); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and 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 99 of file ffi_cipher.cpp.

                                                                                       {
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(any_null_pointers(cipher, cipher_name)) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
      const bool encrypt_p = ((flags & BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION) == BOTAN_CIPHER_INIT_FLAG_ENCRYPT);
      const Botan::Cipher_Dir dir = encrypt_p ? Botan::Cipher_Dir::Encryption : Botan::Cipher_Dir::Decryption;
 
      std::unique_ptr<Botan::Cipher_Mode> mode(Botan::Cipher_Mode::create(cipher_name, dir));
      if(!mode) {
         return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
      }
 
      const size_t update_size = ffi_choose_update_size(*mode);
      const size_t ideal_update_size = std::max(mode->ideal_granularity(), update_size);
 
      return ffi_new_object(cipher, std::move(mode), update_size, ideal_update_size);
   });
}

References Botan_FFI::any_null_pointers(), BOTAN_CIPHER_INIT_FLAG_ENCRYPT, BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, 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 352 of file ffi_cipher.cpp.

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

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

                                                                           {
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { return write_str_output(name, name_len, c.name()); });
}

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

                                                                                      {
   if(out_len == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
 
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) { *out_len = c.output_length(in_len); });
}

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

                                                                                                                   {
   return BOTAN_FFI_VISIT(cipher, [=](const auto& c) {
      if(out_minimum_keylength) {
         *out_minimum_keylength = c.key_spec().minimum_keylength();
      }
      if(out_maximum_keylength) {
         *out_maximum_keylength = c.key_spec().maximum_keylength();
      }
   });
}

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

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

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

                                              {
   return BOTAN_FFI_VISIT(cipher, [=](auto& c) {
      cipher->buf().clear();
      c.reset();
   });
}

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

                                                                                              {
   return BOTAN_FFI_VISIT(cipher, [=](auto& c) {
      if(Botan::AEAD_Mode* aead = dynamic_cast<Botan::AEAD_Mode*>(&c)) {
         aead->set_associated_data(ad, ad_len);
         return BOTAN_FFI_SUCCESS;
      }
      return BOTAN_FFI_ERROR_BAD_PARAMETER;
   });
}

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

                                                                                    {
   if(key_len > 0 && key == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(cipher, [=](auto& c) { c.set_key(key, key_len); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and 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 180 of file ffi_cipher.cpp.

                                                                                          {
   return ffi_guard_thunk(__func__, [=]() -> int {
      Botan::Cipher_Mode& cipher = safe_get(cipher_obj);
      cipher.start(nonce, nonce_len);
      return BOTAN_FFI_SUCCESS;
   });
}

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

                                                {
   if(any_null_pointers(output_written, input_consumed)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
 
   return ffi_guard_thunk(__func__, [=]() -> int {
      using namespace Botan;
      Cipher_Mode& cipher = safe_get(cipher_obj);
      secure_vector<uint8_t>& mbuf = cipher_obj->buf();
 
      // If the cipher object's internal buffer contains residual data from
      // a previous invocation, we can be sure that botan_cipher_update() was
      // called with the final flag set but not enough buffer space was provided
      // to accommodate the final output.
      const bool was_finished_before = !mbuf.empty();
      const bool final_input = (flags & BOTAN_CIPHER_UPDATE_FLAG_FINAL) != 0;
 
      // Bring the output variables into a defined state.
      *output_written = 0;
      *input_consumed = 0;
 
      // Once the final flag was set once, it must always be set for
      // consecutive invocations.
      if(was_finished_before && !final_input) {
         return BOTAN_FFI_ERROR_INVALID_OBJECT_STATE;
      }
 
      // If the final flag was set in a previous invocation, no more input
      // data can be processed.
      if(was_finished_before && input_size > 0) {
         return BOTAN_FFI_ERROR_BAD_PARAMETER;
      }
 
      // Make sure that we always clear the internal buffer before returning
      // or aborting this invocation due to an exception.
      auto clean_buffer = scoped_cleanup([&mbuf] { mbuf.clear(); });
 
      if(final_input) {
         // If the final flag is set for the first time, we need to process the
         // remaining input data and then finalize the cipher object.
         if(!was_finished_before) {
            *input_consumed = input_size;
            mbuf.resize(input_size);
            copy_mem(mbuf, std::span(input, input_size));
 
            try {
               cipher.finish(mbuf);
            } catch(Invalid_Authentication_Tag&) {
               return BOTAN_FFI_ERROR_BAD_MAC;
            }
         }
 
         // At this point, the cipher object is finalized (potentially in a
         // previous invocation) and we can copy the final output to the caller.
         *output_written = mbuf.size();
 
         // Not enough space to copy the final output out to the caller.
         // Inform them how much space we need for a successful operation.
         if(output_size < mbuf.size()) {
            // This is the only place where mbuf is not cleared before returning.
            clean_buffer.disengage();
            return BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE;
         }
 
         // Copy the final output to the caller, mbuf is cleared afterwards.
         copy_mem(std::span(output, mbuf.size()), mbuf);
      } else {
         // Process data in a streamed fashion without finalizing. No data is
         // ever retained in the cipher object's internal buffer. If we run out
         // of either input data or output capacity, we stop and report that not
         // all bytes were processed via *output_written and *input_consumed.
 
         BufferSlicer in({input, input_size});
         BufferStuffer out({output, output_size});
 
         // Helper function to do blockwise processing of data.
         auto blockwise_update = [&](const size_t granularity) {
            if(granularity == 0) {
               return;
            }
 
            const size_t expected_output_per_iteration = cipher.requires_entire_message() ? 0 : granularity;
            mbuf.resize(granularity);
 
            while(in.remaining() >= granularity && out.remaining_capacity() >= expected_output_per_iteration) {
               copy_mem(mbuf, in.take(granularity));
               const auto written_bytes = cipher.process(mbuf);
               BOTAN_DEBUG_ASSERT(written_bytes == expected_output_per_iteration);
               if(written_bytes > 0) {
                  BOTAN_ASSERT_NOMSG(written_bytes <= granularity);
                  copy_mem(out.next(written_bytes), std::span(mbuf).first(written_bytes));
               }
            }
         };
 
         // First, process as much data as possible in chunks of ideal granularity
         blockwise_update(cipher_obj->ideal_update_size());
 
         // Then process the remaining bytes in chunks of update_size() or, in one go
         // if update_size() is equal to 1 --> i.e. likely a stream cipher.
         const bool is_stream_cipher = (cipher_obj->update_size() == 1);
         const size_t tail_granularity =
            is_stream_cipher ? std::min(in.remaining(), out.remaining_capacity()) : cipher_obj->update_size();
         BOTAN_DEBUG_ASSERT(tail_granularity < cipher_obj->ideal_update_size());
         blockwise_update(tail_granularity);
 
         // Inform the caller about the amount of data processed.
         *output_written = output_size - out.remaining_capacity();
         *input_consumed = input_size - in.remaining();
      }
 
      return BOTAN_FFI_SUCCESS;
   });
}

References Botan_FFI::any_null_pointers(), 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_ERROR_NULL_POINTER, 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 320 of file ffi_cipher.cpp.

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

References BOTAN_FFI_VISIT.