Botan 2.19.5 Crypto and TLS for C&

Functions
ffi_rng.cpp File Reference
`#include <botan/ffi.h>`
`#include <botan/internal/ffi_util.h>`
`#include <botan/internal/ffi_rng.h>`
`#include <botan/system_rng.h>`
`#include <botan/auto_rng.h>`
`#include <functional>`

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)

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

174 {
175 return BOTAN_FFI_DO(Botan::RandomNumberGenerator, rng, r, { r.add_entropy(input, len); });
176 }
Botan::RandomNumberGenerator
Definition: rng.h:26
Botan::RandomNumberGenerator::add_entropy
virtual void add_entropy(const uint8_t input[], size_t length)=0
BOTAN_FFI_DO
#define BOTAN_FFI_DO(T, obj, param, block)
Definition: ffi_util.h:92

References Botan::RandomNumberGenerator::add_entropy(), and BOTAN_FFI_DO.

## ◆ 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 158 of file ffi_rng.cpp.

159 {
160 return BOTAN_FFI_CHECKED_DELETE(rng);
161 }
BOTAN_FFI_CHECKED_DELETE
#define BOTAN_FFI_CHECKED_DELETE(o)
Definition: ffi_util.h:129

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

164 {
165 return BOTAN_FFI_DO(Botan::RandomNumberGenerator, rng, r, { r.randomize(out, out_len); });
166 }
Botan::RandomNumberGenerator::randomize
virtual void randomize(uint8_t output[], size_t length)=0

References BOTAN_FFI_DO, and Botan::RandomNumberGenerator::randomize().

## ◆ 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 "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 24 of file ffi_rng.cpp.

25 {
26 return ffi_guard_thunk(__func__, [=]() -> int {
27 if(rng_out == nullptr)
28 return BOTAN_FFI_ERROR_NULL_POINTER;
29
30 const std::string rng_type_s(rng_type ? rng_type : "system");
31
32 std::unique_ptr<Botan::RandomNumberGenerator> rng;
33
34 if(rng_type_s == "system")
35 {
36 rng.reset(new Botan::System_RNG);
37 }
38 else if(rng_type_s == "user" || rng_type_s == "user-threadsafe")
39 {
40 rng.reset(new Botan::AutoSeeded_RNG);
41 }
42 else if(rng_type_s == "null")
43 {
44 rng.reset(new Botan::Null_RNG);
45 }
46#if defined(BOTAN_HAS_PROCESSOR_RNG)
47 else if((rng_type_s == "rdrand" || rng_type_s == "hwrng") && Botan::Processor_RNG::available())
48 {
49 rng.reset(new Botan::Processor_RNG);
50 }
51#endif
52
53 if(!rng)
54 {
55 return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
56 }
57
58 *rng_out = new botan_rng_struct(rng.release());
59 return BOTAN_FFI_SUCCESS;
60 });
61 }
Botan::AutoSeeded_RNG
Definition: auto_rng.h:21
Botan::Null_RNG
Definition: rng.h:207
Botan::Processor_RNG
Definition: processor_rng.h:20
Botan::Processor_RNG::available
static bool available()
Definition: processor_rng.cpp:100
Botan::System_RNG
Definition: system_rng.h:26
BOTAN_FFI_ERROR_NOT_IMPLEMENTED
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition: ffi.h:83
BOTAN_FFI_ERROR_NULL_POINTER
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition: ffi.h:77
BOTAN_FFI_SUCCESS
@ BOTAN_FFI_SUCCESS
Definition: ffi.h:63
Botan_FFI::ffi_guard_thunk
int ffi_guard_thunk(const char *func_name, std::function< int()> thunk)
Definition: ffi.cpp:89

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(*)(void *context, uint8_t *out, size_t out_len) | get_cb,
|  | int(*)(void *context, const uint8_t input[], size_t length) | add_entropy_cb,
|  | void(*)(void *context) | destroy_cb
| ) |  |

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

Parameters

  rng_out | rng object that will be created
  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 63 of file ffi_rng.cpp.

67{
68 return ffi_guard_thunk(__func__,[=]() -> int {
69 if(rng_out == nullptr)
70 return BOTAN_FFI_ERROR_NULL_POINTER;
71
72 if(rng_name == nullptr)
73 return BOTAN_FFI_ERROR_NULL_POINTER;
74
75 if(get_cb == nullptr)
76 return BOTAN_FFI_ERROR_NULL_POINTER;
77
78 class Custom_RNG : public Botan::RandomNumberGenerator
79 {
80 public:
81 Custom_RNG(const std::string& name, void* context,
82 int(* get_cb)(void* context, uint8_t* out, size_t out_len),
83 int(* add_entropy_cb)(void* context, const uint8_t input[], size_t length),
84 void(* destroy_cb)(void* context)) :
85 m_name(name)
86 {
87 m_context = context;
88 m_get_cb = get_cb;
89 m_add_entropy_cb = add_entropy_cb;
90 m_destroy_cb = destroy_cb;
91 }
92
93 ~Custom_RNG()
94 {
95 if(m_destroy_cb)
96 {
97 m_destroy_cb(m_context);
98 }
99 }
100
101 void randomize(uint8_t output[], size_t length) override
102 {
103 int rc = m_get_cb(m_context, output, length);
104 if(rc)
105 {
106 throw Botan::Invalid_State("Failed to get random from C callback, rc=" + std::to_string(rc));
107 }
108 }
109
110 bool accepts_input() const override
111 {
112 return m_add_entropy_cb != nullptr;
113 }
114
115 void add_entropy(const uint8_t input[], size_t length) override
116 {
117 if(m_add_entropy_cb == nullptr)
118 {
119 return;
120 }
121
122 int rc = m_add_entropy_cb(m_context, input, length);
123 if(rc)
124 {
125 throw Botan::Invalid_State("Failed to add entropy via C callback, rc=" + std::to_string(rc));
126 }
127 }
128
129 std::string name() const override
130 {
131 return m_name;
132 }
133
134 void clear() override
135 {
136 }
137
138 bool is_seeded() const override
139 {
140 return true;
141 }
142
143 private:
144 std::string m_name;
145 void* m_context;
146 std::function<int(void* context, uint8_t* out, size_t out_len)> m_get_cb;
147 std::function<int(void* context, const uint8_t input[], size_t length)> m_add_entropy_cb;
148 std::function<void(void* context)> m_destroy_cb;
149 };
150
151 std::unique_ptr<Botan::RandomNumberGenerator> rng(new Custom_RNG(rng_name, context, get_cb, add_entropy_cb, destroy_cb));
152
153 *rng_out = new botan_rng_struct(rng.release());
154 return BOTAN_FFI_SUCCESS;
155 });
156}
Botan::Invalid_State
Definition: exceptn.h:216
Botan::RandomNumberGenerator::clear
virtual void clear()=0
Botan::RandomNumberGenerator::accepts_input
virtual bool accepts_input() const =0
Botan::RandomNumberGenerator::is_seeded
virtual bool is_seeded() const =0
Botan::RandomNumberGenerator::name
virtual std::string name() const =0
name
std::string name
Definition: commoncrypto_hash.cpp:24
Botan::ASN1::to_string
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:213

References BOTAN_FFI_ERROR_NULL_POINTER, 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 to reseed with

Returns
  0 on success, a negative value on failure

Definition at line 168 of file ffi_rng.cpp.

169 {
170 return BOTAN_FFI_DO(Botan::RandomNumberGenerator, rng, r, { r.reseed_from_rng(Botan::system_rng(), bits); });
171 }
Botan::RandomNumberGenerator::reseed_from_rng
virtual void reseed_from_rng(RandomNumberGenerator &rng, size_t poll_bits=BOTAN_RNG_RESEED_POLL_BITS)
Definition: rng.cpp:59
Botan::system_rng
RandomNumberGenerator & system_rng()
Definition: system_rng.cpp:283

References BOTAN_FFI_DO, Botan::RandomNumberGenerator::reseed_from_rng(), 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 to reseed with

Returns
  0 on success, a negative value on failure

Definition at line 178 of file ffi_rng.cpp.

179 {
180 return BOTAN_FFI_DO(Botan::RandomNumberGenerator, rng, r, { r.reseed_from_rng(safe_get(source_rng), bits); });
181 }
Botan_FFI::safe_get
T & safe_get(botan_struct< T, M > *p)
Definition: ffi_util.h:61

References BOTAN_FFI_DO, Botan::RandomNumberGenerator::reseed_from_rng(), and Botan_FFI::safe_get().