diff options
| -rw-r--r-- | doc/manual/ffi.rst | 380 | ||||
| -rw-r--r-- | src/lib/ffi/ffi.h | 225 |
2 files changed, 554 insertions, 51 deletions
diff --git a/doc/manual/ffi.rst b/doc/manual/ffi.rst index b7a0d750f..1f28b1b37 100644 --- a/doc/manual/ffi.rst +++ b/doc/manual/ffi.rst @@ -7,7 +7,8 @@ FFI Interface 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 +ctypes module (included in default Python). Code examples can be found +in `src/tests/test_ffi.cpp`. Versioning ---------------------------------------- @@ -18,9 +19,9 @@ Versioning expressed in the form YYYYMMDD of the release date of this version of the API. -.. cpp:function int botan_ffi_supports_api(uint32_t version) +.. cpp:function:: int botan_ffi_supports_api(uint32_t version) - Return 0 iff the FFI version specified is supported by this + Returns 0 iff the FFI version specified is supported by this library. Otherwise returns -1. The expression botan_ffi_supports_api(botan_ffi_api_version()) will always evaluate to 0. A particular version of the library may also support @@ -28,59 +29,100 @@ Versioning .. cpp:function:: const char* botan_version_string() - Returns a free-from version string + Returns a free-from version string, e.g., 2.0.0 .. cpp:function:: uint32_t botan_version_major() - Returns the major version of the library + Returns the major version of the library .. cpp:function:: uint32_t botan_version_minor() - Returns the minor version of the library + Returns the minor version of the library + .. cpp:function:: uint32_t botan_version_patch() - Returns the patch version of the library + 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 + Returns the date this version was released as an integer, or 0 + if an unreleased version + +Utility Functions +---------------------------------------- + +.. cpp:function:: int botan_same_mem(const uint8_t* x, const uint8_t* y, size_t len) + + Returns 0 if `x[0..len] == y[0..len]`, -1 otherwise. + +.. cpp:function:: int botan_hex_encode(const uint8_t* x, size_t len, char* out, uint32_t flags) + + Performs hex encoding of binary data in *x* of size *len* bytes. + The output buffer *out* must be of at least *x*2* bytes in size. + If *flags* contains ``BOTAN_FFI_HEX_LOWER_CASE``, hex encoding + will only contain lower-case letters, upper-case letters otherwise. + Returns 0 on success, 1 otherwise. + +Random Number Generators +---------------------------------------- + +.. cpp:type:: opaque* botan_rng_t + + An opaque data type for a random number generator. Don't mess with it. + +.. cpp:function:: int botan_rng_init(botan_rng_t* rng, const char* rng_type) + + Initialize a random number generator object from the given + *rng_type*: "system" or `nullptr`: `System_RNG`, "user": `AutoSeeded_RNG`. + +.. cpp:function:: int botan_rng_get(botan_rng_t rng, uint8_t* out, size_t out_len) + + Get random bytes from a random number generator. + +.. cpp:function:: int botan_rng_reseed(botan_rng_t rng, size_t bits) + + Reseeds the random number generator with *bits* number of bits + from the `System_RNG`. + +.. cpp:function:: int botan_rng_destroy(botan_rng_t rng) + + Destroy the object created by :cpp:func:`botan_rng_init`. Hash Functions ---------------------------------------- .. cpp:type:: opaque* botan_hash_t - An opaque data type for a hash. Don't mess with it. + 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. + Creates a hash of the given name, e.g., "SHA-384". + 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 + Destroy the object created by :cpp:func:`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 + 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 + Return the output length of the hash function. .. cpp:function:: int botan_hash_update(botan_hash_t hash, const uint8_t* input, size_t len) - Add input to the hash computation + 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. + Finalize the hash and place the output in out. Exactly + :cpp:func:`botan_hash_output_length` bytes will be written. -Authentication Codes +Message Authentication Codes ---------------------------------------- .. cpp:type:: opaque* botan_mac_t @@ -89,17 +131,34 @@ Authentication Codes .. cpp:function:: botan_mac_t botan_mac_init(const char* mac, uint32_t flags) + Creates a MAC of the given name, e.g., "HMAC(SHA-384)". + Returns null on failure. Flags should always be zero in this version of the API. + .. cpp:function:: int botan_mac_destroy(botan_mac_t mac) -.. cpp:function:: int botan_mac_clear(botan_mac_t hash) + Destroy the object created by :cpp:func:`botan_mac_init`. + +.. cpp:function:: int botan_mac_clear(botan_mac_t mac) + + Reset the state of this object back to clean, as if no key and input have + been supplied. + +.. cpp:function:: size_t botan_mac_output_length(botan_mac_t mac) + + Return the output length of the MAC. .. cpp:function:: int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len) + Set the random key. + .. cpp:function:: int botan_mac_update(botan_mac_t mac, uint8_t buf[], size_t len) + Add input to the MAC computation. + .. 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) + Finalize the MAC and place the output in out. Exactly + :cpp:func:`botan_mac_output_length` bytes will be written. Ciphers ---------------------------------------- @@ -137,3 +196,280 @@ Ciphers .. cpp:function:: size_t botan_cipher_default_nonce_length(botan_cipher_t cipher) +PBKDF +---------------------------------------- + +.. cpp:function:: int botan_pbkdf(const char* pbkdf_algo, \ + uint8_t out[], size_t out_len, \ + const char* passphrase, \ + const uint8_t salt[], size_t salt_len, \ + size_t iterations) + + Derive a key from a passphrase for a number of iterations + using the given PBKDF algorithm, e.g., "PBKDF2". + +.. cpp:function:: int botan_pbkdf_timed(const char* pbkdf_algo, \ + uint8_t out[], size_t out_len, \ + const char* passphrase, \ + const uint8_t salt[], size_t salt_len, \ + size_t milliseconds_to_run, \ + size_t* out_iterations_used) + + Derive a key from a passphrase using the given PBKDF algorithm, + e.g., "PBKDF2". If *out_iterations_used* is zero, instead the + PBKDF is run until *milliseconds_to_run* milliseconds have passed. + In this case, the number of iterations run will be written to + *out_iterations_used*. + +KDF +---------------------------------------- + +.. cpp:function:: int botan_kdf(const char* kdf_algo, \ + uint8_t out[], size_t out_len, \ + const uint8_t secret[], size_t secret_len, \ + const uint8_t salt[], size_t salt_len, \ + const uint8_t label[], size_t label_len) + + Derive a key using the given KDF algorithm, e.g., "SP800-56C". + The derived key of length *out_len* bytes will be placed in *out*. + +Password Hashing +---------------------------------------- + +.. cpp:function:: int botan_bcrypt_generate(uint8_t* out, size_t* out_len, \ + const char* password, \ + botan_rng_t rng, \ + size_t work_factor, \ + uint32_t flags) + + Create a password hash using Bcrypt. + The output buffer *out* should be of length 64 bytes. + The output is formatted bcrypt $2a$... + +.. cpp:function:: int botan_bcrypt_is_valid(const char* pass, const char* hash) + + Check a previously created password hash. + Returns 0 if if this password/hash combination is valid, + 1 if the combination is not valid (but otherwise well formed), + negative on error. + +Public Key Creation, Import and Export +---------------------------------------- + +.. cpp:type:: opaque* botan_privkey_t + + An opaque data type for a private key. Don't mess with it. + +.. cpp:function:: int botan_privkey_create(botan_privkey_t* key, \ + const char* algo_name, \ + const char* algo_params, \ + botan_rng_t rng) + +.. cpp:function:: int botan_privkey_create_rsa(botan_privkey_t* key, botan_rng_t rng, size_t n_bits) + +.. cpp:function:: int botan_privkey_create_ecdsa(botan_privkey_t* key, botan_rng_t rng, const char* params) + +.. cpp:function:: int botan_privkey_create_ecdh(botan_privkey_t* key, botan_rng_t rng, const char* params) + +.. cpp:function:: int botan_privkey_create_mceliece(botan_privkey_t* key, botan_rng_t rng, size_t n, size_t t) + +.. cpp:function:: int botan_privkey_load(botan_privkey_t* key, botan_rng_t rng, \ + const uint8_t bits[], size_t len, \ + const char* password) + +.. cpp:function:: int botan_privkey_destroy(botan_privkey_t key) + +.. cpp:function:: int botan_privkey_export(botan_privkey_t key, \ + uint8_t out[], size_t* out_len, \ + uint32_t flags) + +.. cpp:function:: int botan_privkey_export_encrypted(botan_privkey_t key, \ + uint8_t out[], size_t* out_len, \ + botan_rng_t rng, \ + const char* passphrase, \ + const char* encryption_algo, \ + uint32_t flags) + +.. cpp:type:: opaque* botan_pubkey_t + + An opaque data type for a public key. Don't mess with it. + +.. cpp:function:: int botan_pubkey_load(botan_pubkey_t* key, const uint8_t bits[], size_t len) + +.. cpp:function:: int botan_privkey_export_pubkey(botan_pubkey_t* out, botan_privkey_t in) + +.. cpp:function:: int botan_pubkey_export(botan_pubkey_t key, uint8_t out[], size_t* out_len, uint32_t flags) + +.. cpp:function:: int botan_pubkey_algo_name(botan_pubkey_t key, char out[], size_t* out_len) + +.. cpp:function:: int botan_pubkey_estimated_strength(botan_pubkey_t key, size_t* estimate) + +.. cpp:function:: int botan_pubkey_fingerprint(botan_pubkey_t key, const char* hash, \ + uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_pubkey_destroy(botan_pubkey_t key) + +Public Key Encryption/Decryption +---------------------------------------- + +.. cpp:type:: opaque* botan_pk_op_encrypt_t + + An opaque data type for an encryption operation. Don't mess with it. + +.. cpp:function:: int botan_pk_op_encrypt_create(botan_pk_op_encrypt_t* op, \ + botan_pubkey_t key, \ + const char* padding, \ + uint32_t flags) + +.. cpp:function:: int botan_pk_op_encrypt_destroy(botan_pk_op_encrypt_t op) + +.. cpp:function:: int botan_pk_op_encrypt(botan_pk_op_encrypt_t op, \ + botan_rng_t rng, \ + uint8_t out[], size_t* out_len, \ + const uint8_t plaintext[], size_t plaintext_len) + +.. cpp:type:: opaque* botan_pk_op_decrypt_t + + An opaque data type for a decryption operation. Don't mess with it. + +.. cpp:function:: int botan_pk_op_decrypt_create(botan_pk_op_decrypt_t* op, \ + botan_privkey_t key, \ + const char* padding, \ + uint32_t flags) + +.. cpp:function:: int botan_pk_op_decrypt_destroy(botan_pk_op_decrypt_t op) + +.. cpp:function:: int botan_pk_op_decrypt(botan_pk_op_decrypt_t op, \ + uint8_t out[], size_t* out_len, \ + uint8_t ciphertext[], size_t ciphertext_len) + +Signatures +---------------------------------------- + +.. cpp:type:: opaque* botan_pk_op_sign_t + + An opaque data type for a signature generation operation. Don't mess with it. + +.. cpp:function:: int botan_pk_op_sign_create(botan_pk_op_sign_t* op, \ + botan_privkey_t key, \ + const char* hash_and_padding, \ + uint32_t flags) + +.. cpp:function:: int botan_pk_op_sign_destroy(botan_pk_op_sign_t op) + +.. cpp:function:: int botan_pk_op_sign_update(botan_pk_op_sign_t op, \ + const uint8_t in[], size_t in_len) + +.. cpp:function:: int botan_pk_op_sign_finish(botan_pk_op_sign_t op, botan_rng_t rng, \ + uint8_t sig[], size_t* sig_len) + +.. cpp:type:: opaque* botan_pk_op_verify_t + + An opaque data type for a signature verification operation. Don't mess with it. + +.. cpp:function:: int botan_pk_op_verify_create(botan_pk_op_verify_t* op, \ + botan_pubkey_t key, \ + const char* hash_and_padding, \ + uint32_t flags) + +.. cpp:function:: int botan_pk_op_verify_destroy(botan_pk_op_verify_t op) + +.. cpp:function:: int botan_pk_op_verify_update(botan_pk_op_verify_t op, \ + const uint8_t in[], size_t in_len) + +.. cpp:function:: int botan_pk_op_verify_finish(botan_pk_op_verify_t op, \ + const uint8_t sig[], size_t sig_len) + +Key Agreement +---------------------------------------- + +.. cpp:type:: opaque* botan_pk_op_ka_t + + An opaque data type for a key agreement operation. Don't mess with it. + +.. cpp:function:: int botan_pk_op_key_agreement_create(botan_pk_op_ka_t* op, \ + botan_privkey_t key, \ + const char* kdf, \ + uint32_t flags) + +.. cpp:function:: int botan_pk_op_key_agreement_destroy(botan_pk_op_ka_t op) + +.. cpp:function:: int botan_pk_op_key_agreement_export_public(botan_privkey_t key, \ + uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_pk_op_key_agreement(botan_pk_op_ka_t op, \ + uint8_t out[], size_t* out_len, \ + const uint8_t other_key[], size_t other_key_len, \ + const uint8_t salt[], size_t salt_len) + +.. cpp:function:: int botan_mceies_encrypt(botan_pubkey_t mce_key, \ + botan_rng_t rng, \ + const char* aead, \ + const uint8_t pt[], size_t pt_len, \ + const uint8_t ad[], size_t ad_len, \ + uint8_t ct[], size_t* ct_len) + +.. cpp:function:: int botan_mceies_decrypt(botan_privkey_t mce_key, \ + const char* aead, \ + const uint8_t ct[], size_t ct_len, \ + const uint8_t ad[], size_t ad_len, \ + uint8_t pt[], size_t* pt_len) + +X.509 Certificates +---------------------------------------- + +.. cpp:type:: opaque* botan_x509_cert_t + + An opaque data type for an X.509 certificate. Don't mess with it. + +.. cpp:function:: int botan_x509_cert_load(botan_x509_cert_t* cert_obj, \ + const uint8_t cert[], size_t cert_len) + +.. cpp:function:: int botan_x509_cert_load_file(botan_x509_cert_t* cert_obj, const char* filename) + +.. cpp:function:: int botan_x509_cert_destroy(botan_x509_cert_t cert) + +.. cpp:function:: int botan_x509_cert_gen_selfsigned(botan_x509_cert_t* cert, \ + botan_privkey_t key, \ + botan_rng_t rng, \ + const char* common_name, \ + const char* org_name) + +.. cpp:function:: int botan_x509_cert_get_time_starts(botan_x509_cert_t cert, char out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_time_expires(botan_x509_cert_t cert, char out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_fingerprint(botan_x509_cert_t cert, const char* hash, uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_serial_number(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_authority_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_subject_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_path_verify(botan_x509_cert_t cert, \ + const char* ca_dir) + +.. cpp:function:: int botan_x509_cert_get_public_key_bits(botan_x509_cert_t cert, \ + uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_public_key(botan_x509_cert_t cert, botan_pubkey_t* key) + +.. cpp:function:: int botan_x509_cert_get_issuer_dn(botan_x509_cert_t cert, \ + const char* key, size_t index, \ + uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_get_subject_dn(botan_x509_cert_t cert, \ + const char* key, size_t index, \ + uint8_t out[], size_t* out_len) + +.. cpp:function:: int botan_x509_cert_to_string(botan_x509_cert_t cert, char out[], size_t* out_len) + +.. cpp:enum:: botan_x509_cert_key_constraints + + Certificate key usage constraints. Allowed values: `NO_CONSTRAINTS`, + `DIGITAL_SIGNATURE`, `NON_REPUDIATION`, `KEY_ENCIPHERMENT`, + `DATA_ENCIPHERMENT`, `KEY_AGREEMENT`, `KEY_CERT_SIGN`, + `CRL_SIGN`, `ENCIPHER_ONLY`, `DECIPHER_ONLY`. + +.. cpp:function:: int botan_x509_cert_allowed_usage(botan_x509_cert_t cert, unsigned int key_usage) diff --git a/src/lib/ffi/ffi.h b/src/lib/ffi/ffi.h index 3378e0dcd..264c3d24d 100644 --- a/src/lib/ffi/ffi.h +++ b/src/lib/ffi/ffi.h @@ -61,21 +61,43 @@ how to provide the cleanest API for such users would be most welcome. #include <stdint.h> #include <stddef.h> -/* -* Versioning +/** +* 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. */ BOTAN_DLL uint32_t botan_ffi_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. */ BOTAN_DLL int botan_ffi_supports_api(uint32_t api_version); +/** +* Return a free-form version string, e.g., 2.0.0 +*/ BOTAN_DLL const char* botan_version_string(); + +/** +* Return the major version of the library +*/ BOTAN_DLL uint32_t botan_version_major(); + +/** +* Return the minor version of the library +*/ BOTAN_DLL uint32_t botan_version_minor(); + +/** +* Return the patch version of the library +*/ BOTAN_DLL uint32_t botan_version_patch(); + +/** +* Return the date this version was released as +* an integer, or 0 if an unreleased version +*/ BOTAN_DLL uint32_t botan_version_datestamp(); /* @@ -120,60 +142,100 @@ doesn't exactly work well either! //const char* botan_error_description(int err); -/* +/** * Returns 0 if x[0..len] == y[0..len], or otherwise -1 */ BOTAN_DLL int botan_same_mem(const uint8_t* x, const uint8_t* y, size_t len); #define BOTAN_FFI_HEX_LOWER_CASE 1 +/** +* Perform hex encoding +* @param x is some binary data +* @param len length of x in bytes +* @param out an array of at least x*2 bytes +* @param flags flags out be upper or lower case? +* @return 0 on success, 1 on failure +*/ BOTAN_DLL int botan_hex_encode(const uint8_t* x, size_t len, char* out, uint32_t flags); // TODO: botan_hex_decode // TODO: botan_base64_encode // TODO: botan_base64_decode -/* -* RNG +/** +* RNG type */ typedef struct botan_rng_struct* botan_rng_t; /** +* Initialize a random number generator object +* @param rng rng object +* @param rng_type type of the rng, possible values: +* "system" or nullptr: System_RNG, "user": AutoSeeded_RNG +* * TODO: replace rng_type with simple flags? */ BOTAN_DLL int botan_rng_init(botan_rng_t* rng, const char* rng_type); /** +* Get random bytes from a random number generator +* @param rng rng object +* @param out output buffer of size out_len +* @param out_len number of requested bytes +* @return 0 on success, -1 on failure +* * TODO: better name */ BOTAN_DLL int botan_rng_get(botan_rng_t rng, uint8_t* out, size_t out_len); + +/** +* Reseed a random number generator +* Uses the System_RNG as a seed generator. +* +* @param rng rng object +* @param bits number of bits to to reseed with +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_rng_reseed(botan_rng_t rng, size_t bits); + +/** +* Frees all resources of the random number generator object +* @param rng rng object +* @return always returns 0 +*/ BOTAN_DLL int botan_rng_destroy(botan_rng_t rng); /* -* Hashing +* Hash type */ typedef struct botan_hash_struct* botan_hash_t; /** -* Initialize a hash object: -* botan_hash_t hash -* botan_hash_init(&hash, "SHA-384", 0); +* Initialize a hash function object +* @param hash hash object +* @param hash_name name of the hash function, e.g., "SHA-384" +* @param flags should be 0 in current API revision, all other uses are reserved +* and return BOTAN_FFI_ERROR_BAD_FLAG * -* Flags should be 0 in current API revision, all other uses are reserved. -* and return BOTAN_FFI_ERROR_BAD_FLAG. - * TODO: since output_length is effectively required to use this API, * return it from init as an output parameter */ BOTAN_DLL int botan_hash_init(botan_hash_t* hash, const char* hash_name, uint32_t flags); /** -* Writes the output length of the hash object to *output_length +* Writes the output length of the hash function to *output_length +* @param hash hash object +* @param output_length output buffer to hold the hash function output length +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_hash_output_length(botan_hash_t hash, size_t* output_length); /** -* Send more input to the hash function. +* Send more input to the hash function +* @param hash hash object +* @param in input buffer +* @param in_len number of bytes to read from the input buffer +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_hash_update(botan_hash_t hash, const uint8_t* in, size_t in_len); @@ -181,33 +243,96 @@ BOTAN_DLL int botan_hash_update(botan_hash_t hash, const uint8_t* in, size_t in_ * Finalizes the hash computation and writes the output to * out[0:botan_hash_output_length()] then reinitializes for computing * another digest as if botan_hash_clear had been called. +* @param hash hash object +* @param out output buffer +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_hash_final(botan_hash_t hash, uint8_t out[]); /** * Reinitializes the state of the hash computation. A hash can * be computed (with update/final) immediately. +* @param hash hash object +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_hash_clear(botan_hash_t hash); /** -* Frees all resources of this object +* Frees all resources of the hash object +* @param hash hash object +* @return always returns 0 */ BOTAN_DLL int botan_hash_destroy(botan_hash_t hash); +/** +* TODO has no implementation +*/ BOTAN_DLL int botan_hash_name(botan_hash_t hash, char* name, size_t name_len); /* -* Message Authentication +* Message Authentication type */ typedef struct botan_mac_struct* botan_mac_t; +/** +* Initialize a message authentication code object +* @param mac mac object +* @param mac_name name of the hash function, e.g., "HMAC(SHA-384)" +* @param flags should be 0 in current API revision, all other uses are reserved +* and return -1 +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_mac_init(botan_mac_t* mac, const char* mac_name, uint32_t flags); + +/** +* Writes the output length of the message authentication code to *output_length +* @param mac mac object +* @param output_length output buffer to hold the MAC output length +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_mac_output_length(botan_mac_t mac, size_t* output_length); + +/** +* Sets the key on the MAC +* @param mac mac object +* @param key buffer holding the key +* @param key_len size of the key buffer in bytes +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len); + +/** +* Send more input to the message authentication code +* @param mac mac object +* @param buf input buffer +* @param len number of bytes to read from the input buffer +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_mac_update(botan_mac_t mac, const uint8_t* buf, size_t len); + +/** +* Finalizes the MAC computation and writes the output to +* out[0:botan_mac_output_length()] then reinitializes for computing +* another MAC as if botan_mac_clear had been called. +* @param mac mac object +* @param out output buffer +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_mac_final(botan_mac_t mac, uint8_t out[]); -BOTAN_DLL int botan_mac_clear(botan_mac_t hash); + +/** +* Reinitializes the state of the MAC computation. A MAC can +* be computed (with update/final) immediately. +* @param mac mac object +* @return 0 on success, a negative value on failure +*/ +BOTAN_DLL int botan_mac_clear(botan_mac_t mac); + +/** +* Frees all resources of the MAC object +* @param mac mac object +* @return always returns 0 +*/ BOTAN_DLL int botan_mac_destroy(botan_mac_t mac); /* @@ -254,23 +379,54 @@ BOTAN_DLL int botan_cipher_clear(botan_cipher_t hash); BOTAN_DLL int botan_cipher_destroy(botan_cipher_t cipher); /* -* PBKDF +* Derive a key from a passphrase for a number of iterations +* @param pbkdf_algo PBKDF algorithm, e.g., "PBKDF2" +* @param out buffer to store the derived key, must be of out_len bytes +* @param out_len the desired length of the key to produce +* @param passphrase the password to derive the key from +* @param salt a randomly chosen salt +* @param salt_len length of salt in bytes +* @param iterations the number of iterations to use (use 10K or more) +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_pbkdf(const char* pbkdf_algo, uint8_t out[], size_t out_len, - const char* password, + const char* passphrase, const uint8_t salt[], size_t salt_len, size_t iterations); +/** +* Derive a key from a passphrase, running until msec time has elapsed. +* @param pbkdf_algo PBKDF algorithm, e.g., "PBKDF2" +* @param out buffer to store the derived key, must be of out_len bytes +* @param out_len the desired length of the key to produce +* @param passphrase the password to derive the key from +* @param salt a randomly chosen salt +* @param salt_len length of salt in bytes +* @param milliseconds_to_run if iterations is zero, then instead the PBKDF is +* run until milliseconds_to_run milliseconds has passed +* @param out_iterations_used set to the number iterations executed +* @return 0 on success, a negative value on failure +*/ BOTAN_DLL int botan_pbkdf_timed(const char* pbkdf_algo, uint8_t out[], size_t out_len, - const char* password, + const char* passphrase, const uint8_t salt[], size_t salt_len, size_t milliseconds_to_run, size_t* out_iterations_used); -/* -* KDF +/** +* Derive a key +* @param kdf_algo KDF algorithm, e.g., "SP800-56C" +* @param out buffer holding the derived key, must be of length out_len +* @param out_len the desired output length in bytes +* @param secret the secret input +* @param secret_len size of secret in bytes +* @param salt a diversifier +* @param salt_len size of salt in bytes +* @param label purpose for the derived keying material +* @param label_len size of label in bytes +* @return 0 on success, a negative value on failure */ BOTAN_DLL int botan_kdf(const char* kdf_algo, uint8_t out[], size_t out_len, @@ -278,9 +434,17 @@ BOTAN_DLL int botan_kdf(const char* kdf_algo, const uint8_t salt[], size_t salt_len, const uint8_t label[], size_t label_len); -/* -* Bcrypt -* *out_len should be 64 bytes +/** +* Create a password hash using Bcrypt +* @param out buffer holding the password hash, should be of length 64 bytes +* @param out_len the desired output length in bytes +* @param password the password +* @param rng a random number generator +* @param work_factor how much work to do to slow down guessing attacks +* @param flags should be 0 in current API revision, all other uses are reserved +* and return BOTAN_FFI_ERROR_BAD_FLAG +* @return 0 on success, a negative value on failure + * Output is formatted bcrypt $2a$... */ BOTAN_DLL int botan_bcrypt_generate(uint8_t* out, size_t* out_len, @@ -290,9 +454,12 @@ BOTAN_DLL int botan_bcrypt_generate(uint8_t* out, size_t* out_len, uint32_t flags); /** -* Returns 0 if if this password/hash combination is valid -* Returns 1 if the combination is not valid (but otherwise well formed) -* Returns negative on error +* Check a previously created password hash +* @param pass the password to check against +* @param hash the stored hash to check against +* @return 0 if if this password/hash combination is valid, +* 1 if the combination is not valid (but otherwise well formed), +* negative on error */ BOTAN_DLL int botan_bcrypt_is_valid(const char* pass, const char* hash); |