From bf9cd01f64e2cccf90ca9a42ff210120eb2a18b3 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Fri, 27 May 2016 13:45:33 +0200 Subject: [PATCH 01/16] Add yaca_error_e typedef. Change-Id: I5bf5e9ad7cc91df53cbb437044d31dd8a7e1efad --- api/yaca/yaca_error.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h index 26f1979..17c1f30 100755 --- a/api/yaca/yaca_error.h +++ b/api/yaca/yaca_error.h @@ -44,7 +44,7 @@ extern "C" { * * @since_tizen 3.0 */ -enum __yaca_error_code { +typedef enum { YACA_ERROR_NONE = TIZEN_ERROR_NONE, YACA_ERROR_INVALID_ARGUMENT = TIZEN_ERROR_INVALID_PARAMETER, @@ -54,7 +54,7 @@ enum __yaca_error_code { YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_YACA | 0x04, YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x05, YACA_ERROR_PASSWORD_INVALID = TIZEN_ERROR_YACA | 0x06 -}; +} yaca_error_e; /**@}*/ -- 2.7.4 From e30b55d0522b8a9d51e9ab89aae301ea3b454c45 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Fri, 27 May 2016 15:27:46 +0200 Subject: [PATCH 02/16] Remove YACA_ERROR_NOT_IMPLEMENTED Change-Id: If8361e25c012984d3ebfaf7ae03df5964140f230 --- api/yaca/yaca_error.h | 1 - src/encrypt.c | 3 ++- src/key.c | 23 +++++++++++------------ src/sign.c | 4 ++-- 4 files changed, 15 insertions(+), 16 deletions(-) diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h index 17c1f30..5bcfec7 100755 --- a/api/yaca/yaca_error.h +++ b/api/yaca/yaca_error.h @@ -48,7 +48,6 @@ typedef enum { YACA_ERROR_NONE = TIZEN_ERROR_NONE, YACA_ERROR_INVALID_ARGUMENT = TIZEN_ERROR_INVALID_PARAMETER, - YACA_ERROR_NOT_IMPLEMENTED = TIZEN_ERROR_YACA | 0x01, YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x02, YACA_ERROR_TOO_BIG_ARGUMENT = TIZEN_ERROR_YACA | 0x03, YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_YACA | 0x04, diff --git a/src/encrypt.c b/src/encrypt.c index 3d83b78..dc1a1b3 100644 --- a/src/encrypt.c +++ b/src/encrypt.c @@ -292,8 +292,9 @@ int encrypt_get_algorithm(yaca_enc_algo_e algo, ret = snprintf(cipher_name, sizeof(cipher_name), "%s", algo_name); break; case YACA_ENC_UNSAFE_SKIPJACK: + //TODO NOT_IMPLEMENTED default: - return YACA_ERROR_NOT_IMPLEMENTED; + return YACA_ERROR_INVALID_ARGUMENT; } if (ret < 0) diff --git a/src/key.c b/src/key.c index b3e2c07..a0e771a 100755 --- a/src/key.c +++ b/src/key.c @@ -530,9 +530,7 @@ int export_evp(struct yaca_key_evp_s *evp_key, case YACA_KEY_TYPE_DH_PUB: case YACA_KEY_TYPE_EC_PRIV: case YACA_KEY_TYPE_EC_PUB: - ret = YACA_ERROR_NOT_IMPLEMENTED; - goto free_bio; - + //TODO NOT_IMPLEMENTED default: ret = YACA_ERROR_INVALID_ARGUMENT; goto free_bio; @@ -560,9 +558,7 @@ int export_evp(struct yaca_key_evp_s *evp_key, case YACA_KEY_TYPE_DH_PUB: case YACA_KEY_TYPE_EC_PRIV: case YACA_KEY_TYPE_EC_PUB: - ret = YACA_ERROR_NOT_IMPLEMENTED; - goto free_bio; - + //TODO NOT_IMPLEMENTED default: ret = YACA_ERROR_INVALID_ARGUMENT; goto free_bio; @@ -945,7 +941,7 @@ API int yaca_key_import(yaca_key_h *key, case YACA_KEY_TYPE_DH_PRIV: case YACA_KEY_TYPE_EC_PUB: case YACA_KEY_TYPE_EC_PRIV: - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED default: return YACA_ERROR_INVALID_ARGUMENT; } @@ -985,8 +981,9 @@ API int yaca_key_export(const yaca_key_h key, evp_key != NULL) return export_evp(evp_key, key_file_fmt, password, data, data_len); - if (key_fmt == YACA_KEY_FORMAT_PKCS8) - return YACA_ERROR_NOT_IMPLEMENTED; + if (key_fmt == YACA_KEY_FORMAT_PKCS8) { + //TODO NOT_IMPLEMENTED + } return YACA_ERROR_INVALID_ARGUMENT; } @@ -1049,7 +1046,7 @@ API int yaca_key_gen(yaca_key_h *key, case YACA_KEY_TYPE_DH_PRIV: case YACA_KEY_TYPE_EC_PRIV: - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED default: return YACA_ERROR_INVALID_ARGUMENT; } @@ -1143,7 +1140,8 @@ API int yaca_key_derive_dh(const yaca_key_h prv_key, const yaca_key_h pub_key, yaca_key_h *sym_key) { - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED + return YACA_ERROR_INVALID_ARGUMENT; } API int yaca_key_derive_kea(const yaca_key_h prv_key, @@ -1152,7 +1150,8 @@ API int yaca_key_derive_kea(const yaca_key_h prv_key, const yaca_key_h pub_key_auth, yaca_key_h *sym_key) { - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED + return YACA_ERROR_INVALID_ARGUMENT; } API int yaca_key_derive_pbkdf2(const char *password, diff --git a/src/sign.c b/src/sign.c index 6b76062..8ed5a6b 100644 --- a/src/sign.c +++ b/src/sign.c @@ -253,7 +253,7 @@ API int yaca_sign_init(yaca_ctx_h *ctx, case YACA_KEY_TYPE_DSA_PRIV: break; case YACA_KEY_TYPE_EC_PRIV: - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED default: return YACA_ERROR_INVALID_ARGUMENT; } @@ -508,7 +508,7 @@ API int yaca_verify_init(yaca_ctx_h *ctx, case YACA_KEY_TYPE_DSA_PUB: break; case YACA_KEY_TYPE_EC_PUB: - return YACA_ERROR_NOT_IMPLEMENTED; + //TODO NOT_IMPLEMENTED default: return YACA_ERROR_INVALID_ARGUMENT; } -- 2.7.4 From 19bfe2cbaa8eb0bb92dd30882c5c78e9513e5914 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Fri, 27 May 2016 15:37:13 +0200 Subject: [PATCH 03/16] Remove not implemented Skipjack algorithm. Change-Id: Ibc5a55bef78165344f839113361aa252749deacf --- api/yaca/yaca_types.h | 6 ------ src/encrypt.c | 4 ---- 2 files changed, 10 deletions(-) diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h index 70a097d..7af84f6 100644 --- a/api/yaca/yaca_types.h +++ b/api/yaca/yaca_types.h @@ -235,12 +235,6 @@ typedef enum { * - see #yaca_block_cipher_mode_e for details on additional parameters (mandatory). */ YACA_ENC_CAST5, - - /** - * SKIPJACK algorithm. - * - Supported key length: 80 bits. - */ - YACA_ENC_UNSAFE_SKIPJACK } yaca_enc_algo_e; /** diff --git a/src/encrypt.c b/src/encrypt.c index dc1a1b3..0edeb3e 100644 --- a/src/encrypt.c +++ b/src/encrypt.c @@ -218,8 +218,6 @@ static const char *encrypt_algo_to_str(yaca_enc_algo_e algo) return "rc4"; case YACA_ENC_CAST5: return "cast5"; - - case YACA_ENC_UNSAFE_SKIPJACK: // TODO: add skipjack implementation default: return NULL; } @@ -291,8 +289,6 @@ int encrypt_get_algorithm(yaca_enc_algo_e algo, case YACA_ENC_UNSAFE_RC4: ret = snprintf(cipher_name, sizeof(cipher_name), "%s", algo_name); break; - case YACA_ENC_UNSAFE_SKIPJACK: - //TODO NOT_IMPLEMENTED default: return YACA_ERROR_INVALID_ARGUMENT; } -- 2.7.4 From 9d4b87bf6648013465896e58fdc9c94e37673be6 Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Fri, 27 May 2016 15:47:45 +0200 Subject: [PATCH 04/16] Replace YACA_ERROR_TOO_BIG_ARGUMENT with YACA_ERROR_INVALID_ARGUMENT Change-Id: Iadf4d6a6044e6bc68389897f369064ec61ca309f --- src/encrypt.c | 2 +- src/key.c | 12 ++++++------ src/seal.c | 2 +- src/simple.c | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/encrypt.c b/src/encrypt.c index 0edeb3e..385bec7 100644 --- a/src/encrypt.c +++ b/src/encrypt.c @@ -89,7 +89,7 @@ static int get_encrypt_output_length(const yaca_ctx_h ctx, size_t input_len, siz if (input_len > 0) { if ((size_t)block_size > SIZE_MAX - input_len + 1) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; *output_len = block_size + input_len - 1; } else { diff --git a/src/key.c b/src/key.c index a0e771a..3de2ba4 100755 --- a/src/key.c +++ b/src/key.c @@ -93,7 +93,7 @@ int base64_decode(const char *data, size_t data_len, BIO **output) /* This is because of BIO_new_mem_buf() having its length param typed int */ if (data_len > INT_MAX) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; /* First phase of correctness checking, calculate expected output length */ ret = base64_decode_length(data, data_len, &b64_len); @@ -204,7 +204,7 @@ int import_simple(yaca_key_h *key, } if (key_data_len > SIZE_MAX - sizeof(struct yaca_key_simple_s)) { - ret = YACA_ERROR_TOO_BIG_ARGUMENT; + ret = YACA_ERROR_INVALID_ARGUMENT; goto out; } @@ -278,7 +278,7 @@ int import_evp(yaca_key_h *key, /* This is because of BIO_new_mem_buf() having its length param typed int */ if (data_len > INT_MAX) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; src = BIO_new_mem_buf(data, data_len); if (src == NULL) { @@ -616,7 +616,7 @@ int gen_simple(struct yaca_key_simple_s **out, size_t key_bits) size_t key_byte_len = key_bits / 8; if (key_byte_len > SIZE_MAX - sizeof(struct yaca_key_simple_s)) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; nk = yaca_zalloc(sizeof(struct yaca_key_simple_s) + key_byte_len); if (nk == NULL) @@ -646,7 +646,7 @@ int gen_simple_des(struct yaca_key_simple_s **out, size_t key_bits) size_t key_byte_len = key_bits / 8; if (key_byte_len > SIZE_MAX - sizeof(struct yaca_key_simple_s)) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; nk = yaca_zalloc(sizeof(struct yaca_key_simple_s) + key_byte_len); if (nk == NULL) @@ -1175,7 +1175,7 @@ API int yaca_key_derive_pbkdf2(const char *password, return YACA_ERROR_INVALID_ARGUMENT; if (key_byte_len > SIZE_MAX - sizeof(struct yaca_key_simple_s)) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; ret = digest_get_algorithm(algo, &md); if (ret != YACA_ERROR_NONE) diff --git a/src/seal.c b/src/seal.c index c17cc5d..5c1ecb1 100644 --- a/src/seal.c +++ b/src/seal.c @@ -88,7 +88,7 @@ static int get_seal_output_length(const yaca_ctx_h ctx, size_t input_len, size_t if (input_len > 0) { if ((size_t)block_size > SIZE_MAX - input_len + 1) - return YACA_ERROR_TOO_BIG_ARGUMENT; + return YACA_ERROR_INVALID_ARGUMENT; *output_len = block_size + input_len - 1; } else { diff --git a/src/simple.c b/src/simple.c index 3ba93f8..df4839a 100644 --- a/src/simple.c +++ b/src/simple.c @@ -112,7 +112,7 @@ API int yaca_encrypt(yaca_enc_algo_e algo, goto err; if (out_len > SIZE_MAX - lcipher_len) { - ret = YACA_ERROR_TOO_BIG_ARGUMENT; + ret = YACA_ERROR_INVALID_ARGUMENT; goto err; } @@ -189,7 +189,7 @@ API int yaca_decrypt(yaca_enc_algo_e algo, goto err; if (out_len > SIZE_MAX - lplain_len) { - ret = YACA_ERROR_TOO_BIG_ARGUMENT; + ret = YACA_ERROR_INVALID_ARGUMENT; goto err; } -- 2.7.4 From cae0e6ff8e9ba782d63f02921fed43e4e9955c73 Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Fri, 27 May 2016 15:28:34 +0200 Subject: [PATCH 05/16] Modify error codes according to ACR Change-Id: I9e41174c1a38811dd3d5d85b66513bd271cfdd0b --- api/yaca/yaca_error.h | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h index 5bcfec7..aca3d2d 100755 --- a/api/yaca/yaca_error.h +++ b/api/yaca/yaca_error.h @@ -47,12 +47,11 @@ extern "C" { typedef enum { YACA_ERROR_NONE = TIZEN_ERROR_NONE, YACA_ERROR_INVALID_ARGUMENT = TIZEN_ERROR_INVALID_PARAMETER, + YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, - YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x02, - YACA_ERROR_TOO_BIG_ARGUMENT = TIZEN_ERROR_YACA | 0x03, - YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_YACA | 0x04, - YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x05, - YACA_ERROR_PASSWORD_INVALID = TIZEN_ERROR_YACA | 0x06 + YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01, + YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02, + YACA_ERROR_PASSWORD_INVALID = TIZEN_ERROR_YACA | 0x03 } yaca_error_e; /**@}*/ -- 2.7.4 From 29c83d14715426177ea525dbb0cecca9fce07eb0 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Fri, 27 May 2016 14:34:51 +0200 Subject: [PATCH 06/16] Do not enumerate all related modules with only one @see tag. Change-Id: I5b7e3856794f099e7f2f65dde3e67bc35a81625a --- api/yaca/yaca_crypto.h | 30 ++++++++++++++++++++------ api/yaca/yaca_digest.h | 13 +++++++++--- api/yaca/yaca_encrypt.h | 28 +++++++++++++++++++------ api/yaca/yaca_key.h | 26 ++++++++++++++++++----- api/yaca/yaca_seal.h | 28 +++++++++++++++++++------ api/yaca/yaca_sign.h | 56 ++++++++++++++++++++++++++++++++++++------------- api/yaca/yaca_simple.h | 31 +++++++++++++++++++++------ 7 files changed, 165 insertions(+), 47 deletions(-) diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index 30c2734..6b8e634 100644 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -52,6 +52,7 @@ extern "C" { * @since_tizen 3.0 * * @return YACA_ERROR_NONE on success, negative on error. + * * @see yaca_exit() */ int yaca_init(void); @@ -73,7 +74,10 @@ 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() + * + * @see yaca_zalloc() + * @see yaca_realloc() + * @see yaca_free() */ void *yaca_malloc(size_t size); @@ -85,7 +89,10 @@ 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() + * + * @see yaca_malloc() + * @see yaca_realloc() + * @see yaca_free() */ void *yaca_zalloc(size_t size); @@ -98,7 +105,10 @@ 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() + * + * @see yaca_malloc() + * @see yaca_zalloc() + * @see yaca_free() */ void *yaca_realloc(void *addr, size_t size); @@ -109,7 +119,10 @@ void *yaca_realloc(void *addr, size_t size); * @since_tizen 3.0 * * @param[in] ptr Pointer to the memory to be freed. - * @see yaca_malloc(), yaca_zalloc(), yaca_realloc() + * + * @see yaca_malloc() + * @see yaca_zalloc() + * @see yaca_realloc() * */ void yaca_free(void *ptr); @@ -138,7 +151,9 @@ int yaca_rand_bytes(char *data, size_t data_len); * @param[in] value_len Length of the parameter value. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_ex_param_e, yaca_ctx_get_param() + * + * @see #yaca_ex_param_e + * @see yaca_ctx_get_param() */ int yaca_ctx_set_param(yaca_ctx_h ctx, yaca_ex_param_e param, @@ -157,7 +172,9 @@ int yaca_ctx_set_param(yaca_ctx_h ctx, * @param[out] value_len Length of the parameter value will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_ex_param_e, yaca_ctx_set_param() + * + * @see #yaca_ex_param_e + * @see yaca_ctx_set_param() */ int yaca_ctx_get_param(const yaca_ctx_h ctx, yaca_ex_param_e param, @@ -171,6 +188,7 @@ int yaca_ctx_get_param(const yaca_ctx_h ctx, * @since_tizen 3.0 * * @param[in,out] ctx Crypto context. + * * @see #yaca_ctx_h * */ diff --git a/api/yaca/yaca_digest.h b/api/yaca/yaca_digest.h index 2c7be86..c91298a 100644 --- a/api/yaca/yaca_digest.h +++ b/api/yaca/yaca_digest.h @@ -48,7 +48,10 @@ extern "C" { * @param[in] algo Digest algorithm that will be used. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_digest_algo_e, yaca_digest_update(), yaca_digest_final() + * + * @see #yaca_digest_algo_e + * @see yaca_digest_update() + * @see yaca_digest_final() */ int yaca_digest_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo); @@ -62,7 +65,9 @@ int yaca_digest_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo); * @param[in] data_len Length of the data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_digest_init(), yaca_digest_final() + * + * @see yaca_digest_init() + * @see yaca_digest_final() */ int yaca_digest_update(yaca_ctx_h ctx, const char *data, size_t data_len); @@ -77,7 +82,9 @@ int yaca_digest_update(yaca_ctx_h ctx, const char *data, size_t data_len); * @param[out] digest_len Length of the digest, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_digest_init(), yaca_digest_update() + * + * @see yaca_digest_init() + * @see yaca_digest_update() */ int yaca_digest_final(yaca_ctx_h ctx, char *digest, size_t *digest_len); diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index cba5332..02269c0 100644 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -51,7 +51,11 @@ extern "C" { * @param[in] iv Initialization vector that will be used. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_encrypt_update(), yaca_encrypt_final() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_encrypt_update() + * @see yaca_encrypt_final() */ int yaca_encrypt_init(yaca_ctx_h *ctx, yaca_enc_algo_e algo, @@ -72,7 +76,9 @@ int yaca_encrypt_init(yaca_ctx_h *ctx, * @param[out] cipher_len Length of the encrypted data, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_encrypt_init(), yaca_encrypt_final() + * + * @see yaca_encrypt_init() + * @see yaca_encrypt_final() */ int yaca_encrypt_update(yaca_ctx_h ctx, const char *plain, @@ -91,7 +97,9 @@ int yaca_encrypt_update(yaca_ctx_h ctx, * @param[out] cipher_len Length of the final piece, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_encrypt_init(), yaca_encrypt_update() + * + * @see yaca_encrypt_init() + * @see yaca_encrypt_update() */ int yaca_encrypt_final(yaca_ctx_h ctx, char *cipher, @@ -109,7 +117,11 @@ int yaca_encrypt_final(yaca_ctx_h ctx, * @param[in] iv Initialization vector that was used to encrypt the data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_decrypt_update(), yaca_decrypt_final() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_decrypt_update() + * @see yaca_decrypt_final() */ int yaca_decrypt_init(yaca_ctx_h *ctx, yaca_enc_algo_e algo, @@ -130,7 +142,9 @@ int yaca_decrypt_init(yaca_ctx_h *ctx, * @param[out] plain_len Length of the decrypted data, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_decrypt_init(), yaca_decrypt_final() + * + * @see yaca_decrypt_init() + * @see yaca_decrypt_final() */ int yaca_decrypt_update(yaca_ctx_h ctx, const char *cipher, @@ -149,7 +163,9 @@ int yaca_decrypt_update(yaca_ctx_h ctx, * @param[out] plain_len Length of the final piece, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_decrypt_init(), yaca_decrypt_update() + * + * @see yaca_decrypt_init() + * @see yaca_decrypt_update() */ int yaca_decrypt_final(yaca_ctx_h ctx, char *plain, diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 4786d9a..455df79 100755 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -96,7 +96,10 @@ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits); * * @return YACA_ERROR_NONE on success, YACA_ERROR_PASSWORD_INVALID if wrong password given, * negative on error. - * @see #yaca_key_type_e, yaca_key_export(), yaca_key_free() + * + * @see #yaca_key_type_e + * @see yaca_key_export() + * @see yaca_key_free() */ int yaca_key_import(yaca_key_h *key, yaca_key_type_e key_type, @@ -137,7 +140,11 @@ int yaca_key_import(yaca_key_h *key, * @param[out] data_len Size of the output data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_fmt_e, #yaca_key_file_fmt_e, yaca_key_import(), yaca_key_free() + * + * @see #yaca_key_fmt_e + * @see #yaca_key_file_fmt_e + * @see yaca_key_import() + * @see yaca_key_free() */ int yaca_key_export(const yaca_key_h key, yaca_key_fmt_e key_fmt, @@ -158,7 +165,10 @@ int yaca_key_export(const yaca_key_h key, * @param[in] key_bits Length of the key (in bits) to be generated. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_key_bits_e, yaca_key_free() + * + * @see #yaca_key_type_e + * @see #yaca_key_bits_e + * @see yaca_key_free() */ int yaca_key_gen(yaca_key_h *key, yaca_key_type_e key_type, @@ -173,7 +183,10 @@ int yaca_key_gen(yaca_key_h *key, * @param[out] pub_key Extracted public key (must be freed with yaca_key_free()). * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_key_gen(), yaca_key_import(), yaca_key_free() + * + * @see yaca_key_gen() + * @see yaca_key_import() + * @see yaca_key_free() */ int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key); @@ -183,7 +196,10 @@ int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key); * @since_tizen 3.0 * * @param key Key to be freed. - * @see yaca_key_import(), yaca_key_export(), yaca_key_gen() + * + * @see yaca_key_import() + * @see yaca_key_export() + * @see yaca_key_gen() * */ void yaca_key_free(yaca_key_h key); diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index 81cd401..190be94 100644 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -57,7 +57,11 @@ extern "C" { * @param[out] iv Generated initialization vector that will be used. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_seal_update(), yaca_seal_final() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_seal_update() + * @see yaca_seal_final() */ int yaca_seal_init(yaca_ctx_h *ctx, const yaca_key_h pub_key, @@ -80,7 +84,9 @@ int yaca_seal_init(yaca_ctx_h *ctx, * @param[out] cipher_len Length of the encrypted data, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_seal_init(), yaca_seal_final() + * + * @see yaca_seal_init() + * @see yaca_seal_final() */ int yaca_seal_update(yaca_ctx_h ctx, const char *plain, @@ -99,7 +105,9 @@ int yaca_seal_update(yaca_ctx_h ctx, * @param[out] cipher_len Length of the final piece, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_seal_init(), yaca_seal_update() + * + * @see yaca_seal_init() + * @see yaca_seal_update() */ int yaca_seal_final(yaca_ctx_h ctx, char *cipher, @@ -119,7 +127,11 @@ int yaca_seal_final(yaca_ctx_h ctx, * @param[in] iv Initialization vector that was used for the encryption. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_open_update(), yaca_open_final() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_open_update() + * @see yaca_open_final() */ int yaca_open_init(yaca_ctx_h *ctx, const yaca_key_h prv_key, @@ -142,7 +154,9 @@ int yaca_open_init(yaca_ctx_h *ctx, * @param[out] plain_len Length of the decrypted data, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_open_init(), yaca_open_final() + * + * @see yaca_open_init() + * @see yaca_open_final() */ int yaca_open_update(yaca_ctx_h ctx, const char *cipher, @@ -161,7 +175,9 @@ int yaca_open_update(yaca_ctx_h ctx, * @param[out] plain_len Length of the final piece, actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_open_init(), yaca_open_update() + * + * @see yaca_open_init() + * @see yaca_open_update() */ int yaca_open_final(yaca_ctx_h ctx, char *plain, diff --git a/api/yaca/yaca_sign.h b/api/yaca/yaca_sign.h index d8098c6..0d2f399 100644 --- a/api/yaca/yaca_sign.h +++ b/api/yaca/yaca_sign.h @@ -57,9 +57,14 @@ extern "C" { * - #YACA_KEY_TYPE_EC_PRIV. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_sign_update(), - * yaca_sign_final(), yaca_verify_init(), yaca_verify_update(), - * yaca_verify_final() + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_sign_update() + * @see yaca_sign_final() + * @see yaca_verify_init() + * @see yaca_verify_update() + * @see yaca_verify_final() */ int yaca_sign_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo, @@ -80,8 +85,12 @@ int yaca_sign_init(yaca_ctx_h *ctx, * - #YACA_KEY_TYPE_DES. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_sign_update(), - * yaca_sign_final(), yaca_memcmp() + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_sign_update() + * @see yaca_sign_final() + * @see yaca_memcmp() */ int yaca_sign_hmac_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo, @@ -102,8 +111,12 @@ int yaca_sign_hmac_init(yaca_ctx_h *ctx, * - #YACA_KEY_TYPE_DES. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_enc_algo_e, yaca_sign_update(), - * yaca_sign_final(), yaca_memcmp() + * + * @see #yaca_key_type_e + * @see #yaca_enc_algo_e + * @see yaca_sign_update() + * @see yaca_sign_final() + * @see yaca_memcmp() */ int yaca_sign_cmac_init(yaca_ctx_h *ctx, yaca_enc_algo_e algo, @@ -120,8 +133,11 @@ int yaca_sign_cmac_init(yaca_ctx_h *ctx, * @param[in] data_len Length of the data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_sign_init(), yaca_sign_final(), yaca_sign_hmac_init(), - * yaca_sign_cmac_init() + * + * @see yaca_sign_init() + * @see yaca_sign_final() + * @see yaca_sign_hmac_init() + * @see yaca_sign_cmac_init() */ int yaca_sign_update(yaca_ctx_h ctx, const char *data, @@ -139,8 +155,11 @@ int yaca_sign_update(yaca_ctx_h ctx, * actual number of bytes written will be returned here. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_sign_init(), yaca_sign_update(), yaca_sign_hmac_init(), - * yaca_sign_cmac_init() + * + * @see yaca_sign_init() + * @see yaca_sign_update() + * @see yaca_sign_hmac_init() + * @see yaca_sign_cmac_init() */ int yaca_sign_final(yaca_ctx_h ctx, char *signature, @@ -160,8 +179,11 @@ int yaca_sign_final(yaca_ctx_h ctx, * - #YACA_KEY_TYPE_EC_PUB. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_verify_update(), - * yaca_verify_final() + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_verify_update() + * @see yaca_verify_final() */ int yaca_verify_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo, @@ -177,7 +199,9 @@ int yaca_verify_init(yaca_ctx_h *ctx, * @param[in] data_len Length of the data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see yaca_verify_init(), yaca_verify_final() + * + * @see yaca_verify_init() + * @see yaca_verify_final() */ int yaca_verify_update(yaca_ctx_h ctx, const char *data, @@ -194,7 +218,9 @@ int yaca_verify_update(yaca_ctx_h ctx, * * @return YACA_ERROR_NONE on success, YACA_ERROR_DATA_MISMATCH if verification fails, * negative on error. - * @see yaca_verify_init(), yaca_verify_update() + * + * @see yaca_verify_init() + * @see yaca_verify_update() */ int yaca_verify_final(yaca_ctx_h ctx, const char *signature, diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index e50f7b2..9f3d90c 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -60,6 +60,7 @@ extern "C" { * @param[out] digest_len Length of message digest (depends on algorithm). * * @return YACA_ERROR_NONE on success, negative on error. + * * @see #yaca_digest_algo_e */ int yaca_digest_calc(yaca_digest_algo_e algo, @@ -84,7 +85,10 @@ int yaca_digest_calc(yaca_digest_algo_e algo, * @param[out] cipher_len Length of the encrypted data (may be larger than decrypted). * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_decrypt() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_decrypt() */ int yaca_encrypt(yaca_enc_algo_e algo, yaca_block_cipher_mode_e bcm, @@ -111,7 +115,10 @@ int yaca_encrypt(yaca_enc_algo_e algo, * @param[out] plain_len Length of the decrypted data. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_enc_algo_e, #yaca_block_cipher_mode_e, yaca_encrypt() + * + * @see #yaca_enc_algo_e + * @see #yaca_block_cipher_mode_e + * @see yaca_encrypt() */ int yaca_decrypt(yaca_enc_algo_e algo, yaca_block_cipher_mode_e bcm, @@ -140,7 +147,10 @@ int yaca_decrypt(yaca_enc_algo_e algo, * @param[out] signature_len Length of the signature. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_verify(), + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_verify() */ int yaca_sign(yaca_digest_algo_e algo, const yaca_key_h key, @@ -167,7 +177,10 @@ int yaca_sign(yaca_digest_algo_e algo, * * @return YACA_ERROR_NONE on success, YACA_ERROR_SIGNATURE_INVALID if verification fails, * negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_sign(), + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_sign() */ int yaca_verify(yaca_digest_algo_e algo, const yaca_key_h key, @@ -195,7 +208,10 @@ int yaca_verify(yaca_digest_algo_e algo, * @param[out] mac_len Length of the MAC. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_digest_algo_e, yaca_memcmp() + * + * @see #yaca_key_type_e + * @see #yaca_digest_algo_e + * @see yaca_memcmp() */ int yaca_hmac(yaca_digest_algo_e algo, const yaca_key_h key, @@ -223,7 +239,10 @@ int yaca_hmac(yaca_digest_algo_e algo, * @param[out] mac_len Length of the MAC. * * @return YACA_ERROR_NONE on success, negative on error. - * @see #yaca_key_type_e, #yaca_enc_algo_e, yaca_memcmp() + * + * @see #yaca_key_type_e + * @see #yaca_enc_algo_e + * @see yaca_memcmp() */ int yaca_cmac(yaca_enc_algo_e algo, const yaca_key_h key, -- 2.7.4 From 0e25baf4e38d99bd52336c6b562ff9bcf9d415e4 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Mon, 30 May 2016 12:16:17 +0200 Subject: [PATCH 07/16] ACR: yaca_seal.h doxygen fixes Change-Id: Ia0956240a40fb5a4ac39a1cdee1aeaa93699c578 --- api/yaca/yaca_seal.h | 121 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 44 deletions(-) diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index 190be94..40a6f24 100644 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -17,7 +17,7 @@ */ /** - * @file seal.h + * @file yaca_seal.h * @brief */ @@ -48,15 +48,21 @@ extern "C" { * * @since_tizen 3.0 * - * @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[in] sym_key_bits Symmetric key length (in bits) that will be generated. - * @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 YACA_ERROR_NONE on success, negative on error. + * @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[in] sym_key_bits Symmetric key length (in bits) that will be generated + * @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 #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, bcm, sym_key_bits, invalid prv_key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -76,14 +82,19 @@ int yaca_seal_init(yaca_ctx_h *ctx, * * @since_tizen 3.0 * - * @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_len Length of the encrypted data, actual number of bytes written will be returned here. + * @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_len Length of the encrypted data, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_seal_init() * @see yaca_seal_final() @@ -99,12 +110,17 @@ int yaca_seal_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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_len Length of the final piece, actual number of bytes written will be returned here. + * @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_len Length of the final piece, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_seal_init() * @see yaca_seal_update() @@ -118,15 +134,22 @@ int yaca_seal_final(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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_bits Symmetric key length (in bits) that was used for the encryption. - * @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 YACA_ERROR_NONE on success, negative on error. + * @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_bits Symmetric key length (in bits) that was used for the encryption + * @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 #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, bcm, sym_key_bits, + * invalid prv_key, sym_key or iv) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -146,14 +169,19 @@ int yaca_open_init(yaca_ctx_h *ctx, * * @since_tizen 3.0 * - * @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_len Length of the decrypted data, actual number of bytes written will be returned here. + * @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_len Length of the decrypted data, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_open_init() * @see yaca_open_final() @@ -169,12 +197,17 @@ int yaca_open_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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_len Length of the final piece, actual number of bytes written will be returned here. - * - * @return YACA_ERROR_NONE on success, negative on error. + * @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_len Length of the final piece, + * actual number of bytes written will be returned here + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_open_init() * @see yaca_open_update() -- 2.7.4 From a9b8123fb4c8653801a8b0794be91f1335f585c9 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Mon, 30 May 2016 12:53:53 +0200 Subject: [PATCH 08/16] ACR: yaca_encrypt.h doxygen fixes Change-Id: Id2603e9f858894eafc19e850909685d9801a5081 --- api/yaca/yaca_encrypt.h | 119 +++++++++++++++++++++++++++++++----------------- 1 file changed, 77 insertions(+), 42 deletions(-) diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index 02269c0..23ed8ba 100644 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -17,7 +17,7 @@ */ /** - * @file encrypt.h + * @file yaca_encrypt.h * @brief */ @@ -44,13 +44,18 @@ extern "C" { * * @since_tizen 3.0 * - * @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. + * @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 YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, bcm, invalid sym_key or iv) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -68,14 +73,19 @@ int yaca_encrypt_init(yaca_ctx_h *ctx, * * @since_tizen 3.0 * - * @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_len Length of the encrypted data, actual number of bytes written will be returned here. + * @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_len Length of the encrypted data, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_encrypt_init() * @see yaca_encrypt_final() @@ -91,12 +101,17 @@ int yaca_encrypt_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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_len Length of the final piece, actual number of bytes written will be returned here. + * @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_len Length of the final piece, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_encrypt_init() * @see yaca_encrypt_update() @@ -110,13 +125,18 @@ int yaca_encrypt_final(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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. + * @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 YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, bcm, invalid sym_key or iv) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -134,14 +154,19 @@ int yaca_decrypt_init(yaca_ctx_h *ctx, * * @since_tizen 3.0 * - * @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_len Length of the decrypted data, actual number of bytes written will be returned here. + * @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_len Length of the decrypted data, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_decrypt_init() * @see yaca_decrypt_final() @@ -157,12 +182,17 @@ int yaca_decrypt_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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_len Length of the final piece, actual number of bytes written will be returned here. + * @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_len Length of the final piece, + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_decrypt_init() * @see yaca_decrypt_update() @@ -179,12 +209,17 @@ int yaca_decrypt_final(yaca_ctx_h ctx, * @remarks If returned iv_bits equals 0 that means that for this * specific algorithm and its parameters IV is not used. * - * @param[in] algo Encryption algorithm. - * @param[in] bcm Chain mode. - * @param[in] key_bits Key length in bits. - * @param[out] iv_bits Recommended IV length in bits. + * @param[in] algo Encryption algorithm + * @param[in] bcm Chain mode + * @param[in] key_bits Key length in bits + * @param[out] iv_bits Recommended IV length in bits + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * invalid algo, bcm or key_bits) + * @retval #YACA_ERROR_INTERNAL Internal error * - * @return YACA_ERROR_NONE on success, negative on error. */ int yaca_get_iv_bits(yaca_enc_algo_e algo, yaca_block_cipher_mode_e bcm, -- 2.7.4 From 03d82d98a4268246cd9a552cffd79aea265fce64 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Mon, 30 May 2016 13:27:44 +0200 Subject: [PATCH 09/16] ACR: yaca_digest.h doxygen fixes Change-Id: Ia6f8d263b7c31b22fe7d97c4bedd3754b3ae00dc --- api/yaca/yaca_digest.h | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/api/yaca/yaca_digest.h b/api/yaca/yaca_digest.h index c91298a..72d6fe1 100644 --- a/api/yaca/yaca_digest.h +++ b/api/yaca/yaca_digest.h @@ -17,7 +17,7 @@ */ /** - * @file digest.h + * @file yaca_digest.h * @brief */ @@ -44,10 +44,15 @@ extern "C" { * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()). - * @param[in] algo Digest algorithm that will be used. + * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()) + * @param[in] algo Digest algorithm that will be used * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_digest_algo_e * @see yaca_digest_update() @@ -60,11 +65,15 @@ int yaca_digest_init(yaca_ctx_h *ctx, yaca_digest_algo_e algo); * * @since_tizen 3.0 * - * @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. + * @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 YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_digest_init() * @see yaca_digest_final() @@ -76,12 +85,17 @@ int yaca_digest_update(yaca_ctx_h ctx, const char *data, size_t data_len); * * @since_tizen 3.0 * - * @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_len Length of the digest, actual number of bytes written will be returned here. - * - * @return YACA_ERROR_NONE on success, negative on error. + * @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_len Length of the digest, + * actual number of bytes written will be returned here + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_digest_init() * @see yaca_digest_update() -- 2.7.4 From 774dc5ac8446f75fc7afbf3b0549854bc109b3af Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Mon, 30 May 2016 14:32:44 +0200 Subject: [PATCH 10/16] ACR: yaca_crypto.h doxygen fixes Change-Id: I421e3095f70efe3264461fbd364d813eb999d93e --- api/yaca/yaca_crypto.h | 88 +++++++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 34 deletions(-) diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index 6b8e634..3672972 100644 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -17,7 +17,7 @@ */ /** - * @file crypto.h + * @file yaca_crypto.h * @brief */ @@ -51,7 +51,10 @@ extern "C" { * * @since_tizen 3.0 * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_exit() */ @@ -71,9 +74,9 @@ void yaca_exit(void); * * @since_tizen 3.0 * - * @param[in] size Size of the allocation (bytes). + * @param[in] size Size of the allocation (bytes) * - * @return NULL on failure, pointer to allocated memory otherwise. + * @return NULL on failure, pointer to allocated memory otherwise * * @see yaca_zalloc() * @see yaca_realloc() @@ -86,9 +89,9 @@ void *yaca_malloc(size_t size); * * @since_tizen 3.0 * - * @param[in] size Size of the allocation (bytes). + * @param[in] size Size of the allocation (bytes) * - * @return NULL on failure, pointer to allocated and zeroed memory otherwise. + * @return NULL on failure, pointer to allocated and zeroed memory otherwise * * @see yaca_malloc() * @see yaca_realloc() @@ -101,10 +104,10 @@ void *yaca_zalloc(size_t size); * * @since_tizen 3.0 * - * @param[in] addr Address of the memory to be reallocated. - * @param[in] size Size of the new allocation (bytes). + * @param[in] addr Address of the memory to be reallocated + * @param[in] size Size of the new allocation (bytes) * - * @return NULL on failure, pointer to allocated memory otherwise. + * @return NULL on failure, pointer to allocated memory otherwise * * @see yaca_malloc() * @see yaca_zalloc() @@ -118,12 +121,11 @@ void *yaca_realloc(void *addr, size_t size); * * @since_tizen 3.0 * - * @param[in] ptr Pointer to the memory to be freed. + * @param[in] ptr Pointer to the memory to be freed * * @see yaca_malloc() * @see yaca_zalloc() * @see yaca_realloc() - * */ void yaca_free(void *ptr); @@ -132,10 +134,13 @@ void yaca_free(void *ptr); * * @since_tizen 3.0 * - * @param[in,out] data Pointer to the memory to be randomized. - * @param[in] data_len Length of the memory to be randomized. + * @param[in,out] data Pointer to the memory to be randomized + * @param[in] data_len Length of the memory to be randomized * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0) + * @retval #YACA_ERROR_INTERNAL Internal error */ int yaca_rand_bytes(char *data, size_t data_len); @@ -145,12 +150,16 @@ int yaca_rand_bytes(char *data, size_t data_len); * * @since_tizen 3.0 * - * @param[in,out] ctx Previously initialized crypto context. - * @param[in] param Parameter to be set. - * @param[in] value Parameter value. - * @param[in] value_len Length of the parameter value. + * @param[in,out] ctx Previously initialized crypto context + * @param[in] param Parameter to be set + * @param[in] value Parameter value + * @param[in] value_len Length of the parameter value * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context, invalid param) + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_ex_param_e * @see yaca_ctx_get_param() @@ -166,12 +175,17 @@ int yaca_ctx_set_param(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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 yaca_free()). - * @param[out] value_len Length of the parameter value will be returned here. + * @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 yaca_free()) + * @param[out] value_len Length of the parameter value will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context, invalid param) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_ex_param_e * @see yaca_ctx_set_param() @@ -183,11 +197,11 @@ int yaca_ctx_get_param(const yaca_ctx_h ctx, /** * @brief Destroys the crypto context. Must be called on all contexts that are - * no longer used. Passing YACA_CTX_NULL is allowed. + * no longer used. Passing #YACA_CTX_NULL is allowed. * * @since_tizen 3.0 * - * @param[in,out] ctx Crypto context. + * @param[in,out] ctx Crypto context * * @see #yaca_ctx_h * @@ -200,11 +214,15 @@ void yaca_ctx_free(yaca_ctx_h ctx); * * @since_tizen 3.0 * - * @param[in] ctx Previously initialized crypto context. - * @param[in] input_len Length of the input data to be processed. - * @param[in] output_len Required length of the output. + * @param[in] ctx Previously initialized crypto context + * @param[in] input_len Length of the input data to be processed + * @param[out] output_len Required length of the output * - * @return negative on error or length of output. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context, invalid input_len) + * @retval #YACA_ERROR_INTERNAL Internal error */ int yaca_get_output_length(const yaca_ctx_h ctx, size_t input_len, size_t *output_len); @@ -234,11 +252,13 @@ int yaca_get_output_length(const yaca_ctx_h ctx, size_t input_len, size_t *outpu * * @since_tizen 3.0 * - * @param[in] first Pointer to the first buffer. - * @param[in] second Pointer to the second buffer. - * @param[in] len Length to compare. + * @param[in] first Pointer to the first buffer + * @param[in] second Pointer to the second buffer + * @param[in] len Length to compare * - * @return YACA_ERROR_NONE when buffers are equal otherwise #YACA_ERROR_DATA_MISMATCH + * @return #YACA_ERROR_NONE when buffers are equal otherwise #YACA_ERROR_DATA_MISMATCH + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_DATA_MISMATCH Buffers are different */ int yaca_memcmp(const void *first, const void *second, size_t len); -- 2.7.4 From 0559d632bcd7a31c4410f3568e7a93b7deeeaeec Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Mon, 30 May 2016 15:16:38 +0200 Subject: [PATCH 11/16] ACR: yaca_error.h doxygen fixes Change-Id: I2555c31e6890d2d184c2bc1e454f18271f26db6b --- api/yaca/yaca_error.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h index aca3d2d..edbbfe7 100755 --- a/api/yaca/yaca_error.h +++ b/api/yaca/yaca_error.h @@ -17,7 +17,7 @@ */ /** - * @file error.h + * @file yaca_error.h * @brief */ @@ -45,12 +45,18 @@ extern "C" { * @since_tizen 3.0 */ typedef enum { + /** Successful */ YACA_ERROR_NONE = TIZEN_ERROR_NONE, + /** Invalid function parameter */ YACA_ERROR_INVALID_ARGUMENT = TIZEN_ERROR_INVALID_PARAMETER, + /** Out of memory */ YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, + /** Internal error */ YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01, + /** Data mismatch */ YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02, + /** Invalid password */ YACA_ERROR_PASSWORD_INVALID = TIZEN_ERROR_YACA | 0x03 } yaca_error_e; -- 2.7.4 From ae7a3cd315b976ba4e8a46566b711adbb46c50ce Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Fri, 27 May 2016 14:07:02 +0200 Subject: [PATCH 12/16] ACR: remove key derive dh/kea Change-Id: I0008dd2179597bb54e4ca3e8da8a0bb862d4fce9 --- api/yaca/yaca_key.h | 34 ---------------------------------- examples/CMakeLists.txt | 1 - src/key.c | 18 ------------------ 3 files changed, 53 deletions(-) diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 455df79..0a3cc42 100755 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -215,40 +215,6 @@ void yaca_key_free(yaca_key_h key); */ /** - * @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. - * @param[out] sym_key Shared secret, that can be used as a symmetric key - * (must be freed with yaca_key_free()). - * - * @return YACA_ERROR_NONE 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); - -/** - * @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. - * @param[in] prv_key_auth Our private key used to create signature on our - * 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 yaca_key_free()). - * - * @return YACA_ERROR_NONE 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); - -/** * @brief Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm). * * @since_tizen 3.0 diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index af00c1c..c1f6ef1 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -48,7 +48,6 @@ BUILD_EXAMPLE("yaca-example-encrypt" encrypt.c) BUILD_EXAMPLE("yaca-example-seal" seal.c) BUILD_EXAMPLE("yaca-example-encrypt-gcm-ccm" encrypt_aes_gcm_ccm.c) BUILD_EXAMPLE("yaca-example-sign" sign.c) -BUILD_EXAMPLE("yaca-example-key-exchange" key_exchange.c) BUILD_EXAMPLE("yaca-example-key-impexp" key_import_export.c) BUILD_EXAMPLE("yaca-example-key-password" key_password.c) diff --git a/src/key.c b/src/key.c index 3de2ba4..cdffd45 100755 --- a/src/key.c +++ b/src/key.c @@ -1136,24 +1136,6 @@ API void yaca_key_free(yaca_key_h key) } } -API int yaca_key_derive_dh(const yaca_key_h prv_key, - const yaca_key_h pub_key, - yaca_key_h *sym_key) -{ - //TODO NOT_IMPLEMENTED - return YACA_ERROR_INVALID_ARGUMENT; -} - -API 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) -{ - //TODO NOT_IMPLEMENTED - return YACA_ERROR_INVALID_ARGUMENT; -} - API int yaca_key_derive_pbkdf2(const char *password, const char *salt, size_t salt_len, -- 2.7.4 From 2c6b2974d28f6227f26ed744f252bf543961ec9b Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Fri, 27 May 2016 16:08:33 +0200 Subject: [PATCH 13/16] ACR: yaca_key.h doxygen fixes @return statements cleaned up Added @retval statements Removed dot at the end of some statements Change-Id: If0495e03f6bf0fc24341f217c94dbbf68550a72e --- api/yaca/yaca_key.h | 119 +++++++++++++++++++++++++++++++--------------------- todo.txt | 3 ++ 2 files changed, 74 insertions(+), 48 deletions(-) diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 0a3cc42..bd959b2 100755 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -17,7 +17,7 @@ */ /** - * @file key.h + * @file yaca_key.h * @brief */ @@ -41,17 +41,17 @@ extern "C" { #define YACA_KEY_NULL ((yaca_key_h) NULL) -// TODO: We need a way to import keys encrypted with hw (or other) keys. New function like yaca_key_load or sth?? - /** * @brief Get key's type. * * @since_tizen 3.0 * - * @param[in] key Key which type we return. - * @param[out] key_type Key type. + * @param[in] key Key which type we return + * @param[out] key_type Key type * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Either of the params is NULL */ int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type); @@ -60,10 +60,13 @@ int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type); * * @since_tizen 3.0 * - * @param[in] key Key which length we return. - * @param[out] key_bits Key length in bits. + * @param[in] key Key which length we return + * @param[out] key_bits Key length in bits * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Either of the params is NULL + * @retval #YACA_ERROR_INTERNAL Internal error */ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits); @@ -86,16 +89,22 @@ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits); * * If the key is encrypted the algorithm will be autodetected and password * used. If it's not known if the key is encrypted one should pass NULL as - * password and check for the YACA_ERROR_PASSWORD_INVALID return code. - * - * @param[out] key Returned key (must be freed with yaca_key_free()). - * @param[in] key_type Type of the key. - * @param[in] password null terminated password for the key (can be NULL). - * @param[in] data Blob containing the key. - * @param[in] data_len Size of the blob. - * - * @return YACA_ERROR_NONE on success, YACA_ERROR_PASSWORD_INVALID if wrong password given, - * negative on error. + * password and check for the #YACA_ERROR_PASSWORD_INVALID return code. + * + * @param[out] key Returned key (must be freed with yaca_key_free()) + * @param[in] key_type Type of the key + * @param[in] password null terminated password for the key (can be NULL) + * @param[in] data Blob containing the key + * @param[in] data_len Size of the blob + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect key_type or data_len too big) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error + * @retval #YACA_ERROR_PASSWORD_INVALID Invalid password given or password was required + * and none was given * * @see #yaca_key_type_e * @see yaca_key_export() @@ -131,15 +140,20 @@ int yaca_key_import(yaca_key_h *key, * TODO:document the default encryption algorithm (AES256 for FORMAT_DEFAULT, * unknown yet for the FORMAT_PKCS8). * - * @param[in] key Key to be exported. - * @param[in] key_fmt Format of the key. - * @param[in] key_file_fmt Format of the key file. - * @param[in] password Password used for the encryption (can be NULL). + * @param[in] key Key to be exported + * @param[in] key_fmt Format of the key + * @param[in] key_file_fmt Format of the key file + * @param[in] password Password used for the encryption (can be NULL) * @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. + * (must be freed with yaca_free()) + * @param[out] data_len Size of the output data * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect key formats or data_len too big) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_fmt_e * @see #yaca_key_file_fmt_e @@ -160,11 +174,16 @@ int yaca_key_export(const yaca_key_h key, * * @remarks This function is used to generate symmetric and private asymmetric keys. * - * @param[out] 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. + * @param[out] 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 YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT key is NULL, incorrect key_type or + * key_bits is not dividable by 8 + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_key_bits_e @@ -179,10 +198,14 @@ int yaca_key_gen(yaca_key_h *key, * * @since_tizen 3.0 * - * @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()). + * @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()) * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT prv_key is of incorrect type or pub_key is NULL + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_key_gen() * @see yaca_key_import() @@ -195,12 +218,11 @@ int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key); * * @since_tizen 3.0 * - * @param key Key to be freed. + * @param[in,out] key Key to be freed * * @see yaca_key_import() * @see yaca_key_export() * @see yaca_key_gen() - * */ void yaca_key_free(yaca_key_h key); @@ -219,15 +241,20 @@ void yaca_key_free(yaca_key_h key); * * @since_tizen 3.0 * - * @param[in] password User password as a NULL-terminated string. - * @param[in] salt Salt, should be non-zero. - * @param[in] salt_len Length of the salt. - * @param[in] iter Number of iterations. - * @param[in] algo Digest algorithm that should be used in key generation. - * @param[in] key_bits Length of a key (in bits) to be generated. - * @param[out] key Newly generated key (must be freed with yaca_key_free()). - * - * @return YACA_ERROR_NONE on success, negative on error. + * @param[in] password User password as a NULL-terminated string + * @param[in] salt Salt, should be non-zero + * @param[in] salt_len Length of the salt + * @param[in] iter Number of iterations + * @param[in] algo Digest algorithm that should be used in key generation + * @param[in] key_bits Length of a key (in bits) to be generated + * @param[out] key Newly generated key (must be freed with yaca_key_free()) + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect algo or key_bits not dividable by 8) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error */ int yaca_key_derive_pbkdf2(const char *password, const char *salt, @@ -237,10 +264,6 @@ int yaca_key_derive_pbkdf2(const char *password, size_t key_bits, yaca_key_h *key); -// TODO: specify -//int yaca_key_wrap(yaca_key_h key, ??); -//int yaca_key_unwrap(yaca_key_h key, ??); - /**@}*/ #ifdef __cplusplus diff --git a/todo.txt b/todo.txt index 216c413..26e6208 100644 --- a/todo.txt +++ b/todo.txt @@ -4,3 +4,6 @@ Global: - Importing/exporting encrypted (passphrased) RSA keys - Support for OCB mode was added in OpenSSL 1.1.0 - Remove debug function from examples +- yaca_key_wrap(), yaca_key_unwrap() +- We need a way to import keys encrypted with hw (or other) keys. New + function like yaca_key_load or sth? -- 2.7.4 From 90a9617a3618a061cc1dac8c4570c0b013acc3e7 Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Fri, 27 May 2016 17:15:53 +0200 Subject: [PATCH 14/16] ACR: change the ordering of key related functions (out last) Change-Id: I4a2df099c1dc594dd0fc08aa7146110ba723c861 --- api/yaca/yaca_key.h | 16 ++++++++-------- examples/encrypt.c | 6 +++--- examples/encrypt_aes_gcm_ccm.c | 8 ++++---- examples/key_exchange.c | 10 +++++----- examples/key_import_export.c | 20 ++++++++++---------- examples/key_password.c | 6 +++--- examples/seal.c | 2 +- examples/sign.c | 12 ++++++------ src/key.c | 12 ++++++------ 9 files changed, 46 insertions(+), 46 deletions(-) diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index bd959b2..83428cc 100755 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -91,11 +91,11 @@ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits); * used. If it's not known if the key is encrypted one should pass NULL as * password and check for the #YACA_ERROR_PASSWORD_INVALID return code. * - * @param[out] key Returned key (must be freed with yaca_key_free()) * @param[in] key_type Type of the key * @param[in] password null terminated password for the key (can be NULL) * @param[in] data Blob containing the key * @param[in] data_len Size of the blob + * @param[out] key Returned key (must be freed with yaca_key_free()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Succesful @@ -110,11 +110,11 @@ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits); * @see yaca_key_export() * @see yaca_key_free() */ -int yaca_key_import(yaca_key_h *key, - yaca_key_type_e key_type, +int yaca_key_import(yaca_key_type_e key_type, const char *password, const char *data, - size_t data_len); + size_t data_len, + yaca_key_h *key); /** * @brief Exports a key to arbitrary format. Export may fail if key is HW-based. @@ -174,9 +174,9 @@ int yaca_key_export(const yaca_key_h key, * * @remarks This function is used to generate symmetric and private asymmetric keys. * - * @param[out] 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 + * @param[out] key Newly generated key (must be freed with yaca_key_free()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Succesful @@ -189,9 +189,9 @@ int yaca_key_export(const yaca_key_h key, * @see #yaca_key_bits_e * @see yaca_key_free() */ -int yaca_key_gen(yaca_key_h *key, - yaca_key_type_e key_type, - size_t key_bits); +int yaca_key_gen(yaca_key_type_e key_type, + size_t key_bits, + yaca_key_h *key); /** * @brief Extracts public key from a private one. diff --git a/examples/encrypt.c b/examples/encrypt.c index ca84b1c..e4c18f7 100644 --- a/examples/encrypt.c +++ b/examples/encrypt.c @@ -56,7 +56,7 @@ void encrypt_simple(const yaca_enc_algo_e algo, if (yaca_get_iv_bits(algo, bcm, key_bits, &iv_bits) != YACA_ERROR_NONE) goto exit; - if (iv_bits > 0 && yaca_key_gen(&iv, YACA_KEY_TYPE_IV, iv_bits) != YACA_ERROR_NONE) + if (iv_bits > 0 && yaca_key_gen(YACA_KEY_TYPE_IV, iv_bits, &iv) != YACA_ERROR_NONE) goto exit; if (yaca_encrypt(algo, bcm, key, iv, lorem4096, LOREM4096_SIZE, &enc, &enc_size) != YACA_ERROR_NONE) @@ -100,13 +100,13 @@ void encrypt_advanced(const yaca_enc_algo_e algo, printf("Plain data (16 of %zu bytes): %.16s\n", LOREM4096_SIZE, lorem4096); /* Key generation */ - if (yaca_key_gen(&key, key_type, key_bits) != YACA_ERROR_NONE) + if (yaca_key_gen(key_type, key_bits, &key) != YACA_ERROR_NONE) return; if (yaca_get_iv_bits(algo, bcm, key_bits, &iv_bits) != YACA_ERROR_NONE) goto ex_key; - if (iv_bits > 0 && yaca_key_gen(&iv, YACA_KEY_TYPE_IV, iv_bits) != YACA_ERROR_NONE) + if (iv_bits > 0 && yaca_key_gen(YACA_KEY_TYPE_IV, iv_bits, &iv) != YACA_ERROR_NONE) goto ex_key; /* Encryption */ diff --git a/examples/encrypt_aes_gcm_ccm.c b/examples/encrypt_aes_gcm_ccm.c index 00cffca..523153a 100644 --- a/examples/encrypt_aes_gcm_ccm.c +++ b/examples/encrypt_aes_gcm_ccm.c @@ -63,11 +63,11 @@ void encrypt_decrypt_aes_gcm(void) printf("Plain data (16 of %zu bytes): %.16s\n", LOREM4096_SIZE, lorem4096); /* Key generation */ - if (yaca_key_gen(&key, key_type, key_bits) != YACA_ERROR_NONE) + if (yaca_key_gen(key_type, key_bits, &key) != YACA_ERROR_NONE) return; /* IV generation */ - if (yaca_key_gen(&iv, YACA_KEY_TYPE_IV, iv_bits) != YACA_ERROR_NONE) + if (yaca_key_gen(YACA_KEY_TYPE_IV, iv_bits, &iv) != YACA_ERROR_NONE) goto clean; if ((aad = yaca_zalloc(aad_size)) == NULL) @@ -203,11 +203,11 @@ void encrypt_decrypt_aes_ccm(void) printf("Plain data (16 of %zu bytes): %.16s\n", LOREM4096_SIZE, lorem4096); /* Key generation */ - if (yaca_key_gen(&key, key_type, key_bits) != YACA_ERROR_NONE) + if (yaca_key_gen(key_type, key_bits, &key) != YACA_ERROR_NONE) return; /* IV generation */ - if (yaca_key_gen(&iv, YACA_KEY_TYPE_IV, iv_bits) != YACA_ERROR_NONE) + if (yaca_key_gen(YACA_KEY_TYPE_IV, iv_bits, &iv) != YACA_ERROR_NONE) goto clean; if ((aad = yaca_zalloc(aad_size)) == NULL) diff --git a/examples/key_exchange.c b/examples/key_exchange.c index 4bcfce6..7233a10 100644 --- a/examples/key_exchange.c +++ b/examples/key_exchange.c @@ -44,7 +44,7 @@ void key_exchange_dh(void) long size; // generate private, public key - ret = yaca_key_gen(&private_key, YACA_KEY_TYPE_DH_PRIV, YACA_KEY_2048BIT); + ret = yaca_key_gen(YACA_KEY_TYPE_DH_PRIV, YACA_KEY_2048BIT, &private_key); if (ret != YACA_ERROR_NONE) goto clean; @@ -70,8 +70,8 @@ void key_exchange_dh(void) if (1 != fread(buffer, size, 1, fp)) goto clean; - ret = yaca_key_import(&peer_key, YACA_KEY_TYPE_DH_PUB, NULL, - buffer, size); + ret = yaca_key_import(YACA_KEY_TYPE_DH_PUB, NULL, + buffer, size, &peer_key); if (ret != YACA_ERROR_NONE) goto clean; @@ -104,7 +104,7 @@ void key_exchange_ecdh(void) long size; // generate private, public key - ret = yaca_key_gen(&private_key, YACA_KEY_TYPE_EC_PRIV, YACA_KEY_CURVE_P256); + ret = yaca_key_gen(YACA_KEY_TYPE_EC_PRIV, YACA_KEY_CURVE_P256, &private_key); if (ret != YACA_ERROR_NONE) goto clean; @@ -130,7 +130,7 @@ void key_exchange_ecdh(void) if (1 != fread(buffer, size, 1, fp)) goto clean; - ret = yaca_key_import(&peer_key, YACA_KEY_TYPE_EC_PUB, NULL, buffer, size); + ret = yaca_key_import(YACA_KEY_TYPE_EC_PUB, NULL, buffer, size, &peer_key); if (ret != YACA_ERROR_NONE) goto clean; diff --git a/examples/key_import_export.c b/examples/key_import_export.c index 0a79fdf..3fb33e6 100644 --- a/examples/key_import_export.c +++ b/examples/key_import_export.c @@ -48,7 +48,7 @@ int key_import_export_sym(yaca_key_h sym) ret = yaca_key_export(sym, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_BASE64, NULL, &b64, &b64_len); if (ret != YACA_ERROR_NONE) return ret; - ret = yaca_key_import(&b64_imported, YACA_KEY_TYPE_SYMMETRIC, NULL, b64, b64_len); + ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, b64, b64_len, &b64_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -68,7 +68,7 @@ int key_import_export_sym(yaca_key_h sym) ret = yaca_key_export(sym, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_RAW, NULL, &raw, &raw_len); if (ret != YACA_ERROR_NONE) goto free; - ret = yaca_key_import(&raw_imported, YACA_KEY_TYPE_SYMMETRIC, NULL, raw, raw_len); + ret = yaca_key_import(YACA_KEY_TYPE_SYMMETRIC, NULL, raw, raw_len, &raw_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -120,7 +120,7 @@ int key_import_export_asym(yaca_key_h priv, yaca_key_h pub, ret = yaca_key_export(priv, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_PEM, NULL, &pem_prv, &pem_prv_len); if (ret != YACA_ERROR_NONE) return ret; - ret = yaca_key_import(&pem_prv_imported, priv_type, NULL, pem_prv, pem_prv_len); + ret = yaca_key_import(priv_type, NULL, pem_prv, pem_prv_len, &pem_prv_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -140,7 +140,7 @@ int key_import_export_asym(yaca_key_h priv, yaca_key_h pub, ret = yaca_key_export(priv, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_DER, NULL, &der_prv, &der_prv_len); if (ret != YACA_ERROR_NONE) goto free; - ret = yaca_key_import(&der_prv_imported, priv_type, NULL, der_prv, der_prv_len); + ret = yaca_key_import(priv_type, NULL, der_prv, der_prv_len, &der_prv_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -160,7 +160,7 @@ int key_import_export_asym(yaca_key_h priv, yaca_key_h pub, ret = yaca_key_export(pub, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_PEM, NULL, &pem_pub, &pem_pub_len); if (ret != YACA_ERROR_NONE) goto free; - ret = yaca_key_import(&pem_pub_imported, pub_type, NULL, pem_pub, pem_pub_len); + ret = yaca_key_import(pub_type, NULL, pem_pub, pem_pub_len, &pem_pub_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -180,7 +180,7 @@ int key_import_export_asym(yaca_key_h priv, yaca_key_h pub, ret = yaca_key_export(pub, YACA_KEY_FORMAT_DEFAULT, YACA_KEY_FILE_FORMAT_DER, NULL, &der_pub, &der_pub_len); if (ret != YACA_ERROR_NONE) goto free; - ret = yaca_key_import(&der_pub_imported, pub_type, NULL, der_pub, der_pub_len); + ret = yaca_key_import(pub_type, NULL, der_pub, der_pub_len, &der_pub_imported); if (ret != YACA_ERROR_NONE) goto free; @@ -224,7 +224,7 @@ int key_import_x509(void) return ret; } - ret = yaca_key_import(&rsa_pub_from_cert, YACA_KEY_TYPE_RSA_PUB, NULL, pub, pub_len); + ret = yaca_key_import(YACA_KEY_TYPE_RSA_PUB, NULL, pub, pub_len, &rsa_pub_from_cert); if (ret != YACA_ERROR_NONE) goto free; @@ -260,11 +260,11 @@ int main() yaca_debug_set_error_cb(debug_func); - ret = yaca_key_gen(&sym, YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_1024BIT); + ret = yaca_key_gen(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_1024BIT, &sym); if (ret != YACA_ERROR_NONE) goto exit; - ret = yaca_key_gen(&rsa_priv, YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_1024BIT); + ret = yaca_key_gen(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_1024BIT, &rsa_priv); if (ret != YACA_ERROR_NONE) goto free; @@ -272,7 +272,7 @@ int main() if (ret != YACA_ERROR_NONE) goto free; - ret = yaca_key_gen(&dsa_priv, YACA_KEY_TYPE_DSA_PRIV, YACA_KEY_1024BIT); + ret = yaca_key_gen(YACA_KEY_TYPE_DSA_PRIV, YACA_KEY_1024BIT, &dsa_priv); if (ret != YACA_ERROR_NONE) goto free; diff --git a/examples/key_password.c b/examples/key_password.c index 5a79e15..7890464 100644 --- a/examples/key_password.c +++ b/examples/key_password.c @@ -40,7 +40,7 @@ int main(int argc, char* argv[]) if (ret != YACA_ERROR_NONE) goto exit; - ret = yaca_key_gen(&key, YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_1024BIT); + ret = yaca_key_gen(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_1024BIT, &key); if (ret != YACA_ERROR_NONE) goto exit; @@ -57,13 +57,13 @@ int main(int argc, char* argv[]) password = NULL; key = YACA_KEY_NULL; - ret = yaca_key_import(&key, YACA_KEY_TYPE_RSA_PRIV, NULL, k, kl); + ret = yaca_key_import(YACA_KEY_TYPE_RSA_PRIV, NULL, k, kl, &key); if (ret == YACA_ERROR_PASSWORD_INVALID) { ret = read_stdin_line("decryption pass: ", &password); if (ret != YACA_ERROR_NONE) goto exit; - ret = yaca_key_import(&key, YACA_KEY_TYPE_RSA_PRIV, password, k, kl); + ret = yaca_key_import(YACA_KEY_TYPE_RSA_PRIV, password, k, kl, &key); if (ret == YACA_ERROR_PASSWORD_INVALID) printf("invalid password\n"); diff --git a/examples/seal.c b/examples/seal.c index 586874e..be640ff 100644 --- a/examples/seal.c +++ b/examples/seal.c @@ -56,7 +56,7 @@ void encrypt_seal(void) printf("Plain data (16 of %zu bytes): %.16s\n", LOREM4096_SIZE, lorem4096); /* Generate key pair */ - if (yaca_key_gen(&key_priv, YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_4096BIT) != YACA_ERROR_NONE) + if (yaca_key_gen(YACA_KEY_TYPE_RSA_PRIV, YACA_KEY_4096BIT, &key_priv) != YACA_ERROR_NONE) return; if (yaca_key_extract_public(key_priv, &key_pub) != YACA_ERROR_NONE) diff --git a/examples/sign.c b/examples/sign.c index d5f65d6..2dc456b 100644 --- a/examples/sign.c +++ b/examples/sign.c @@ -43,7 +43,7 @@ void simple_sign_verify_asym(yaca_key_type_e type, const char *algo) yaca_key_h pub = YACA_KEY_NULL; // GENERATE - if (yaca_key_gen(&prv, type, YACA_KEY_1024BIT) != YACA_ERROR_NONE) + if (yaca_key_gen(type, YACA_KEY_1024BIT, &prv) != YACA_ERROR_NONE) return; if (yaca_key_extract_public(prv, &pub) != YACA_ERROR_NONE) @@ -86,7 +86,7 @@ void simple_sign_verify_hmac(void) yaca_key_h key = YACA_KEY_NULL; // GENERATE - if (yaca_key_gen(&key, YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT) != YACA_ERROR_NONE) + if (yaca_key_gen(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT, &key) != YACA_ERROR_NONE) return; // SIGN @@ -129,7 +129,7 @@ void simple_sign_verify_cmac(void) yaca_key_h key = YACA_KEY_NULL; // GENERATE - if (yaca_key_gen(&key, YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT)) + if (yaca_key_gen(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT, &key)) return; // SIGN @@ -176,7 +176,7 @@ void sign_verify_asym(yaca_key_type_e type, const char *algo) yaca_padding_e padding = YACA_PADDING_PKCS1_PSS; // GENERATE - if (yaca_key_gen(&prv, type, YACA_KEY_1024BIT) != YACA_ERROR_NONE) + if (yaca_key_gen(type, YACA_KEY_1024BIT, &prv) != YACA_ERROR_NONE) return; if (yaca_key_extract_public(prv, &pub) != YACA_ERROR_NONE) @@ -239,7 +239,7 @@ void sign_verify_hmac(void) yaca_key_h key = YACA_KEY_NULL; // GENERATE - if (yaca_key_gen(&key, YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT) != YACA_ERROR_NONE) + if (yaca_key_gen(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT, &key) != YACA_ERROR_NONE) return; // SIGN @@ -302,7 +302,7 @@ void sign_verify_cmac(void) yaca_key_h key = YACA_KEY_NULL; // GENERATE - if (yaca_key_gen(&key, YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT)) + if (yaca_key_gen(YACA_KEY_TYPE_SYMMETRIC, YACA_KEY_256BIT, &key)) return; // SIGN diff --git a/src/key.c b/src/key.c index cdffd45..9b4e9c0 100755 --- a/src/key.c +++ b/src/key.c @@ -912,11 +912,11 @@ API int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits) return YACA_ERROR_INVALID_ARGUMENT; } -API int yaca_key_import(yaca_key_h *key, - yaca_key_type_e key_type, +API int yaca_key_import(yaca_key_type_e key_type, const char *password, const char *data, - size_t data_len) + size_t data_len, + yaca_key_h *key) { if (key == NULL || data == NULL || data_len == 0) return YACA_ERROR_INVALID_ARGUMENT; @@ -990,9 +990,9 @@ API int yaca_key_export(const yaca_key_h key, // TODO: this NEEDS random number generator initialized // there is some other TODO elsewhere about it -API int yaca_key_gen(yaca_key_h *key, - yaca_key_type_e key_type, - size_t key_bits) +API int yaca_key_gen(yaca_key_type_e key_type, + size_t key_bits, + yaca_key_h *key) { int ret; struct yaca_key_simple_s *nk_simple = NULL; -- 2.7.4 From 2230c015acbcaa43a5b306355b3c7f3af4e3f4f2 Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Mon, 30 May 2016 14:39:33 +0200 Subject: [PATCH 15/16] ACR: yaca_sign.h doxygen fixes Change-Id: I1570a1201b59ced862e3ce580f7563420eca5eab --- api/yaca/yaca_sign.h | 124 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 82 insertions(+), 42 deletions(-) diff --git a/api/yaca/yaca_sign.h b/api/yaca/yaca_sign.h index 0d2f399..27895f4 100644 --- a/api/yaca/yaca_sign.h +++ b/api/yaca/yaca_sign.h @@ -17,7 +17,7 @@ */ /** - * @file sign.h + * @file yaca_sign.h * @brief */ @@ -48,15 +48,20 @@ extern "C" { * @remarks For verification use yaca_verify_init(), yaca_verify_update() and * yaca_verify_final() functions with matching public key. * - * @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 key that will be used. Algorithm is deduced based - * on key type. Supported key types: + * @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 key that will be used, algorithm is deduced based + * on key type, supported key types: * - #YACA_KEY_TYPE_RSA_PRIV, * - #YACA_KEY_TYPE_DSA_PRIV, - * - #YACA_KEY_TYPE_EC_PRIV. + * - #YACA_KEY_TYPE_EC_PRIV * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -78,13 +83,18 @@ int yaca_sign_init(yaca_ctx_h *ctx, * @remarks For verification, calculate message HMAC and compare with received MAC using * yaca_memcmp(). * - * @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 Symmetric key that will be used. Supported key types: + * @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 Symmetric key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES. + * - #YACA_KEY_TYPE_DES * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -104,13 +114,18 @@ int yaca_sign_hmac_init(yaca_ctx_h *ctx, * @remarks For verification, calculate message CMAC and compare with received MAC using * yaca_memcmp(). * - * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()). - * @param[in] algo Encryption algorithm that will be used. - * @param[in] key Symmetric key that will be used. Supported key types: + * @param[out] ctx Newly created context (must be freed with yaca_ctx_free()) + * @param[in] algo Encryption algorithm that will be used + * @param[in] key Symmetric key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES. + * - #YACA_KEY_TYPE_DES * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_enc_algo_e @@ -128,11 +143,16 @@ int yaca_sign_cmac_init(yaca_ctx_h *ctx, * @since_tizen 3.0 * * @param[in,out] ctx Context created by yaca_sign_init(), - * yaca_sign_hmac_init() or yaca_sign_cmac_init(). - * @param[in] data Data to be signed. - * @param[in] data_len Length of the data. + * yaca_sign_hmac_init() or yaca_sign_cmac_init() + * @param[in] data Data to be signed + * @param[in] data_len Length of the data * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_sign_init() * @see yaca_sign_final() @@ -148,13 +168,18 @@ int yaca_sign_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx A valid sign context. - * @param[out] signature Buffer for the MAC or the signature, - * (must be allocated by client, see yaca_get_sign_length()). + * @param[in,out] ctx A valid sign context + * @param[out] signature Buffer for the MAC or the signature + * (must be allocated by client, see yaca_get_sign_length()) * @param[out] signature_len Length of the MAC or the signature, - * actual number of bytes written will be returned here. + * actual number of bytes written will be returned here * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_sign_init() * @see yaca_sign_update() @@ -170,15 +195,20 @@ int yaca_sign_final(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @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 Public key that will be used. Algorithm is deduced based on - * key type. Supported key types: + * @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 Public key that will be used, algorithm is deduced based on + * key type, supported key types: * - #YACA_KEY_TYPE_RSA_PUB, * - #YACA_KEY_TYPE_DSA_PUB, - * - #YACA_KEY_TYPE_EC_PUB. + * - #YACA_KEY_TYPE_EC_PUB * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -194,11 +224,16 @@ int yaca_verify_init(yaca_ctx_h *ctx, * * @since_tizen 3.0 * - * @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. + * @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 YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0, + * incorrect context) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see yaca_verify_init() * @see yaca_verify_final() @@ -212,12 +247,17 @@ int yaca_verify_update(yaca_ctx_h ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx A valid verify context. - * @param[in] signature Input signature (returned by yaca_sign_final()). - * @param[in] signature_len Size of the signature. - * - * @return YACA_ERROR_NONE on success, YACA_ERROR_DATA_MISMATCH if verification fails, - * negative on error. + * @param[in,out] ctx A valid verify context + * @param[in] signature Input signature (returned by yaca_sign_final()) + * @param[in] signature_len Size of the signature + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, + * incorrect context) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error + * @retval #YACA_ERROR_DATA_MISMATCH The verification failed * * @see yaca_verify_init() * @see yaca_verify_update() -- 2.7.4 From 4e4bd1215e231034e0b9031274860b56dacce5b7 Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Mon, 30 May 2016 14:43:16 +0200 Subject: [PATCH 16/16] ACR: yaca_simple.h doxygen fixes Change-Id: I0fd4c1d626275ae690b0a25e022687583f838445 --- api/yaca/yaca_simple.h | 183 +++++++++++++++++++++++++++++-------------------- 1 file changed, 109 insertions(+), 74 deletions(-) diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index 9f3d90c..10a0467 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -17,7 +17,7 @@ */ /** - * @file simple.h + * @file yaca_simple.h * @brief */ @@ -34,13 +34,13 @@ extern "C" { /** * @defgroup Simple-API Simple API. * - * This is simple API. - * Design constraints: - * - All operations are single-shot (no streaming possible) - * - Context is not used - * - For now only digest and symmetric ciphers are supported - * - GCM and CCM chaining is not supported - * - All outputs are allocated by the library + * @remarks This is simple API. + * Design constraints: + * - All operations are single-shot (no streaming possible) + * - Context is not used + * - For now only digest and symmetric ciphers are supported + * - GCM and CCM chaining is not supported + * - All outputs are allocated by the library * * TODO: extended description and examples. * @@ -52,14 +52,19 @@ extern "C" { * * @since_tizen 3.0 * - * @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[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 yaca_free()). - * @param[out] digest_len Length of message digest (depends on algorithm). + * (should be freed with yaca_free()) + * @param[out] digest_len Length of message digest (depends on algorithm) * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_digest_algo_e */ @@ -74,17 +79,22 @@ int yaca_digest_calc(yaca_digest_algo_e algo, * * @since_tizen 3.0 * - * @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[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 yaca_free()). - * @param[out] cipher_len Length of the encrypted data (may be larger than decrypted). + * (should be freed with yaca_free()) + * @param[out] cipher_len Length of the encrypted data (may be larger than decrypted) * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, bcm, invalid sym_key, iv) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -104,17 +114,22 @@ int yaca_encrypt(yaca_enc_algo_e algo, * * @since_tizen 3.0 * - * @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[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. + * (should be freed with yaca_free()) + * @param[out] plain_len Length of the decrypted data * - * @return YACA_ERROR_NONE on success, negative on error. + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, bcm, invalid sym_key, iv) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_enc_algo_e * @see #yaca_block_cipher_mode_e @@ -134,19 +149,24 @@ int yaca_decrypt(yaca_enc_algo_e algo, * * @since_tizen 3.0 * - * @param[in] algo Digest algorithm that will be used. - * @param[in] key Private key that will be used. Algorithm is - * deduced based on key type. Supported key types: + * @param[in] algo Digest algorithm that will be used + * @param[in] key Private key that will be used, algorithm is + * deduced based on key type, supported key types: * - #YACA_KEY_TYPE_RSA_PRIV, * - #YACA_KEY_TYPE_DSA_PRIV, - * - #YACA_KEY_TYPE_EC_PRIV. - * @param[in] data Data to be signed. - * @param[in] data_len Length of the data. - * @param[out] signature Message signature. Will be allocated by the - * library. Should be freed with yaca_free(). - * @param[out] signature_len Length of the signature. - * - * @return YACA_ERROR_NONE on success, negative on error. + * - #YACA_KEY_TYPE_EC_PRIV + * @param[in] data Data to be signed + * @param[in] data_len Length of the data + * @param[out] signature Message signature, will be allocated by the + * library (should be freed with yaca_free()) + * @param[out] signature_len Length of the signature + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -164,19 +184,24 @@ int yaca_sign(yaca_digest_algo_e algo, * * @since_tizen 3.0 * - * @param[in] algo Digest algorithm that will be used. - * @param[in] key Public key that will be used. Algorithm is - * deduced based on key type. Supported key types: + * @param[in] algo Digest algorithm that will be used + * @param[in] key Public key that will be used, algorithm is + * deduced based on key type, supported key types: * - #YACA_KEY_TYPE_RSA_PUB, * - #YACA_KEY_TYPE_DSA_PUB, - * - #YACA_KEY_TYPE_EC_PUB. - * @param[in] data Signed data. - * @param[in] data_len Length of the data. - * @param[in] signature Message signature. - * @param[in] signature_len Length of the signature. - * - * @return YACA_ERROR_NONE on success, YACA_ERROR_SIGNATURE_INVALID if verification fails, - * negative on error. + * - #YACA_KEY_TYPE_EC_PUB + * @param[in] data Signed data + * @param[in] data_len Length of the data + * @param[in] signature Message signature + * @param[in] signature_len Length of the signature + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error + * @retval #YACA_ERROR_DATA_MISMATCH The verification failed * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -197,17 +222,22 @@ int yaca_verify(yaca_digest_algo_e algo, * @remarks For verification, calculate message HMAC and compare with received MAC using * yaca_memcmp(). * - * @param[in] algo Digest algorithm that will be used. - * @param[in] key Key that will be used. Supported key types: + * @param[in] algo Digest algorithm that will be used + * @param[in] key Key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES. - * @param[in] data Data to calculate HMAC from. - * @param[in] data_len Length of the data. - * @param[out] mac MAC. Will be allocated by the library. Should be freed - * with yaca_free(). - * @param[out] mac_len Length of the MAC. - * - * @return YACA_ERROR_NONE on success, negative on error. + * - #YACA_KEY_TYPE_DES + * @param[in] data Data to calculate HMAC from + * @param[in] data_len Length of the data + * @param[out] mac MAC, will be allocated by the library + * (should be freed with yaca_free()) + * @param[out] mac_len Length of the MAC + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_digest_algo_e @@ -228,17 +258,22 @@ int yaca_hmac(yaca_digest_algo_e algo, * @remarks For verification, calculate message CMAC and compare with received MAC using * yaca_memcmp(). * - * @param[in] algo Encryption algorithm that will be used. - * @param[in] key Key that will be used. Supported key types: + * @param[in] algo Encryption algorithm that will be used + * @param[in] key Key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES. - * @param[in] data Data to calculate CMAC from. - * @param[in] data_len Length of the data. - * @param[out] mac MAC. Will be allocated by the library. Should be freed - * with yaca_free(). - * @param[out] mac_len Length of the MAC. - * - * @return YACA_ERROR_NONE on success, negative on error. + * - #YACA_KEY_TYPE_DES + * @param[in] data Data to calculate CMAC from + * @param[in] data_len Length of the data + * @param[out] mac MAC, will be allocated by the library + * (should be freed with yaca_free()) + * @param[out] mac_len Length of the MAC + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Succesful + * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0 + * incorrect algo, invalid key) + * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error + * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_key_type_e * @see #yaca_enc_algo_e -- 2.7.4