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_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_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

rng	rng object
entropy	the data to add
entropy_len	length of entropy buffer

Returns

0 on success, a negative value on failure

Definition at line 181 of file ffi_rng.cpp.

                                                                             {
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.add_entropy(input, len); });
}

References BOTAN_FFI_VISIT.

botan_rng_destroy()

int botan_rng_destroy

(

botan_rng_t

rng

)

Frees all resources of the random number generator object

Parameters

rng	rng object

Returns

0 if success, error if invalid object handle

Definition at line 162 of file ffi_rng.cpp.

                                       {
   return BOTAN_FFI_CHECKED_DELETE(rng);
}

References BOTAN_FFI_CHECKED_DELETE.

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

rng	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 166 of file ffi_rng.cpp.

                                                                 {
   return BOTAN_FFI_VISIT(rng, [=](auto& r) { r.randomize(out, out_len); });
}

References 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

rng	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 33 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 ? 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;
      }
 
      *rng_out = new botan_rng_struct(std::move(rng));
      return BOTAN_FFI_SUCCESS;
   });
}

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

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 77 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 : 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()) {
                  int rc = m_add_entropy_cb(m_context, input.data(), input.size());
                  if(rc) {
                     throw Botan::Invalid_State("Failed to add entropy via C callback, rc=" + std::to_string(rc));
                  }
               }
 
               if(!output.empty()) {
                  int rc = m_get_cb(m_context, output.data(), output.size());
                  if(rc) {
                     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);
 
      *rng_out = new botan_rng_struct(std::move(rng));
      return BOTAN_FFI_SUCCESS;
   });
}

References BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), and name.

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

rng	rng object
bits	number of bits to reseed with

Returns

0 on success, a negative value on failure

Definition at line 177 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

rng	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 185 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 170 of file ffi_rng.cpp.

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

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