From: Dariusz Michaluk Date: Thu, 28 Apr 2016 11:07:47 +0000 (+0200) Subject: Cleanup API documentation. X-Git-Tag: accepted/tizen/common/20160810.161523~191 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=76c758b272e5837520af1837c1fa49f68ff5f5fe;p=platform%2Fcore%2Fsecurity%2Fyaca.git Cleanup API documentation. Change-Id: I4e4e1ce027d9672adb1bf92eebfc8e8696f90cb5 --- diff --git a/api/yaca/crypto.h b/api/yaca/crypto.h index b3d16db..52c7a32 100644 --- a/api/yaca/crypto.h +++ b/api/yaca/crypto.h @@ -32,7 +32,7 @@ extern "C" { #endif /** - * @defgroup Non-Crypto Non crypto related functions. + * @defgroup Non-Crypto Yet Another Crypto API - non crypto related functions. * * TODO: extended description and examples. * @@ -47,13 +47,15 @@ extern "C" { /** * @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); @@ -63,6 +65,7 @@ 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); @@ -73,6 +76,7 @@ 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); @@ -84,15 +88,17 @@ 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_* @@ -104,7 +110,7 @@ void yaca_free(void *ptr); * @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); @@ -117,10 +123,13 @@ 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. @@ -128,13 +137,16 @@ int yaca_ctx_set_param(yaca_ctx_h ctx, yaca_ex_param_e param, * * @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 @@ -142,6 +154,7 @@ int yaca_ctx_get_param(const yaca_ctx_h ctx, yaca_ex_param_e param, * Passing YACA_CTX_NULL is allowed. * * @param[in,out] ctx Crypto context. + * @see #yaca_ctx_h * */ void yaca_ctx_free(yaca_ctx_h ctx); @@ -153,7 +166,7 @@ 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 diff --git a/api/yaca/digest.h b/api/yaca/digest.h index 1e8edf3..dc49b92 100644 --- a/api/yaca/digest.h +++ b/api/yaca/digest.h @@ -42,21 +42,23 @@ extern "C" { /** * @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); @@ -64,10 +66,12 @@ 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); diff --git a/api/yaca/encrypt.h b/api/yaca/encrypt.h index 8c52fc9..b62541d 100644 --- a/api/yaca/encrypt.h +++ b/api/yaca/encrypt.h @@ -44,109 +44,119 @@ extern "C" { /** * @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); /**@}*/ diff --git a/api/yaca/error.h b/api/yaca/error.h index 5012c34..d82c3fc 100644 --- a/api/yaca/error.h +++ b/api/yaca/error.h @@ -24,21 +24,27 @@ #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? @@ -58,6 +64,7 @@ typedef void (*yaca_debug_func)(const char*); */ void yaca_error_set_debug_func(yaca_debug_func fn); +/**@}*/ #ifdef __cplusplus } /* extern */ diff --git a/api/yaca/key.h b/api/yaca/key.h index 114b02c..c9c924c 100644 --- a/api/yaca/key.h +++ b/api/yaca/key.h @@ -32,7 +32,7 @@ extern "C" { #endif /** - * @defgroup Key Key and IV handling functions + * @defgroup Key Advanced API for the key and IV handling. * * TODO: extended description and examples. * @@ -48,77 +48,81 @@ extern "C" { * * @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); @@ -126,7 +130,7 @@ 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. @@ -139,13 +143,14 @@ void yaca_key_free(yaca_key_h key); * * @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. @@ -156,15 +161,16 @@ int yaca_key_derive_dh(const yaca_key_h prv_key, * 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). @@ -175,17 +181,17 @@ int yaca_key_derive_kea(const yaca_key_h prv_key, * @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, ??); diff --git a/api/yaca/seal.h b/api/yaca/seal.h index 3467291..a6897be 100644 --- a/api/yaca/seal.h +++ b/api/yaca/seal.h @@ -46,7 +46,7 @@ extern "C" { /** * @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. @@ -54,50 +54,55 @@ extern "C" { * @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. @@ -105,45 +110,50 @@ int yaca_seal_final(yaca_ctx_h ctx, * @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); /**@}*/ diff --git a/api/yaca/sign.h b/api/yaca/sign.h index 217d15d..91c47d1 100644 --- a/api/yaca/sign.h +++ b/api/yaca/sign.h @@ -43,81 +43,87 @@ extern "C" { /** * @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); /**@}*/ diff --git a/api/yaca/simple.h b/api/yaca/simple.h index 8a7dc25..3075aac 100644 --- a/api/yaca/simple.h +++ b/api/yaca/simple.h @@ -50,65 +50,71 @@ extern "C" { /** * @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 diff --git a/api/yaca/types.h b/api/yaca/types.h index 19428df..80750bf 100644 --- a/api/yaca/types.h +++ b/api/yaca/types.h @@ -29,7 +29,7 @@ extern "C" { #endif /** - * @defgroup Crypto-Types Enumerations for CryptoAPI + * @defgroup Crypto-Types Yet Another Crypto API - types. * * TODO: extended description. * @@ -128,63 +128,124 @@ typedef enum { * @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; @@ -207,7 +268,7 @@ typedef enum { } 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 */ diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index b6a7957..87e9f10 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -551,7 +551,7 @@ INLINE_INFO = YES # 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 @@ -578,7 +578,7 @@ SORT_MEMBERS_CTORS_1ST = NO # 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