diff options
author | sangwan.kwon <sangwan.kwon@samsung.com> | 2017-02-06 09:46:40 +0900 |
---|---|---|
committer | sangwan.kwon <sangwan.kwon@samsung.com> | 2017-02-06 09:48:55 +0900 |
commit | 895749ef686eba394f373e9f715537b8be70a47f (patch) | |
tree | b17e327fbb82fac4e132c19c56793cd54b1604d5 | |
parent | 80eb9a273e45395cadfba33b5de78f71e8a795ef (diff) | |
parent | 6a9daa80f2d8aa268f7f6613e6bcbf42d48379d9 (diff) | |
download | yaca-tizen_3.0_tv.tar.gz yaca-tizen_3.0_tv.tar.bz2 yaca-tizen_3.0_tv.zip |
Merge branch 'tizen' into tizen_3.0submit/tizen_3.0/20170206.014242accepted/tizen/3.0/wearable/20170207.084542accepted/tizen/3.0/tv/20170207.084526accepted/tizen/3.0/mobile/20170207.084442accepted/tizen/3.0/ivi/20170207.084600accepted/tizen/3.0/common/20170207.092131tizen_3.0_tvtizen_3.0accepted/tizen_3.0_wearableaccepted/tizen_3.0_tvaccepted/tizen_3.0_mobileaccepted/tizen_3.0_iviaccepted/tizen_3.0_common
Change-Id: Ib5824e85d13046dae4b06363745dc6f3df0ce014
Signed-off-by: sangwan.kwon <sangwan.kwon@samsung.com>
-rw-r--r-- | api/yaca/yaca_crypto.h | 237 | ||||
-rw-r--r-- | api/yaca/yaca_digest.h | 69 | ||||
-rw-r--r-- | api/yaca/yaca_encrypt.h | 215 | ||||
-rw-r--r-- | api/yaca/yaca_error.h | 29 | ||||
-rw-r--r-- | api/yaca/yaca_key.h | 441 | ||||
-rw-r--r-- | api/yaca/yaca_rsa.h | 168 | ||||
-rw-r--r-- | api/yaca/yaca_seal.h | 238 | ||||
-rw-r--r-- | api/yaca/yaca_sign.h | 260 | ||||
-rw-r--r-- | api/yaca/yaca_simple.h | 332 | ||||
-rw-r--r-- | api/yaca/yaca_types.h | 171 | ||||
-rw-r--r-- | src/CMakeLists.txt | 8 |
11 files changed, 922 insertions, 1246 deletions
diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index 56425eb..6108336 100644 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -16,283 +16,246 @@ * limitations under the License */ + /** - * @file yaca_crypto.h - * @brief Non crypto related functions. + * @file yaca_crypto.h + * @brief Non crypto related functions. */ + #ifndef YACA_CRYPTO_H #define YACA_CRYPTO_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_ENCRYPTION_MODULE * @{ */ + /** - * @brief NULL value for the crypto context. - * + * @brief Definition for NULL value for the crypto context. * @since_tizen 3.0 */ #define YACA_CONTEXT_NULL ((yaca_context_h) NULL) + /** - * @brief Initializes the library. Must be called before any other crypto - * function. Should be called once in each thread that uses yaca. - * + * @brief Initializes the library. Must be called before any other crypto + * function. Should be called once in each thread that uses yaca. * @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 Successful * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_cleanup() */ int yaca_initialize(void); + /** - * @brief Cleans up the library. Must be called before exiting the thread that - * called yaca_initialize(). - * + * @brief Cleans up the library. Must be called before exiting the thread that called yaca_initialize(). * @since_tizen 3.0 - * * @see yaca_initialize() */ void yaca_cleanup(void); + /** - * @brief Allocates the memory. - * + * @brief Allocates the memory. * @since_tizen 3.0 - * - * @remarks The @a memory should be freed using yaca_free(). - * - * @param[in] size Size of the allocation (bytes) + * @remarks The @a memory should be freed using yaca_free(). + * @param[in] size Size of the allocation (bytes) * @param[out] memory Allocated memory - * - * @return #YACA_ERROR_NONE on success, negative on error + * @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) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error - * * @see yaca_zalloc() * @see yaca_realloc() * @see yaca_free() */ int yaca_malloc(size_t size, void **memory); + /** - * @brief Allocates the zeroed memory. - * + * @brief Allocates the zeroed memory. * @since_tizen 3.0 - * - * @remarks The @a memory should be freed using yaca_free(). - * - * @param[in] size Size of the allocation (bytes) - * @param[out] memory Allocated memory - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a memory should be freed using yaca_free(). + * @param[in] size Size of the allocation (bytes) + * @param[out] memory Allocated memory + * @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) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error - * * @see yaca_malloc() * @see yaca_realloc() * @see yaca_free() */ int yaca_zalloc(size_t size, void **memory); + /** - * @brief Re-allocates the memory. - * + * @brief Re-allocates the memory. * @since_tizen 3.0 - * - * @remarks In case of failure the function doesn't free the memory pointed by @a memory. - * - * @remarks If @a memory is NULL then the call is equivalent to yaca_malloc(). - * - * @remarks If the function fails the contents of @a memory will be left unchanged. - * - * @remarks The @a memory should be freed using yaca_free(). - * - * @param[in] size Size of the new allocation (bytes) + * @remarks In case of failure the function doesn't free the memory pointed by @a memory. + * @remarks If @a memory is NULL then the call is equivalent to yaca_malloc(). + * @remarks If the function fails the contents of @a memory will be left unchanged. + * @remarks The @a memory should be freed using yaca_free(). + * @param[in] size Size of the new allocation (bytes) * @param[in,out] memory Memory to be reallocated - * - * @return #YACA_ERROR_NONE on success, negative on error + * @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) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error - * * @see yaca_malloc() * @see yaca_zalloc() * @see yaca_free() */ int yaca_realloc(size_t size, void **memory); + /** - * @brief Frees the memory allocated by yaca_malloc(), yaca_zalloc(), - * yaca_realloc() or one of the cryptographic operations. - * + * @brief Frees the memory allocated by yaca_malloc(), yaca_zalloc(), + * yaca_realloc() or one of the cryptographic operations. * @since_tizen 3.0 - * - * @param[in] memory Pointer to the memory to be freed - * + * @param[in] memory Pointer to the memory to be freed * @see yaca_malloc() * @see yaca_zalloc() * @see yaca_realloc() */ void yaca_free(void *memory); + /** - * @brief Safely compares first @a len bytes of two buffers. - * + * @brief Safely compares first @a len bytes of two buffers. * @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 - * - * @return #YACA_ERROR_NONE when buffers are equal otherwise #YACA_ERROR_DATA_MISMATCH + * @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 * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0) * @retval #YACA_ERROR_DATA_MISMATCH Buffers are different */ int yaca_memcmp(const void *first, const void *second, size_t len); + /** - * @brief Generates random data. - * + * @brief Generates random data. * @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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @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 * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0) * @retval #YACA_ERROR_INTERNAL Internal error */ int yaca_randomize_bytes(char *data, size_t data_len); + /** - * @brief Sets the non-standard context properties. Can only be called on an - * initialized context. - * - * @remarks The @a value has to be of type appropriate for given property. See #yaca_property_e - * for details on corresponding types. - * + * @brief Sets the non-standard context properties. Can only be called on an initialized context. * @since_tizen 3.0 - * - * @param[in,out] ctx Previously initialized crypto context - * @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 + * @remarks The @a value has to be of type appropriate for given property. See #yaca_property_e + * for details on corresponding types. + * @param[in,out] ctx Previously initialized crypto context + * @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 @a ctx or @a 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 property, - const void *value, - size_t value_len); +int yaca_context_set_property(yaca_context_h ctx, yaca_property_e property, const void *value, size_t value_len); + /** - * @brief Returns the non-standard context properties. Can only be called on an - * initialized context. - * + * @brief Returns the non-standard context properties. Can only be called on an initialized context. * @since_tizen 3.0 - * - * @remarks The @a value should be freed using yaca_free(). - * - * @remarks The @a value has to be of type appropriate for given property. See #yaca_property_e - * for details on corresponding types. - * - * @remarks The @a value_len can be NULL if returned @a value is a single object - * (i.e. not an array/buffer). - * - * @param[in] ctx Previously initialized crypto context - * @param[in] property Property to be read - * @param[out] value Copy of the property value - * @param[out] value_len Length of the property value will be returned here - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a value should be freed using yaca_free(). + * @remarks The @a value has to be of type appropriate for given property. See #yaca_property_e + * for details on corresponding types. + * @remarks The @a value_len can be NULL if returned @a value is a single object (i.e. not an array/buffer). + * @param[in] ctx Previously initialized crypto context + * @param[in] property Property to be read + * @param[out] value Copy of the property value + * @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 @a ctx or @a property) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_property_e * @see yaca_context_set_property() * @see yaca_free() */ -int yaca_context_get_property(const yaca_context_h ctx, - yaca_property_e property, - void **value, - size_t *value_len); +int yaca_context_get_property(const yaca_context_h ctx, yaca_property_e property, void **value, size_t *value_len); + /** - * @brief Returns the minimum required size of the output buffer for a single crypto function call. - * + * @brief Returns the minimum required size of the output buffer for a single crypto function call. * @since_tizen 3.0 - * - * @remarks This function should be used to learn the required size of the output buffer - * for a single function call (eg. *_update or *_finalize). The actual output length - * (number of bytes that has been used) will be returned by the function call itself. - * - * @remarks In case the function call has no output (e.g. yaca_sign_update(), - * yaca_digest_update()), there is no need to use this function. - * - * @remarks In case the function call has no input (eg. *_finalize), the value of - * @a input_len has to be set to 0. - * - * @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 #YACA_ERROR_NONE on success, negative on error + * @remarks This function should be used to learn the required size of the output buffer + * for a single function call (eg. *_update or *_finalize). The actual output length + * (number of bytes that has been used) will be returned by the function call itself. + * @remarks In case the function call has no output (e.g. yaca_sign_update(), + * yaca_digest_update()), there is no need to use this function. + * @remarks In case the function call has no input (eg. *_finalize), the value of + * @a input_len has to be set to 0. + * @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 #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 @a ctx or too big @a 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); + /** - * @brief Destroys the crypto context. Must be called on all contexts that are - * no longer used. Passing #YACA_CONTEXT_NULL is allowed. - * + * @brief Destroys the crypto context. Must be called on all contexts that are no longer used. + * Passing #YACA_CONTEXT_NULL is allowed. * @since_tizen 3.0 - * * @param[in,out] ctx Crypto context - * * @see #yaca_context_h - * */ void yaca_context_destroy(yaca_context_h ctx); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_CRYPTO_H */ diff --git a/api/yaca/yaca_digest.h b/api/yaca/yaca_digest.h index 8d3bd02..377f85b 100644 --- a/api/yaca/yaca_digest.h +++ b/api/yaca/yaca_digest.h @@ -16,43 +16,45 @@ * limitations under the License */ + /** - * @file yaca_digest.h - * @brief Advanced API for the message digests. + * @file yaca_digest.h + * @brief Advanced API for the message digests. */ + #ifndef YACA_DIGEST_H #define YACA_DIGEST_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_INTEGRITY_MODULE * @{ */ + /** - * @brief Initializes a digest context. - * + * @brief Initializes a digest context. * @since_tizen 3.0 - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @param[in] algo Digest algorithm that will be used - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @param[in] algo Digest algorithm that will be used + * @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 @a algo) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_digest_algorithm_e * @see yaca_digest_update() * @see yaca_digest_finalize() @@ -60,58 +62,55 @@ extern "C" { */ int yaca_digest_initialize(yaca_context_h *ctx, yaca_digest_algorithm_e algo); + /** - * @brief Feeds the message into the message digest algorithm. - * + * @brief Feeds the message into the message digest algorithm. * @since_tizen 3.0 - * - * @param[in,out] ctx Context created by yaca_digest_initialize() - * @param[in] message Message from which the digest is to be calculated - * @param[in] message_len Length of the message - * - * @return #YACA_ERROR_NONE on success, negative on error + * @param[in,out] ctx Context created by yaca_digest_initialize() + * @param[in] message Message from which the digest is to be calculated + * @param[in] message_len Length of the message + * @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 @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_digest_initialize() * @see yaca_digest_finalize() */ int yaca_digest_update(yaca_context_h ctx, const char *message, size_t message_len); + /** - * @brief Calculates the final digest. - * + * @brief Calculates the final digest. * @since_tizen 3.0 - * - * @remarks Skipping yaca_digest_update() and calling only yaca_digest_finalize() will produce an - * empty message digest. - * - * @param[in,out] ctx A valid digest context - * @param[out] digest Buffer for the message digest - * (must be allocated by client, see yaca_context_get_output_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 + * @remarks Skipping yaca_digest_update() and calling only yaca_digest_finalize() will produce an empty message digest. + * @param[in,out] ctx A valid digest context + * @param[out] digest Buffer for the message digest + * (must be allocated by client, see yaca_context_get_output_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 Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_digest_initialize() * @see yaca_digest_update() * @see yaca_context_get_output_length() */ int yaca_digest_finalize(yaca_context_h ctx, char *digest, size_t *digest_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_DIGEST_H */ diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index 4031f2c..ba2de37 100644 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -16,238 +16,201 @@ * limitations under the License */ + /** - * @file yaca_encrypt.h - * @brief Advanced API for the symmetric encryption. + * @file yaca_encrypt.h + * @brief Advanced API for the symmetric encryption. */ + #ifndef YACA_ENCRYPT_H #define YACA_ENCRYPT_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_ENCRYPTION_MODULE * @{ */ + /** - * @brief Returns the recommended/default length of the Initialization Vector - * for a given encryption configuration. - * + * @brief Returns the recommended/default length of the Initialization Vector for a given encryption configuration. * @since_tizen 3.0 - * - * @remarks If returned @a iv_bit_len equals 0 that means that for this - * specific algorithm and its parameters Initialization Vector 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 Initialization Vector length in bits - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks If returned @a iv_bit_len equals 0 that means that for this + * specific algorithm and its parameters Initialization Vector 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 Initialization Vector 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 @a algo, @a bcm or @a 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); +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. - * + * @brief Initializes an encryption context. * @since_tizen 3.0 - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @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 + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @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 * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_encrypt_update() * @see yaca_encrypt_finalize() * @see yaca_context_destroy() */ -int yaca_encrypt_initialize(yaca_context_h *ctx, - yaca_encrypt_algorithm_e algo, - yaca_block_cipher_mode_e bcm, - const yaca_key_h sym_key, - const yaca_key_h iv); +int yaca_encrypt_initialize(yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv); + /** - * @brief Encrypts chunk of the data. - * + * @brief Encrypts chunk of the data. * @since_tizen 3.0 - * - * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, * invalid @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_encrypt_initialize() * @see yaca_encrypt_finalize() * @see yaca_context_get_output_length() */ -int yaca_encrypt_update(yaca_context_h ctx, - const char *plaintext, - size_t plaintext_len, - char *ciphertext, - size_t *ciphertext_len); +int yaca_encrypt_update(yaca_context_h ctx, const char *plaintext, size_t plaintext_len, char *ciphertext, size_t *ciphertext_len); + /** - * @brief Encrypts the final chunk of the data. - * - * @remarks Skipping yaca_encrypt_update() and calling only yaca_encrypt_finalize() will produce an - * encryption of an empty message. - * + * @brief Encrypts the final chunk of the data. * @since_tizen 3.0 - * - * @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 + * @remarks Skipping yaca_encrypt_update() and calling only yaca_encrypt_finalize() will produce an encryption of an empty message. + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_encrypt_initialize() * @see yaca_encrypt_update() * @see yaca_context_get_output_length() */ -int yaca_encrypt_finalize(yaca_context_h ctx, - char *ciphertext, - size_t *ciphertext_len); +int yaca_encrypt_finalize(yaca_context_h ctx, char *ciphertext, size_t *ciphertext_len); + /** - * @brief Initializes an decryption context. - * + * @brief Initializes an decryption context. * @since_tizen 3.0 - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @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 + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @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 * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_decrypt_update() * @see yaca_decrypt_finalize() * @see yaca_context_destroy() */ -int yaca_decrypt_initialize(yaca_context_h *ctx, - yaca_encrypt_algorithm_e algo, - yaca_block_cipher_mode_e bcm, - const yaca_key_h sym_key, - const yaca_key_h iv); +int yaca_decrypt_initialize(yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv); + /** - * @brief Decrypts chunk of the data. - * + * @brief Decrypts chunk of the data. * @since_tizen 3.0 - * - * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, * invalid @a ctx), wrong #YACA_PROPERTY_CCM_AAD or * wrong #YACA_PROPERTY_CCM_TAG was used * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_decrypt_initialize() * @see yaca_decrypt_finalize() * @see yaca_context_get_output_length() */ -int yaca_decrypt_update(yaca_context_h ctx, - const char *ciphertext, - size_t ciphertext_len, - char *plaintext, - size_t *plaintext_len); +int yaca_decrypt_update(yaca_context_h ctx, const char *ciphertext, size_t ciphertext_len, char *plaintext, size_t *plaintext_len); + /** - * @brief Decrypts the final chunk of the data. - * - * @remarks Skipping yaca_decrypt_update() and calling only yaca_decrypt_finalize() will produce a - * decryption of an empty ciphertext. - * + * @brief Decrypts the final chunk of the data. * @since_tizen 3.0 - * - * @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 + * @remarks Skipping yaca_decrypt_update() and calling only yaca_decrypt_finalize() will produce a decryption of an empty ciphertext. + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a ctx), wrong #YACA_PROPERTY_GCM_AAD or * wrong #YACA_PROPERTY_GCM_TAG was used * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_decrypt_initialize() * @see yaca_decrypt_update() * @see yaca_context_get_output_length() */ -int yaca_decrypt_finalize(yaca_context_h ctx, - char *plaintext, - size_t *plaintext_len); +int yaca_decrypt_finalize(yaca_context_h ctx, char *plaintext, size_t *plaintext_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_ENCRYPT_H */ diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h index f062812..d8909ec 100644 --- a/api/yaca/yaca_error.h +++ b/api/yaca/yaca_error.h @@ -16,58 +16,67 @@ * limitations under the License */ + /** - * @file yaca_error.h - * @brief Error enums and defines. + * @file yaca_error.h + * @brief Error enums and defines. */ + #ifndef YACA_ERROR_H #define YACA_ERROR_H + #include <tizen.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_ENCRYPTION_MODULE * @{ */ + /* @cond Define it temporarily until this code goes into capi-base-common package */ #ifndef TIZEN_ERROR_YACA #define TIZEN_ERROR_YACA -0x01E30000 #endif /* @endcond */ + /** - * @brief Enumeration of YACA error values. - * + * @brief Enumeration for YACA error values. * @since_tizen 3.0 */ typedef enum { /** Successful */ - YACA_ERROR_NONE = TIZEN_ERROR_NONE, + YACA_ERROR_NONE = TIZEN_ERROR_NONE, /** Invalid function parameter */ - YACA_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, + YACA_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /** Out of memory */ - YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, + YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /** Internal error */ - YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01, + YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01, /** Data mismatch */ - YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02, + YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02, /** Invalid password */ - YACA_ERROR_INVALID_PASSWORD = TIZEN_ERROR_YACA | 0x03 + YACA_ERROR_INVALID_PASSWORD = TIZEN_ERROR_YACA | 0x03 } yaca_error_e; + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_ERROR_H */ diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 5c87944..f946534 100644 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -16,115 +16,105 @@ * limitations under the License */ + /** - * @file yaca_key.h - * @brief Advanced API for the key and Initialization Vector handling. + * @file yaca_key.h + * @brief Advanced API for the key and Initialization Vector handling. */ + #ifndef YACA_KEY_H #define YACA_KEY_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_KEY_MODULE * @{ */ + /** - * @brief NULL value for yaca_key_h type. - * + * @brief Definition for NULL value for yaca_key_h type. * @since_tizen 3.0 */ #define YACA_KEY_NULL ((yaca_key_h) NULL) + /** - * @brief Gets key's type. - * + * @brief Gets key's type. * @since_tizen 3.0 - * - * @param[in] key Key which type we return - * @param[out] key_type Key type - * - * @return #YACA_ERROR_NONE on success, negative on error + * @param[in] key Key which type we return + * @param[out] key_type Key type + * @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 - * * @see #yaca_key_type_e */ int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type); + /** - * @brief Gets key's length (in bits). - * + * @brief Gets key's length (in bits). * @since_tizen 3.0 - * - * @remarks The @a key can be any symmetric (including an Initialization Vector) or - * asymmetric key (including key generation parameters). - * - * @remarks For Diffie-Helmann @a key_bit_len returns prime length in bits. Values - * used to generate the key/parameters in yaca_key_generate() are not - * restored. Neither generator number nor values from #yaca_key_bit_length_dh_rfc_e. - * - * @remarks For Elliptic Curves @a key_bit_len returns values from #yaca_key_bit_length_ec_e. - * - * @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 + * @remarks The @a key can be any symmetric (including an Initialization Vector) or + * asymmetric key (including key generation parameters). + * @remarks For Diffie-Helmann @a key_bit_len returns prime length in bits. Values + * used to generate the key/parameters in yaca_key_generate() are not + * restored. Neither generator number nor values from #yaca_key_bit_length_dh_rfc_e. + * @remarks For Elliptic Curves @a key_bit_len returns values from #yaca_key_bit_length_ec_e. + * @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 - * * @see #yaca_key_bit_length_e * @see #yaca_key_bit_length_dh_rfc_e * @see #yaca_key_bit_length_ec_e */ int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len); + /** - * @brief Imports a key or key generation parameters. - * + * @brief Imports a key or key generation parameters. * @since_tizen 3.0 - * - * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred - * in the documentation of this function key generator parameters are also included. - * - * @remarks This function imports a key trying to match it to the @a key_type specified. - * It should autodetect both the key format and the file format. - * - * @remarks For symmetric, Initialization Vector and DES keys RAW binary format and BASE64 encoded - * binary format are supported. - * For asymmetric keys PEM and DER file formats are supported. - * - * @remarks Asymmetric keys can be in their default ASN1 structure formats (like - * PKCS#1, SSleay or PKCS#3). Private asymmetric keys can also be in - * PKCS#8 format. Additionally it is possible to import public RSA/DSA/EC - * keys from X509 certificate. - * - * @remarks 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_INVALID_PASSWORD return code. - * - * @remarks If the imported key will be detected as a format that does not support - * encryption and password was passed #YACA_ERROR_INVALID_PARAMETER will - * be returned. For a list of keys and formats that do support encryption - * see yaca_key_export() documentation. - * - * @remarks The @a key should be released using yaca_key_destroy(). - * - * @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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred + * in the documentation of this function key generator parameters are also included. + * @remarks This function imports a key trying to match it to the @a key_type specified. + * It should autodetect both the key format and the file format. + * @remarks For symmetric, Initialization Vector and DES keys RAW binary format and BASE64 encoded + * binary format are supported. + * For asymmetric keys PEM and DER file formats are supported. + * @remarks Asymmetric keys can be in their default ASN1 structure formats (like + * PKCS#1, SSleay or PKCS#3). Private asymmetric keys can also be in + * PKCS#8 format. Additionally it is possible to import public RSA/DSA/EC + * keys from X509 certificate. + * @remarks 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_INVALID_PASSWORD return code. + * @remarks If the imported key will be detected as a format that does not support + * encryption and password was passed #YACA_ERROR_INVALID_PARAMETER will + * be returned. For a list of keys and formats that do support encryption + * see yaca_key_export() documentation. + * @remarks The @a key should be released using yaca_key_destroy(). + * @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 + * @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 @a key_type or @a data_len too big) @@ -132,110 +122,86 @@ int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len); * @retval #YACA_ERROR_INTERNAL Internal error * @retval #YACA_ERROR_INVALID_PASSWORD Invalid @a password given or @a password was required * and none was given - * * @see #yaca_key_type_e * @see yaca_key_export() * @see yaca_key_destroy() */ -int yaca_key_import(yaca_key_type_e key_type, - const char *password, - const char *data, - size_t data_len, - yaca_key_h *key); +int yaca_key_import(yaca_key_type_e key_type, const char *password, const char *data, size_t data_len, yaca_key_h *key); + /** - * @brief Exports a key or key generation parameters to arbitrary format. - * + * @brief Exports a key or key generation parameters to arbitrary format. * @since_tizen 3.0 - * - * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred - * in the documentation of this function key generator parameters are also included. - * - * @remarks This function exports the key to an arbitrary key format and key file format. - * - * @remarks For key formats two values are allowed: - * - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric keys - * (or Initialization Vector), for asymmetric keys it will - * export to their default ASN1 structure format - * (e.g. PKCS#1, SSLeay, PKCS#3). - * - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys. - * - * @remarks The following file formats are supported: - * - #YACA_KEY_FILE_FORMAT_RAW: used only for symmetric, raw binary format - * - #YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form - * - #YACA_KEY_FILE_FORMAT_PEM: used only for asymmetric, PEM file format - * - #YACA_KEY_FILE_FORMAT_DER: used only for asymmetric, DER file format - * - * @remarks Encryption is supported and optional for RSA/DSA private keys in the - * #YACA_KEY_FORMAT_DEFAULT with #YACA_KEY_FILE_FORMAT_PEM format. If no password is - * provided the exported key will be unencrypted. The encryption algorithm used - * in this case is AES-256-CBC. - * - * @remarks Encryption is obligatory for #YACA_KEY_FORMAT_PKCS8 format (for both, PEM and DER - * file formats). If no password is provided the #YACA_ERROR_INVALID_PARAMETER will - * be returned. The encryption algorithm used in this case is AES-256-CBC. The key is - * generated from password using PBKDF2 with HMAC-SHA1 function and 2048 iterations. - * - * @remarks Encryption is not supported for the symmetric, public keys and key generation - * parameters in all their supported formats. If a password is provided in such - * case the #YACA_ERROR_INVALID_PARAMETER will be returned. - * - * @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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred + * in the documentation of this function key generator parameters are also included. + * @remarks This function exports the key to an arbitrary key format and key file format. + * @remarks For key formats two values are allowed: + * - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric keys + * (or Initialization Vector), for asymmetric keys it will + * export to their default ASN1 structure format + * (e.g. PKCS#1, SSLeay, PKCS#3). + * - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys. + * @remarks The following file formats are supported: + * - #YACA_KEY_FILE_FORMAT_RAW: used only for symmetric, raw binary format + * - #YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form + * - #YACA_KEY_FILE_FORMAT_PEM: used only for asymmetric, PEM file format + * - #YACA_KEY_FILE_FORMAT_DER: used only for asymmetric, DER file format + * @remarks Encryption is supported and optional for RSA/DSA private keys in the + * #YACA_KEY_FORMAT_DEFAULT with #YACA_KEY_FILE_FORMAT_PEM format. If no password is + * provided the exported key will be unencrypted. The encryption algorithm used + * in this case is AES-256-CBC. + * @remarks Encryption is obligatory for #YACA_KEY_FORMAT_PKCS8 format (for both, PEM and DER + * file formats). If no password is provided the #YACA_ERROR_INVALID_PARAMETER will + * be returned. The encryption algorithm used in this case is AES-256-CBC. The key is + * generated from password using PBKDF2 with HMAC-SHA1 function and 2048 iterations. + * @remarks Encryption is not supported for the symmetric, public keys and key generation + * parameters in all their supported formats. If a password is provided in such + * case the #YACA_ERROR_INVALID_PARAMETER will be returned. + * @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 + * @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 @a key_fmt, @a key_file_fmt or @a data_len too big) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_format_e * @see #yaca_key_file_format_e * @see yaca_key_import() * @see yaca_key_destroy() */ -int yaca_key_export(const yaca_key_h key, - yaca_key_format_e key_fmt, - yaca_key_file_format_e key_file_fmt, - const char *password, - char **data, - size_t *data_len); +int yaca_key_export(const yaca_key_h key, yaca_key_format_e key_fmt, yaca_key_file_format_e key_file_fmt, const char *password, char **data, size_t *data_len); + /** - * @brief Generates a secure key or key generation parameters (or an Initialization Vector). - * + * @brief Generates a secure key or key generation parameters (or an Initialization Vector). * @since_tizen 3.0 - * - * @remarks This function is used to generate symmetric keys, private asymmetric keys - * or key generation parameters for key types that support them (DSA, DH and EC). - * - * @remarks Supported key lengths: - * - RSA: length >= 512bits - * - DSA: length >= 512bits, multiple of 64 - * - DH: a value taken from #yaca_key_bit_length_dh_rfc_e or - * (YACA_KEY_LENGTH_DH_GENERATOR_* | prime_length_in_bits), - * where prime_length_in_bits can be any positive number - * - EC: a value taken from #yaca_key_bit_length_ec_e - * - * @remarks The @a key should be released using 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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks This function is used to generate symmetric keys, private asymmetric keys + * or key generation parameters for key types that support them (DSA, DH and EC). + * @remarks Supported key lengths: + * - RSA: length >= 512bits + * - DSA: length >= 512bits, multiple of 64 + * - DH: a value taken from #yaca_key_bit_length_dh_rfc_e or + * (YACA_KEY_LENGTH_DH_GENERATOR_* | prime_length_in_bits), + * where prime_length_in_bits can be any positive number + * - EC: a value taken from #yaca_key_bit_length_ec_e + * @remarks The @a key should be released using 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 + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER @a key is NULL, incorrect @a key_type or * @a key_bit_len 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_bit_length_e * @see #yaca_key_bit_length_dh_rfc_e @@ -244,73 +210,61 @@ int yaca_key_export(const yaca_key_h key, * @see #yaca_key_bit_length_ec_e * @see yaca_key_destroy() */ -int yaca_key_generate(yaca_key_type_e key_type, - size_t key_bit_len, - yaca_key_h *key); +int yaca_key_generate(yaca_key_type_e key_type, size_t key_bit_len, yaca_key_h *key); + /** - * @brief Generates a secure private asymmetric key from parameters. - * + * @brief Generates a secure private asymmetric key from parameters. * @since_tizen 3.0 - * - * @remarks This function is used to generate private asymmetric keys - * based on pre-generated parameters. - * - * @remarks The @a key should be released using yaca_key_destroy(). - * - * @param[in] params Pre-generated parameters - * @param[out] prv_key Newly generated private key - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks This function is used to generate private asymmetric keys + * based on pre-generated parameters. + * @remarks The @a key should be released using yaca_key_destroy(). + * @param[in] params Pre-generated parameters + * @param[out] prv_key Newly generated private key + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER @a prv_key is NULL or incorrect @a params * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_key_destroy() * @see yaca_key_generate() * @see yaca_key_extract_parameters() */ int yaca_key_generate_from_parameters(const yaca_key_h params, yaca_key_h *prv_key); + /** - * @brief Extracts public key from a private one. - * + * @brief Extracts public key from a private one. * @since_tizen 3.0 - * - * @remarks The @a pub_key should be released using yaca_key_destroy(). - * - * @param[in] prv_key Private key to extract the public one from - * @param[out] pub_key Extracted public key - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a pub_key should be released using yaca_key_destroy(). + * @param[in] prv_key Private key to extract the public one from + * @param[out] pub_key Extracted public key + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER @a prv_key is of invalid type or @a pub_key is NULL * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_key_generate() * @see yaca_key_import() * @see yaca_key_destroy() */ int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key); + /** - * @brief Extracts parameters from a private or a public key. - * + * @brief Extracts parameters from a private or a public key. * @since_tizen 3.0 - * - * @remarks The @a params should be released using yaca_key_destroy(). - * - * @param[in] key A key to extract the parameters from - * @param[out] params Extracted parameters - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a params should be released using yaca_key_destroy(). + * @param[in] key A key to extract the parameters from + * @param[out] params Extracted parameters + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER @a key is of invalid type or @a params is NULL * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_key_generate() * @see yaca_key_generate_from_parameters() * @see yaca_key_import() @@ -318,134 +272,107 @@ int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key); */ int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params); + /** - * @brief Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol. - * + * @brief Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol. * @since_tizen 3.0 - * - * @remarks The @a secret should not be used as a symmetric key, - * to produce a symmetric key pass the secret to a key derivation function (KDF) - * or a message digest function. - * - * @remarks The @a secret should be freed with yaca_free(). - * - * @param[in] prv_key Our private key - * @param[in] pub_key Peer public key - * @param[out] secret Generated shared secret - * @param[out] secret_len Size of the shared secret - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a secret should not be used as a symmetric key, + * to produce a symmetric key pass the secret to a key derivation function (KDF) + * or a message digest function. + * @remarks The @a secret should be freed with yaca_free(). + * @param[in] prv_key Our private key + * @param[in] pub_key Peer public key + * @param[out] secret Generated shared secret + * @param[out] secret_len Size of the shared secret + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values * (invalid @a prv_key or @a pub_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_key_derive_kdf() * @see yaca_simple_calculate_digest() * @see yaca_free() */ -int yaca_key_derive_dh(const yaca_key_h prv_key, - const yaca_key_h pub_key, - char **secret, - size_t *secret_len); +int yaca_key_derive_dh(const yaca_key_h prv_key, const yaca_key_h pub_key, char **secret, size_t *secret_len); + /** - * @brief Derives a key material from shared secret. - * + * @brief Derives a key material from shared secret. * @since_tizen 3.0 - * - * @remarks The @a info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure, - * more information can be found in ANSI X9.42/62 standard specification. - * - * @remarks The @a key_material or separate parts of it can be used to import a symmetric key - * with yaca_key_import(). - * - * @remarks The @a key_material should be freed using yaca_free(). - * - * @param[in] kdf Key derivation function - * @param[in] algo Digest algorithm that should be used in key derivation - * @param[in] secret Shared secret - * @param[in] secret_len Size of the shared secret - * @param[in] info Optional additional info, use NULL if not appending extra info - * @param[in] info_len Length of additional info, use 0 if not using additional info - * @param[in] key_material_len Length of a key material to be generated - * @param[out] key_material Newly generated key material - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure, + * more information can be found in ANSI X9.42/62 standard specification. + * @remarks The @a key_material or separate parts of it can be used to import a symmetric key + * with yaca_key_import(). + * @remarks The @a key_material should be freed using yaca_free(). + * @param[in] kdf Key derivation function + * @param[in] algo Digest algorithm that should be used in key derivation + * @param[in] secret Shared secret + * @param[in] secret_len Size of the shared secret + * @param[in] info Optional additional info, use NULL if not appending extra info + * @param[in] info_len Length of additional info, use 0 if not using additional info + * @param[in] key_material_len Length of a key material to be generated + * @param[out] key_material Newly generated key material + * @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 @a algo or @a kdf) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_kdf_e * @see #yaca_digest_algorithm_e * @see yaca_key_derive_dh() * @see yaca_key_import() * @see yaca_free() */ -int yaca_key_derive_kdf(yaca_kdf_e kdf, - yaca_digest_algorithm_e algo, - const char *secret, - size_t secret_len, - const char *info, - size_t info_len, - size_t key_material_len, - char **key_material); +int yaca_key_derive_kdf(yaca_kdf_e kdf, yaca_digest_algorithm_e algo, const char *secret, size_t secret_len, const char *info, size_t info_len, size_t key_material_len, char **key_material); + /** - * @brief Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm). - * + * @brief Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm). * @since_tizen 3.0 - * - * @remarks The @a key should be released using 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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a key should be released using 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 + * @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 @a algo or @a key_bit_len not dividable by 8) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_digest_algorithm_e * @see yaca_key_destroy() */ -int yaca_key_derive_pbkdf2(const char *password, - const char *salt, - size_t salt_len, - size_t iterations, - yaca_digest_algorithm_e algo, - size_t key_bit_len, - yaca_key_h *key); +int yaca_key_derive_pbkdf2(const char *password, const char *salt, size_t salt_len, size_t iterations, yaca_digest_algorithm_e algo, size_t key_bit_len, yaca_key_h *key); + /** - * @brief Release the key created by the library. Passing YACA_KEY_NULL is allowed. - * + * @brief Releases the key created by the library. Passing YACA_KEY_NULL is allowed. * @since_tizen 3.0 - * - * @param[in,out] key Key to be released - * + * @param[in,out] key Key to be released * @see yaca_key_import() * @see yaca_key_export() * @see yaca_key_generate() */ void yaca_key_destroy(yaca_key_h key); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_KEY_H */ diff --git a/api/yaca/yaca_rsa.h b/api/yaca/yaca_rsa.h index a57bfd7..4c226a8 100644 --- a/api/yaca/yaca_rsa.h +++ b/api/yaca/yaca_rsa.h @@ -16,182 +16,150 @@ * limitations under the License */ + /** - * @file yaca_rsa.h - * @brief Advanced API for low-level RSA operations + * @file yaca_rsa.h + * @brief Advanced API for low-level RSA operations. */ + #ifndef YACA_RSA_H #define YACA_RSA_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_RSA_MODULE * @{ */ + /** - * @brief Encrypts data using a RSA public key (low-level encrypt equivalent). - * + * @brief Encrypts data using a RSA public key (low-level encrypt equivalent). * @since_tizen 3.0 - * - * @remarks The @a ciphertext should be freed using yaca_free(). - * - * @remarks The @a pub_key used has to be of a #YACA_KEY_TYPE_RSA_PUB type. - * - * @remarks The maximum length of plaintext depends on the key length and padding method. - * See #yaca_padding_e for details. - * - * @remarks The @a plaintext can be NULL but then the @a plaintext_len must be 0. - * - * @param[in] padding Padding method - * @param[in] pub_key Public RSA key (see yaca_key.h for key generation functions) - * @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 - * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a ciphertext should be freed using yaca_free(). + * @remarks The @a pub_key used has to be of a #YACA_KEY_TYPE_RSA_PUB type. + * @remarks The maximum length of plaintext depends on the key length and padding method. + * See #yaca_padding_e for details. + * @remarks The @a plaintext can be NULL but then the @a plaintext_len must be 0. + * @param[in] padding Padding method + * @param[in] pub_key Public RSA key (see yaca_key.h for key generation functions) + * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a padding, @a pub_key or @a plaintext_len) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_padding_e * @see yaca_rsa_private_decrypt() * @see yaca_free() */ -int yaca_rsa_public_encrypt(yaca_padding_e padding, - const yaca_key_h pub_key, - const char *plaintext, - size_t plaintext_len, - char **ciphertext, - size_t *ciphertext_len); +int yaca_rsa_public_encrypt(yaca_padding_e padding, const yaca_key_h pub_key, const char *plaintext, size_t plaintext_len, char **ciphertext, size_t *ciphertext_len); + /** - * @brief Decrypts data using a RSA private key (low-level decrypt equivalent). - * + * @brief Decrypts data using a RSA private key (low-level decrypt equivalent). * @since_tizen 3.0 - * - * @remarks The @a plaintext should be freed using yaca_free(). - * - * @remarks The @a prv_key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type. - * - * @param[in] padding Padding method - * @param[in] prv_key Private RSA key matching the public one 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 - * @param[out] plaintext_len Length of the decrypted data - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a plaintext should be freed using yaca_free(). + * @remarks The @a prv_key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type. + * @param[in] padding Padding method + * @param[in] prv_key Private RSA key matching the public one 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 + * @param[out] plaintext_len Length of the decrypted data + * @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 @a padding or @a prv_key), padding check failed * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_padding_e * @see yaca_rsa_public_encrypt() * @see yaca_free() */ -int yaca_rsa_private_decrypt(yaca_padding_e padding, - const yaca_key_h prv_key, - const char *ciphertext, - size_t ciphertext_len, - char **plaintext, - size_t *plaintext_len); +int yaca_rsa_private_decrypt(yaca_padding_e padding, const yaca_key_h prv_key, const char *ciphertext, size_t ciphertext_len, char **plaintext, size_t *plaintext_len); + /** - * @brief Encrypts data using a RSA private key (low-level sign equivalent). - * + * @brief Encrypts data using a RSA private key (low-level sign equivalent). * @since_tizen 3.0 - * - * @remarks The @a ciphertext should be freed using yaca_free(). - * - * @remarks The @a prv_key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type. - * - * @remarks The maximum length of plaintext depends on the key length and padding method, - * see #yaca_padding_e for details. - * - * @remarks The @a plaintext can be NULL but then the @a plaintext_len must be 0. - * - * @param[in] padding Padding method - * @param[in] prv_key Private RSA key (see yaca_key.h for key generation functions) - * @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 - * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a ciphertext should be freed using yaca_free(). + * @remarks The @a prv_key used has to be of a #YACA_KEY_TYPE_RSA_PRIV type. + * @remarks The maximum length of plaintext depends on the key length and padding method, + * see #yaca_padding_e for details. + * @remarks The @a plaintext can be NULL but then the @a plaintext_len must be 0. + * @param[in] padding Padding method + * @param[in] prv_key Private RSA key (see yaca_key.h for key generation functions) + * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a padding, @a prv_key or @a plaintext_len) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_padding_e * @see yaca_rsa_public_decrypt() * @see yaca_free() */ -int yaca_rsa_private_encrypt(yaca_padding_e padding, - const yaca_key_h prv_key, - const char *plaintext, - size_t plaintext_len, - char **ciphertext, - size_t *ciphertext_len); +int yaca_rsa_private_encrypt(yaca_padding_e padding, const yaca_key_h prv_key, const char *plaintext, size_t plaintext_len, char **ciphertext, size_t *ciphertext_len); + /** - * @brief Decrypts data using a RSA public key (low-level verify equivalent). - * + * @brief Decrypts data using a RSA public key (low-level verify equivalent). * @since_tizen 3.0 - * - * @remarks The @a plaintext should be freed using yaca_free(). - * - * @remarks The @a pub_key used has to be of a #YACA_KEY_TYPE_RSA_PUB type. - * - * @param[in] padding Padding method - * @param[in] pub_key Public RSA key matching the private one 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 - * @param[out] plaintext_len Length of the decrypted data - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a plaintext should be freed using yaca_free(). + * @remarks The @a pub_key used has to be of a #YACA_KEY_TYPE_RSA_PUB type. + * @param[in] padding Padding method + * @param[in] pub_key Public RSA key matching the private one 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 + * @param[out] plaintext_len Length of the decrypted data + * @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 @a padding or @a pub_key), padding check failed * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_padding_e * @see yaca_rsa_private_encrypt() * @see yaca_free() */ -int yaca_rsa_public_decrypt(yaca_padding_e padding, - const yaca_key_h pub_key, - const char *ciphertext, - size_t ciphertext_len, - char **plaintext, - size_t *plaintext_len); +int yaca_rsa_public_decrypt(yaca_padding_e padding, const yaca_key_h pub_key, const char *ciphertext, size_t ciphertext_len, char **plaintext, size_t *plaintext_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_RSA_H */ diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index 5db810e..1e08345 100644 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -16,67 +16,62 @@ * limitations under the License */ + /** - * @file yaca_seal.h - * @brief Advanced API for the asymmetric encryption. - * - * @details Seal does more than just encrypt. It first generates the encryption key and - * Initialization Vector, then encrypts whole message using this key - * (and selected symmetric algorithm). - * Finally it encrypts symmetric key with public key. + * @file yaca_seal.h + * @brief Advanced API for the asymmetric encryption. + * @details Seal does more than just encrypt. It first generates the encryption key and + * Initialization Vector, then encrypts whole message using this key + * (and selected symmetric algorithm). + * Finally it encrypts symmetric key with public key. */ + #ifndef YACA_SEAL_H #define YACA_SEAL_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_ENCRYPTION_MODULE * @{ */ + /** - * @brief Initializes an asymmetric encryption context and generates - * symmetric key and Initialization Vector. - * - * @remarks Generated symmetric key is encrypted with public key, - * so can be only used with yaca_open_initialize(). It can be exported, - * but after import it can be only used with yaca_open_initialize() as well. - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @remarks The @a pub_key must be #YACA_KEY_TYPE_RSA_PUB. - * - * @remarks The @a sym_key_bit_len must be at least 88 bits shorter than the @a pub_key bit length. - * - * @remarks The @a sym_key should be released using yaca_key_destroy(). - * - * @remarks The @a iv should be released using yaca_key_destroy(). - * + * @brief Initializes an asymmetric encryption context and generates symmetric key and Initialization Vector. * @since_tizen 3.0 - * - * @param[out] ctx Newly created context - * @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 - * @param[out] iv Generated Initialization Vector that will be used - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks Generated symmetric key is encrypted with public key, + * so can be only used with yaca_open_initialize(). It can be exported, + * but after import it can be only used with yaca_open_initialize() as well. + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @remarks The @a pub_key must be #YACA_KEY_TYPE_RSA_PUB. + * @remarks The @a sym_key_bit_len must be at least 88 bits shorter than the @a pub_key bit length. + * @remarks The @a sym_key should be released using yaca_key_destroy(). + * @remarks The @a iv should be released using yaca_key_destroy(). + * @param[out] ctx Newly created context + * @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 + * @param[out] iv Generated Initialization Vector that will be used + * @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 @a algo, @a bcm, @a sym_key_bit_len or @a pub_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see #yaca_key_bit_length_e @@ -86,97 +81,77 @@ extern "C" { * @see yaca_key_destroy() * @see yaca_context_destroy() */ -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, - size_t sym_key_bit_len, - yaca_key_h *sym_key, - yaca_key_h *iv); +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, size_t sym_key_bit_len, + yaca_key_h *sym_key, yaca_key_h *iv); + /** - * @brief Encrypts piece of the data. - * + * @brief Encrypts piece of the data. * @since_tizen 3.0 - * - * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, * invalid @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_seal_initialize() * @see yaca_seal_finalize() * @see yaca_context_get_output_length() */ -int yaca_seal_update(yaca_context_h ctx, - const char *plaintext, - size_t plaintext_len, - char *ciphertext, - size_t *ciphertext_len); +int yaca_seal_update(yaca_context_h ctx, const char *plaintext, size_t plaintext_len, char *ciphertext, size_t *ciphertext_len); + /** - * @brief Encrypts the final piece of the data. - * - * @remarks Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an - * encryption of an empty message. - * + * @brief Encrypts the final piece of the data. * @since_tizen 3.0 - * - * @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 + * @remarks Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an + * encryption of an empty message. + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_seal_initialize() * @see yaca_seal_update() * @see yaca_context_get_output_length() */ -int yaca_seal_finalize(yaca_context_h ctx, - char *ciphertext, - size_t *ciphertext_len); +int yaca_seal_finalize(yaca_context_h ctx, char *ciphertext, size_t *ciphertext_len); + /** - * @brief Initializes an asymmetric decryption context. - * + * @brief Initializes an asymmetric decryption context. * @since_tizen 3.0 - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @remarks The @a prv_key must be #YACA_KEY_TYPE_RSA_PRIV. - * - * @param[out] ctx Newly created context - * @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 + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @remarks The @a prv_key must be #YACA_KEY_TYPE_RSA_PRIV. + * @param[out] ctx Newly created context + * @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 * @a algo, @a bcm, @a sym_key_bit_len, @a prv_key, * @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see #yaca_key_bit_length_e @@ -184,79 +159,66 @@ int yaca_seal_finalize(yaca_context_h ctx, * @see yaca_open_finalize() * @see yaca_context_destroy() */ -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, - size_t sym_key_bit_len, - const yaca_key_h sym_key, - const yaca_key_h iv); +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, size_t sym_key_bit_len, + const yaca_key_h sym_key, const yaca_key_h iv); + /** - * @brief Decrypts piece of the data. - * + * @brief Decrypts piece of the data. * @since_tizen 3.0 - * - * @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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0, * invalid @a ctx), wrong #YACA_PROPERTY_CCM_AAD or * wrong #YACA_PROPERTY_CCM_TAG was used * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_open_initialize() * @see yaca_open_finalize() * @see yaca_context_get_output_length() */ -int yaca_open_update(yaca_context_h ctx, - const char *ciphertext, - size_t ciphertext_len, - char *plaintext, - size_t *plaintext_len); +int yaca_open_update(yaca_context_h ctx, const char *ciphertext, size_t ciphertext_len, char *plaintext, size_t *plaintext_len); + /** - * @brief Decrypts last chunk of sealed message. - * - * @remarks Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a - * decryption of an empty ciphertext. - * + * @brief Decrypts last chunk of sealed message. * @since_tizen 3.0 - * - * @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 + * @remarks Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a + * decryption of an empty ciphertext. + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a ctx), wrong #YACA_PROPERTY_GCM_AAD or * wrong #YACA_PROPERTY_GCM_TAG was used * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_open_initialize() * @see yaca_open_update() * @see yaca_context_get_output_length() */ -int yaca_open_finalize(yaca_context_h ctx, - char *plaintext, - size_t *plaintext_len); +int yaca_open_finalize(yaca_context_h ctx, char *plaintext, size_t *plaintext_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_SEAL_H */ diff --git a/api/yaca/yaca_sign.h b/api/yaca/yaca_sign.h index 0fcbec3..3ac545e 100644 --- a/api/yaca/yaca_sign.h +++ b/api/yaca/yaca_sign.h @@ -16,61 +16,58 @@ * limitations under the License */ + /** - * @file yaca_sign.h - * @brief Advanced API for the integrity handling - HMAC, CMAC and digital signature. + * @file yaca_sign.h + * @brief Advanced API for the integrity handling - HMAC, CMAC and digital signature. */ + #ifndef YACA_SIGN_H #define YACA_SIGN_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_INTEGRITY_MODULE * @{ */ + /** - * @brief Initializes a signature context for asymmetric signatures. - * + * @brief Initializes a signature context for asymmetric signatures. * @since_tizen 3.0 - * - * @remarks For verification use yaca_verify_initialize(), yaca_verify_update() and - * yaca_verify_finalize() functions with matching public key. - * - * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be - * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING. - * - * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than - * #YACA_KEY_LENGTH_512BIT. - * - * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. - * - * @remarks Using of #YACA_DIGEST_MD5 or #YACA_DIGEST_SHA224 with #YACA_PADDING_X931 is prohibited. - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @param[in] algo Digest algorithm that will be used - * @param[in] prv_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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification use yaca_verify_initialize(), yaca_verify_update() and + * yaca_verify_finalize() functions with matching public key. + * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be + * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING. + * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than + * #YACA_KEY_LENGTH_512BIT. + * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. + * @remarks Using of #YACA_DIGEST_MD5 or #YACA_DIGEST_SHA224 with #YACA_PADDING_X931 is prohibited. + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @param[in] algo Digest algorithm that will be used + * @param[in] prv_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 + * @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 @a algo or @a prv_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_algorithm_e * @see #yaca_padding_e @@ -82,33 +79,26 @@ extern "C" { * @see yaca_verify_finalize() * @see yaca_context_destroy() */ -int yaca_sign_initialize(yaca_context_h *ctx, - yaca_digest_algorithm_e algo, - const yaca_key_h prv_key); +int yaca_sign_initialize(yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h prv_key); + /** - * @brief Initializes a signature context for HMAC. - * + * @brief Initializes a signature context for HMAC. * @since_tizen 3.0 - * - * @remarks For verification, calculate message HMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @param[in] algo Digest algorithm that will be used - * @param[in] sym_key Symmetric key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message HMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @param[in] algo Digest algorithm that will be used + * @param[in] sym_key Symmetric key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @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 @a algo or @a sym_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_algorithm_e * @see yaca_sign_update() @@ -116,33 +106,26 @@ int yaca_sign_initialize(yaca_context_h *ctx, * @see yaca_memcmp() * @see yaca_context_destroy() */ -int yaca_sign_initialize_hmac(yaca_context_h *ctx, - yaca_digest_algorithm_e algo, - const yaca_key_h sym_key); +int yaca_sign_initialize_hmac(yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h sym_key); + /** - * @brief Initializes a signature context for CMAC. - * + * @brief Initializes a signature context for CMAC. * @since_tizen 3.0 - * - * @remarks For verification, calculate message CMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @param[in] algo Encryption algorithm that will be used - * @param[in] sym_key Symmetric key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message CMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @param[in] algo Encryption algorithm that will be used + * @param[in] sym_key Symmetric key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @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 @a algo or @a sym_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_encrypt_algorithm_e * @see yaca_sign_update() @@ -150,91 +133,76 @@ int yaca_sign_initialize_hmac(yaca_context_h *ctx, * @see yaca_memcmp() * @see yaca_context_destroy() */ -int yaca_sign_initialize_cmac(yaca_context_h *ctx, - yaca_encrypt_algorithm_e algo, - const yaca_key_h sym_key); +int yaca_sign_initialize_cmac(yaca_context_h *ctx, yaca_encrypt_algorithm_e algo, const yaca_key_h sym_key); + /** - * @brief Feeds the message into the digital signature or MAC algorithm. - * + * @brief Feeds the message into the digital signature or MAC algorithm. * @since_tizen 3.0 - * - * @param[in,out] ctx Context created by yaca_sign_initialize(), - * yaca_sign_initialize_hmac() or yaca_sign_initialize_cmac() - * @param[in] message Message to be signed - * @param[in] message_len Length of the message - * - * @return #YACA_ERROR_NONE on success, negative on error + * @param[in,out] ctx Context created by yaca_sign_initialize(), + * yaca_sign_initialize_hmac() or yaca_sign_initialize_cmac() + * @param[in] message Message to be signed + * @param[in] message_len Length of the message + * @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 @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_sign_initialize() * @see yaca_sign_finalize() * @see yaca_sign_initialize_hmac() * @see yaca_sign_initialize_cmac() */ -int yaca_sign_update(yaca_context_h ctx, - const char *message, - size_t message_len); +int yaca_sign_update(yaca_context_h ctx, const char *message, size_t message_len); + /** - * @brief Calculates the final signature or MAC. - * + * @brief Calculates the final signature or MAC. * @since_tizen 3.0 - * - * @remarks Skipping yaca_sign_update() and calling only yaca_sign_finalize() will produce a - * signature or MAC of an empty message. - * - * @param[in,out] ctx A valid sign context - * @param[out] signature Buffer for the MAC or the message signature - * (must be allocated by client, see yaca_context_get_output_length()) - * @param[out] signature_len Length of the MAC or the signature, - * actual number of bytes written will be returned here - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks Skipping yaca_sign_update() and calling only yaca_sign_finalize() will produce a + * signature or MAC of an empty message. + * @param[in,out] ctx A valid sign context + * @param[out] signature Buffer for the MAC or the message signature + * (must be allocated by client, see yaca_context_get_output_length()) + * @param[out] signature_len Length of the MAC or the signature, + * actual number of bytes written 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 @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_sign_initialize() * @see yaca_sign_update() * @see yaca_sign_initialize_hmac() * @see yaca_sign_initialize_cmac() * @see yaca_context_get_output_length() */ -int yaca_sign_finalize(yaca_context_h ctx, - char *signature, - size_t *signature_len); +int yaca_sign_finalize(yaca_context_h ctx, char *signature, size_t *signature_len); + /** - * @brief Initializes a signature verification context for asymmetric signatures. - * + * @brief Initializes a signature verification context for asymmetric signatures. * @since_tizen 3.0 - * - * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be - * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING. - * For verify to succeed it has to be set to the same value it was signed with. - * - * @remarks The @a ctx should be released using yaca_context_destroy(). - * - * @param[out] ctx Newly created context - * @param[in] algo Digest algorithm that will be used - * @param[in] pub_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 - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be + * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING. + * For verify to succeed it has to be set to the same value it was signed with. + * @remarks The @a ctx should be released using yaca_context_destroy(). + * @param[out] ctx Newly created context + * @param[in] algo Digest algorithm that will be used + * @param[in] pub_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 + * @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 @a algo or @a pub_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_algorithm_e * @see #yaca_padding_e @@ -243,65 +211,57 @@ int yaca_sign_finalize(yaca_context_h ctx, * @see yaca_verify_finalize() * @see yaca_context_destroy() */ -int yaca_verify_initialize(yaca_context_h *ctx, - yaca_digest_algorithm_e algo, - const yaca_key_h pub_key); +int yaca_verify_initialize(yaca_context_h *ctx, yaca_digest_algorithm_e algo, const yaca_key_h pub_key); + /** - * @brief Feeds the message into the digital signature verification algorithm. - * + * @brief Feeds the message into the digital signature verification algorithm. * @since_tizen 3.0 - * - * @param[in,out] ctx Context created by yaca_verify_initialize() - * @param[in] message Message - * @param[in] message_len Length of the message - * - * @return #YACA_ERROR_NONE on success, negative on error + * @param[in,out] ctx Context created by yaca_verify_initialize() + * @param[in] message Message + * @param[in] message_len Length of the message + * @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 @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error - * * @see yaca_verify_initialize() * @see yaca_verify_finalize() */ -int yaca_verify_update(yaca_context_h ctx, - const char *message, - size_t message_len); +int yaca_verify_update(yaca_context_h ctx, const char *message, size_t message_len); + /** - * @brief Performs the verification. - * + * @brief Performs the verification. * @since_tizen 3.0 - * - * @remarks Skipping yaca_verify_update() and calling only yaca_verify_finalize() will verify - * the signature of an empty message. - * - * @param[in,out] ctx A valid verify context - * @param[in] signature Message signature to be verified - * @param[in] signature_len Length of the signature - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks Skipping yaca_verify_update() and calling only yaca_verify_finalize() will verify + * the signature of an empty message. + * @param[in,out] ctx A valid verify context + * @param[in] signature Message signature to be verified + * @param[in] signature_len Length of the signature + * @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 @a ctx) * @retval #YACA_ERROR_INTERNAL Internal error * @retval #YACA_ERROR_DATA_MISMATCH The verification failed - * * @see yaca_verify_initialize() * @see yaca_verify_update() * @see yaca_sign_finalize() */ -int yaca_verify_finalize(yaca_context_h ctx, - const char *signature, - size_t signature_len); +int yaca_verify_finalize(yaca_context_h ctx, const char *signature, size_t signature_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_SIGN_H */ diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index 97a9826..7328c7c 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -16,317 +16,253 @@ * limitations under the License */ + /** - * @file yaca_simple.h - * @brief Simple API. - * - * @details This is simple API. - * Design constraints: - * - All operations are single-shot (no streaming possible) - * - Context is not used - * - Only digest, signatures and symmetric ciphers are supported - * - Disabling PKCS#7 padding for ECB and CBC chaining is not supported - * - Changing the default PKCS#1 padding for sign/verify is not supported - * - GCM and CCM chaining is not supported - * - RC2 effective key bits property is not supported - * - All outputs are allocated by the library + * @file yaca_simple.h + * @brief Simple API. + * @details This is simple API. + * Design constraints: + * - All operations are single-shot (no streaming possible) + * - Context is not used + * - Only digest, signatures and symmetric ciphers are supported + * - Disabling PKCS#7 padding for ECB and CBC chaining is not supported + * - Changing the default PKCS#1 padding for sign/verify is not supported + * - GCM and CCM chaining is not supported + * - RC2 effective key bits property is not supported + * - All outputs are allocated by the library */ + #ifndef YACA_SIMPLE_H #define YACA_SIMPLE_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_SIMPLE_MODULE * @{ */ + /** - * @brief Encrypts data using a symmetric cipher. - * + * @brief Encrypts data using a symmetric cipher. * @since_tizen 3.0 - * - * @remarks yaca_simple_encrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. - * - * @remarks The @a ciphertext should be freed using yaca_free(). - * - * @remarks The @a plaintext can be NULL but then @a plaintext_len must be 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 yaca_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 - * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks yaca_simple_encrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. + * @remarks The @a ciphertext should be freed using yaca_free(). + * @remarks The @a plaintext can be NULL but then @a plaintext_len must be 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 yaca_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 + * @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 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_simple_decrypt() * @see yaca_free() */ -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 *plaintext, - size_t plaintext_len, - char **ciphertext, - size_t *ciphertext_len); +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 *plaintext, + size_t plaintext_len, char **ciphertext, size_t *ciphertext_len); + /** - * @brief Decrypts data using a symmetric cipher. - * + * @brief Decrypts data using a symmetric cipher. * @since_tizen 3.0 - * - * @remarks yaca_simple_decrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. - * - * @remarks The @a plaintext should be freed using yaca_free(). - * - * @remarks The @a ciphertext can be NULL but then @a ciphertext_len must be 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] ciphertext Ciphertext to be decrypted - * @param[in] ciphertext_len Length of ciphertext - * @param[out] plaintext Decrypted data, will be allocated by the library - * @param[out] plaintext_len Length of the decrypted data - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks yaca_simple_decrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. + * @remarks The @a plaintext should be freed using yaca_free(). + * @remarks The @a ciphertext can be NULL but then @a ciphertext_len must be 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] ciphertext Ciphertext to be decrypted + * @param[in] ciphertext_len Length of ciphertext + * @param[out] plaintext Decrypted data, will be allocated by the library + * @param[out] plaintext_len Length of the decrypted data + * @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 @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_simple_encrypt() * @see yaca_free() */ -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 *ciphertext, - size_t ciphertext_len, - char **plaintext, - size_t *plaintext_len); +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 *ciphertext, + size_t ciphertext_len, char **plaintext, size_t *plaintext_len); + /** - * @brief Calculates a digest of a message. - * + * @brief Calculates a digest of a message. * @since_tizen 3.0 - * - * @remarks The @a digest should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure) - * @param[in] message Message from which the digest is to be calculated - * @param[in] message_len Length of the message - * @param[out] digest Message digest, will be allocated by the library - * @param[out] digest_len Length of message digest (depends on algorithm) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a digest should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure) + * @param[in] message Message from which the digest is to be calculated + * @param[in] message_len Length of the message + * @param[out] digest Message digest, will be allocated by the library + * @param[out] digest_len Length of message digest (depends on algorithm) + * @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 @a algo) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_digest_algorithm_e * @see yaca_free() */ -int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, - const char *message, - size_t message_len, - char **digest, - size_t *digest_len); +int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, const char *message, size_t message_len, char **digest, size_t *digest_len); + /** - * @brief Creates a signature using asymmetric private key. - * + * @brief Creates a signature using asymmetric private key. * @since_tizen 3.0 - * - * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than - * #YACA_KEY_LENGTH_512BIT. - * - * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. - * - * @remarks The @a signature should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] prv_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] message Message to be signed - * @param[in] message_len Length of the message - * @param[out] signature Message signature, will be allocated by the library - * @param[out] signature_len Length of the signature - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than + * #YACA_KEY_LENGTH_512BIT. + * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. + * @remarks The @a signature should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] prv_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] message Message to be signed + * @param[in] message_len Length of the message + * @param[out] signature Message signature, will be allocated by the library + * @param[out] signature_len Length of the signature + * @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 @a algo or @a prv_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_algorithm_e * @see yaca_simple_verify_signature() * @see yaca_free() */ -int yaca_simple_calculate_signature(yaca_digest_algorithm_e algo, - const yaca_key_h prv_key, - const char *message, - size_t message_len, - char **signature, - size_t *signature_len); +int yaca_simple_calculate_signature(yaca_digest_algorithm_e algo, const yaca_key_h prv_key, const char *message, size_t message_len, char **signature, size_t *signature_len); + /** - * @brief Verifies a signature using asymmetric public key. - * + * @brief Verifies a signature using asymmetric public key. * @since_tizen 3.0 - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] pub_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] message Message - * @param[in] message_len Length of the message - * @param[in] signature Message signature to be verified - * @param[in] signature_len Length of the signature - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] pub_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] message Message + * @param[in] message_len Length of the message + * @param[in] signature Message signature to be verified + * @param[in] signature_len Length of the signature + * @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 @a algo or @a pub_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_algorithm_e * @see yaca_simple_calculate_signature() */ -int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, - const yaca_key_h pub_key, - const char *message, - size_t message_len, - const char *signature, - size_t signature_len); +int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, const yaca_key_h pub_key, const char *message, size_t message_len, const char *signature, size_t signature_len); + /** - * @brief Calculates a HMAC of given message using symmetric key. - * + * @brief Calculates a HMAC of given message using symmetric key. * @since_tizen 3.0 - * - * @remarks For verification, calculate message HMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a mac should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] sym_key Key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * @param[in] message Message to calculate HMAC from - * @param[in] message_len Length of the message - * @param[out] mac MAC, will be allocated by the library - * @param[out] mac_len Length of the MAC - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message HMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a mac should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] sym_key Key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @param[in] message Message to calculate HMAC from + * @param[in] message_len Length of the message + * @param[out] mac MAC, will be allocated by the library + * @param[out] mac_len Length of the MAC + * @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 @a algo or @a sym_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_algorithm_e * @see yaca_memcmp() * @see yaca_free() */ -int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, - const yaca_key_h sym_key, - const char *message, - size_t message_len, - char **mac, - size_t *mac_len); +int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, const yaca_key_h sym_key, const char *message, size_t message_len, char **mac, size_t *mac_len); + /** - * @brief Calculates a CMAC of given message using symmetric key. - * + * @brief Calculates a CMAC of given message using symmetric key. * @since_tizen 3.0 - * - * @remarks For verification, calculate message CMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a mac should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Encryption algorithm that will be used - * @param[in] sym_key Key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * @param[in] message Message to calculate CMAC from - * @param[in] message_len Length of the message - * @param[out] mac MAC, will be allocated by the library - * @param[out] mac_len Length of the MAC - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message CMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a mac should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Encryption algorithm that will be used + * @param[in] sym_key Key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @param[in] message Message to calculate CMAC from + * @param[in] message_len Length of the message + * @param[out] mac MAC, will be allocated by the library + * @param[out] mac_len Length of the MAC + * @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 @a algo or @a sym_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_encrypt_algorithm_e * @see yaca_memcmp() * @see yaca_free() */ -int yaca_simple_calculate_cmac(yaca_encrypt_algorithm_e algo, - const yaca_key_h sym_key, - const char *message, - size_t message_len, - char **mac, - size_t *mac_len); +int yaca_simple_calculate_cmac(yaca_encrypt_algorithm_e algo, const yaca_key_h sym_key, const char *message, size_t message_len, char **mac, size_t *mac_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_SIMPLE_H */ diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h index c6b1cb3..a4ae309 100644 --- a/api/yaca/yaca_types.h +++ b/api/yaca/yaca_types.h @@ -16,25 +16,29 @@ * limitations under the License */ + /** - * @file yaca_types.h - * @brief Types enums and defines. + * @file yaca_types.h + * @brief Types enums and defines. */ + #ifndef YACA_TYPES_H #define YACA_TYPES_H + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_ENCRYPTION_MODULE * @{ */ + /* The format of the unsigned int used to indicate key_bit_len is as follows: - * * Bits indicating a type: * bits 31-28 (4 bits) indicate key_length type: * 0000(0) - regular type for RSA, DSA @@ -42,10 +46,8 @@ extern "C" { * 0010(2) - DH with RFC 5114 * 0011(3) - elliptic curve * remaining combinations reserved - * * Bits for a regular type: * bits 27-0 (28 bits) indicate length of the key in bits - * * Bits for a DH with specified generator number: * bits 27-24 (4 bits) indicate DH generator * 0000(0) - generator 2 @@ -53,7 +55,6 @@ extern "C" { * remaining combinations reserved * bits 23-16 (8 bits) reserved * bits 15-0 (16 bits) length of the safe prime in bits - * * Bits for a DH with RFC 5114: * bits 27-24 (4 bits) indicate a bit subgroup: * 0000(0) - 160 @@ -62,7 +63,6 @@ extern "C" { * remaining combinations reserved * bits 23-16 (8 bits) reserved * bits 15-0 (16 bits) length of the safe prime in bits - * * Bits for an elliptic curve type: * bits 27-24 (4 bits) indicate type of an elliptic curve: * 0000(0) - X9.62 Prime @@ -83,75 +83,79 @@ extern "C" { * 0011(3) - 4 * remaining combinations reserved * bits 15-0 (16 bits) - length of the prime field in bits - * * Those bits are used for DH and EC. For any other keys key_bit_len can be passed just * as a number of bits (4 most significant bits set to 0000, 28 bits for bit length). - * * In any case those defines are not be used directly. - * * For DH keys use YACA_KEY_LENGTH_DH_GENERATOR_* or'ed with safe prime length. * Alternatively one can use values from yaca_key_bit_length_dh_rfc_e enum to use * RFC 5114 parameters. - * * For elliptic curves use values from yaca_key_bit_length_ec_e enum. */ + /** @cond Don't include those defines in doxygen, they are not to be used directly */ + /* types */ -#define YACA_KEYLEN_COMPONENT_TYPE_MASK (0xF << 28) -#define YACA_KEYLEN_COMPONENT_TYPE_BITS (0U << 28) -#define YACA_KEYLEN_COMPONENT_TYPE_DH (1U << 28) -#define YACA_KEYLEN_COMPONENT_TYPE_DH_RFC (2U << 28) -#define YACA_KEYLEN_COMPONENT_TYPE_EC (3U << 28) +#define YACA_KEYLEN_COMPONENT_TYPE_MASK (0xF << 28) +#define YACA_KEYLEN_COMPONENT_TYPE_BITS (0U << 28) +#define YACA_KEYLEN_COMPONENT_TYPE_DH (1U << 28) +#define YACA_KEYLEN_COMPONENT_TYPE_DH_RFC (2U << 28) +#define YACA_KEYLEN_COMPONENT_TYPE_EC (3U << 28) + /* DH type */ -#define YACA_KEYLEN_COMPONENT_DH_GEN_MASK (0xF << 24) -#define YACA_KEYLEN_COMPONENT_DH_GEN_2 (0U << 24) -#define YACA_KEYLEN_COMPONENT_DH_GEN_5 (1U << 24) +#define YACA_KEYLEN_COMPONENT_DH_GEN_MASK (0xF << 24) +#define YACA_KEYLEN_COMPONENT_DH_GEN_2 (0U << 24) +#define YACA_KEYLEN_COMPONENT_DH_GEN_5 (1U << 24) + #define YACA_KEYLEN_COMPONENT_DH_PRIME_MASK (0xFFFF << 0) + /* DH_RFC type */ -#define YACA_KEYLEN_COMPONENT_DH_RFC_MASK (0xF << 24) -#define YACA_KEYLEN_COMPONENT_DH_RFC_160 (0U << 24) -#define YACA_KEYLEN_COMPONENT_DH_RFC_224 (1U << 24) -#define YACA_KEYLEN_COMPONENT_DH_RFC_256 (2U << 24) +#define YACA_KEYLEN_COMPONENT_DH_RFC_MASK (0xF << 24) +#define YACA_KEYLEN_COMPONENT_DH_RFC_160 (0U << 24) +#define YACA_KEYLEN_COMPONENT_DH_RFC_224 (1U << 24) +#define YACA_KEYLEN_COMPONENT_DH_RFC_256 (2U << 24) + /* EC type */ -#define YACA_KEYLEN_COMPONENT_EC_PRIME (0U << 24) -#define YACA_KEYLEN_COMPONENT_EC_SECP (1U << 24) -#define YACA_KEYLEN_COMPONENT_EC_SECT (2U << 24) -#define YACA_KEYLEN_COMPONENT_EC_BRAINPOOL (3U << 24) - -#define YACA_KEYLEN_COMPONENT_EC_V (0U << 20) -#define YACA_KEYLEN_COMPONENT_EC_R (1U << 20) -#define YACA_KEYLEN_COMPONENT_EC_K (2U << 20) -#define YACA_KEYLEN_COMPONENT_EC_T (3U << 20) - -#define YACA_KEYLEN_COMPONENT_EC_1 (0U << 16) -#define YACA_KEYLEN_COMPONENT_EC_2 (1U << 16) -#define YACA_KEYLEN_COMPONENT_EC_3 (2U << 16) -#define YACA_KEYLEN_COMPONENT_EC_4 (3U << 16) +#define YACA_KEYLEN_COMPONENT_EC_PRIME (0U << 24) +#define YACA_KEYLEN_COMPONENT_EC_SECP (1U << 24) +#define YACA_KEYLEN_COMPONENT_EC_SECT (2U << 24) +#define YACA_KEYLEN_COMPONENT_EC_BRAINPOOL (3U << 24) + + +#define YACA_KEYLEN_COMPONENT_EC_V (0U << 20) +#define YACA_KEYLEN_COMPONENT_EC_R (1U << 20) +#define YACA_KEYLEN_COMPONENT_EC_K (2U << 20) +#define YACA_KEYLEN_COMPONENT_EC_T (3U << 20) + + +#define YACA_KEYLEN_COMPONENT_EC_1 (0U << 16) +#define YACA_KEYLEN_COMPONENT_EC_2 (1U << 16) +#define YACA_KEYLEN_COMPONENT_EC_3 (2U << 16) +#define YACA_KEYLEN_COMPONENT_EC_4 (3U << 16) /** @endcond */ + /** * @brief The context handle. - * * @since_tizen 3.0 */ typedef struct yaca_context_s *yaca_context_h; + /** - * @brief The handle of a key, an Initialization Vector or a key generation parameters. - * + * @brief An Initialization Vector or a key generation parameters by the key handle. * @since_tizen 3.0 */ typedef struct yaca_key_s *yaca_key_h; + /** - * @brief Enumeration of YACA key formats. - * + * @brief Enumeration for formats YACA key. * @since_tizen 3.0 */ typedef enum { @@ -161,9 +165,9 @@ typedef enum { YACA_KEY_FORMAT_PKCS8 } yaca_key_format_e; + /** - * @brief Enumeration of YACA key file formats. - * + * @brief Enumeration for formats YACA key file. * @since_tizen 3.0 */ typedef enum { @@ -177,9 +181,9 @@ typedef enum { YACA_KEY_FILE_FORMAT_DER } yaca_key_file_format_e; + /** - * @brief Enumeration of YACA key types, Initialization Vector is considered as key. - * + * @brief Enumeration for YACA key types, Initialization Vector is considered as key. * @since_tizen 3.0 */ typedef enum { @@ -218,11 +222,11 @@ typedef enum { YACA_KEY_TYPE_EC_PARAMS } yaca_key_type_e; + /** - * @brief Enumeration of YACA key lengths. + * @brief Enumeration for YACA key lengths. * It is possible to use arbitrary integer instead, * this enum values are placed here to avoid magic numbers. - * * @since_tizen 3.0 */ typedef enum { @@ -257,10 +261,9 @@ typedef enum { } yaca_key_bit_length_e; /** - * @brief Enumeration of YACA elliptic curve types with their bit lengths. + * @brief Enumeration for YACA elliptic curve types with their bit lengths. * It's meant to be passed or returned as a @a key_bit_len param * in appropriate functions when dealing with elliptic curves. - * * @since_tizen 3.0 */ typedef enum { @@ -277,24 +280,23 @@ typedef enum { } yaca_key_bit_length_ec_e; /** - * @brief A value indicating generator equal 2 for DH parameters. + * @brief Definition for the value indicating generator equal 2 for DH parameters. * To be or'ed with safe prime length in bits. Prime length is recommended * to be 2048 bits or higher. */ #define YACA_KEY_LENGTH_DH_GENERATOR_2 (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_2) /** - * @brief A value indicating generator equal 5 for DH parameters. + * @brief Definition for the value indicating generator equal 5 for DH parameters. * To be or'ed with safe prime length in bits. Prime length is recommended * to be 2048 bits or higher. */ #define YACA_KEY_LENGTH_DH_GENERATOR_5 (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_5) /** - * @brief Enumeration of YACA DH parameters taken from RFC 5114. + * @brief Enumeration for YACA DH parameters taken from RFC 5114. * It's meant to be passed or returned as a @a key_bit_len param * in appropriate functions when dealing with DH and wanting to * use RFC 5114 values. - * * @since_tizen 3.0 */ typedef enum { @@ -306,9 +308,9 @@ typedef enum { YACA_KEY_LENGTH_DH_RFC_2048_256 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_256 | 2048U } yaca_key_bit_length_dh_rfc_e; + /** - * @brief Enumeration of YACA message digest algorithms. - * + * @brief Enumeration for YACA message digest algorithms. * @since_tizen 3.0 */ typedef enum { @@ -326,9 +328,9 @@ typedef enum { YACA_DIGEST_SHA512, } yaca_digest_algorithm_e; + /** - * @brief Enumeration of YACA symmetric encryption algorithms. - * + * @brief Enumeration for YACA symmetric encryption algorithms. * @since_tizen 3.0 */ typedef enum { @@ -435,9 +437,9 @@ typedef enum { YACA_ENCRYPT_CAST5, } yaca_encrypt_algorithm_e; + /** - * @brief Enumeration of YACA chaining modes for block ciphers. - * + * @brief Enumeration for YACA chaining modes for block ciphers. * @since_tizen 3.0 */ typedef enum { @@ -450,7 +452,6 @@ typedef enum { /** * ECB block cipher mode. * Initialization Vector is not used. - * * By default the input data is padded using standard block padding (#YACA_PADDING_PKCS7). * Padding can be disabled using yaca_context_set_property() and * #YACA_PROPERTY_PADDING,#YACA_PADDING_NONE, @@ -470,7 +471,6 @@ typedef enum { * CBC block cipher mode. * 128-bit Initialization Vector for AES, * 64-bit for other algorithms is mandatory. - * * By default the input data is padded using standard block padding (#YACA_PADDING_PKCS7). * Padding can be disabled using yaca_context_set_property() and * #YACA_PROPERTY_PADDING, #YACA_PADDING_NONE, @@ -482,7 +482,6 @@ typedef enum { /** * GCM block cipher mode. * This is a variable Initialization Vector length mode (recommended 96-bits). - * * Supported properties: * - #YACA_PROPERTY_GCM_TAG_LEN = GCM tag length (optional)\n * Supported tag lengths: @c 4, @c 8, @c 12, @c 13, @c 14, @c 15, @c 16 @@ -490,22 +489,18 @@ typedef enum { * Set after yaca_encrypt_finalize() / yaca_seal_finalize() and before * yaca_context_get_property(#YACA_PROPERTY_GCM_TAG) in encryption / seal operation.\n * The @a value should be a size_t variable.\n - * In decryption / open operation tag length is not set.\n\n - * + * In decryption / open operation tag length is not set.\n * - #YACA_PROPERTY_GCM_TAG = GCM tag\n * Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation.\n * Set after yaca_decrypt_update() / yaca_open_update() and before - * yaca_decrypt_finalize() / yaca_open_finalize() in decryption / open operation.\n\n - * + * yaca_decrypt_finalize() / yaca_open_finalize() in decryption / open operation.\n * - #YACA_PROPERTY_GCM_AAD = additional authentication data (optional)\n * Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before * yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n * Set after yaca_decrypt_initialize() / yaca_open_initialize() and before - * yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n\n - * + * yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n * @see yaca_context_set_property() * @see yaca_context_get_property() - * */ YACA_BCM_GCM, @@ -541,61 +536,50 @@ typedef enum { * CBC-MAC Mode (AES). * This is a variable Initialization Vector length mode.\n * Supported Initialization Vector lengths: 56-104 bits in steps of 8 bits - * (recommended 56-bits).\n\n - * + * (recommended 56-bits).\n * Supported properties: * - #YACA_PROPERTY_CCM_TAG_LEN = CCM tag length (optional)\n * Supported tag lengths: 4-16 bytes in steps of 2 bytes (12 bytes tag by default).\n * Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before * yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n * The @a value should be a size_t variable.\n - * In decryption / open operation tag length is not set.\n\n - * + * In decryption / open operation tag length is not set.\n * - #YACA_PROPERTY_CCM_TAG = CCM tag\n * Get after yaca_encrypt_finalize() / yaca_seal_finalize() in encryption / seal operation.\n * Set after yaca_decrypt_initialize() / yaca_open_initialize() and before - * yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n\n - * + * yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n * - #YACA_PROPERTY_CCM_AAD = additional authentication data (optional)\n * The total plaintext length must be passed to yaca_encrypt_update() / yaca_seal_update() * if AAD is used.\n * Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before * yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n * You can only call yaca_encrypt_update() / yaca_seal_update() once for AAD - * and once for the plaintext.\n\n - * + * and once for the plaintext.\n * The total encrypted text length must be passed to yaca_decrypt_update() / * yaca_open_update() if AAD is used.\n * Set after yaca_decrypt_initialize() / yaca_open_initialize() and before * yaca_decrypt_update() / yaca_open_update() in decryption / open operation.\n * You can only call yaca_decrypt_update() / yaca_open_update() once for AAD - * and once for the encrypted text.\n\n - * + * and once for the encrypted text.\n * @see yaca_context_set_property() * @see yaca_context_get_property() - * */ YACA_BCM_CCM, /** * Used with #YACA_ENCRYPT_AES or #YACA_ENCRYPT_3DES_3TDEA to perform a key wrapping * (key material symmetric encryption). - * * Only a single yaca_encrypt_update() / yaca_decrypt_update() is allowed. - * * Usage in yaca_seal_initialize() / yaca_open_finalize() is forbidden. - * * Key used to do the wrapping with #YACA_ENCRYPT_AES can be a 128-bit key, a 192-bit key, * or a 256-bit key.\n * 64-bit Initialization Vector is used.\n * Wrapped key can be a 128-bit key, a 192-bit key, or a 256-bit key.\n * #YACA_ENCRYPT_AES allows wrapping multiple keys together. - * * Key used to do the wrapping with #YACA_ENCRYPT_3DES_3TDEA can be a 192-bit DES key only.\n * Initialization Vector is not used.\n * Wrapped key can be a 128-bit DES key (two-key), or a 192-bit DES key (three-key).\n * #YACA_ENCRYPT_3DES_3TDEA allows wrapping only one key. - * */ YACA_BCM_WRAP @@ -603,16 +587,13 @@ typedef enum { /** - * @brief Enumeration of YACA non-standard properties for algorithms. - * + * @brief Enumeration for YACA non-standard properties for algorithms. * @since_tizen 3.0 - * * @see #yaca_padding_e */ typedef enum { /** * Padding for the encrypt/decrypt or sign/verify operation. Property type is #yaca_padding_e. - * * This property can be set at the latest before the *_finalize() call. */ YACA_PROPERTY_PADDING, @@ -636,8 +617,7 @@ typedef enum { } yaca_property_e; /** - * @brief Enumeration of YACA paddings. - * + * @brief Enumeration for YACA paddings. * @since_tizen 3.0 */ typedef enum { @@ -689,9 +669,9 @@ typedef enum { YACA_PADDING_PKCS7 } yaca_padding_e; + /** - * @brief Enumeration of YACA key derivation functions. - * + * @brief Enumeration for YACA key derivation functions. * @since_tizen 3.0 */ typedef enum { @@ -708,12 +688,15 @@ typedef enum { YACA_KDF_X962, } yaca_kdf_e; + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_TYPES_H */ diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index ae4168b..8d8badd 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -45,7 +45,13 @@ SET_TARGET_PROPERTIES(${PROJECT_NAME} PROPERTIES VERSION ${_LIB_VERSION_}) ## Link libraries ############################################################## -PKG_CHECK_MODULES(YACA_DEPS REQUIRED openssl capi-base-common) +PKG_CHECK_MODULES(YACA_DEPS REQUIRED openssl) + +PKG_CHECK_MODULES(CAPI_BASE_COMMON capi-base-common) +IF (CAPI_BASE_COMMON_FOUND) + ADD_DEFINITIONS(-DCAPI_BASE_COMMON_PRESENT) + INCLUDE_DIRECTORIES(SYSTEM ${CAPI_BASE_COMMON_INCLUDE_DIRS}) +ENDIF() FIND_PACKAGE (Threads) |