diff options
Diffstat (limited to 'doc/manual/ffi.rst')
| -rw-r--r-- | doc/manual/ffi.rst | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/doc/manual/ffi.rst b/doc/manual/ffi.rst new file mode 100644 index 000000000..bf6483295 --- /dev/null +++ b/doc/manual/ffi.rst @@ -0,0 +1,103 @@ + +FFI Interface +======================================== + +.. versionadded:: 1.11.14 + +Botan's ffi module provides a C API intended to be easily usable with +other language's foreign function interface (FFI) libraries. For +instance the Python module using the FFI interface needs only the +ctypes module (included in default Python) and works with + +Versioning +---------------------------------------- + +.. cpp:function:: uint32_t botan_ffi_api_version() + Returns the FFI version + +.. cpp:function:: const char* botan_version_string() + Returns a free-from version string + +.. cpp:function:: uint32_t botan_version_major() + Returns the major version of the library +.. cpp:function:: uint32_t botan_version_minor() + Returns the minor version of the library +.. cpp:function:: uint32_t botan_version_patch() + Returns the patch version of the library + +.. cpp:function:: uint32_t botan_version_datestamp() + Returns the date this version was released as an integer, or 0 + if an unreleased version + +Hash Functions +---------------------------------------- + +.. cpp:type:: typedef struct botan_hash_struct* botan_hash_t + An opaque data type for a hash. Don't mess with it. + +.. cpp:function:: botan_hash_t botan_hash_init(const char* hash, uint32_t flags) + Creates a hash of the given name. Returns null on failure. Flags should + always be zero in this version of the API. + +.. cpp:function:: int botan_hash_destroy(botan_hash_t hash) + Destroy the object created by botan_hash_init + +.. cpp:function:: int botan_hash_clear(botan_hash_t hash) + Reset the state of this object back to clean, as if no input has + been supplied + +.. cpp:function:: size_t botan_hash_output_length(botan_hash_t hash) + Return the output length of the hash + +.. cpp:function:: int botan_hash_update(botan_hash_t hash, const uint8_t* input, size_t len) + Add input to the hash computation +.. cpp:function:: int botan_hash_final(botan_hash_t hash, uint8_t out[]) + Finalize the hash and place the output in out. Exactly + botan_hash_output_length() bytes will be written. + +Authentication Codes +---------------------------------------- +.. cpp:type:: typedef struct botan_mac_struct* botan_mac_t + An opaque data type for a MAC. Don't mess with it, but do remember + to set a random key first. + +.. cpp:function:: botan_mac_t botan_mac_init(const char* mac, uint32_t flags) +.. cpp:function:: int botan_mac_destroy(botan_mac_t mac) +.. cpp:function:: int botan_mac_clear(botan_mac_t hash) + +.. cpp:function:: int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len) +.. cpp:function:: int botan_mac_update(botan_mac_t mac, uint8_t buf[], size_t len) +.. cpp:function:: int botan_mac_final(botan_mac_t mac, uint8_t out[], size_t* out_len) +.. cpp:function:: size_t botan_mac_output_length(botan_mac_t mac) + +Ciphers +---------------------------------------- +.. cpp:type:: typedef struct botan_cipher_struct* botan_cipher_t + An opaque data type for a MAC. Don't mess with it, but do remember + to set a random key first. And please use an AEAD. + +.. cpp:function:: botan_cipher_t botan_cipher_init(const char* cipher_name, uint32_t flags) + Create a cipher object from a name such as "AES-256/GCM" or "Serpent/OCB". + + Flags is a bitfield + The low bit of flags specifies if encrypt or decrypt + +.. cpp:function:: int botan_cipher_destroy(botan_cipher_t cipher) +.. cpp:function:: int botan_cipher_clear(botan_cipher_t hash) + +.. cpp:function:: int botan_cipher_set_key(botan_cipher_t cipher, + const uint8_t* key, size_t key_len) + +.. cpp:function:: int botan_cipher_set_associated_data(botan_cipher_t cipher, + const uint8_t* ad, + size_t ad_len) + +.. cpp:function:: int botan_cipher_start(botan_cipher_t cipher, + const uint8_t* nonce, size_t nonce_len) + +.. cpp:function:: int botan_cipher_is_authenticated(botan_cipher_t cipher) +.. cpp:function:: size_t botan_cipher_tag_size(botan_cipher_t cipher) +.. cpp:function:: int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl) + +.. cpp:function:: size_t botan_cipher_default_nonce_length(botan_cipher_t cipher) + |