Merge GH #886 Improve ffi docs

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);