Document hash, rng, mac, pbkdf and kdf in ffi handbook

2 files changed, 244 insertions, 58 deletions

diff --git a/doc/manual/ffi.rst b/doc/manual/ffi.rst
index 41907e47e..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,7 +19,7 @@ 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)
 
    Returns 0 iff the FFI version specified is supported by this
    library. Otherwise returns -1. The expression
@@ -28,31 +29,31 @@ Versioning
 
 .. cpp:function:: const char* botan_version_string()
 
-    Returns a free-from version string, e.g., 2.0.0
+   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], or otherwise -1
+   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)
 
@@ -71,47 +72,57 @@ Random Number Generators
 
 .. 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
 
@@ -120,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
 ----------------------------------------
@@ -173,17 +201,26 @@ PBKDF
 
 .. cpp:function:: 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 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* password, \
+                                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
 ----------------------------------------
 
@@ -193,6 +230,9 @@ KDF
                         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
 ----------------------------------------
 
@@ -202,8 +242,17 @@ Password Hashing
                                     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
 ----------------------------------------
 
diff --git a/src/lib/ffi/ffi.h b/src/lib/ffi/ffi.h
index 672c17a07..264c3d24d 100644
--- a/src/lib/ffi/ffi.h
+++ b/src/lib/ffi/ffi.h
@@ -61,40 +61,40 @@ how to provide the cleanest API for such users would be most welcome.
 #include <stdint.h>
 #include <stddef.h>
 
-/*
+/**
 * 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
 */
@@ -142,14 +142,14 @@ 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
@@ -162,48 +162,80 @@ BOTAN_DLL int botan_hex_encode(const uint8_t* x, size_t len, char* out, uint32_t
 // 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);
 
@@ -211,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);
 
 /*
@@ -284,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,
@@ -308,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,
@@ -320,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);