#endif
/**
- * @defgroup Non-Crypto Non crypto related functions.
+ * @defgroup Non-Crypto Yet Another Crypto API - non crypto related functions.
*
* TODO: extended description and examples.
*
/**
* @brief yaca_init Initializes the library. Must be called before any other crypto function.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @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.
*
+ * @see yaca_init()
*/
void yaca_exit(void);
* @param[in] size Size of the allocation (bytes).
*
* @return NULL on failure, pointer to allocated memory otherwise.
+ * @see yaca_zalloc(), yaca_realloc(), yaca_free()
*/
// TODO: this should be a macro to CRYPTO_*
void *yaca_malloc(size_t size);
* @param[in] size Size of the allocation (bytes).
*
* @return NULL on failure, pointer to allocated and zeroed memory otherwise.
+ * @see yaca_malloc(), yaca_realloc(), yaca_free()
*/
// TODO: this should be a macro to CRYPTO_*
void *yaca_zalloc(size_t size);
* @param[in] size Size of the new allocation (bytes).
*
* @return NULL on failure, pointer to allocated memory otherwise.
+ * @see yaca_malloc(), yaca_zalloc(), yaca_free()
*/
// TODO: this should be a macro to CRYPTO_*
void *yaca_realloc(void *addr, size_t size);
/**
- * @brief yaca_free Frees the memory allocated by @see yaca_malloc
- * or one of the cryptographics operations.
+ * @brief yaca_free 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()
*
*/
// TODO: this should be a macro to CRYPTO_*
* @param[in,out] data Pointer to the memory to be randomized.
* @param[in] data_len Length of the memory to be randomized.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
*/
int yaca_rand_bytes(char *data, size_t data_len);
* @param[in] value Parameter value.
* @param[in] value_len Length of the parameter value.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_ex_param_e, yaca_ctx_get_param()
*/
-int yaca_ctx_set_param(yaca_ctx_h ctx, yaca_ex_param_e param,
- const void *value, size_t value_len);
+int yaca_ctx_set_param(yaca_ctx_h ctx,
+ yaca_ex_param_e param,
+ const void *value,
+ size_t value_len);
/**
* @brief yaca_ctx_get_param Returns the extended context parameters.
*
* @param[in] ctx Previously initialized crypto context.
* @param[in] param Parameter to be read.
- * @param[out] value Copy of the parameter value (must be freed with @see yaca_free).
+ * @param[out] value Copy of the parameter value (must be freed with yaca_free()).
* @param[out] value_len Length of the parameter value will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_ex_param_e, yaca_ctx_set_param()
*/
-int yaca_ctx_get_param(const yaca_ctx_h ctx, yaca_ex_param_e param,
- void **value, size_t *value_len);
+int yaca_ctx_get_param(const yaca_ctx_h ctx,
+ yaca_ex_param_e param,
+ void **value,
+ size_t *value_len);
/**
* @brief yaca_ctx_free Destroys the crypto context. Must be called
* Passing YACA_CTX_NULL is allowed.
*
* @param[in,out] ctx Crypto context.
+ * @see #yaca_ctx_h
*
*/
void yaca_ctx_free(yaca_ctx_h ctx);
* @param[in] ctx Previously initialized crypto context.
* @param[in] input_len Length of the input data to be processed.
*
- * @return negative on error (@see error.h) or length of output.
+ * @return negative on error or length of output.
*/
// TODO: this function should probably return the value by param of
// size_t type and leave the return int value only to report errors
/**
* @brief yaca_digest_init Initializes a digest context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_digest_algo_e, yaca_digest_update(), yaca_digest_final()
*/
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.
*
- * @param[in,out] ctx Context created by @see yaca_digest_init.
+ * @param[in,out] ctx Context created by yaca_digest_init().
* @param[in] data Data from which the digest is to be calculated.
* @param[in] data_len Length of the data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_digest_init(), yaca_digest_final()
*/
int yaca_digest_update(yaca_ctx_h ctx, const char *data, size_t data_len);
* @brief yaca_digest_final 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, @see yaca_get_digest_length).
+ * @param[out] digest Buffer for the message digest (must be allocated by client,
+ * see yaca_get_digest_length()).
* @param[out] digest_len Length of the digest, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_digest_init(), yaca_digest_update()
*/
int yaca_digest_final(yaca_ctx_h ctx, char *digest, size_t *digest_len);
/**
* @brief yaca_encrypt_init Initializes an encryption context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Encryption algorithm that will be used.
* @param[in] bcm Chaining mode that will be used.
* @param[in] sym_key Symmetric key that will be used.
* @param[in] iv Initialization vector that will be used.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_encrypt_update(), yaca_encrypt_final()
*/
int yaca_encrypt_init(yaca_ctx_h *ctx,
- yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- const yaca_key_h sym_key,
- const yaca_key_h iv);
+ yaca_enc_algo_e algo,
+ yaca_block_cipher_mode_e bcm,
+ const yaca_key_h sym_key,
+ const yaca_key_h iv);
/**
* @brief yaca_encrypt_update Encrypts chunk of the data.
*
- * @param[in,out] ctx Context created by @see yaca_encrypt_init.
+ * @param[in,out] ctx Context created by yaca_encrypt_init().
* @param[in] plain Plain text to be encrypted.
* @param[in] plain_len Length of the plain text.
- * @param[out] cipher Buffer for the encrypted data (must be allocated by client, @see yaca_get_output_length).
+ * @param[out] cipher Buffer for the encrypted data (must be allocated by client, see
+ * yaca_get_output_length()).
* @param[out] cipher_len Length of the encrypted data, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_encrypt_init(), yaca_encrypt_final()
*/
int yaca_encrypt_update(yaca_ctx_h ctx,
- const char *plain,
- size_t plain_len,
- char *cipher,
- size_t *cipher_len);
+ const char *plain,
+ size_t plain_len,
+ char *cipher,
+ size_t *cipher_len);
/**
* @brief yaca_encrypt_final 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 yaca_get_block_length).
+ * @param[out] cipher Final piece of the encrypted data (must be allocated by client, see
+ * yaca_get_block_length()).
* @param[out] cipher_len Length of the final piece, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_encrypt_init(), yaca_encrypt_update()
*/
int yaca_encrypt_final(yaca_ctx_h ctx,
- char *cipher,
- size_t *cipher_len);
+ char *cipher,
+ size_t *cipher_len);
/**
* @brief yaca_decrypt_init Initializes an decryption context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @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.
* @param[in] bcm Chaining mode that was used to encrypt the data.
* @param[in] sym_key Symmetric key that was used to encrypt the data.
* @param[in] iv Initialization vector that was used to encrypt the data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_decrypt_update(), yaca_decrypt_final()
*/
int yaca_decrypt_init(yaca_ctx_h *ctx,
- yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- const yaca_key_h sym_key,
- const yaca_key_h iv);
+ yaca_enc_algo_e algo,
+ yaca_block_cipher_mode_e bcm,
+ const yaca_key_h sym_key,
+ const yaca_key_h iv);
/**
* @brief yaca_decrypt_update Decrypts chunk of the data.
*
- * @param[in,out] ctx Context created by @see yaca_decrypt_init.
+ * @param[in,out] ctx Context created by yaca_decrypt_init().
* @param[in] cipher Cipher text to be decrypted.
* @param[in] cipher_len Length of the cipher text.
- * @param[out] plain Buffer for the decrypted data (must be allocated by client, @see yaca_get_output_length).
+ * @param[out] plain Buffer for the decrypted data (must be allocated by client, see
+ * yaca_get_output_length()).
* @param[out] plain_len Length of the decrypted data, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_decrypt_init(), yaca_decrypt_final()
*/
int yaca_decrypt_update(yaca_ctx_h ctx,
- const char *cipher,
- size_t cipher_len,
- char *plain,
- size_t *plain_len);
+ const char *cipher,
+ size_t cipher_len,
+ char *plain,
+ size_t *plain_len);
/**
* @brief yaca_decrypt_final 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 yaca_get_block_length).
+ * @param[out] plain Final piece of the decrypted data (must be allocated by client, see
+ * yaca_get_block_length()).
* @param[out] plain_len Length of the final piece, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_decrypt_init(), yaca_decrypt_update()
*/
int yaca_decrypt_final(yaca_ctx_h ctx,
- char *plain,
- size_t *plain_len);
+ char *plain,
+ size_t *plain_len);
/**
* @brief yaca_get_iv_bits Returns the recomended/default length of the IV for a given encryption configuration.
*
* @param[in] algo Encryption algorithm.
* @param[in] bcm Chain mode.
- * @param[in] key_bits Key length in bits (@see crypto_key_len_e).
+ * @param[in] key_bits Key length in bits.
*
- * @return negative on error (@see error.h) or the IV length in bits.
+ * @return negative on error or the IV length in bits.
*/
int yaca_get_iv_bits(yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- size_t key_bits);
+ yaca_block_cipher_mode_e bcm,
+ size_t key_bits);
/**@}*/
#ifndef ERROR_H
#define ERROR_H
-/*
- TODO: Error enums should be placed here
- */
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * @defgroup Error Yet another Crypto API - error enums and debug functions.
+ *
+ * @{
+ */
+
+/**
+ * @brief Error enums
+ */
enum __yaca_error_code {
- YACA_ERROR_INVALID_ARGUMENT = -1,
- YACA_ERROR_NOT_IMPLEMENTED = -2,
- YACA_ERROR_OPENSSL_FAILURE = -3,
- YACA_ERROR_NOT_SUPPORTED = -4,
- YACA_ERROR_TOO_BIG_ARGUMENT = -5,
- YACA_ERROR_OUT_OF_MEMORY = -6,
- YACA_ERROR_SIGNATURE_INVALID = -7
+ YACA_ERROR_INVALID_ARGUMENT = -1,
+ YACA_ERROR_NOT_IMPLEMENTED = -2,
+ YACA_ERROR_OPENSSL_FAILURE = -3,
+ YACA_ERROR_NOT_SUPPORTED = -4,
+ YACA_ERROR_TOO_BIG_ARGUMENT = -5,
+ YACA_ERROR_OUT_OF_MEMORY = -6,
+ YACA_ERROR_SIGNATURE_INVALID = -7
};
// TODO disable debug function in release?
*/
void yaca_error_set_debug_func(yaca_debug_func fn);
+/**@}*/
#ifdef __cplusplus
} /* extern */
#endif
/**
- * @defgroup Key Key and IV handling functions
+ * @defgroup Key Advanced API for the key and IV handling.
*
* TODO: extended description and examples.
*
*
* @param[in] key Key which length we return.
*
- * @return negative on error (@see error.h) or key length (in bits).
+ * @return negative on error or key length (in bits).
*/
int yaca_key_get_bits(const yaca_key_h key);
/**
* @brief yaca_key_import Imports a key from the arbitrary format.
*
- * @param[out] key Returned key (must be freed with @see yaca_key_free).
+ * @param[out] key Returned key (must be freed with yaca_key_free()).
* @param[in] key_fmt Format of the key.
* @param[in] key_type Type of the key.
* @param[in] data Blob containing the key.
* @param[in] data_len Size of the blob.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_key_fmt_e, #yaca_key_type_e, yaca_key_export(), yaca_key_free()
*/
int yaca_key_import(yaca_key_h *key,
- yaca_key_fmt_e key_fmt,
- yaca_key_type_e key_type,
- const char *data,
- size_t data_len);
+ yaca_key_fmt_e key_fmt,
+ yaca_key_type_e key_type,
+ const char *data,
+ size_t data_len);
/**
* @brief yaca_key_export Exports a key to arbitrary format. Export may fail if key is HW-based.
*
* @param[in] key Key to be exported.
* @param[in] key_fmt Format of the key.
- * @param[out] data Data, allocated by the library, containing exported key (must be freed with @see yaca_free).
+ * @param[out] data Data, allocated by the library, containing exported key
+ * (must be freed with yaca_free()).
* @param[out] data_len Size of the output data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_key_fmt_e, yaca_key_import(), yaca_key_free()
*/
int yaca_key_export(const yaca_key_h key,
- yaca_key_fmt_e key_fmt,
- char **data,
- size_t *data_len);
-
-// TODO: still a matter of ordering, should the key in key_gen functions be first or last?
+ yaca_key_fmt_e key_fmt,
+ char **data,
+ size_t *data_len);
/**
* @brief yaca_key_gen Generates a secure symmetric key (or an initialization vector).
*
- * @param[out] sym_key Newly generated key (must be freed with @see yaca_key_free).
+ * @param[out] sym_key Newly generated key (must be freed with yaca_key_free()).
* @param[in] key_type Type of the key to be generated.
* @param[in] key_bits Length of the key (in bits) to be generated.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_key_type_e, #yaca_key_bits_e, yaca_key_gen_pair(), yaca_key_free()
*/
int yaca_key_gen(yaca_key_h *sym_key,
- yaca_key_type_e key_type,
- size_t key_bits);
+ yaca_key_type_e key_type,
+ size_t key_bits);
/**
* @brief yaca_key_gen_pair Generates a new key pair.
*
- * @param[out] prv_key Newly generated private key (must be freed with @see yaca_key_free).
- * @param[out] pub_key Newly generated public key (must be freed with @see yaca_key_free).
+ * @param[out] prv_key Newly generated private key (must be freed with yaca_key_free()).
+ * @param[out] pub_key Newly generated public key (must be freed with yaca_key_free()).
* @param[in] key_type Type of the key to be generated (must be YACA_KEY_TYPE_PAIR*).
* @param[in] key_bits Length of the key (in bits) to be generated.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_key_type_e, #yaca_key_bits_e, yaca_key_gen(), yaca_key_free()
*/
int yaca_key_gen_pair(yaca_key_h *prv_key,
- yaca_key_h *pub_key,
- yaca_key_type_e key_type,
- size_t key_bits);
+ yaca_key_h *pub_key,
+ yaca_key_type_e key_type,
+ size_t key_bits);
/**
* @brief yaca_key_free 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(), yaca_key_gen_pair()
*
*/
void yaca_key_free(yaca_key_h key);
/**@}*/
/**
- * @defgroup Key-Derivation Key derivation functions
+ * @defgroup Key-Derivation Advanced API for the key derivation.
*
* TODO: rethink separate group.
* TODO: extended description and examples.
*
* @param[in] prv_key Our private key.
* @param[in] pub_key Peer public key.
- * @param[out] sym_key Shared secret, that can be used as a symmetric key (must be freed with @see yaca_key_free).
+ * @param[out] sym_key Shared secret, that can be used as a symmetric key
+ * (must be freed with yaca_key_free()).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
*/
int yaca_key_derive_dh(const yaca_key_h prv_key,
- const yaca_key_h pub_key,
- yaca_key_h *sym_key);
+ const yaca_key_h pub_key,
+ yaca_key_h *sym_key);
/**
* @brief yaca_key_derive_kea Derives a key using KEA key exchange protocol.
* DH public component sent to peer to verify our identity.
* @param[in] pub_key_auth Peers' public key used for signature verification
* of pub_key from peer (peer authentication).
- * @param[out] sym_key Shared secret, that can be used as a symmetric key (must be freed with @see yaca_key_free).
+ * @param[out] sym_key Shared secret, that can be used as a symmetric key
+ * (must be freed with yaca_key_free()).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
*/
int yaca_key_derive_kea(const yaca_key_h prv_key,
- const yaca_key_h pub_key,
- const yaca_key_h prv_key_auth,
- const yaca_key_h pub_key_auth,
- yaca_key_h *sym_key);
+ const yaca_key_h pub_key,
+ const yaca_key_h prv_key_auth,
+ const yaca_key_h pub_key_auth,
+ yaca_key_h *sym_key);
/**
* @brief yaca_key_derive_pbkdf2 Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
* @param[in] iter Number of iterations. (TODO: add enum to proposed number of iterations, pick sane defaults).
* @param[in] algo Digest algorithm that should be used in key generation. (TODO: sane defaults).
* @param[in] key_bits Length of a key (in bits) to be generated.
- * @param[out] key Newly generated key (must be freed with @see yaca_key_free).
+ * @param[out] key Newly generated key (must be freed with yaca_key_free()).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
*/
int yaca_key_derive_pbkdf2(const char *password,
- const char *salt,
- size_t salt_len,
- int iter,
- yaca_digest_algo_e algo,
- size_t key_bits,
- yaca_key_h *key);
+ const char *salt,
+ size_t salt_len,
+ int iter,
+ yaca_digest_algo_e algo,
+ size_t key_bits,
+ yaca_key_h *key);
// TODO: specify
//int yaca_key_wrap(yaca_key_h key, ??);
/**
* @brief yaca_seal_init Initializes an asymmetric encryption context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @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.
* @param[in] algo Symmetric algorithm that will be used.
* @param[in] bcm Block chaining mode for the symmetric algorithm.
* @param[out] sym_key Generated symmetric key that will be used. It is encrypted with peer's public key.
* @param[out] iv Generated initialization vector that will be used.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_seal_update(), yaca_seal_final()
*/
int yaca_seal_init(yaca_ctx_h *ctx,
- const yaca_key_h pub_key,
- yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- yaca_key_bits_e sym_key_bits,
- yaca_key_h *sym_key,
- yaca_key_h *iv);
+ const yaca_key_h pub_key,
+ yaca_enc_algo_e algo,
+ yaca_block_cipher_mode_e bcm,
+ yaca_key_bits_e sym_key_bits,
+ yaca_key_h *sym_key,
+ yaca_key_h *iv);
/**
* @brief yaca_seal_update Encrypts piece of the data.
*
- * @param[in,out] ctx Context created by @see yaca_seal_init.
+ * @param[in,out] ctx Context created by yaca_seal_init().
* @param[in] plain Plain text to be encrypted.
* @param[in] plain_len Length of the plain text.
- * @param[out] cipher Buffer for the encrypted data (must be allocated by client, @see yaca_get_output_length).
+ * @param[out] cipher Buffer for the encrypted data (must be allocated by client, see
+ * yaca_get_output_length()).
* @param[out] cipher_len Length of the encrypted data, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_seal_init(), yaca_seal_final()
*/
int yaca_seal_update(yaca_ctx_h ctx,
- const char *plain,
- size_t plain_len,
- char *cipher,
- size_t *cipher_len);
+ const char *plain,
+ size_t plain_len,
+ char *cipher,
+ size_t *cipher_len);
/**
* @brief yaca_seal_final 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 yaca_get_block_length).
+ * @param[out] cipher Final piece of the encrypted data (must be allocated by client, see
+ * yaca_get_block_length()).
* @param[out] cipher_len Length of the final piece, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_seal_init(), yaca_seal_update()
*/
int yaca_seal_final(yaca_ctx_h ctx,
- char *cipher,
- size_t *cipher_len);
+ char *cipher,
+ size_t *cipher_len);
/**
* @brief yaca_open_init Initializes an asymmetric decryption context.
*
- * @param[out] ctx Newly created context. Must be freed by @see yaca_ctx_free.
+ * @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.
* @param[in] algo Symmetric algorithm that was used for the encryption.
* @param[in] bcm Block chaining mode for the symmetric algorithm.
* @param[in] sym_key Symmetric key, encrypted with the public key, that was used to encrypt the data.
* @param[in] iv Initialization vector that was used for the encryption.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_open_update(), yaca_open_final()
*/
int yaca_open_init(yaca_ctx_h *ctx,
- const yaca_key_h prv_key,
- yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- yaca_key_bits_e sym_key_bits,
- const yaca_key_h sym_key,
- const yaca_key_h iv);
+ const yaca_key_h prv_key,
+ yaca_enc_algo_e algo,
+ yaca_block_cipher_mode_e bcm,
+ yaca_key_bits_e sym_key_bits,
+ const yaca_key_h sym_key,
+ const yaca_key_h iv);
/**
* @brief yaca_open_update Decrypts piece of the data.
*
- * @param[in,out] ctx Context created by @see yaca_open_init.
+ * @param[in,out] ctx Context created by yaca_open_init().
* @param[in] cipher Cipher text to be decrypted.
* @param[in] cipher_len Length of the cipher text.
- * @param[out] plain Buffer for the decrypted data (must be allocated by client, @see yaca_get_output_length).
+ * @param[out] plain Buffer for the decrypted data (must be allocated by client, see
+ * yaca_get_output_length()).
* @param[out] plain_len Length of the decrypted data, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_open_init(), yaca_open_final()
*/
int yaca_open_update(yaca_ctx_h ctx,
- const char *cipher,
- size_t cipher_len,
- char *plain,
- size_t *plain_len);
+ const char *cipher,
+ size_t cipher_len,
+ char *plain,
+ size_t *plain_len);
/**
* @brief yaca_open_final 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 yaca_get_block_length).
+ * @param[out] plain Final piece of the decrypted data (must be allocated by client, see
+ * yaca_get_block_length()).
* @param[out] plain_len Length of the final piece, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_open_init(), yaca_open_update()
*/
int yaca_open_final(yaca_ctx_h ctx,
- char *plain,
- size_t *plain_len);
+ char *plain,
+ size_t *plain_len);
/**@}*/
/**
* @brief yaca_sign_init Initializes a signature context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
* @param[in] key Private or symmetric key that will be used (algorithm is deduced based on key type).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_digest_algo_e, yaca_sign_update(), yaca_sign_final()
*/
int yaca_sign_init(yaca_ctx_h *ctx,
- yaca_digest_algo_e algo,
- const yaca_key_h key);
+ yaca_digest_algo_e algo,
+ const yaca_key_h key);
/**
* @brief yaca_sign_update Feeds the data into the digital signature algorithm.
*
- * @param[in,out] ctx Context created by @see yaca_sign_init.
+ * @param[in,out] ctx Context created by yaca_sign_init().
* @param[in] data Data to be signed.
* @param[in] data_len Length of the data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_sign_init(), yaca_sign_final()
*/
int yaca_sign_update(yaca_ctx_h ctx,
- const char *data,
- size_t data_len);
+ const char *data,
+ size_t data_len);
/**
* @brief yaca_sign_final 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 yaca_get_sign_length).
+ * @param[out] mac Buffer for the MAC or the signature (must be allocated by client, see
+ * yaca_get_sign_length()).
* @param[out] mac_len Length of the MAC or the signature, actual number of bytes written will be returned here.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_sign_init(), yaca_sign_update()
*/
int yaca_sign_final(yaca_ctx_h ctx,
- char *mac,
- size_t *mac_len);
+ char *mac,
+ size_t *mac_len);
/**
* @brief yaca_verify_init Initializes a signature verification context.
*
- * @param[out] ctx Newly created context (must be freed with @see yaca_ctx_free).
+ * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()).
* @param[in] algo Digest algorithm that will be used.
* @param[in] key Private or symmetric key that will be used (algorithm is deduced based on key type).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_digest_algo_e, yaca_verify_update(), yaca_verify_final()
*/
int yaca_verify_init(yaca_ctx_h *ctx,
- yaca_digest_algo_e algo,
- const yaca_key_h key);
+ yaca_digest_algo_e algo,
+ const yaca_key_h key);
/**
* @brief yaca_verify_update Feeds the data into the digital signature verification algorithm.
*
- * @param[in,out] ctx Context created by @see yaca_verify_init.
+ * @param[in,out] ctx Context created by yaca_verify_init().
* @param[in] data Data to be verified.
* @param[in] data_len Length of the data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see yaca_verify_init(), yaca_verify_final()
*/
int yaca_verify_update(yaca_ctx_h ctx,
- const char *data,
- size_t data_len);
+ const char *data,
+ size_t data_len);
/**
* @brief yaca_verify_final Performs the verification.
*
* @param[in,out] ctx A valid verify context.
- * @param[in] mac Input MAC or signature (returned by @see yaca_sign_final).
+ * @param[in] mac Input MAC or signature (returned by yaca_sign_final()).
* @param[in] mac_len Size of the MAC or the signature.
*
- * @return 0 on success, negative on error (@see error.h).
- * TODO: YACA_ERROR_SIGNATURE_INVALID when verification fails.
+ * @return 0 on success, negative on error.
+ * @see yaca_verify_init(), yaca_verify_update()
*/
int yaca_verify_final(yaca_ctx_h ctx,
- const char *mac,
- size_t mac_len);
+ const char *mac,
+ size_t mac_len);
/**@}*/
/**
* @brief yaca_digest_calc Calculate a digest of a buffer.
*
- * @param[in] algo Digest algorithm (select @see YACA_DIGEST_SHA256 if unsure).
+ * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure).
* @param[in] data Data from which the digest is to be calculated.
* @param[in] data_len Length of the data.
- * @param[out] digest Message digest, will be allocated by the library (should be freed with @see yaca_free).
+ * @param[out] digest Message digest, will be allocated by the library
+ * (should be freed with yaca_free()).
* @param[out] digest_len Length of message digest (depends on algorithm).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_digest_algo_e
*/
int yaca_digest_calc(yaca_digest_algo_e algo,
- const char *data,
- size_t data_len,
- char **digest,
- size_t *digest_len);
+ const char *data,
+ size_t data_len,
+ char **digest,
+ size_t *digest_len);
/**
* @brief yaca_encrypt Encrypt data using a symmetric cipher.
*
- * @param[in] algo Encryption algorithm (select @see YACA_ENC_AES if unsure).
- * @param[in] bcm Chaining mode (select @see YACA_BCM_CBC if unsure).
- * @param[in] sym_key Symmetric encryption key (@see key.h for key generation functions).
+ * @param[in] algo Encryption algorithm (select #YACA_ENC_AES if unsure).
+ * @param[in] bcm Chaining mode (select #YACA_BCM_CBC if unsure).
+ * @param[in] sym_key Symmetric encryption key (see key.h for key generation functions).
* @param[in] iv Initialization vector.
* @param[in] plain Plain text to be encrypted.
* @param[in] plain_len Length of the plain text.
- * @param[out] cipher Encrypted data, will be allocated by the library (should be freed with @see yaca_free).
+ * @param[out] cipher Encrypted data, will be allocated by the library
+ * (should be freed with yaca_free()).
* @param[out] cipher_len Length of the encrypted data (may be larger than decrypted).
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_decrypt()
*/
int yaca_encrypt(yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- const yaca_key_h sym_key,
- const yaca_key_h iv,
- const char *plain,
- size_t plain_len,
- char **cipher,
- size_t *cipher_len);
+ yaca_block_cipher_mode_e bcm,
+ const yaca_key_h sym_key,
+ const yaca_key_h iv,
+ const char *plain,
+ size_t plain_len,
+ char **cipher,
+ size_t *cipher_len);
/**
* @brief yaca_decrypt Decrypta 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.
- * @param[in] sym_key Symmetric encryption key that was used to encrypt the data.
- * @param[in] iv Initialization vector that was used to encrypt the data.
- * @param[in] cipher Cipher text to be decrypted.
- * @param[in] cipher_len Length of cipher text.
- * @param[out] plain Decrypted data, will be allocated by the library (should be freed with @see yaca_free).
+ * @param[in] algo Decryption algorithm that was used to encrypt the data.
+ * @param[in] bcm Chaining mode that was used to encrypt the data.
+ * @param[in] sym_key Symmetric encryption key that was used to encrypt the data.
+ * @param[in] iv Initialization vector that was used to encrypt the data.
+ * @param[in] cipher Cipher text to be decrypted.
+ * @param[in] cipher_len Length of cipher text.
+ * @param[out] plain Decrypted data, will be allocated by the library
+ * (should be freed with yaca_free()).
* @param[out] plain_len Length of the decrypted data.
*
- * @return 0 on success, negative on error (@see error.h).
+ * @return 0 on success, negative on error.
+ * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_encrypt()
*/
int yaca_decrypt(yaca_enc_algo_e algo,
- yaca_block_cipher_mode_e bcm,
- const yaca_key_h sym_key,
- const yaca_key_h iv,
- const char *cipher,
- size_t cipher_len,
- char **plain,
- size_t * plain_len);
+ yaca_block_cipher_mode_e bcm,
+ const yaca_key_h sym_key,
+ const yaca_key_h iv,
+ const char *cipher,
+ size_t cipher_len,
+ char **plain,
+ size_t * plain_len);
// TODO: sign/verify
#endif
/**
- * @defgroup Crypto-Types Enumerations for CryptoAPI
+ * @defgroup Crypto-Types Yet Another Crypto API - types.
*
* TODO: extended description.
*
* @brief Symmetric encryption algorithms
*/
typedef enum {
- YACA_ENC_AES = 0, /**< AES encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- Supported key lengths: @c 128, @c 192 and @c 256 */
-
- YACA_ENC_UNSAFE_DES, /**< DES encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- Supported key lengths: @c 56 */
-
- YACA_ENC_UNSAFE_3DES_2TDEA, /**< 3DES 2-key encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- Use double DES keys to perform corresponding 2-key 3DES encryption. Supported key lengths: @c 112 */
-
- YACA_ENC_3DES_3TDEA, /**< 3DES 3-key encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- Use triple DES keys to perform corresponding 3-key 3DES encryption. Supported key lengths: @c 168 */
-
- YACA_ENC_UNSAFE_RC2, /**< RC2 encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- The key length is extracted from the key buffer. Supported key lengths: 8-1024 bits in steps of 8 bits. */
-
- YACA_ENC_UNSAFE_RC4, /**< RC4 encryption.
- The key length is extracted from the key buffer. Supported key lengths: 40–2048 bits in steps of 8 bits */
-
- YACA_ENC_CAST5, /**< CAST5 encryption.
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- The key length is extracted from the key buffer. Supported key lengths: 40-128 bits in steps of 8 bits */
-
- YACA_ENC_UNSAFE_SKIPJACK /**< SKIPJACK algorithm
- - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory)
- Supported key length: 80 bits */
+ /**
+ * AES encryption.
+ * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory).
+ * - Supported key lengths: @c 128, @c 192 and @c 256.
+ */
+ YACA_ENC_AES = 0,
+
+ /**
+ * DES encryption.
+ * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory).
+ * - Supported key lengths: @c 56.
+ */
+ YACA_ENC_UNSAFE_DES,
+
+ /**
+ * 3DES 2-key encryption.
+ * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory).
+ * - Use double DES keys to perform corresponding 2-key 3DES encryption.
+ * - Supported key lengths: @c 112.
+ */
+ YACA_ENC_UNSAFE_3DES_2TDEA,
+
+ /**
+ * 3DES 3-key encryption.
+ * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory).
+ * - Use triple DES keys to perform corresponding 3-key 3DES encryption.
+ * - Supported key lengths: @c 168.
+ */
+ YACA_ENC_3DES_3TDEA,
+
+ /**
+ * RC2 encryption.
+ * - The key length is extracted from the key buffer.
+ * - Supported key lengths: 8-1024 bits in steps of 8 bits.
+ */
+ YACA_ENC_UNSAFE_RC2,
+
+ /**
+ * RC4 encryption.
+ * - The key length is extracted from the key buffer.
+ * - Supported key lengths: 40–2048 bits in steps of 8 bits.
+ */
+ YACA_ENC_UNSAFE_RC4,
+
+ /**
+ * CAST5 encryption.
+ * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory).
+ * - The key length is extracted from the key buffer.
+ * - Supported key lengths: 40-128 bits in steps of 8 bits.
+ */
+ YACA_ENC_CAST5,
+
+ /**
+ * SKIPJACK algorithm.
+ * - Supported key length: 80 bits.
+ */
+ YACA_ENC_UNSAFE_SKIPJACK
} yaca_enc_algo_e;
/**
* @brief Chaining modes for block ciphers
*/
typedef enum {
- YACA_BCM_ECB, /**< ECB block cipher mode. Encrypts 64 bit at a time. No IV is used. */
-
- YACA_BCM_CTR, /**< CTR block cipher mode. 16-byte initialization vector is mandatory.
- Supported parameters:
- - YACA_PARAM_CTR_CNT = length of counter block in bits
- (optional, only 128b is supported at the moment) */
-
- YACA_BCM_CBC, /**< CBC block cipher mode. 16-byte initialization vector is mandatory. */
-
- YACA_BCM_GCM, /**< GCM block cipher mode. IV is needed.
- Supported parameters:
- - YACA_PARAM_TAG = GCM tag
- - YACA_PARAM_AAD = additional authentication data(optional) */
-
- YACA_BCM_CFB, /**< CFB block cipher mode. 16-byte initialization vector is mandatory. */
-
- YACA_BCM_OFB, /**< OFB block cipher mode. 16-byte initialization vector is mandatory. */
-
- YACA_BCM_OCB, /**< Offest Codebook Mode (AES) */
-
- YACA_BCM_CCM /**< CBC-MAC Mode (AES) */
+ /**
+ * ECB block cipher mode.
+ * Encrypts 64 bit at a time. No IV is used.
+ */
+ YACA_BCM_ECB,
+
+ /**
+ * CTR block cipher mode.
+ * 16-byte initialization vector is mandatory.
+ * Supported parameters:
+ * - #YACA_PARAM_CTR_CNT = length of counter block in bits
+ * (optional, only 128b is supported at the moment)
+ */
+ YACA_BCM_CTR,
+
+ /**
+ * CBC block cipher mode.
+ * 16-byte initialization vector is mandatory.
+ */
+ YACA_BCM_CBC,
+
+ /**
+ * GCM block cipher mode, IV is needed.
+ * Supported parameters:
+ * - #YACA_PARAM_GCM_TAG = GCM tag
+ * - #YACA_PARAM_GCM_TAG_LEN = GCM tag length
+ * - #YACA_PARAM_GCM_AAD = additional authentication data(optional)
+ */
+ YACA_BCM_GCM,
+
+ /**
+ * CFB block cipher mode.
+ * 16-byte initialization vector is mandatory.
+ */
+ YACA_BCM_CFB,
+
+ /**
+ * OFB block cipher mode.
+ * 16-byte initialization vector is mandatory.
+ */
+ YACA_BCM_OFB,
+
+ /**
+ * Offest Codebook Mode (AES)
+ */
+ YACA_BCM_OCB,
+
+ /**
+ * CBC-MAC Mode (AES).
+ * Supported parameters:
+ * - #YACA_PARAM_CCM_TAG = CCM tag
+ * - #YACA_PARAM_CCM_TAG_LEN = CCM tag length
+ * - #YACA_PARAM_CCM_AAD = additional authentication data(optional)
+ */
+ YACA_BCM_CCM
} yaca_block_cipher_mode_e;
} yaca_ex_param_e;
/**
- * @brief Paddings supported by CryptoAPI
+ * @brief Paddings supported by Yet Another Crypto API
*/
typedef enum {
YACA_PADDING_NONE = 0, /**< total number of data MUST multiple of block size, Default */
# name. If set to NO, the members will appear in declaration order.
# The default value is: YES.
-SORT_MEMBER_DOCS = YES
+SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
# appear in their defined order.
# The default value is: NO.
-SORT_GROUP_NAMES = NO
+SORT_GROUP_NAMES = YES
# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
# fully-qualified names, including namespaces. If set to NO, the class list will
projects / platform / core / security / yaca.git / commitdiff