* 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 */
* 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()
*/
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 */
* 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 */
* limitations under the License
*/
+
/**
- * @file yaca_error.h
- * @brief Error enums and defines.
+ * @file yaca_error.h
+ * @brief Error enums and defines.
*/
-#ifdef CAPI_BASE_COMMON_PRESENT
-#include <tizen.h>
-#else
-#include <errno.h>
-#define TIZEN_ERROR_NONE 0
-#define TIZEN_ERROR_INVALID_PARAMETER -EINVAL
-#define TIZEN_ERROR_OUT_OF_MEMORY -ENOMEM
-#endif
#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 */
* 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)
* @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
* @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()
*/
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 */
* 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 */
* 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
* @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
* @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 */
* 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
* @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()
* @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()
* @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
* @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 */
* 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 */
* 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
* 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
* 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
* 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
* 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 {
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 {
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 {
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 {
} 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 {
} 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 {
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 {
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 {
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 {
/**
* 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,
* 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,
/**
* 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
* 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,
* 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
/**
- * @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,
} yaca_property_e;
/**
- * @brief Enumeration of YACA paddings.
- *
+ * @brief Enumeration for YACA paddings.
* @since_tizen 3.0
*/
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 {
YACA_KDF_X962,
} yaca_kdf_e;
+
/**
* @}
*/
+
#ifdef __cplusplus
} /* extern */
#endif
+
#endif /* YACA_TYPES_H */
projects / platform / core / security / yaca.git / commitdiff