From: Lukasz Pawelczyk Date: Wed, 8 Jun 2016 10:44:59 +0000 (+0200) Subject: ACR: extend parameter names a little in specific cases X-Git-Tag: submit/tizen/20160809.225820~62 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a6201c17cd55173b0d7fa0a30ed15c40b3e1215c;p=platform%2Fcore%2Fsecurity%2Fyaca.git ACR: extend parameter names a little in specific cases Change-Id: I8cbad0e2dce8552fb72e901a5b139ec727083bba --- diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index badc635..652913c 100644 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -141,7 +141,7 @@ int yaca_realloc(size_t size, void **memory); * * @since_tizen 3.0 * - * @param[in] ptr Pointer to the memory to be freed + * @param[in] memory Pointer to the memory to be freed * * @return #YACA_ERROR_NONE on success * @retval #YACA_ERROR_NONE Successful @@ -150,7 +150,7 @@ int yaca_realloc(size_t size, void **memory); * @see yaca_zalloc() * @see yaca_realloc() */ -int yaca_free(void *ptr); +int yaca_free(void *memory); /** * @brief Safely compares first @b len bytes of two buffers. @@ -189,21 +189,21 @@ int yaca_randomize_bytes(char *data, size_t data_len); * @since_tizen 3.0 * * @param[in,out] ctx Previously initialized crypto context - * @param[in] param Property to be set + * @param[in] property Property to be set * @param[in] value Property value * @param[in] value_len Length of the property value * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, - * invalid ctx or param) + * invalid ctx or property) * @retval #YACA_ERROR_INTERNAL Internal error * * @see #yaca_property_e * @see yaca_context_get_property() */ int yaca_context_set_property(yaca_context_h ctx, - yaca_property_e param, + yaca_property_e property, const void *value, size_t value_len); @@ -214,14 +214,14 @@ int yaca_context_set_property(yaca_context_h ctx, * @since_tizen 3.0 * * @param[in] ctx Previously initialized crypto context - * @param[in] param Property to be read + * @param[in] property Property to be read * @param[out] value Copy of the property value (must be freed with yaca_free()) * @param[out] value_len Length of the property value will be returned here * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, - * invalid ctx or param) + * invalid ctx or property) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @@ -230,7 +230,7 @@ int yaca_context_set_property(yaca_context_h ctx, * @see yaca_free() */ int yaca_context_get_property(const yaca_context_h ctx, - yaca_property_e param, + yaca_property_e property, void **value, size_t *value_len); @@ -270,7 +270,9 @@ int yaca_context_destroy(yaca_context_h ctx); * invalid context or too big input_len) * @retval #YACA_ERROR_INTERNAL Internal error */ -int yaca_context_get_output_length(const yaca_context_h ctx, size_t input_len, size_t *output_len); +int yaca_context_get_output_length(const yaca_context_h ctx, + size_t input_len, + size_t *output_len); /**@}*/ diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index f0e6ee2..ab50c39 100644 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -39,6 +39,31 @@ extern "C" { * @{ */ +/** + * @brief Returns the recommended/default length of the IV for a given encryption configuration. + * + * @since_tizen 3.0 + * + * @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_bit_len Key length in bits + * @param[out] iv_bit_len Recommended IV length in bits + * + * @return #YACA_ERROR_NONE on success, negative on error + * @retval #YACA_ERROR_NONE Successful + * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, + * invalid algo, bcm or key_bit_len) + * @retval #YACA_ERROR_INTERNAL Internal error + * + */ +int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, + yaca_block_cipher_mode_e bcm, + size_t key_bit_len, + size_t *iv_bit_len); + /** * @brief Initializes an encryption context. * @@ -74,13 +99,13 @@ int yaca_encrypt_initialize(yaca_context_h *ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx Context created by yaca_encrypt_initialize() - * @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_context_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_initialize() + * @param[in] plaintext Plaintext to be encrypted + * @param[in] plaintext_len Length of the plaintext + * @param[out] ciphertext Buffer for the encrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] ciphertext_len Length of the encrypted data, + * actual number of bytes written will be returned here * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -93,21 +118,21 @@ int yaca_encrypt_initialize(yaca_context_h *ctx, * @see yaca_context_get_output_length() */ int yaca_encrypt_update(yaca_context_h ctx, - const char *plain, - size_t plain_len, - char *cipher, - size_t *cipher_len); + const char *plaintext, + size_t plaintext_len, + char *ciphertext, + size_t *ciphertext_len); /** * @brief Encrypts the final chunk of the data. * * @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_context_get_output_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] ciphertext Final piece of the encrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] ciphertext_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 Successful @@ -120,8 +145,8 @@ int yaca_encrypt_update(yaca_context_h ctx, * @see yaca_context_get_output_length() */ int yaca_encrypt_finalize(yaca_context_h ctx, - char *cipher, - size_t *cipher_len); + char *ciphertext, + size_t *ciphertext_len); /** * @brief Initializes an decryption context. @@ -158,13 +183,13 @@ int yaca_decrypt_initialize(yaca_context_h *ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx Context created by yaca_decrypt_initialize() - * @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_context_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_initialize() + * @param[in] ciphertext Ciphertext to be decrypted + * @param[in] ciphertext_len Length of the ciphertext + * @param[out] plaintext Buffer for the decrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] plaintext_len Length of the decrypted data, + * actual number of bytes written will be returned here * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -177,21 +202,21 @@ int yaca_decrypt_initialize(yaca_context_h *ctx, * @see yaca_context_get_output_length() */ int yaca_decrypt_update(yaca_context_h ctx, - const char *cipher, - size_t cipher_len, - char *plain, - size_t *plain_len); + const char *ciphertext, + size_t ciphertext_len, + char *plaintext, + size_t *plaintext_len); /** * @brief Decrypts the final chunk of the data. * * @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_context_get_output_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] plaintext Final piece of the decrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] plaintext_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 Successful @@ -204,33 +229,8 @@ int yaca_decrypt_update(yaca_context_h ctx, * @see yaca_context_get_output_length() */ int yaca_decrypt_finalize(yaca_context_h ctx, - char *plain, - size_t *plain_len); - -/** - * @brief Returns the recommended/default length of the IV for a given encryption configuration. - * - * @since_tizen 3.0 - * - * @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 - * - * @return #YACA_ERROR_NONE on success, negative on error - * @retval #YACA_ERROR_NONE Successful - * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, - * invalid algo, bcm or key_bits) - * @retval #YACA_ERROR_INTERNAL Internal error - * - */ -int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, - yaca_block_cipher_mode_e bcm, - size_t key_bits, - size_t *iv_bits); + char *plaintext, + size_t *plaintext_len); /**@}*/ diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index ee5167e..3dad4f4 100644 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -65,15 +65,15 @@ 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_bit_len Key length in bits * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL * @retval #YACA_ERROR_INTERNAL Internal error */ -int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bits); +int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len); /** * @brief Imports a key. @@ -184,14 +184,14 @@ int yaca_key_export(const yaca_key_h key, * - RSA: length >= 256bits * - DSA: length >= 512bits, multiple of 64 * - * @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_destroy()) + * @param[in] key_type Type of the key to be generated + * @param[in] key_bit_len Length of the key (in bits) to be generated + * @param[out] key Newly generated key (must be freed with yaca_key_destroy()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL, incorrect key_type or - * key_bits is not dividable by 8 + * key_bit_len is not dividable by 8 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @@ -200,7 +200,7 @@ int yaca_key_export(const yaca_key_h key, * @see yaca_key_destroy() */ int yaca_key_generate(yaca_key_type_e key_type, - size_t key_bits, + size_t key_bit_len, yaca_key_h *key); /** @@ -254,18 +254,18 @@ int yaca_key_destroy(yaca_key_h key); * * @since_tizen 3.0 * - * @param[in] password User password as a NULL-terminated string - * @param[in] salt Salt, should be a non-empty string - * @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_destroy()) + * @param[in] password User password as a NULL-terminated string + * @param[in] salt Salt, should be a non-empty string + * @param[in] salt_len Length of the salt + * @param[in] iterations Number of iterations + * @param[in] algo Digest algorithm that should be used in key generation + * @param[in] key_bit_len Length of a key (in bits) to be generated + * @param[out] key Newly generated key (must be freed with yaca_key_destroy()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, - * invalid algo or key_bits not dividable by 8) + * invalid algo or key_bit_len not dividable by 8) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @@ -275,9 +275,9 @@ int yaca_key_destroy(yaca_key_h key); int yaca_key_derive_pbkdf2(const char *password, const char *salt, size_t salt_len, - int iter, + int iterations, yaca_digest_algorithm_e algo, - size_t key_bits, + size_t key_bit_len, yaca_key_h *key); /**@}*/ diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index f1e351b..f6e3df7 100644 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -48,21 +48,21 @@ extern "C" { * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) - * @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 - * (must be freed with yaca_key_destroy()) - * @param[out] iv Generated initialization vector that will be used - * (must be freed with yaca_key_destroy()) + * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @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_bit_len 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 + * (must be freed with yaca_key_destroy()) + * @param[out] iv Generated initialization vector that will be used + * (must be freed with yaca_key_destroy()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, - * invalid algo, bcm, sym_key_bits or pub_key) + * invalid algo, bcm, sym_key_bit_len or pub_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @@ -77,7 +77,7 @@ int yaca_seal_initialize(yaca_context_h *ctx, const yaca_key_h pub_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, - yaca_key_bit_length_e sym_key_bits, + yaca_key_bit_length_e sym_key_bit_len, yaca_key_h *sym_key, yaca_key_h *iv); @@ -86,13 +86,13 @@ int yaca_seal_initialize(yaca_context_h *ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx Context created by yaca_seal_initialize() - * @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_context_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_initialize() + * @param[in] plaintext Plaintext to be encrypted + * @param[in] plaintext_len Length of the plaintext + * @param[out] ciphertext Buffer for the encrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] ciphertext_len Length of the encrypted data, + * actual number of bytes written will be returned here * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -105,21 +105,21 @@ int yaca_seal_initialize(yaca_context_h *ctx, * @see yaca_context_get_output_length() */ int yaca_seal_update(yaca_context_h ctx, - const char *plain, - size_t plain_len, - char *cipher, - size_t *cipher_len); + const char *plaintext, + size_t plaintext_len, + char *ciphertext, + size_t *ciphertext_len); /** * @brief Encrypts the final piece of the data. * * @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_context_get_output_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] ciphertext Final piece of the encrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] ciphertext_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 Successful @@ -132,27 +132,27 @@ int yaca_seal_update(yaca_context_h ctx, * @see yaca_context_get_output_length() */ int yaca_seal_finalize(yaca_context_h ctx, - char *cipher, - size_t *cipher_len); + char *ciphertext, + size_t *ciphertext_len); /** * @brief Initializes an asymmetric decryption context. * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed by yaca_context_destroy()) - * @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 + * @param[out] ctx Newly created context (must be freed by yaca_context_destroy()) + * @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_bit_len 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 Successful - * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, - * invalid algo, bcm, sym_key_bits, prv_key, sym_key or iv) + * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, invalid + * algo, bcm, sym_key_bit_len, prv_key, sym_key or iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @@ -166,7 +166,7 @@ int yaca_open_initialize(yaca_context_h *ctx, const yaca_key_h prv_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, - yaca_key_bit_length_e sym_key_bits, + yaca_key_bit_length_e sym_key_bit_len, const yaca_key_h sym_key, const yaca_key_h iv); @@ -175,13 +175,13 @@ int yaca_open_initialize(yaca_context_h *ctx, * * @since_tizen 3.0 * - * @param[in,out] ctx Context created by yaca_open_initialize() - * @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_context_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_initialize() + * @param[in] ciphertext Ciphertext to be decrypted + * @param[in] ciphertext_len Length of the ciphertext + * @param[out] plaintext Buffer for the decrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] plaintext_len Length of the decrypted data, + * actual number of bytes written will be returned here * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -194,21 +194,21 @@ int yaca_open_initialize(yaca_context_h *ctx, * @see yaca_context_get_output_length() */ int yaca_open_update(yaca_context_h ctx, - const char *cipher, - size_t cipher_len, - char *plain, - size_t *plain_len); + const char *ciphertext, + size_t ciphertext_len, + char *plaintext, + size_t *plaintext_len); /** * @brief Decrypts last chunk of sealed message. * * @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_context_get_output_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 open context + * @param[out] plaintext Final piece of the decrypted data + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] plaintext_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 Successful @@ -221,8 +221,8 @@ int yaca_open_update(yaca_context_h ctx, * @see yaca_context_get_output_length() */ int yaca_open_finalize(yaca_context_h ctx, - char *plain, - size_t *plain_len); + char *plaintext, + size_t *plaintext_len); /**@}*/ diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index ae6ae5d..b1854c6 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -80,15 +80,15 @@ int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, * * @since_tizen 3.0 * - * @param[in] algo Encryption algorithm (select #YACA_ENCRYPT_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) + * @param[in] algo Encryption algorithm (select #YACA_ENCRYPT_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] plaintext Plaintext to be encrypted + * @param[in] plaintext_len Length of the plaintext + * @param[out] ciphertext Encrypted data, will be allocated by the library + * (should be freed with yaca_free()) + * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -106,25 +106,25 @@ int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, - const char *plain, - size_t plain_len, - char **cipher, - size_t *cipher_len); + const char *plaintext, + size_t plaintext_len, + char **ciphertext, + size_t *ciphertext_len); /** * @brief Decrypt data using a symmetric cipher. * * @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[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 + * @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] ciphertext Ciphertext to be decrypted + * @param[in] ciphertext_len Length of ciphertext + * @param[out] plaintext Decrypted data, will be allocated by the library + * (should be freed with yaca_free()) + * @param[out] plaintext_len Length of the decrypted data * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -142,10 +142,10 @@ int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, - const char *cipher, - size_t cipher_len, - char **plain, - size_t *plain_len); + const char *ciphertext, + size_t ciphertext_len, + char **plaintext, + size_t *plaintext_len); /** * @brief Create a signature using asymmetric private key. diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h index f24bb01..96d23c8 100644 --- a/api/yaca/yaca_types.h +++ b/api/yaca/yaca_types.h @@ -344,11 +344,11 @@ typedef enum { * in decryption operation.\n\n * * - #YACA_PROPERTY_CCM_AAD = additional authentication data (optional)\n - * The total plain text length must be passed to yaca_encrypt_update() + * The total plaintext length must be passed to yaca_encrypt_update() * if AAD is used.\n * Set after yaca_encrypt_initialize() and before yaca_encrypt_update() * in encryption operation.\n - * You can only call yaca_encrypt_update() once for AAD and once for the plain text.\n\n + * You can only call yaca_encrypt_update() once for AAD and once for the plaintext.\n\n * * The total encrypted text length must be passed to yaca_decrypt_update() * if AAD is used.\n diff --git a/src/crypto.c b/src/crypto.c index 0d4055a..99fa1db 100644 --- a/src/crypto.c +++ b/src/crypto.c @@ -126,8 +126,10 @@ API int yaca_initialize(void) /* * TODO: * - We should also decide on Openssl config. - * - Here's a good tutorial for initalization and cleanup: https://wiki.openssl.org/index.php/Library_Initialization - * - We should also initialize the entropy for random number generator: https://wiki.openssl.org/index.php/Random_Numbers#Initialization + * - Here's a good tutorial for initalization and cleanup: + * https://wiki.openssl.org/index.php/Library_Initialization + * - We should also initialize the entropy for random number generator: + * https://wiki.openssl.org/index.php/Random_Numbers#Initialization */ return YACA_ERROR_NONE; @@ -191,9 +193,9 @@ API int yaca_realloc(size_t size, void **memory) return YACA_ERROR_NONE; } -API int yaca_free(void *ptr) +API int yaca_free(void *memory) { - OPENSSL_free(ptr); + OPENSSL_free(memory); return YACA_ERROR_NONE; } @@ -215,22 +217,22 @@ API int yaca_randomize_bytes(char *data, size_t data_len) return YACA_ERROR_NONE; } -API int yaca_context_set_property(yaca_context_h ctx, yaca_property_e param, +API int yaca_context_set_property(yaca_context_h ctx, yaca_property_e property, const void *value, size_t value_len) { if (ctx == YACA_CONTEXT_NULL || ctx->set_param == NULL) return YACA_ERROR_INVALID_PARAMETER; - return ctx->set_param(ctx, param, value, value_len); + return ctx->set_param(ctx, property, value, value_len); } -API int yaca_context_get_property(const yaca_context_h ctx, yaca_property_e param, +API int yaca_context_get_property(const yaca_context_h ctx, yaca_property_e property, void **value, size_t *value_len) { if (ctx == YACA_CONTEXT_NULL || ctx->get_param == NULL) return YACA_ERROR_INVALID_PARAMETER; - return ctx->get_param(ctx, param, value, value_len); + return ctx->get_param(ctx, property, value, value_len); } API int yaca_context_destroy(yaca_context_h ctx) @@ -244,7 +246,8 @@ API int yaca_context_destroy(yaca_context_h ctx) return YACA_ERROR_NONE; } -API int yaca_context_get_output_length(const yaca_context_h ctx, size_t input_len, size_t *output_len) +API int yaca_context_get_output_length(const yaca_context_h ctx, + size_t input_len, size_t *output_len) { if (ctx == YACA_CONTEXT_NULL) return YACA_ERROR_INVALID_PARAMETER; diff --git a/src/encrypt.c b/src/encrypt.c index 2ea785e..324e829 100644 --- a/src/encrypt.c +++ b/src/encrypt.c @@ -542,13 +542,13 @@ static int encrypt_final(yaca_context_h ctx, API int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, - size_t key_bits, - size_t *iv_bits) + size_t key_bit_len, + size_t *iv_bit_len) { const EVP_CIPHER *cipher; int ret; - ret = encrypt_get_algorithm(algo, bcm, key_bits, &cipher); + ret = encrypt_get_algorithm(algo, bcm, key_bit_len, &cipher); if (ret != YACA_ERROR_NONE) return ret; @@ -558,7 +558,7 @@ API int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, return YACA_ERROR_INTERNAL; } - *iv_bits = ret * 8; + *iv_bit_len = ret * 8; return YACA_ERROR_NONE; } @@ -572,21 +572,21 @@ API int yaca_encrypt_initialize(yaca_context_h *ctx, } API int yaca_encrypt_update(yaca_context_h ctx, - const char *plain, - size_t plain_len, - char *cipher, - size_t *cipher_len) + const char *plaintext, + size_t plaintext_len, + char *ciphertext, + size_t *ciphertext_len) { - return encrypt_update(ctx, (const unsigned char*)plain, plain_len, - (unsigned char*)cipher, cipher_len, OP_ENCRYPT); + return encrypt_update(ctx, (const unsigned char*)plaintext, plaintext_len, + (unsigned char*)ciphertext, ciphertext_len, OP_ENCRYPT); } API int yaca_encrypt_finalize(yaca_context_h ctx, - char *cipher, - size_t *cipher_len) + char *ciphertext, + size_t *ciphertext_len) { - return encrypt_final(ctx, (unsigned char*)cipher, - cipher_len, OP_ENCRYPT); + return encrypt_final(ctx, (unsigned char*)ciphertext, + ciphertext_len, OP_ENCRYPT); } API int yaca_decrypt_initialize(yaca_context_h *ctx, @@ -599,19 +599,19 @@ API int yaca_decrypt_initialize(yaca_context_h *ctx, } API int yaca_decrypt_update(yaca_context_h ctx, - const char *cipher, - size_t cipher_len, - char *plain, - size_t *plain_len) + const char *ciphertext, + size_t ciphertext_len, + char *plaintext, + size_t *plaintext_len) { - return encrypt_update(ctx, (const unsigned char*)cipher, cipher_len, - (unsigned char*)plain, plain_len, OP_DECRYPT); + return encrypt_update(ctx, (const unsigned char*)ciphertext, ciphertext_len, + (unsigned char*)plaintext, plaintext_len, OP_DECRYPT); } API int yaca_decrypt_finalize(yaca_context_h ctx, - char *plain, - size_t *plain_len) + char *plaintext, + size_t *plaintext_len) { - return encrypt_final(ctx, (unsigned char*)plain, plain_len, + return encrypt_final(ctx, (unsigned char*)plaintext, plaintext_len, OP_DECRYPT); } diff --git a/src/key.c b/src/key.c index 6e45c93..2ba9b9e 100644 --- a/src/key.c +++ b/src/key.c @@ -982,16 +982,16 @@ API int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type) return YACA_ERROR_NONE; } -API int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bits) +API int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len) { const struct yaca_key_simple_s *simple_key = key_get_simple(key); const struct yaca_key_evp_s *evp_key = key_get_evp(key); - if (key_bits == NULL) + if (key_bit_len == NULL) return YACA_ERROR_INVALID_PARAMETER; if (simple_key != NULL) { - *key_bits = simple_key->bits; + *key_bit_len = simple_key->bits; return YACA_ERROR_NONE; } @@ -1006,7 +1006,7 @@ API int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bits) return ret; } - *key_bits = ret; + *key_bit_len = ret; return YACA_ERROR_NONE; } @@ -1086,29 +1086,29 @@ API int yaca_key_export(const yaca_key_h key, } API int yaca_key_generate(yaca_key_type_e key_type, - size_t key_bits, + size_t key_bit_len, yaca_key_h *key) { int ret; struct yaca_key_simple_s *nk_simple = NULL; struct yaca_key_evp_s *nk_evp = NULL; - if (key == NULL || key_bits == 0 || key_bits % 8 != 0) + if (key == NULL || key_bit_len == 0 || key_bit_len % 8 != 0) return YACA_ERROR_INVALID_PARAMETER; switch (key_type) { case YACA_KEY_TYPE_SYMMETRIC: case YACA_KEY_TYPE_IV: - ret = gen_simple(&nk_simple, key_bits); + ret = gen_simple(&nk_simple, key_bit_len); break; case YACA_KEY_TYPE_DES: - ret = gen_simple_des(&nk_simple, key_bits); + ret = gen_simple_des(&nk_simple, key_bit_len); break; case YACA_KEY_TYPE_RSA_PRIV: - ret = gen_evp_rsa(&nk_evp, key_bits); + ret = gen_evp_rsa(&nk_evp, key_bit_len); break; case YACA_KEY_TYPE_DSA_PRIV: - ret = gen_evp_dsa(&nk_evp, key_bits); + ret = gen_evp_dsa(&nk_evp, key_bit_len); break; // case YACA_KEY_TYPE_DH_PRIV: // case YACA_KEY_TYPE_EC_PRIV: @@ -1219,21 +1219,21 @@ API int yaca_key_destroy(yaca_key_h key) API int yaca_key_derive_pbkdf2(const char *password, const char *salt, size_t salt_len, - int iter, + int iterations, yaca_digest_algorithm_e algo, - size_t key_bits, + size_t key_bit_len, yaca_key_h *key) { const EVP_MD *md; struct yaca_key_simple_s *nk; - size_t key_byte_len = key_bits / 8; + size_t key_byte_len = key_bit_len / 8; int ret; if (password == NULL || salt == NULL || salt_len == 0 || - iter == 0 || key_bits == 0 || key == NULL) + iterations == 0 || key_bit_len == 0 || key == NULL) return YACA_ERROR_INVALID_PARAMETER; - if (key_bits % 8) /* Key length must be multiple of 8-bits */ + if (key_bit_len % 8) /* Key length must be multiple of 8-bits */ return YACA_ERROR_INVALID_PARAMETER; ret = digest_get_algorithm(algo, &md); @@ -1244,11 +1244,11 @@ API int yaca_key_derive_pbkdf2(const char *password, if (ret != YACA_ERROR_NONE) return ret; - nk->bits = key_bits; + nk->bits = key_bit_len; nk->key.type = YACA_KEY_TYPE_SYMMETRIC; // TODO: how to handle other keys? ret = PKCS5_PBKDF2_HMAC(password, -1, (const unsigned char*)salt, - salt_len, iter, md, key_byte_len, + salt_len, iterations, md, key_byte_len, (unsigned char*)nk->d); if (ret != 1) { ret = YACA_ERROR_INTERNAL; diff --git a/src/seal.c b/src/seal.c index 89387b7..0859e14 100644 --- a/src/seal.c +++ b/src/seal.c @@ -383,34 +383,34 @@ API int yaca_seal_initialize(yaca_context_h *ctx, const yaca_key_h pub_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, - yaca_key_bit_length_e sym_key_bits, + yaca_key_bit_length_e sym_key_bit_len, yaca_key_h *sym_key, yaca_key_h *iv) { - return seal_init(ctx, pub_key, algo, bcm, sym_key_bits, sym_key, iv); + return seal_init(ctx, pub_key, algo, bcm, sym_key_bit_len, sym_key, iv); } API int yaca_seal_update(yaca_context_h ctx, - const char *plain, - size_t plain_len, - char *cipher, - size_t *cipher_len) + const char *plaintext, + size_t plaintext_len, + char *ciphertext, + size_t *ciphertext_len) { return seal_update(ctx, - (const unsigned char*)plain, - plain_len, - (unsigned char*)cipher, - cipher_len, + (const unsigned char*)plaintext, + plaintext_len, + (unsigned char*)ciphertext, + ciphertext_len, OP_SEAL); } API int yaca_seal_finalize(yaca_context_h ctx, - char *cipher, - size_t *cipher_len) + char *ciphertext, + size_t *ciphertext_len) { return seal_final(ctx, - (unsigned char*)cipher, - cipher_len, + (unsigned char*)ciphertext, + ciphertext_len, OP_SEAL); } @@ -418,30 +418,30 @@ API int yaca_open_initialize(yaca_context_h *ctx, const yaca_key_h prv_key, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, - yaca_key_bit_length_e sym_key_bits, + yaca_key_bit_length_e sym_key_bit_len, const yaca_key_h sym_key, const yaca_key_h iv) { - return open_init(ctx, prv_key, algo, bcm, sym_key_bits, sym_key, iv); + return open_init(ctx, prv_key, algo, bcm, sym_key_bit_len, sym_key, iv); } API int yaca_open_update(yaca_context_h ctx, - const char *cipher, - size_t cipher_len, - char *plain, - size_t *plain_len) + const char *ciphertext, + size_t ciphertext_len, + char *plaintext, + size_t *plaintext_len) { return seal_update(ctx, - (const unsigned char*)cipher, - cipher_len, - (unsigned char*)plain, - plain_len, + (const unsigned char*)ciphertext, + ciphertext_len, + (unsigned char*)plaintext, + plaintext_len, OP_OPEN); } API int yaca_open_finalize(yaca_context_h ctx, - char *plain, - size_t *plain_len) + char *plaintext, + size_t *plaintext_len) { - return seal_final(ctx, (unsigned char*)plain, plain_len, OP_OPEN); + return seal_final(ctx, (unsigned char*)plaintext, plaintext_len, OP_OPEN); } diff --git a/src/simple.c b/src/simple.c index d5e3cae..a17f78e 100644 --- a/src/simple.c +++ b/src/simple.c @@ -84,17 +84,18 @@ API int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, - const char *plain, - size_t plain_len, - char **cipher, - size_t *cipher_len) + const char *plaintext, + size_t plaintext_len, + char **ciphertext, + size_t *ciphertext_len) { yaca_context_h ctx; int ret; char *lcipher = NULL; size_t out_len, lcipher_len, written; - if (plain == NULL || plain_len == 0 || cipher == NULL || cipher_len == NULL || + if (plaintext == NULL || plaintext_len == 0 || + ciphertext == NULL || ciphertext_len == NULL || sym_key == YACA_KEY_NULL) return YACA_ERROR_INVALID_PARAMETER; @@ -102,7 +103,7 @@ API int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, if (ret != YACA_ERROR_NONE) return ret; - ret = yaca_context_get_output_length(ctx, plain_len, &out_len); + ret = yaca_context_get_output_length(ctx, plaintext_len, &out_len); if (ret != YACA_ERROR_NONE) goto exit; @@ -124,7 +125,7 @@ API int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, goto exit; out_len = lcipher_len; - ret = yaca_encrypt_update(ctx, plain, plain_len, lcipher, &out_len); + ret = yaca_encrypt_update(ctx, plaintext, plaintext_len, lcipher, &out_len); if (ret != YACA_ERROR_NONE) goto exit; @@ -143,8 +144,8 @@ API int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, if (ret != YACA_ERROR_NONE) goto exit; - *cipher = lcipher; - *cipher_len = written; + *ciphertext = lcipher; + *ciphertext_len = written; lcipher = NULL; ret = YACA_ERROR_NONE; @@ -159,17 +160,18 @@ API int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, - const char *cipher, - size_t cipher_len, - char **plain, - size_t *plain_len) + const char *ciphertext, + size_t ciphertext_len, + char **plaintext, + size_t *plaintext_len) { yaca_context_h ctx; int ret; char *lplain = NULL; size_t out_len, lplain_len, written; - if (cipher == NULL || cipher_len == 0 || plain == NULL || plain_len == NULL || + if (ciphertext == NULL || ciphertext_len == 0 || + plaintext == NULL || plaintext_len == NULL || sym_key == YACA_KEY_NULL) return YACA_ERROR_INVALID_PARAMETER; @@ -177,7 +179,7 @@ API int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, if (ret != YACA_ERROR_NONE) return ret; - ret = yaca_context_get_output_length(ctx, cipher_len, &out_len); + ret = yaca_context_get_output_length(ctx, ciphertext_len, &out_len); if (ret != YACA_ERROR_NONE) goto exit; @@ -198,7 +200,7 @@ API int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, goto exit; out_len = lplain_len; - ret = yaca_decrypt_update(ctx, cipher, cipher_len, lplain, &out_len); + ret = yaca_decrypt_update(ctx, ciphertext, ciphertext_len, lplain, &out_len); if (ret != YACA_ERROR_NONE) goto exit; @@ -217,8 +219,8 @@ API int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, if (ret != YACA_ERROR_NONE) goto exit; - *plain = lplain; - *plain_len = written; + *plaintext = lplain; + *plaintext_len = written; lplain = NULL; ret = YACA_ERROR_NONE;