Botan 3.14.1
Crypto and TLS for C&
ffi.cpp File Reference
#include <botan/ffi.h>
#include <botan/assert.h>
#include <botan/base64.h>
#include <botan/hex.h>
#include <botan/mem_ops.h>
#include <botan/version.h>
#include <botan/internal/ct_utils.h>
#include <botan/internal/ffi_util.h>
#include <cstdio>
#include <cstring>
#include <type_traits>

Go to the source code of this file.

Namespaces

namespace  Botan_FFI

Functions

int botan_base64_decode (const char *base64_str, size_t in_len, uint8_t *out, size_t *out_len)
int botan_base64_encode (const uint8_t *in, size_t len, char *out, size_t *out_len)
int botan_constant_time_compare (const uint8_t *x, const uint8_t *y, size_t len)
const char * botan_error_description (int err)
const char * botan_error_last_exception_message ()
uint32_t botan_ffi_api_version ()
int botan_ffi_supports_api (uint32_t api_version)
uint32_t botan_ffi_tls_api_version ()
int botan_ffi_tls_supports_api (uint32_t api_version)
int botan_hex_decode (const char *hex_str, size_t in_len, uint8_t *out, size_t *out_len)
int botan_hex_encode (const uint8_t *in, size_t len, char *out, uint32_t flags)
int botan_is_shared (void *handle)
int botan_same_mem (const uint8_t *x, const uint8_t *y, size_t len)
int botan_scrub_mem (void *mem, size_t bytes)
int botan_use_count (void *handle, size_t *out_use_count)
uint32_t botan_version_datestamp ()
uint32_t botan_version_major ()
uint32_t botan_version_minor ()
uint32_t botan_version_patch ()
const char * botan_version_string ()
int Botan_FFI::botan_view_bin_bounce_fn (botan_view_ctx vctx, const uint8_t *buf, size_t len)
int Botan_FFI::botan_view_str_bounce_fn (botan_view_ctx vctx, const char *str, size_t len)
void Botan_FFI::ffi_clear_last_exception ()
int Botan_FFI::ffi_error_exception_thrown (const char *func_name, const char *exn, Botan::ErrorType err)
int Botan_FFI::ffi_error_exception_thrown (const char *func_name, const char *exn, int rc)

Function Documentation

◆ botan_base64_decode()

int botan_base64_decode ( const char * base64_str,
size_t in_len,
uint8_t * out,
size_t * out_len )

Perform base64 decoding

Definition at line 419 of file ffi.cpp.

419 {
420 if(any_null_pointers(out, out_len, base64_str)) {
422 }
423
424 return ffi_guard_thunk(__func__, [=]() -> int {
425 if(*out_len < Botan::base64_decode_max_output(in_len)) {
426 *out_len = Botan::base64_decode_max_output(in_len);
428 }
429
430 *out_len = Botan::base64_decode(out, std::string(base64_str, in_len));
431 return BOTAN_FFI_SUCCESS;
432 });
433}
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition ffi.h:131
@ BOTAN_FFI_SUCCESS
Definition ffi.h:114
@ BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE
Definition ffi.h:122
int ffi_guard_thunk(const char *func_name, T thunk)
Definition ffi_util.h:229
bool any_null_pointers(Ptrs... ptr)
Definition mem_utils.h:54
size_t base64_decode(uint8_t out[], const char in[], size_t input_length, size_t &input_consumed, bool final_inputs, bool ignore_ws)
Definition base64.cpp:203
size_t base64_decode_max_output(size_t input_length)
Definition base64.cpp:273

References Botan_FFI::any_null_pointers(), Botan::base64_decode(), Botan::base64_decode_max_output(), BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, and Botan_FFI::ffi_guard_thunk().

◆ botan_base64_encode()

int botan_base64_encode ( const uint8_t * x,
size_t len,
char * out,
size_t * out_len )

Perform base64 encoding

Parameters
xthe input data
lenthe length of x
outthe output buffer
out_lenthe size of the output buffer on input, set to the number of bytes written
Returns
0 on success, a negative value on failure

Definition at line 409 of file ffi.cpp.

409 {
410 if(len > 0 && in == nullptr) {
412 }
413 return ffi_guard_thunk(__func__, [=]() -> int {
414 const std::string base64 = Botan::base64_encode(in, len);
415 return Botan_FFI::write_str_output(out, out_len, base64);
416 });
417}
int write_str_output(char out[], size_t *out_len, const std::string &str)
Definition ffi_util.h:440
size_t base64_encode(char out[], const uint8_t in[], size_t input_length, size_t &input_consumed, bool final_inputs)
Definition base64.cpp:167

References Botan::base64_encode(), BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::write_str_output().

◆ botan_constant_time_compare()

int botan_constant_time_compare ( const uint8_t * x,
const uint8_t * y,
size_t len )

Returns 0 if x[0..len] == y[0..len], or otherwise -1

Definition at line 367 of file ffi.cpp.

367 {
368 if(len > 0 && any_null_pointers(x, y)) {
370 }
371 const auto same = Botan::CT::is_equal(x, y, len);
372 // Return 0 if same or -1 otherwise
373 return static_cast<int>(same.select(1, 0)) - 1;
374}
constexpr CT::Mask< T > is_equal(const T x[], const T y[], size_t len)
Definition ct_utils.h:803

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NULL_POINTER, and Botan::CT::is_equal().

Referenced by botan_same_mem().

◆ botan_error_description()

const char * botan_error_description ( int err)

Convert an error code into a string. Returns "Unknown error" if the error code is not a known one.

Definition at line 161 of file ffi.cpp.

161 {
162 switch(err) {
164 return "OK";
165
167 return "Invalid verifier";
168
170 return "Invalid input";
171
173 return "Invalid authentication code";
174
176 return "No value available";
177
179 return "Insufficient buffer space";
180
182 return "String conversion error";
183
185 return "Exception thrown";
186
188 return "Out of memory";
189
191 return "Error while calling system API";
192
194 return "Internal error";
195
197 return "Bad flag";
198
200 return "Null pointer argument";
201
203 return "Bad parameter";
204
206 return "Key not set on object";
207
209 return "Invalid key length";
210
212 return "Invalid object state";
213
215 return "Index out of range";
216
218 return "Not implemented";
219
221 return "Invalid object handle";
222
224 return "TLS error";
225
227 return "HTTP error";
228
230 default:
231 return "Unknown error";
232 }
233}
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition ffi.h:138
@ BOTAN_FFI_ERROR_INVALID_KEY_LENGTH
Definition ffi.h:134
@ BOTAN_FFI_ERROR_KEY_NOT_SET
Definition ffi.h:133
@ BOTAN_FFI_ERROR_TLS_ERROR
Definition ffi.h:141
@ BOTAN_FFI_ERROR_EXCEPTION_THROWN
Definition ffi.h:125
@ BOTAN_FFI_ERROR_OUT_OF_MEMORY
Definition ffi.h:126
@ BOTAN_FFI_ERROR_OUT_OF_RANGE
Definition ffi.h:136
@ BOTAN_FFI_ERROR_INTERNAL_ERROR
Definition ffi.h:128
@ BOTAN_FFI_INVALID_VERIFIER
Definition ffi.h:116
@ BOTAN_FFI_ERROR_INVALID_OBJECT
Definition ffi.h:139
@ BOTAN_FFI_ERROR_UNKNOWN_ERROR
Definition ffi.h:146
@ BOTAN_FFI_ERROR_HTTP_ERROR
Definition ffi.h:142
@ BOTAN_FFI_ERROR_BAD_FLAG
Definition ffi.h:130
@ BOTAN_FFI_ERROR_INVALID_INPUT
Definition ffi.h:118
@ BOTAN_FFI_ERROR_STRING_CONVERSION_ERROR
Definition ffi.h:123
@ BOTAN_FFI_ERROR_SYSTEM_ERROR
Definition ffi.h:127
@ BOTAN_FFI_ERROR_NO_VALUE
Definition ffi.h:120
@ BOTAN_FFI_ERROR_INVALID_OBJECT_STATE
Definition ffi.h:135
@ BOTAN_FFI_ERROR_BAD_MAC
Definition ffi.h:119
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition ffi.h:132

References BOTAN_FFI_ERROR_BAD_FLAG, BOTAN_FFI_ERROR_BAD_MAC, BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_ERROR_EXCEPTION_THROWN, BOTAN_FFI_ERROR_HTTP_ERROR, BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE, BOTAN_FFI_ERROR_INTERNAL_ERROR, BOTAN_FFI_ERROR_INVALID_INPUT, BOTAN_FFI_ERROR_INVALID_KEY_LENGTH, BOTAN_FFI_ERROR_INVALID_OBJECT, BOTAN_FFI_ERROR_INVALID_OBJECT_STATE, BOTAN_FFI_ERROR_KEY_NOT_SET, BOTAN_FFI_ERROR_NO_VALUE, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_ERROR_OUT_OF_MEMORY, BOTAN_FFI_ERROR_OUT_OF_RANGE, BOTAN_FFI_ERROR_STRING_CONVERSION_ERROR, BOTAN_FFI_ERROR_SYSTEM_ERROR, BOTAN_FFI_ERROR_TLS_ERROR, BOTAN_FFI_ERROR_UNKNOWN_ERROR, BOTAN_FFI_INVALID_VERIFIER, and BOTAN_FFI_SUCCESS.

◆ botan_error_last_exception_message()

const char * botan_error_last_exception_message ( void )

Return the message of the last exception caught in this thread.

This pointer can/will be reallocated or overwritten the next time this thread calls any other Botan FFI function and must be copied to persistent storage first.

Definition at line 157 of file ffi.cpp.

157 {
158 return g_last_exception_what;
159}

◆ botan_ffi_api_version()

uint32_t botan_ffi_api_version ( void )

Return the version of the currently supported FFI API. This is expressed in the form YYYYMMDD of the release date of this version of the API.

Definition at line 238 of file ffi.cpp.

238 {
239 return BOTAN_HAS_FFI;
240}
#define BOTAN_HAS_FFI
Definition build.h:203

References BOTAN_HAS_FFI.

◆ botan_ffi_supports_api()

int botan_ffi_supports_api ( uint32_t api_version)

Return 0 (ok) if the version given is one this library supports. botan_ffi_supports_api(botan_ffi_api_version()) will always return 0.

Definition at line 242 of file ffi.cpp.

242 {
243 // This is the API introduced in 3.14.0 (not advertised until 3.14.1)
244 if(api_version == 20261104) {
245 return BOTAN_FFI_SUCCESS;
246 }
247
248 // This is the API introduced in 3.13
249 if(api_version == 20260811) {
250 return BOTAN_FFI_SUCCESS;
251 }
252
253 // This is the API introduced in 3.12
254 if(api_version == 20260506) {
255 return BOTAN_FFI_SUCCESS;
256 }
257
258 // This is the API introduced in 3.11
259 if(api_version == 20260303) {
260 return BOTAN_FFI_SUCCESS;
261 }
262
263 // This is the API introduced in 3.10
264 if(api_version == 20250829) {
265 return BOTAN_FFI_SUCCESS;
266 }
267
268 // This is the API introduced in 3.8
269 if(api_version == 20250506) {
270 return BOTAN_FFI_SUCCESS;
271 }
272
273 // This is the API introduced in 3.4
274 if(api_version == 20240408) {
275 return BOTAN_FFI_SUCCESS;
276 }
277
278 // This is the API introduced in 3.2
279 if(api_version == 20231009) {
280 return BOTAN_FFI_SUCCESS;
281 }
282
283 // This is the API introduced in 3.1
284 if(api_version == 20230711) {
285 return BOTAN_FFI_SUCCESS;
286 }
287
288 // This is the API introduced in 3.0
289 if(api_version == 20230403) {
290 return BOTAN_FFI_SUCCESS;
291 }
292
293 // This is the API introduced in 2.18
294 if(api_version == 20210220) {
295 return BOTAN_FFI_SUCCESS;
296 }
297
298 // This is the API introduced in 2.13
299 if(api_version == 20191214) {
300 return BOTAN_FFI_SUCCESS;
301 }
302
303 // This is the API introduced in 2.8
304 if(api_version == 20180713) {
305 return BOTAN_FFI_SUCCESS;
306 }
307
308 // This is the API introduced in 2.3
309 if(api_version == 20170815) {
310 return BOTAN_FFI_SUCCESS;
311 }
312
313 // This is the API introduced in 2.1
314 if(api_version == 20170327) {
315 return BOTAN_FFI_SUCCESS;
316 }
317
318 // This is the API introduced in 2.0
319 if(api_version == 20150515) {
320 return BOTAN_FFI_SUCCESS;
321 }
322
323 // Something else:
324 return -1;
325}

References BOTAN_FFI_SUCCESS.

◆ botan_ffi_tls_api_version()

uint32_t botan_ffi_tls_api_version ( void )

Return the version of the TLS FFI API (declared in ffi_tls.h) provided by this library, in the form YYYYMMDD, or 0 if the library was built without the experimental ffi_tls module. This function is always available, so applications can detect the TLS API at runtime.

Definition at line 327 of file ffi.cpp.

327 {
328#if defined(BOTAN_HAS_FFI_TLS)
329 return BOTAN_HAS_FFI_TLS;
330#else
331 return 0;
332#endif
333}

◆ botan_ffi_tls_supports_api()

int botan_ffi_tls_supports_api ( uint32_t api_version)

Return 0 (ok) if this library supports the given version of the TLS FFI API, otherwise -1 (also whenever the ffi_tls module is not built). botan_ffi_tls_supports_api(botan_ffi_tls_api_version()) returns 0 if botan_ffi_tls_api_version() is nonzero.

Definition at line 335 of file ffi.cpp.

335 {
336#if defined(BOTAN_HAS_FFI_TLS)
337 if(api_version == BOTAN_HAS_FFI_TLS) {
338 return BOTAN_FFI_SUCCESS;
339 }
340#else
341 BOTAN_UNUSED(api_version);
342#endif
343
344 return -1;
345}
#define BOTAN_UNUSED
Definition assert.h:151

References BOTAN_FFI_SUCCESS, and BOTAN_UNUSED.

◆ botan_hex_decode()

int botan_hex_decode ( const char * hex_str,
size_t in_len,
uint8_t * out,
size_t * out_len )

Perform hex decoding

Parameters
hex_stra string of hex chars (whitespace is ignored)
in_lenthe length of hex_str
outthe output buffer should be at least strlen(hex_str)/2 bytes
out_lenthe size of the output buffer on input, set to the number of bytes written
Returns
0 on success, a negative value on failure

Definition at line 399 of file ffi.cpp.

399 {
400 if(any_null_pointers(hex_str, out_len)) {
402 }
403 return ffi_guard_thunk(__func__, [=]() -> int {
404 const std::vector<uint8_t> bin = Botan::hex_decode(hex_str, in_len);
405 return Botan_FFI::write_vec_output(out, out_len, bin);
406 });
407}
int write_vec_output(uint8_t out[], size_t *out_len, std::span< const uint8_t > buf)
Definition ffi_util.h:436
size_t hex_decode(uint8_t output[], const char input[], size_t input_length, size_t &input_consumed, bool ignore_ws)
Definition hex.cpp:75

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), Botan::hex_decode(), and Botan_FFI::write_vec_output().

◆ botan_hex_encode()

int botan_hex_encode ( const uint8_t * x,
size_t len,
char * out,
uint32_t flags )

Perform hex encoding

Parameters
xis some binary data
lenlength of x in bytes
outan array of at least x*2 bytes
flagsflags out be upper or lower case?
Returns
0 on success, a negative value on failure

Definition at line 388 of file ffi.cpp.

388 {
389 if(len > 0 && (in == nullptr || out == nullptr)) {
391 }
392 return ffi_guard_thunk(__func__, [=]() -> int {
393 const bool uppercase = (flags & BOTAN_FFI_HEX_LOWER_CASE) == 0;
394 Botan::hex_encode(out, in, len, uppercase);
395 return BOTAN_FFI_SUCCESS;
396 });
397}
#define BOTAN_FFI_HEX_LOWER_CASE
Definition ffi.h:263
Flags flags(Flag flags)
Definition p11.h:1235
void hex_encode(char output[], const uint8_t input[], size_t input_length, bool uppercase)
Definition hex.cpp:34

References BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_HEX_LOWER_CASE, BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), and Botan::hex_encode().

◆ botan_is_shared()

int botan_is_shared ( void * handle)

Some handles created by functions like botan_*_init() allow sharing internal ownership of the underlying C++ object via a std::shared_ptr. Typically, this is used when some other handle needs to retain ownership of the same object for continuous use internally. The botan_rng_t handle is such an internally sharable object, for instance.

Calling botan_*_destroy() on such a handle drops the shared_ptr reference held by the application, but the underlying object may still be alive because of other handles that retain the internal shared_ptr.

This lets the application query if some handle can be shared internally. That way users can determine if a call to botan_*_destroy() will certainly destroy the underlying object or not.

Returns
1 if the handle can be shared internally, 0 otherwise

Definition at line 435 of file ffi.cpp.

435 {
436 if(any_null_pointers(handle)) {
438 }
439
440 return ffi_guard_thunk(__func__, [=]() -> int {
441 const auto* obj = static_cast<const Botan_FFI::botan_ffi_obj_base*>(handle);
442 if(!obj->appears_to_be_valid_ffi_handle()) {
444 }
445
446 return obj->is_shared() ? 1 : 0;
447 });
448}
virtual bool is_shared() const =0

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_INVALID_OBJECT, BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::botan_ffi_obj_base::is_shared().

◆ botan_same_mem()

int botan_same_mem ( const uint8_t * x,
const uint8_t * y,
size_t len )

Deprecated equivalent to botan_constant_time_compare

Definition at line 376 of file ffi.cpp.

376 {
377 return botan_constant_time_compare(x, y, len);
378}
int botan_constant_time_compare(const uint8_t *x, const uint8_t *y, size_t len)
Definition ffi.cpp:367

References botan_constant_time_compare().

◆ botan_scrub_mem()

int botan_scrub_mem ( void * mem,
size_t bytes )

Clear out memory using a system specific approach to bypass elision by the compiler (currently using RtlSecureZeroMemory or tricks with volatile pointers).

Definition at line 380 of file ffi.cpp.

380 {
381 if(bytes > 0 && mem == nullptr) {
383 }
384 Botan::secure_scrub_memory(mem, bytes);
385 return BOTAN_FFI_SUCCESS;
386}
void secure_scrub_memory(void *ptr, size_t n)
Definition mem_utils.cpp:24

References BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, and Botan::secure_scrub_memory().

◆ botan_use_count()

int botan_use_count ( void * handle,
size_t * out_use_count )

Some handles created by functions like botan_*_init() allow sharing internal ownership of the underlying C++ object via a std::shared_ptr. Typically, this is used when some other handle needs to retain ownership of the same object for continuous use internally. The botan_rng_t handle is such an internally sharable object, for instance.

Calling botan_*_destroy() on such a handle drops the shared_ptr reference held by the application, but the underlying object may still be alive because of other handles that retain the internal shared_ptr.

This lets the application query the current internal reference count of such an object. Assuming no concurrent access, a return value of 1 means that the application is the sole owner of the underlying object and that a call to botan_*_destroy() will destroy the underlying object. Handles for which botan_is_shared() returns 0 will always return 1 for botan_use_count().

Definition at line 450 of file ffi.cpp.

450 {
451 if(out_use_count != nullptr) {
452 // Set the out-param to an implausible value, in case any of the error
453 // paths below return early.
454 *out_use_count = 0;
455 }
456
457 if(any_null_pointers(handle, out_use_count)) {
459 }
460
461 return ffi_guard_thunk(__func__, [=]() -> int {
462 const auto* obj = static_cast<const Botan_FFI::botan_ffi_obj_base*>(handle);
463 if(!obj->appears_to_be_valid_ffi_handle()) {
465 }
466
467 *out_use_count = obj->use_count();
468 return BOTAN_FFI_SUCCESS;
469 });
470}
virtual size_t use_count() const =0

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_INVALID_OBJECT, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), and Botan_FFI::botan_ffi_obj_base::use_count().

◆ botan_version_datestamp()

uint32_t botan_version_datestamp ( void )

Return the date this version was released as an integer.

Returns 0 if the library was not built from an official release

Definition at line 363 of file ffi.cpp.

363 {
365}
uint32_t version_datestamp()
Definition version.cpp:32

References Botan::version_datestamp().

◆ botan_version_major()

uint32_t botan_version_major ( void )

Return the major version of the library

Definition at line 351 of file ffi.cpp.

351 {
352 return Botan::version_major();
353}
uint32_t version_major()
Definition version.cpp:55

References Botan::version_major().

◆ botan_version_minor()

uint32_t botan_version_minor ( void )

Return the minor version of the library

Definition at line 355 of file ffi.cpp.

355 {
356 return Botan::version_minor();
357}
uint32_t version_minor()
Definition version.cpp:59

References Botan::version_minor().

◆ botan_version_patch()

uint32_t botan_version_patch ( void )

Return the patch version of the library

Definition at line 359 of file ffi.cpp.

359 {
360 return Botan::version_patch();
361}
uint32_t version_patch()
Definition version.cpp:63

References Botan::version_patch().

◆ botan_version_string()

const char * botan_version_string ( void )

Return a free-form version string, e.g., 2.0.0

Definition at line 347 of file ffi.cpp.

347 {
348 return Botan::version_cstr();
349}
const char * version_cstr()
Definition version.cpp:20

References Botan::version_cstr().