ffi_rng.cpp File Reference

#include <botan/ffi.h>
#include <botan/auto_rng.h>
#include <botan/system_rng.h>
#include <botan/internal/ffi_rng.h>
#include <botan/internal/ffi_util.h>
#include <functional>
#include <memory>

Go to the source code of this file.

Functions
int	botan_rng_add_entropy (botan_rng_t rng, const uint8_t *input, size_t len)
int	botan_rng_destroy (botan_rng_t rng)
int	botan_rng_generate_with_input (botan_rng_t rng, uint8_t *out, size_t out_len, const uint8_t *addl_input, size_t addl_len)
int	botan_rng_get (botan_rng_t rng, uint8_t *out, size_t out_len)
int	botan_rng_init (botan_rng_t *rng_out, const char *rng_type)
int	botan_rng_init_custom (botan_rng_t *rng_out, const char *rng_name, void *context, int(*get_cb)(void *context, uint8_t *out, size_t out_len), int(*add_entropy_cb)(void *context, const uint8_t input[], size_t length), void(*destroy_cb)(void *context))
int	botan_rng_init_drbg (botan_rng_t *rng_out, const char *drbg_name, const uint8_t *seed, size_t seed_len)
int	botan_rng_reseed (botan_rng_t rng, size_t bits)
int	botan_rng_reseed_from_rng (botan_rng_t rng, botan_rng_t source_rng, size_t bits)
int	botan_system_rng_get (uint8_t *out, size_t out_len)

Function Documentation

botan_rng_add_entropy()

int botan_rng_add_entropy	(	botan_rng_t	rng,
		const uint8_t *	entropy,
		size_t	entropy_len )

Add some seed material to a random number generator

Parameters

Random Number Generators	rng object
Entropy Collection	the data to add
entropy_len	length of entropy buffer

Returns

0 on success, a negative value on failure

Definition at line 189 of file ffi_rng.cpp.

                                                                             {
   if(len > 0 && input == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.add_entropy(input, len); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and BOTAN_FFI_VISIT.

botan_rng_destroy()

int botan_rng_destroy

(

botan_rng_t

rng

)

Frees all resources of the random number generator object

Parameters

Random Number Generators

rng object

Returns

0 if success, error if invalid object handle

Definition at line 164 of file ffi_rng.cpp.

                                       {
   return BOTAN_FFI_CHECKED_DELETE(rng);
}

References BOTAN_FFI_CHECKED_DELETE.

botan_rng_generate_with_input()

int botan_rng_generate_with_input	(	botan_rng_t	rng,
		uint8_t *	out,
		size_t	out_len,
		const uint8_t *	addl_input,
		size_t	addl_len )

Generate random bytes from an RNG with additional input.

For a DRBG, the additional input is mixed in before generating. Many other RNG types (eg RDRAND or system RNG) will ignore the input.

Parameters

Random Number Generators	the RNG object
out	output buffer
out_len	number of bytes to generate
addl_input	additional input to mix in (may be NULL if addl_len is 0)
addl_len	length of additional input

Returns

0 on success, negative on failure

Definition at line 230 of file ffi_rng.cpp.

                                                                                              {
   if(out_len > 0 && out == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   if(addl_len > 0 && addl_input == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.randomize_with_input({out, out_len}, {addl_input, addl_len}); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and BOTAN_FFI_VISIT.

botan_rng_get()

int botan_rng_get	(	botan_rng_t	rng,
		uint8_t *	out,
		size_t	out_len )

Get random bytes from a random number generator

Parameters

Random Number Generators	rng object
out	output buffer of size out_len
out_len	number of requested bytes

Returns

0 on success, negative on failure

Definition at line 168 of file ffi_rng.cpp.

                                                                 {
   if(out_len > 0 && out == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.randomize(out, out_len); });
}

References BOTAN_FFI_ERROR_NULL_POINTER, and BOTAN_FFI_VISIT.

botan_rng_init()

int botan_rng_init	(	botan_rng_t *	rng,
		const char *	rng_type )

Initialize a random number generator object

Parameters

Random Number Generators	rng object
rng_type	type of the rng, possible values: "system": system RNG "esdm-full": ESDM RNG (fully seeded) "esdm-pr": ESDM RNG (w. prediction resistance) "user": userspace RNG "user-threadsafe": userspace RNG, with internal locking "rdrand": directly read RDRAND Set rng_type to null to let the library choose some default.

Definition at line 38 of file ffi_rng.cpp.

                                                               {
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(rng_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      const std::string rng_type_s(rng_type != nullptr ? rng_type : "system");
 
      std::unique_ptr<Botan::RandomNumberGenerator> rng;
 
      if(rng_type_s == "system") {
         rng = std::make_unique<Botan::System_RNG>();
      } else if(rng_type_s == "user" || rng_type_s == "user-threadsafe") {
         rng = std::make_unique<Botan::AutoSeeded_RNG>();
      } else if(rng_type_s == "null") {
         rng = std::make_unique<Botan::Null_RNG>();
      }
#if defined(BOTAN_HAS_PROCESSOR_RNG)
      else if((rng_type_s == "rdrand" || rng_type_s == "hwrng") && Botan::Processor_RNG::available()) {
         rng = std::make_unique<Botan::Processor_RNG>();
      }
#endif
#if defined(BOTAN_HAS_JITTER_RNG)
      else if(rng_type_s == "jitter") {
         rng = std::make_unique<Botan::Jitter_RNG>();
      }
#endif
#if defined(BOTAN_HAS_ESDM_RNG)
      else if(rng_type_s == "esdm-full") {
         rng = std::make_unique<Botan::ESDM_RNG>(false);
      } else if(rng_type_s == "esdm-pr") {
         rng = std::make_unique<Botan::ESDM_RNG>(true);
      }
#endif
 
      if(!rng) {
         return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
      }
 
      return ffi_new_object(rng_out, std::move(rng));
   });
}

References Botan::Processor_RNG::available(), BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_rng_init_custom()

int botan_rng_init_custom	(	botan_rng_t *	rng_out,
		const char *	rng_name,
		void *	context,
		int(*	get_cb )(void *context, uint8_t *out, size_t out_len),
		int(*	add_entropy_cb )(void *context, const uint8_t input[], size_t length),
		void(*	destroy_cb )(void *context) )

Initialize a custom random number generator from a set of callback functions

Parameters

rng_out	rng object to create
rng_name	name of the rng
context	An application-specific context passed to the callback functions
get_cb	Callback for getting random bytes from the rng, return 0 for success
add_entropy_cb	Callback for adding entropy to the rng, return 0 for success, may be NULL
destroy_cb	Callback called when rng is destroyed, may be NULL

Definition at line 81 of file ffi_rng.cpp.

                                                             {
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(rng_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      if(rng_name == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      if(get_cb == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      class Custom_RNG final : public Botan::RandomNumberGenerator {
         public:
            Custom_RNG(std::string_view name,
                       void* context,
                       int (*get_cb)(void* context, uint8_t* out, size_t out_len),
                       int (*add_entropy_cb)(void* context, const uint8_t input[], size_t length),
                       void (*destroy_cb)(void* context)) :
                  m_name(name),
                  m_context(context),
                  m_get_cb(get_cb),
                  m_add_entropy_cb(add_entropy_cb),
                  m_destroy_cb(destroy_cb) {}
 
            ~Custom_RNG() override {
               if(m_destroy_cb) {
                  m_destroy_cb(m_context);
               }
            }
 
            Custom_RNG(const Custom_RNG& other) = delete;
            Custom_RNG(Custom_RNG&& other) = delete;
            Custom_RNG& operator=(const Custom_RNG& other) = delete;
            Custom_RNG& operator=(Custom_RNG&& other) = delete;
 
         protected:
            void fill_bytes_with_input(std::span<uint8_t> output, std::span<const uint8_t> input) override {
               if(accepts_input() && !input.empty()) {
                  const int rc = m_add_entropy_cb(m_context, input.data(), input.size());
                  if(rc != 0) {
                     throw Botan::Invalid_State("Failed to add entropy via C callback, rc=" + std::to_string(rc));
                  }
               }
 
               if(!output.empty()) {
                  const int rc = m_get_cb(m_context, output.data(), output.size());
                  if(rc != 0) {
                     throw Botan::Invalid_State("Failed to get random from C callback, rc=" + std::to_string(rc));
                  }
               }
            }
 
         public:
            bool accepts_input() const override { return m_add_entropy_cb != nullptr; }
 
            std::string name() const override { return m_name; }
 
            void clear() override {}
 
            bool is_seeded() const override { return true; }
 
         private:
            std::string m_name;
            void* m_context;
            std::function<int(void* context, uint8_t* out, size_t out_len)> m_get_cb;
            std::function<int(void* context, const uint8_t input[], size_t length)> m_add_entropy_cb;
            std::function<void(void* context)> m_destroy_cb;
      };
 
      auto rng = std::make_unique<Custom_RNG>(rng_name, context, get_cb, add_entropy_cb, destroy_cb);
 
      return ffi_new_object(rng_out, std::move(rng));
   });
}

References BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_rng_init_drbg()

int botan_rng_init_drbg	(	botan_rng_t *	rng_out,
		const char *	drbg_name,
		const uint8_t *	seed,
		size_t	seed_len )

Create and seed a DRBG

Parameters

rng_out	the new DRBG object
drbg_name	the name of the DRBG (e.g. "HMAC_DRBG(SHA-256)")
SEED	the seed material (entropy || nonce || personalization_string)
seed_len	length of seed in bytes

Returns

0 on success, negative on failure

Definition at line 200 of file ffi_rng.cpp.

                                                                                                           {
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(rng_out == nullptr || drbg_name == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
      if(seed_len > 0 && seed == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      std::unique_ptr<Botan::Stateful_RNG> drbg;
      const std::string name(drbg_name);
 
#if defined(BOTAN_HAS_HMAC_DRBG)
      if(name.starts_with("HMAC_DRBG(") && name.ends_with(")") && name.size() > 12) {
         const std::string hash = name.substr(10, name.size() - 11);
         drbg = std::make_unique<Botan::HMAC_DRBG>(hash);
      }
#endif
 
      if(!drbg) {
         return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
      }
 
      drbg->initialize_with(std::span(seed, seed_len));
      // Upcast to RandomNumberGenerator for the FFI object
      std::unique_ptr<Botan::RandomNumberGenerator> rng(std::move(drbg));
      return ffi_new_object(rng_out, std::move(rng));
   });
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_rng_reseed()

int botan_rng_reseed	(	botan_rng_t	rng,
		size_t	bits )

Reseed a random number generator Uses the System_RNG as a seed generator.

Parameters

Random Number Generators	rng object
bits	number of bits to reseed with

Returns

0 on success, a negative value on failure

Definition at line 185 of file ffi_rng.cpp.

                                                   {
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.reseed_from_rng(Botan::system_rng(), bits); });
}

References BOTAN_FFI_VISIT, and Botan::system_rng().

botan_rng_reseed_from_rng()

int botan_rng_reseed_from_rng	(	botan_rng_t	rng,
		botan_rng_t	source_rng,
		size_t	bits )

Reseed a random number generator

Parameters

Random Number Generators	rng object
source_rng	the rng that will be read from
bits	number of bits to reseed with

Returns

0 on success, a negative value on failure

Definition at line 196 of file ffi_rng.cpp.

                                                                                    {
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.reseed_from_rng(safe_get(source_rng), bits); });
}

References BOTAN_FFI_VISIT, and Botan_FFI::safe_get().

botan_system_rng_get()

int botan_system_rng_get	(	uint8_t *	out,
		size_t	out_len )

Get random bytes from system random number generator

Parameters

out	output buffer of size out_len
out_len	number of requested bytes

Returns

0 on success, negative on failure

Definition at line 175 of file ffi_rng.cpp.

                                                       {
   if(out_len > 0 && out == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return ffi_guard_thunk(__func__, [=]() -> int {
      Botan::system_rng().randomize(out, out_len);
      return BOTAN_FFI_SUCCESS;
   });
}

References BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), Botan::RandomNumberGenerator::randomize(), and Botan::system_rng().