*/
/**
- * @brief YACA_CTX_NULL NULL value for the crypto context.
+ * @brief NULL value for the crypto context.
*/
#define YACA_CTX_NULL ((yaca_ctx_h) NULL)
/**
- * @brief yaca_init Initializes the library. Must be called before any other crypto function.
+ * @brief Initializes the library. Must be called before any other crypto function.
*
* @return 0 on success, negative on error.
* @see yaca_exit()
int yaca_init(void);
/**
- * @brief yaca_exit Closes the library. Must be called before exiting the application.
+ * @brief Closes the library. Must be called before exiting the application.
*
* @see yaca_init()
*/
void yaca_exit(void);
/**
- * @brief yaca_malloc Allocates the memory.
+ * @brief Allocates the memory.
*
* @param[in] size Size of the allocation (bytes).
*
void *yaca_malloc(size_t size);
/**
- * @brief yaca_zalloc Allocates the zeroed memory.
+ * @brief Allocates the zeroed memory.
*
* @param[in] size Size of the allocation (bytes).
*
void *yaca_zalloc(size_t size);
/**
- * @brief yaca_realloc Re-allocates the memory.
+ * @brief Re-allocates the memory.
*
* @param[in] addr Address of the memory to be reallocated.
* @param[in] size Size of the new allocation (bytes).
void *yaca_realloc(void *addr, size_t size);
/**
- * @brief yaca_free Frees the memory allocated by yaca_malloc(), yaca_zalloc(),
- * yaca_realloc() or one of the cryptographic operations.
+ * @brief Frees the memory allocated by yaca_malloc(), yaca_zalloc(),
+ * yaca_realloc() or one of the cryptographic operations.
*
* @param[in] ptr Pointer to the memory to be freed.
* @see yaca_malloc(), yaca_zalloc(), yaca_realloc()
void yaca_free(void *ptr);
/**
- * @brief yaca_rand_bytes Generates random data.
+ * @brief Generates random data.
*
* @param[in,out] data Pointer to the memory to be randomized.
* @param[in] data_len Length of the memory to be randomized.
int yaca_rand_bytes(char *data, size_t data_len);
/**
- * @brief yaca_ctx_set_param Sets the extended context parameters.
- * Can only be called on an initialized context.
+ * @brief Sets the extended context parameters. Can only be called on an
+ * initialized context.
*
* @param[in,out] ctx Previously initialized crypto context.
* @param[in] param Parameter to be set.
size_t value_len);
/**
- * @brief yaca_ctx_get_param Returns the extended context parameters.
- * Can only be called on an initialized context.
+ * @brief Returns the extended context parameters. Can only be called on an
+ * initialized context.
*
* @param[in] ctx Previously initialized crypto context.
* @param[in] param Parameter to be read.
size_t *value_len);
/**
- * @brief yaca_ctx_free Destroys the crypto context. Must be called
- * on all contexts that are no longer used.
- * Passing YACA_CTX_NULL is allowed.
+ * @brief Destroys the crypto context. Must be called on all contexts that are
+ * no longer used. Passing YACA_CTX_NULL is allowed.
*
* @param[in,out] ctx Crypto context.
* @see #yaca_ctx_h
void yaca_ctx_free(yaca_ctx_h ctx);
/**
- * @brief yaca_get_output_length Returns the output length for a given algorithm.
- * Can only be called on an initialized context.
+ * @brief Returns the output length for a given algorithm. Can only be called
+ * on an initialized context.
*
* @param[in] ctx Previously initialized crypto context.
* @param[in] input_len Length of the input data to be processed.
int yaca_get_output_length(const yaca_ctx_h ctx, size_t input_len);
/**
- * @brief yaca_get_digest_length Wrapper - returns the length of the digest (for a given context).
+ * @brief Wrapper - returns the length of the digest (for a given context).
*/
#define yaca_get_digest_length(ctxa) yaca_get_output_length((ctxa), 0)
/**
- * @brief yaca_get_sign_length Wrapper - returns the length of the signature (for a given context).
+ * @brief Wrapper - returns the length of the signature (for a given context).
*/
#define yaca_get_sign_length(ctxa) yaca_get_output_length((ctxa), 0)
/**
- * @brief yaca_get_block_length Wrapper - returns the length of the block (for a given context).
+ * @brief Wrapper - returns the length of the block (for a given context).
*/
#define yaca_get_block_length(ctxa) yaca_get_output_length((ctxa), 0)
*/
/**
- * @brief yaca_digest_init Initializes a digest context.
+ * @brief Initializes a digest context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
int yaca_digest_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo);
/**
- * @brief yaca_digest_update Feeds the data into the message digest algorithm.
+ * @brief Feeds the data into the message digest algorithm.
*
* @param[in,out] ctx Context created by yaca_digest_init().
* @param[in] data Data from which the digest is to be calculated.
int yaca_digest_update(yaca_ctx_h ctx, const char *data, size_t data_len);
/**
- * @brief yaca_digest_final Calculates the final digest.
+ * @brief Calculates the final digest.
*
* @param[in,out] ctx A valid digest context.
* @param[out] digest Buffer for the message digest (must be allocated by client,
*/
/**
- * @brief yaca_encrypt_init Initializes an encryption context.
+ * @brief Initializes an encryption context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Encryption algorithm that will be used.
const yaca_key_h iv);
/**
- * @brief yaca_encrypt_update Encrypts chunk of the data.
+ * @brief Encrypts chunk of the data.
*
* @param[in,out] ctx Context created by yaca_encrypt_init().
* @param[in] plain Plain text to be encrypted.
size_t *cipher_len);
/**
- * @brief yaca_encrypt_final Encrypts the final chunk of the data.
+ * @brief Encrypts the final chunk of the data.
*
* @param[in,out] ctx A valid encrypt context.
* @param[out] cipher Final piece of the encrypted data (must be allocated by client, see
size_t *cipher_len);
/**
- * @brief yaca_decrypt_init Initializes an decryption context.
+ * @brief Initializes an decryption context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Encryption algorithm that was used to encrypt the data.
const yaca_key_h iv);
/**
- * @brief yaca_decrypt_update Decrypts chunk of the data.
+ * @brief Decrypts chunk of the data.
*
* @param[in,out] ctx Context created by yaca_decrypt_init().
* @param[in] cipher Cipher text to be decrypted.
size_t *plain_len);
/**
- * @brief yaca_decrypt_final Decrypts the final chunk of the data.
+ * @brief Decrypts the final chunk of the data.
*
* @param[in,out] ctx A valid decrypt context.
* @param[out] plain Final piece of the decrypted data (must be allocated by client, see
size_t *plain_len);
/**
- * @brief yaca_get_iv_bits Returns the recomended/default length of the IV for a given encryption configuration.
+ * @brief Returns the recomended/default length of the IV for a given encryption configuration.
*
* @param[in] algo Encryption algorithm.
* @param[in] bcm Chain mode.
typedef void (*yaca_debug_func)(const char*);
/**
- * @brief yaca_error_set_debug_func Sets a current thread debug callback that will be called each
- * time an internal error occurs. A NULL terminated string with
- * location and description of the error will be passed as an
- * argument.
+ * @brief Sets a current thread debug callback that will be called each time an
+ * internal error occurs. A NULL terminated string with location and
+ * description of the error will be passed as an argument.
*
- * @param[in] fn Function to set as internal error callback.
+ * @param[in] fn Function to set as internal error callback.
*/
void yaca_error_set_debug_func(yaca_debug_func fn);
// TODO: We need a way to import keys encrypted with hw (or other) keys. New function like yaca_key_load or sth??
/**
- * @brief yaca_key_get_bits Get key's length (in bits).
+ * @brief Get key's length (in bits).
*
* @param[in] key Key which length we return.
*
int yaca_key_get_bits(const yaca_key_h key);
/**
- * @brief yaca_key_import Imports a key.
+ * @brief Imports a key.
*
* This function imports a key trying to match it to the key_type specified.
* It should autodetect both, key format and file format.
size_t data_len);
/**
- * @brief yaca_key_export Exports a key to arbitrary format. Export may fail if key is HW-based.
+ * @brief Exports a key to arbitrary format. Export may fail if key is HW-based.
*
* This function exports the key to an arbitrary key format and key file format.
*
size_t *data_len);
/**
- * @brief yaca_key_gen Generates a secure key (or an initialization vector).
+ * @brief Generates a secure key (or an initialization vector).
*
* This function is used to generate symmetric and private asymmetric keys.
*
size_t key_bits);
/**
- * @brief yaca_key_extract_public Extracts public key from a private one.
+ * @brief Extracts public key from a private one.
*
* @param[in] prv_key Private key to extract the public one from.
* @param[out] pub_key Extracted public key (must be freed with yaca_key_free()).
int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key);
/**
- * @brief yaca_key_free Frees the key created by the library.
- * Passing YACA_KEY_NULL is allowed.
+ * @brief Frees the key created by the library. Passing YACA_KEY_NULL is allowed.
*
* @param key Key to be freed.
* @see yaca_key_import(), yaca_key_export(), yaca_key_gen()
*/
/**
- * @brief yaca_key_derive_dh Derives a key using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.
+ * @brief Derives a key using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.
*
* @param[in] prv_key Our private key.
* @param[in] pub_key Peer public key.
yaca_key_h *sym_key);
/**
- * @brief yaca_key_derive_kea Derives a key using KEA key exchange protocol.
+ * @brief Derives a key using KEA key exchange protocol.
*
* @param[in] prv_key Our DH private component.
* @param[in] pub_key Peers' DH public component.
yaca_key_h *sym_key);
/**
- * @brief yaca_key_derive_pbkdf2 Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
+ * @brief Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
*
* @param[in] password User password as a NULL-terminated string.
* @param[in] salt Salt, should be non-zero.
*/
/**
- * @brief yaca_seal_init Initializes an asymmetric encryption context.
+ * @brief Initializes an asymmetric encryption context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] pub_key Public key of the peer that will receive the encrypted data.
yaca_key_h *iv);
/**
- * @brief yaca_seal_update Encrypts piece of the data.
+ * @brief Encrypts piece of the data.
*
* @param[in,out] ctx Context created by yaca_seal_init().
* @param[in] plain Plain text to be encrypted.
size_t *cipher_len);
/**
- * @brief yaca_seal_final Encrypts the final piece of the data.
+ * @brief Encrypts the final piece of the data.
*
* @param[in,out] ctx A valid seal context.
* @param[out] cipher Final piece of the encrypted data (must be allocated by client, see
size_t *cipher_len);
/**
- * @brief yaca_open_init Initializes an asymmetric decryption context.
+ * @brief Initializes an asymmetric decryption context.
*
* @param[out] ctx Newly created context. Must be freed by yaca_ctx_free().
* @param[in] prv_key Private key, part of the pair that was used for the encryption.
const yaca_key_h iv);
/**
- * @brief yaca_open_update Decrypts piece of the data.
+ * @brief Decrypts piece of the data.
*
* @param[in,out] ctx Context created by yaca_open_init().
* @param[in] cipher Cipher text to be decrypted.
size_t *plain_len);
/**
- * @brief yaca_open_final Decrypts last chunk of sealed message.
+ * @brief Decrypts last chunk of sealed message.
*
* @param[in,out] ctx A valid open context.
* @param[out] plain Final piece of the decrypted data (must be allocated by client, see
*/
/**
- * @brief yaca_sign_init Initializes a signature context.
+ * @brief Initializes a signature context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
const yaca_key_h key);
/**
- * @brief yaca_sign_update Feeds the data into the digital signature algorithm.
+ * @brief Feeds the data into the digital signature algorithm.
*
* @param[in,out] ctx Context created by yaca_sign_init().
* @param[in] data Data to be signed.
size_t data_len);
/**
- * @brief yaca_sign_final Calculates the final signature.
+ * @brief Calculates the final signature.
*
* @param[in,out] ctx A valid sign context.
* @param[out] mac Buffer for the MAC or the signature (must be allocated by client, see
size_t *mac_len);
/**
- * @brief yaca_verify_init Initializes a signature verification context.
+ * @brief Initializes a signature verification context.
*
* @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
const yaca_key_h key);
/**
- * @brief yaca_verify_update Feeds the data into the digital signature verification algorithm.
+ * @brief Feeds the data into the digital signature verification algorithm.
*
* @param[in,out] ctx Context created by yaca_verify_init().
* @param[in] data Data to be verified.
size_t data_len);
/**
- * @brief yaca_verify_final Performs the verification.
+ * @brief Performs the verification.
*
* @param[in,out] ctx A valid verify context.
* @param[in] mac Input MAC or signature (returned by yaca_sign_final()).
*/
/**
- * @brief yaca_digest_calc Calculate a digest of a buffer.
+ * @brief Calculate a digest of a buffer.
*
* @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure).
* @param[in] data Data from which the digest is to be calculated.
size_t *digest_len);
/**
- * @brief yaca_encrypt Encrypt data using a symmetric cipher.
+ * @brief Encrypt data using a symmetric cipher.
*
* @param[in] algo Encryption algorithm (select #YACA_ENC_AES if unsure).
* @param[in] bcm Chaining mode (select #YACA_BCM_CBC if unsure).
size_t *cipher_len);
/**
- * @brief yaca_decrypt Decrypta data using a symmetric cipher.
+ * @brief Decrypt data using a symmetric cipher.
*
* @param[in] algo Decryption algorithm that was used to encrypt the data.
* @param[in] bcm Chaining mode that was used to encrypt the data.