ffi.cpp File Reference

#include <botan/ffi.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>

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)
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_same_mem (const uint8_t *x, const uint8_t *y, size_t len)
int	botan_scrub_mem (void *mem, size_t bytes)
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 370 of file ffi.cpp.

                                                                                              {
   if(any_null_pointers(out, out_len, base64_str)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
 
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(*out_len < Botan::base64_decode_max_output(in_len)) {
         *out_len = Botan::base64_decode_max_output(in_len);
         return BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE;
      }
 
      *out_len = Botan::base64_decode(out, std::string(base64_str, in_len));
      return BOTAN_FFI_SUCCESS;
   });
}

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

x	the input data
len	the length of x
out	the output buffer
out_len	the 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 360 of file ffi.cpp.

                                                                                   {
   if(len > 0 && in == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return ffi_guard_thunk(__func__, [=]() -> int {
      const std::string base64 = Botan::base64_encode(in, len);
      return Botan_FFI::write_str_output(out, out_len, base64);
   });
}

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 318 of file ffi.cpp.

                                                                                {
   if(len > 0 && any_null_pointers(x, y)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   auto same = Botan::CT::is_equal(x, y, len);
   // Return 0 if same or -1 otherwise
   return static_cast<int>(same.select(1, 0)) - 1;
}

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 142 of file ffi.cpp.

                                             {
   switch(err) {
      case BOTAN_FFI_SUCCESS:
         return "OK";
 
      case BOTAN_FFI_INVALID_VERIFIER:
         return "Invalid verifier";
 
      case BOTAN_FFI_ERROR_INVALID_INPUT:
         return "Invalid input";
 
      case BOTAN_FFI_ERROR_BAD_MAC:
         return "Invalid authentication code";
 
      case BOTAN_FFI_ERROR_NO_VALUE:
         return "No value available";
 
      case BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE:
         return "Insufficient buffer space";
 
      case BOTAN_FFI_ERROR_STRING_CONVERSION_ERROR:
         return "String conversion error";
 
      case BOTAN_FFI_ERROR_EXCEPTION_THROWN:
         return "Exception thrown";
 
      case BOTAN_FFI_ERROR_OUT_OF_MEMORY:
         return "Out of memory";
 
      case BOTAN_FFI_ERROR_SYSTEM_ERROR:
         return "Error while calling system API";
 
      case BOTAN_FFI_ERROR_INTERNAL_ERROR:
         return "Internal error";
 
      case BOTAN_FFI_ERROR_BAD_FLAG:
         return "Bad flag";
 
      case BOTAN_FFI_ERROR_NULL_POINTER:
         return "Null pointer argument";
 
      case BOTAN_FFI_ERROR_BAD_PARAMETER:
         return "Bad parameter";
 
      case BOTAN_FFI_ERROR_KEY_NOT_SET:
         return "Key not set on object";
 
      case BOTAN_FFI_ERROR_INVALID_KEY_LENGTH:
         return "Invalid key length";
 
      case BOTAN_FFI_ERROR_INVALID_OBJECT_STATE:
         return "Invalid object state";
 
      case BOTAN_FFI_ERROR_OUT_OF_RANGE:
         return "Index out of range";
 
      case BOTAN_FFI_ERROR_NOT_IMPLEMENTED:
         return "Not implemented";
 
      case BOTAN_FFI_ERROR_INVALID_OBJECT:
         return "Invalid object handle";
 
      case BOTAN_FFI_ERROR_TLS_ERROR:
         return "TLS error";
 
      case BOTAN_FFI_ERROR_HTTP_ERROR:
         return "HTTP error";
 
      case BOTAN_FFI_ERROR_UNKNOWN_ERROR:
      default:
         return "Unknown error";
   }
}

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 138 of file ffi.cpp.

                                                 {
   return g_last_exception_what.c_str();
}

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 219 of file ffi.cpp.

                                 {
   return BOTAN_HAS_FFI;
}

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 223 of file ffi.cpp.

                                                 {
   // This is the API introduced in 3.12
   if(api_version == 20260506) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.11
   if(api_version == 20260303) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.10
   if(api_version == 20250829) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.8
   if(api_version == 20250506) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.4
   if(api_version == 20240408) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.2
   if(api_version == 20231009) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.1
   if(api_version == 20230711) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 3.0
   if(api_version == 20230403) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.18
   if(api_version == 20210220) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.13
   if(api_version == 20191214) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.8
   if(api_version == 20180713) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.3
   if(api_version == 20170815) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.1
   if(api_version == 20170327) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // This is the API introduced in 2.0
   if(api_version == 20150515) {
      return BOTAN_FFI_SUCCESS;
   }
 
   // Something else:
   return -1;
}

References BOTAN_FFI_SUCCESS.

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_str	a string of hex chars (whitespace is ignored)
in_len	the length of hex_str
out	the output buffer should be at least strlen(hex_str)/2 bytes
out_len	the 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 350 of file ffi.cpp.

                                                                                        {
   if(any_null_pointers(hex_str, out_len)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return ffi_guard_thunk(__func__, [=]() -> int {
      const std::vector<uint8_t> bin = Botan::hex_decode(hex_str, in_len);
      return Botan_FFI::write_vec_output(out, out_len, bin);
   });
}

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

x	is some binary data
len	length of x in bytes
out	an array of at least x*2 bytes
flags	flags out be upper or lower case?

Returns

0 on success, a negative value on failure

Definition at line 339 of file ffi.cpp.

                                                                               {
   if(len > 0 && (in == nullptr || out == nullptr)) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   return ffi_guard_thunk(__func__, [=]() -> int {
      const bool uppercase = (flags & BOTAN_FFI_HEX_LOWER_CASE) == 0;
      Botan::hex_encode(out, in, len, uppercase);
      return BOTAN_FFI_SUCCESS;
   });
}

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

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 327 of file ffi.cpp.

                                                                   {
   return botan_constant_time_compare(x, y, len);
}

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 331 of file ffi.cpp.

                                             {
   if(bytes > 0 && mem == nullptr) {
      return BOTAN_FFI_ERROR_NULL_POINTER;
   }
   Botan::secure_scrub_memory(mem, bytes);
   return BOTAN_FFI_SUCCESS;
}

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

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 314 of file ffi.cpp.

                                   {
   return Botan::version_datestamp();
}

References Botan::version_datestamp().

botan_version_major()

uint32_t botan_version_major

(

void

)

Return the major version of the library

Definition at line 302 of file ffi.cpp.

                               {
   return Botan::version_major();
}

References Botan::version_major().

botan_version_minor()

uint32_t botan_version_minor

(

void

)

Return the minor version of the library

Definition at line 306 of file ffi.cpp.

                               {
   return Botan::version_minor();
}

References Botan::version_minor().

botan_version_patch()

uint32_t botan_version_patch

(

void

)

Return the patch version of the library

Definition at line 310 of file ffi.cpp.

                               {
   return Botan::version_patch();
}

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 298 of file ffi.cpp.

                                   {
   return Botan::version_cstr();
}

References Botan::version_cstr().