/**
* @file yaca_crypto.h
+ *
* @brief Non crypto related functions.
*/
-#ifndef YACA_CRYPTO_H
-#define YACA_CRYPTO_H
+#ifndef __TIZEN_CORE_YACA_CRYPTO_H__
+#define __TIZEN_CORE_YACA_CRYPTO_H__
#include <stddef.h>
/**
* @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.
+ *
* @since_tizen 3.0
- * @return #YACA_ERROR_NONE on success,
- * negative on error
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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().
+ *
* @since_tizen 3.0
+ *
* @see yaca_initialize()
*/
void yaca_cleanup(void);
/**
* @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)
* @param[out] memory Allocated memory
- * @return #YACA_ERROR_NONE on success,
- * negative on error
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_malloc(size_t size,
+ void **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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_zalloc(size_t size,
+ void **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)
- * @param[in,out] memory Memory to be reallocated
- * @return #YACA_ERROR_NONE on success,
- * negative on error
+ * @param[in,out] memory Memory to be reallocated
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+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.
+ *
* @since_tizen 3.0
+ *
* @param[in] memory Pointer to the memory to be freed
+ *
* @see yaca_malloc()
* @see yaca_zalloc()
* @see yaca_realloc()
/**
- * @brief Safely compares first @a len bytes of two buffers.
+ * @brief Compares @a len bytes of two buffers safely.
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_memcmp(const void *first,
+ const void *second,
+ size_t len);
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+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.
+ *
* @since_tizen 3.0
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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.
* 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
* 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.
+ *
* @since_tizen 3.0
+ *
* @param[in,out] ctx Crypto context
+ *
* @see #yaca_context_h
*/
void yaca_context_destroy(yaca_context_h ctx);
#endif
-#endif /* YACA_CRYPTO_H */
+#endif /* __TIZEN_CORE_YACA_CRYPTO_H__ */
/**
* @file yaca_digest.h
+ *
* @brief Advanced API for the message digests.
*/
-#ifndef YACA_DIGEST_H
-#define YACA_DIGEST_H
+#ifndef __TIZEN_CORE_YACA_DIGEST_H__
+#define __TIZEN_CORE_YACA_DIGEST_H__
#include <stddef.h>
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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()
* @see yaca_context_destroy()
*/
-int yaca_digest_initialize(yaca_context_h *ctx, yaca_digest_algorithm_e algo);
+int yaca_digest_initialize(yaca_context_h *ctx,
+ yaca_digest_algorithm_e algo);
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_digest_update(yaca_context_h ctx,
+ const char *message,
+ size_t message_len);
/**
* @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.
+ * @remarks The @a digest buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] digest_len Length of the digest (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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()
#endif
-#endif /* YACA_DIGEST_H */
+#endif /* __TIZEN_CORE_YACA_DIGEST_H__ */
/**
* @file yaca_encrypt.h
+ *
* @brief Advanced API for the symmetric encryption.
*/
-#ifndef YACA_ENCRYPT_H
-#define YACA_ENCRYPT_H
+#ifndef __TIZEN_CORE_YACA_ENCRYPT_H__
+#define __TIZEN_CORE_YACA_ENCRYPT_H__
#include <stddef.h>
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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 not
* divisible by 8)
* @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.
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
+ * @remarks The @a ciphertext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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[out] ciphertext_len Length of the encrypted data (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
* @remarks Skipping yaca_encrypt_update() and calling only yaca_encrypt_finalize() will produce an encryption of an empty message.
+ * @remarks The @a ciphertext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] ciphertext_len Length of the final piece (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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 a 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
+ * @remarks The @a plaintext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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[out] plaintext_len Length of the decrypted data (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
* @remarks Skipping yaca_decrypt_update() and calling only yaca_decrypt_finalize() will produce a decryption of an empty ciphertext.
+ * @remarks The @a plaintext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] plaintext_len Length of the final piece (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
/**
#endif
-#endif /* YACA_ENCRYPT_H */
+#endif /* __TIZEN_CORE_YACA_ENCRYPT_H__ */
*/
-#ifndef YACA_ERROR_H
-#define YACA_ERROR_H
+#ifndef __TIZEN_CORE_YACA_ERROR_H__
+#define __TIZEN_CORE_YACA_ERROR_H__
#include <tizen.h>
/**
* @brief Enumeration for YACA error values.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /** Successful */
- YACA_ERROR_NONE = TIZEN_ERROR_NONE,
- /** Invalid function parameter */
- YACA_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
- /** Out of memory */
- YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,
-
- /** Internal error */
- YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01,
- /** Data mismatch */
- YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02,
- /** Invalid password */
- YACA_ERROR_INVALID_PASSWORD = TIZEN_ERROR_YACA | 0x03
+ YACA_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
+ YACA_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid function parameter */
+ YACA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
+
+ YACA_ERROR_INTERNAL = TIZEN_ERROR_YACA | 0x01, /**< Internal error */
+ YACA_ERROR_DATA_MISMATCH = TIZEN_ERROR_YACA | 0x02, /**< Data mismatch */
+ YACA_ERROR_INVALID_PASSWORD = TIZEN_ERROR_YACA | 0x03 /**< Invalid password */
} yaca_error_e;
#endif
-#endif /* YACA_ERROR_H */
+#endif /* __TIZEN_CORE_YACA_ERROR_H__ */
/**
* @file yaca_key.h
+ *
* @brief Advanced API for the key and Initialization Vector handling.
*/
-#ifndef YACA_KEY_H
-#define YACA_KEY_H
+#ifndef __TIZEN_CORE_YACA_KEY_H__
+#define __TIZEN_CORE_YACA_KEY_H__
#include <stddef.h>
/**
* @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.
+ *
* @since_tizen 3.0
- * @param[in] key Key which type we return
+ *
+ * @param[in] key Key which type will be returned
* @param[out] key_type Key type
- * @return #YACA_ERROR_NONE on success,
- * negative on error
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_key_get_type(const yaca_key_h key,
+ yaca_key_type_e *key_type);
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_key_get_bit_length(const yaca_key_h key,
+ size_t *key_bit_len);
/**
* @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 Everywhere where either a key (of any type) or an asymmetric key is referred to
+ * in the documentation of this function the 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.
+ * 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 If the key is encrypted the algorithm will be autodetected and password will be used.
+ * If it's unknown 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 format is detected as an unsupported encryption and
+ * password was passed a #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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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 Everywhere where either a key (of any type) or an asymmetric key is referred to
+ * in the documentation of this function the 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).
+ * (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
+ * - #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
* @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.
+ * @remarks The @a data parameter must be freed with yaca_free().
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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).
+ *
* @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:
- * - SYMMETRIC/IV: >= 8bits
- * - DES: 64, 128 or 192bits
- * - RSA: length >= 512bits
- * - DSA: length >= 1024bits, multiple of 64
+ * - SYMMETRIC/IV: >= 8bits,
+ * - DES: 64, 128 or 192bits,
+ * - RSA: length >= 512bits,
+ * - DSA: length >= 1024bits, 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 has to be >= 512
- * - EC: a value taken from #yaca_key_bit_length_ec_e
+ * where prime_length_in_bits has to be >= 512,
+ * - 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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 divisible 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.
+ *
* @since_tizen 3.0
+ *
* @remarks This function is used to generate private asymmetric keys
* based on pre-generated parameters.
* @remarks This function does not support RSA keys, as it's not possible
* to extract parameters from them.
* @remarks The @a prv_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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+int yaca_key_generate_from_parameters(const yaca_key_h params,
+ yaca_key_h *prv_key);
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
+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.
+ *
* @since_tizen 3.0
+ *
* @remarks The @a params should be released using yaca_key_destroy().
* @remarks This function does not support RSA keys.
+ *
* @param[in] key A key to extract the parameters from
* @param[out] params Extracted parameters
- * @return #YACA_ERROR_NONE on success,
- * negative on error
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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()
* @see yaca_key_destroy()
*/
-int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params);
+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.
+ *
* @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 Both the keys passed should be of DH or EC type.
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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] 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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).
+ *
* @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] 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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 divisible 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 Releases the key created by the library. Passing YACA_KEY_NULL is allowed.
+ * @brief Releases the key created by the library.
+ *
* @since_tizen 3.0
+ *
+ * @remarks Passing YACA_KEY_NULL is allowed.
+ *
* @param[in,out] key Key to be released
+ *
* @see yaca_key_import()
* @see yaca_key_export()
* @see yaca_key_generate()
#endif
-#endif /* YACA_KEY_H */
+#endif /* __TIZEN_CORE_YACA_KEY_H__ */
/**
* @file yaca_rsa.h
+ *
* @brief Advanced API for low-level RSA operations.
*/
-#ifndef YACA_RSA_H
-#define YACA_RSA_H
+#ifndef __TIZEN_CORE_YACA_RSA_H__
+#define __TIZEN_CORE_YACA_RSA_H__
#include <stddef.h>
/**
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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).
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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).
+ *
* @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.
+ * @remarks For key generation functions see yaca_key.h header file.
+ *
* @param[in] padding Padding method
- * @param[in] prv_key Private RSA key (see yaca_key.h for key generation functions)
+ * @param[in] prv_key Private RSA key
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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).
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
/**
#endif
-#endif /* YACA_RSA_H */
+#endif /* __TIZEN_CORE_YACA_RSA_H__ */
/**
* @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).
*/
-#ifndef YACA_SEAL_H
-#define YACA_SEAL_H
+#ifndef __TIZEN_CORE_YACA_SEAL_H__
+#define __TIZEN_CORE_YACA_SEAL_H__
#include <stddef.h>
/**
* @brief Initializes an asymmetric encryption context and generates symmetric key and Initialization Vector.
+ *
* @since_tizen 3.0
+ *
* @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 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().
+ * @remarks The @a sym_key is encrypted with peer's public key.
+ *
* @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
+ * @param[out] sym_key Generated symmetric key
+ * @param[out] iv Generated Initialization Vector
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
+ * @remarks The @a ciphertext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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[out] ciphertext_len Length of the encrypted data (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
* @remarks Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an
* encryption of an empty message.
+ * @remarks The @a ciphertext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] ciphertext_len Length of the final piece (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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] 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
+ * @remarks The @a plaintext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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[out] plaintext_len Length of the decrypted data (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
* @remarks Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a
* decryption of an empty ciphertext.
+ * @remarks The @a plaintext buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] plaintext_len Length of the final piece (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
/**
#endif
-#endif /* YACA_SEAL_H */
+#endif /* __TIZEN_CORE_YACA_SEAL_H__ */
/**
* @file yaca_sign.h
+ *
* @brief Advanced API for the integrity handling - HMAC, CMAC and digital signature.
*/
-#ifndef YACA_SIGN_H
-#define YACA_SIGN_H
+#ifndef __TIZEN_CORE_YACA_SIGN_H__
+#define __TIZEN_CORE_YACA_SIGN_H__
#include <stddef.h>
/**
* @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 use of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited.
+ * @remarks The use 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().
+ * @remarks The @a prv_key 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[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
+ * @param[in] prv_key Private key that will be used
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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().
+ * @remarks The @a sym_key supported key types:
+ * - #YACA_KEY_TYPE_SYMMETRIC,
+ * - #YACA_KEY_TYPE_DES.
+ *
* @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
+ * @param[in] sym_key Symmetric key that will be used
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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().
+ * @remarks The @a sym_key supported key types:
+ * - #YACA_KEY_TYPE_SYMMETRIC,
+ * - #YACA_KEY_TYPE_DES.
+ *
* @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
+ * @param[in] sym_key Symmetric key that will be used
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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
* @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.
+ *
* @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.
+ * @remarks The @a signature buffer must be allocated by client (see yaca_context_get_output_length()).
+ *
* @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
+ * @param[out] signature_len Length of the MAC or the signature (the number of returned written bytes)
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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().
+ * @remarks The @a pub_key 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[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
+ * @param[in] pub_key Public key that will be used
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
/**
#endif
-#endif /* YACA_SIGN_H */
+#endif /* __TIZEN_CORE_YACA_SIGN_H__ */
/**
* @file yaca_simple.h
+ *
* @brief Simple API.
+ *
* @details This is simple API.
* Design constraints:
* - All operations are single-shot (no streaming possible)
*/
-#ifndef YACA_SIMPLE_H
-#define YACA_SIMPLE_H
+#ifndef __TIZEN_CORE_YACA_SIMPLE_H__
+#define __TIZEN_CORE_YACA_SIMPLE_H__
#include <stddef.h>
/**
* @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)
+ * @remarks If unsure which encrytpion algorithm to use in @a algo, select #YACA_ENCRYPT_AES.
+ * @remarks If unsure which chaining mode to use in @a bcm, select #YACA_BCM_CBC.
+ * @remarks For key generation functions see yaca_key.h header file.
+ *
+ * @param[in] algo Encryption algorithm
+ * @param[in] bcm Chaining mode
+ * @param[in] sym_key Symmetric encryption key
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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] 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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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)
+ * @remarks If unsure which digest algorithm to use in @a algo, select #YACA_DIGEST_SHA256.
+ *
+ * @param[in] algo Digest algorithm
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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.
+ * @remarks The @a prv_key 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] 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] prv_key Private key that will be used
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
+ *
* @remarks The @a message can be NULL but then @a message_len must be 0.
+ * @remarks The @a pub_key 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] 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] pub_key Public key that will be used
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @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.
+ * @remarks The @a sym_key supported key types:
+ * - #YACA_KEY_TYPE_SYMMETRIC,
+ * - #YACA_KEY_TYPE_DES.
+ *
* @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] sym_key Key that will be used
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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.
+ *
* @since_tizen 3.0
- * @remarks For verification, calculate message CMAC and compare with received MAC using yaca_memcmp().
+ *
+ * @remarks For verification, calculate message CMAC and compare it 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.
+ * @remarks The @a sym_key supported key types:
+ * - #YACA_KEY_TYPE_SYMMETRIC,
+ * - #YACA_KEY_TYPE_DES.
+ *
* @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] sym_key Key that will be used
* @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
+ *
+ * @return @c 0 on success, otherwise a negative error value
* @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);
/**
#endif
-#endif /* YACA_SIMPLE_H */
+#endif /* __TIZEN_CORE_YACA_SIMPLE_H__ */
*/
-#ifndef YACA_TYPES_H
-#define YACA_TYPES_H
+#ifndef __TIZEN_CORE_YACA_TYPES_H__
+#define __TIZEN_CORE_YACA_TYPES_H__
#ifdef __cplusplus
/* 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
* 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.
/**
* @brief The context handle.
+ *
* @since_tizen 3.0
*/
typedef struct yaca_context_s *yaca_context_h;
/**
* @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 for formats YACA key.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /** Key is either PKCS#1 for RSA or SSLeay for DSA, also use this option for symmetric */
- YACA_KEY_FORMAT_DEFAULT,
- /** Key is in PKCS#8, can only be used for asymmetric private keys */
- YACA_KEY_FORMAT_PKCS8
+ YACA_KEY_FORMAT_DEFAULT, /**< Key is either PKCS#1 for RSA or SSLeay for DSA, also use this option for symmetric */
+ YACA_KEY_FORMAT_PKCS8 /**< Key is in PKCS#8, can only be used for asymmetric private keys */
} yaca_key_format_e;
/**
* @brief Enumeration for formats YACA key file.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /** Key file is in raw binary format, used for symmetric keys */
- YACA_KEY_FILE_FORMAT_RAW,
- /** Key file is encoded in ASCII-base64, used for symmetric keys */
- YACA_KEY_FILE_FORMAT_BASE64,
- /** Key file is in PEM file format, used for asymmetric keys */
- YACA_KEY_FILE_FORMAT_PEM,
- /** Key file is in DER file format, used for asymmetric keys */
- YACA_KEY_FILE_FORMAT_DER
+ YACA_KEY_FILE_FORMAT_RAW, /**< Key file is in raw binary format, used for symmetric keys */
+ YACA_KEY_FILE_FORMAT_BASE64, /**< Key file is encoded in ASCII-base64, used for symmetric keys */
+ YACA_KEY_FILE_FORMAT_PEM, /**< Key file is in PEM file format, used for asymmetric keys */
+ YACA_KEY_FILE_FORMAT_DER /**< Key file is in DER file format, used for asymmetric keys */
} yaca_key_file_format_e;
/**
* @brief Enumeration for YACA key types, Initialization Vector is considered as key.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /** Generic symmetric cipher KEY */
- YACA_KEY_TYPE_SYMMETRIC,
- /** DES* key - must be handled differently because of parity bits */
- YACA_KEY_TYPE_DES,
- /** Initialization Vector for symmetric algorithms */
- YACA_KEY_TYPE_IV,
-
- /** RSA public key */
- YACA_KEY_TYPE_RSA_PUB,
- /** RSA private key */
- YACA_KEY_TYPE_RSA_PRIV,
-
- /** Digital Signature Algorithm public key */
- YACA_KEY_TYPE_DSA_PUB,
- /** Digital Signature Algorithm private key */
- YACA_KEY_TYPE_DSA_PRIV,
-
- /** Diffie-Hellman public key */
- YACA_KEY_TYPE_DH_PUB,
- /** Diffie-Hellman private key */
- YACA_KEY_TYPE_DH_PRIV,
-
- /** Elliptic Curve public key (for DSA and DH) */
- YACA_KEY_TYPE_EC_PUB,
- /** Elliptic Curve private key (for DSA and DH) */
- YACA_KEY_TYPE_EC_PRIV,
-
- /** Digital Signature Algorithm parameters */
- YACA_KEY_TYPE_DSA_PARAMS,
- /** Diffie-Hellman parameters */
- YACA_KEY_TYPE_DH_PARAMS,
- /** Elliptic Curve parameters */
- YACA_KEY_TYPE_EC_PARAMS
+ YACA_KEY_TYPE_SYMMETRIC, /**< Generic symmetric cipher KEY */
+ YACA_KEY_TYPE_DES, /**< DES* key - must be handled differently because of parity bits */
+ YACA_KEY_TYPE_IV, /**< Initialization Vector for symmetric algorithms */
+
+ YACA_KEY_TYPE_RSA_PUB, /**< RSA public key */
+ YACA_KEY_TYPE_RSA_PRIV, /**< RSA private key */
+
+ YACA_KEY_TYPE_DSA_PUB, /**< Digital Signature Algorithm public key */
+ YACA_KEY_TYPE_DSA_PRIV, /**< Digital Signature Algorithm private key */
+
+ YACA_KEY_TYPE_DH_PUB, /**< Diffie-Hellman public key */
+ YACA_KEY_TYPE_DH_PRIV, /**< Diffie-Hellman private key */
+
+ YACA_KEY_TYPE_EC_PUB, /**< Elliptic Curve public key (for DSA and DH) */
+ YACA_KEY_TYPE_EC_PRIV, /**< Elliptic Curve private key (for DSA and DH) */
+
+ YACA_KEY_TYPE_DSA_PARAMS, /**< Digital Signature Algorithm parameters */
+ YACA_KEY_TYPE_DH_PARAMS, /**< Diffie-Hellman parameters */
+ YACA_KEY_TYPE_EC_PARAMS /**< Elliptic Curve parameters */
} yaca_key_type_e;
* @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 {
- /** 64 bits */
- YACA_KEY_LENGTH_IV_64BIT = 64,
- /** 128 bits */
- YACA_KEY_LENGTH_IV_128BIT = 128,
- /** 8 bits */
- YACA_KEY_LENGTH_UNSAFE_8BIT = 8,
- /** 40 bits */
- YACA_KEY_LENGTH_UNSAFE_40BIT = 40,
- /** 64 bits */
- YACA_KEY_LENGTH_UNSAFE_64BIT = 64,
- /** 80 bits */
- YACA_KEY_LENGTH_UNSAFE_80BIT = 80,
- /** 128 bits */
- YACA_KEY_LENGTH_UNSAFE_128BIT = 128,
- /** 192 bits */
- YACA_KEY_LENGTH_192BIT = 192,
- /** 256 bits */
- YACA_KEY_LENGTH_256BIT = 256,
- /** 512 bits */
- YACA_KEY_LENGTH_512BIT = 512,
- /** 1024 bits */
- YACA_KEY_LENGTH_1024BIT = 1024,
- /** 2048 bits */
- YACA_KEY_LENGTH_2048BIT = 2048,
- /** 3072 bits */
- YACA_KEY_LENGTH_3072BIT = 3072,
- /** 4096 bits */
- YACA_KEY_LENGTH_4096BIT = 4096
+ YACA_KEY_LENGTH_IV_64BIT = 64, /**< 64 bits */
+ YACA_KEY_LENGTH_IV_128BIT = 128, /**< 128 bits */
+ YACA_KEY_LENGTH_UNSAFE_8BIT = 8, /**< 8 bits */
+ YACA_KEY_LENGTH_UNSAFE_40BIT = 40, /**< 40 bits */
+ YACA_KEY_LENGTH_UNSAFE_64BIT = 64, /**< 64 bits */
+ YACA_KEY_LENGTH_UNSAFE_80BIT = 80, /**< 80 bits */
+ YACA_KEY_LENGTH_UNSAFE_128BIT = 128, /**< 128 bits */
+ YACA_KEY_LENGTH_192BIT = 192, /**< 192 bits */
+ YACA_KEY_LENGTH_256BIT = 256, /**< 256 bits */
+ YACA_KEY_LENGTH_512BIT = 512, /**< 512 bits */
+ YACA_KEY_LENGTH_1024BIT = 1024, /**< 1024 bits */
+ YACA_KEY_LENGTH_2048BIT = 2048, /**< 2048 bits */
+ YACA_KEY_LENGTH_3072BIT = 3072, /**< 3072 bits */
+ YACA_KEY_LENGTH_4096BIT = 4096 /**< 4096 bits */
} yaca_key_bit_length_e;
+
/**
* @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 {
- /** Elliptic curve prime192v1 */
- YACA_KEY_LENGTH_EC_PRIME192V1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_PRIME | YACA_KEYLEN_COMPONENT_EC_V | YACA_KEYLEN_COMPONENT_EC_1 | 192U,
- /** Elliptic curve prime256v1 */
- YACA_KEY_LENGTH_EC_PRIME256V1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_PRIME | YACA_KEYLEN_COMPONENT_EC_V | YACA_KEYLEN_COMPONENT_EC_1 | 256U,
- /** Elliptic curve secp256k1 */
- YACA_KEY_LENGTH_EC_SECP256K1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_K | YACA_KEYLEN_COMPONENT_EC_1 | 256U,
- /** Elliptic curve secp384r1 */
- YACA_KEY_LENGTH_EC_SECP384R1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_R | YACA_KEYLEN_COMPONENT_EC_1 | 384U,
- /** Elliptic curve secp521r1 */
- YACA_KEY_LENGTH_EC_SECP521R1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_R | YACA_KEYLEN_COMPONENT_EC_1 | 521U
+ /** Elliptic curve prime192v1 */
+ YACA_KEY_LENGTH_EC_PRIME192V1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_PRIME | YACA_KEYLEN_COMPONENT_EC_V | YACA_KEYLEN_COMPONENT_EC_1 | 192U,
+ /** Elliptic curve prime256v1 */
+ YACA_KEY_LENGTH_EC_PRIME256V1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_PRIME | YACA_KEYLEN_COMPONENT_EC_V | YACA_KEYLEN_COMPONENT_EC_1 | 256U,
+ /** Elliptic curve secp256k1 */
+ YACA_KEY_LENGTH_EC_SECP256K1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_K | YACA_KEYLEN_COMPONENT_EC_1 | 256U,
+ /** Elliptic curve secp384r1 */
+ YACA_KEY_LENGTH_EC_SECP384R1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_R | YACA_KEYLEN_COMPONENT_EC_1 | 384U,
+ /** Elliptic curve secp521r1 */
+ YACA_KEY_LENGTH_EC_SECP521R1 = YACA_KEYLEN_COMPONENT_TYPE_EC | YACA_KEYLEN_COMPONENT_EC_SECP | YACA_KEYLEN_COMPONENT_EC_R | YACA_KEYLEN_COMPONENT_EC_1 | 521U
} yaca_key_bit_length_ec_e;
+
/**
* @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.
+ *
* @since_tizen 3.0
*/
#define YACA_KEY_LENGTH_DH_GENERATOR_2 (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_2)
+
+
/**
* @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.
+ *
* @since_tizen 3.0
*/
#define YACA_KEY_LENGTH_DH_GENERATOR_5 (YACA_KEYLEN_COMPONENT_TYPE_DH | YACA_KEYLEN_COMPONENT_DH_GEN_5)
+
/**
* @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 {
- /** RFC 5114 DH parameters 1024_160 */
- YACA_KEY_LENGTH_DH_RFC_1024_160 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_160 | 1024U,
- /** RFC 5114 DH parameters 2048_224 */
- YACA_KEY_LENGTH_DH_RFC_2048_224 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_224 | 2048U,
- /** RFC 5114 DH parameters 2048_256 */
- YACA_KEY_LENGTH_DH_RFC_2048_256 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_256 | 2048U
+ /** RFC 5114 DH parameters 1024_160 */
+ YACA_KEY_LENGTH_DH_RFC_1024_160 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_160 | 1024U,
+ /** RFC 5114 DH parameters 2048_224 */
+ YACA_KEY_LENGTH_DH_RFC_2048_224 = YACA_KEYLEN_COMPONENT_TYPE_DH_RFC | YACA_KEYLEN_COMPONENT_DH_RFC_224 | 2048U,
+ /** RFC 5114 DH parameters 2048_256 */
+ 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 for YACA message digest algorithms.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /** Message digest algorithm MD5 */
- YACA_DIGEST_MD5,
- /** Message digest algorithm SHA1 */
- YACA_DIGEST_SHA1,
- /** Message digest algorithm SHA2, 224bit */
- YACA_DIGEST_SHA224,
- /** Message digest algorithm SHA2, 256bit */
- YACA_DIGEST_SHA256,
- /** Message digest algorithm SHA2, 384bit */
- YACA_DIGEST_SHA384,
- /** Message digest algorithm SHA2, 512bit */
- YACA_DIGEST_SHA512,
+ YACA_DIGEST_MD5, /**< Message digest algorithm MD5 */
+ YACA_DIGEST_SHA1, /**< Message digest algorithm SHA1 */
+ YACA_DIGEST_SHA224, /**< Message digest algorithm SHA2, 224bit */
+ YACA_DIGEST_SHA256, /**< Message digest algorithm SHA2, 256bit */
+ YACA_DIGEST_SHA384, /**< Message digest algorithm SHA2, 384bit */
+ YACA_DIGEST_SHA512, /**< Message digest algorithm SHA2, 512bit */
} yaca_digest_algorithm_e;
/**
* @brief Enumeration for YACA symmetric encryption algorithms.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /**
- * AES encryption.
- * - Supported key lengths: @c 128, @c 192 and @c 256 bits.
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_CFB1,\n
- * #YACA_BCM_CFB8,\n
- * #YACA_BCM_ECB,\n
- * #YACA_BCM_GCM,\n
- * #YACA_BCM_CCM,\n
- * #YACA_BCM_CTR,\n
- * #YACA_BCM_WRAP
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- */
- YACA_ENCRYPT_AES = 0,
-
- /**
- * DES encryption.
- * - Supported key lengths: @c 64 bits.
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_CFB1,\n
- * #YACA_BCM_CFB8,\n
- * #YACA_BCM_ECB
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- */
- YACA_ENCRYPT_UNSAFE_DES,
-
- /**
- * 3DES 2-key encryption.
- * - Supported key lengths: @c 128 bits.
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_ECB
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- * - Use double DES keys to perform corresponding 2-key 3DES encryption.
- */
- YACA_ENCRYPT_UNSAFE_3DES_2TDEA,
-
- /**
- * 3DES 3-key encryption.
- * - Supported key lengths: @c 192 bits.
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_CFB1,\n
- * #YACA_BCM_CFB8,\n
- * #YACA_BCM_ECB,\n
- * #YACA_BCM_WRAP
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- * - Use triple DES keys to perform corresponding 3-key 3DES encryption.
- */
- YACA_ENCRYPT_3DES_3TDEA,
-
- /**
- * RC2 encryption.
- * This is a variable key length cipher.
- * - Supported key lengths: 8-1024 bits in steps of 8 bits.
- * - Effective key bits property by default equals to 128 bits.\n
- * Effective key bits can be set using yaca_context_set_property() and
- * #YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS.\n
- * It can be set after yaca_encrypt_initialize() / yaca_decrypt_initialize(), and before
- * yaca_encrypt_update() / yaca_decrypt_update() in encryption / decryption operation.
- *
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_ECB
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- */
- YACA_ENCRYPT_UNSAFE_RC2,
-
- /**
- * RC4 encryption.
- * This is a variable key length cipher.
- * - Supported key lengths: 40–2048 bits in steps of 8 bits.
- * - Initialization Vector is not used.
- * - This cipher doesn't support block cipher modes, use #YACA_BCM_NONE instead.
- */
- YACA_ENCRYPT_UNSAFE_RC4,
-
- /**
- * CAST5 encryption.
- * This is a variable key length cipher.
- * - Supported key lengths: 40-128 bits in steps of 8 bits.
- * - Supported block cipher modes:\n
- * #YACA_BCM_CBC,\n
- * #YACA_BCM_OFB,\n
- * #YACA_BCM_CFB,\n
- * #YACA_BCM_ECB
- * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
- */
- YACA_ENCRYPT_CAST5,
+ /**
+ * AES encryption.
+ * - Supported key lengths: @c 128, @c 192 and @c 256 bits.
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_CFB1,\n
+ * #YACA_BCM_CFB8,\n
+ * #YACA_BCM_ECB,\n
+ * #YACA_BCM_GCM,\n
+ * #YACA_BCM_CCM,\n
+ * #YACA_BCM_CTR,\n
+ * #YACA_BCM_WRAP
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ */
+ YACA_ENCRYPT_AES = 0,
+
+ /**
+ * DES encryption.
+ * - Supported key lengths: @c 64 bits.
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_CFB1,\n
+ * #YACA_BCM_CFB8,\n
+ * #YACA_BCM_ECB
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ */
+ YACA_ENCRYPT_UNSAFE_DES,
+
+ /**
+ * 3DES 2-key encryption.
+ * - Supported key lengths: @c 128 bits.
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_ECB
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ * - Use double DES keys to perform corresponding 2-key 3DES encryption.
+ */
+ YACA_ENCRYPT_UNSAFE_3DES_2TDEA,
+
+ /**
+ * 3DES 3-key encryption.
+ * - Supported key lengths: @c 192 bits.
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_CFB1,\n
+ * #YACA_BCM_CFB8,\n
+ * #YACA_BCM_ECB,\n
+ * #YACA_BCM_WRAP
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ * - Use triple DES keys to perform corresponding 3-key 3DES encryption.
+ */
+ YACA_ENCRYPT_3DES_3TDEA,
+
+ /**
+ * RC2 encryption.
+ * This is a variable key length cipher.
+ * - Supported key lengths: 8-1024 bits in steps of 8 bits.
+ * - Effective key bits property by default equals to 128 bits.\n
+ * Effective key bits can be set using yaca_context_set_property() and
+ * #YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS.\n
+ * It can be set after yaca_encrypt_initialize() / yaca_decrypt_initialize(), and before
+ * yaca_encrypt_update() / yaca_decrypt_update() in encryption / decryption operation.
+ *
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_ECB
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ */
+ YACA_ENCRYPT_UNSAFE_RC2,
+
+ /**
+ * RC4 encryption.
+ * This is a variable key length cipher.
+ * - Supported key lengths: 40–2048 bits in steps of 8 bits.
+ * - Initialization Vector is not used.
+ * - This cipher doesn't support block cipher modes, use #YACA_BCM_NONE instead.
+ */
+ YACA_ENCRYPT_UNSAFE_RC4,
+
+ /**
+ * CAST5 encryption.
+ * This is a variable key length cipher.
+ * - Supported key lengths: 40-128 bits in steps of 8 bits.
+ * - Supported block cipher modes:\n
+ * #YACA_BCM_CBC,\n
+ * #YACA_BCM_OFB,\n
+ * #YACA_BCM_CFB,\n
+ * #YACA_BCM_ECB
+ * - see #yaca_block_cipher_mode_e for details on additional properties (mandatory).
+ */
+ YACA_ENCRYPT_CAST5,
} yaca_encrypt_algorithm_e;
/**
* @brief Enumeration for YACA chaining modes for block ciphers.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /**
- * Used when algorithm doesn't support block ciphers modes.
- * Initialization Vector is not used.
- */
- YACA_BCM_NONE,
-
- /**
- * 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,
- * then the total length of data passed until *_finalize() MUST be a multiple of block size.
- * In case of encrypt/seal #YACA_PROPERTY_PADDING can be set at the
- * latest before the *_finalize() call. In case of decrypt/open
- * it can be set at the latest before the *_update() call.
- */
- YACA_BCM_ECB,
-
- /**
- * CTR block cipher mode.
- * 128-bit Initialization Vector for AES,
- * 64-bit for other algorithms is mandatory.
- */
- YACA_BCM_CTR,
-
- /**
- * 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,
- * then the total length of data passed until *_finalize() MUST be a multiple of block size.
- * In case of encrypt/seal #YACA_PROPERTY_PADDING can be set at the
- * latest before the *_finalize() call. In case of decrypt/open
- * it can be set at the latest before the *_update() call.
- */
- YACA_BCM_CBC,
-
- /**
- * 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
- * (16 bytes tag by default).\n
- * 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
- * - #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
- * - #YACA_PROPERTY_GCM_AAD = additional authentication data (optional)\n
- * AAD length can have any positive value.\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
- * .
- * @see yaca_context_set_property()
- * @see yaca_context_get_property()
- */
- YACA_BCM_GCM,
-
- /**
- * Default CFB block cipher mode.
- * 128-bit Initialization Vector for AES,
- * 64-bit for other algorithms is mandatory.
- */
- YACA_BCM_CFB,
-
- /**
- * 1 bit CFB block cipher mode.
- * 128-bit Initialization Vector for AES,
- * 64-bit for other algorithms is mandatory.
- */
- YACA_BCM_CFB1,
-
- /**
- * 8 bits CFB block cipher mode.
- * 128-bit Initialization Vector for AES,
- * 64-bit for other algorithms is mandatory.
- */
- YACA_BCM_CFB8,
-
- /**
- * OFB block cipher mode.
- * 128-bit Initialization Vector for AES,
- * 64-bit for other algorithms is mandatory.
- */
- YACA_BCM_OFB,
-
- /**
- * 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
- * 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
- * - #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
- * - #YACA_PROPERTY_CCM_AAD = additional authentication data (optional)\n
- * AAD length can have any positive value.\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
- * 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_encrypt_update() / yaca_seal_update() once for AAD (if used)
- * and once for the plaintext.\n
- * You can only call yaca_decrypt_update() / yaca_open_update() once for AAD (if used)
- * 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
+ /**
+ * Used when algorithm doesn't support block ciphers modes.
+ * Initialization Vector is not used.
+ */
+ YACA_BCM_NONE,
+
+ /**
+ * 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
+ * then the total length of data passed until *_finalize() MUST be a multiple of block size.
+ * In case of encrypt/seal #YACA_PROPERTY_PADDING can be set at the
+ * latest before the *_finalize() call. In case of decrypt/open
+ * it can be set at the latest before the *_update() call.
+ */
+ YACA_BCM_ECB,
+
+ /**
+ * CTR block cipher mode.
+ * 128-bit Initialization Vector for AES,
+ * 64-bit for other algorithms is mandatory.
+ */
+ YACA_BCM_CTR,
+
+ /**
+ * 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,
+ * then the total length of data passed until *_finalize() MUST be a multiple of block size.
+ * In case of encrypt/seal #YACA_PROPERTY_PADDING can be set at the
+ * latest before the *_finalize() call. In case of decrypt/open
+ * it can be set at the latest before the *_update() call.
+ */
+ YACA_BCM_CBC,
+
+ /**
+ * 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
+ * (16 bytes tag by default).\n
+ * 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
+ * - #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
+ * - #YACA_PROPERTY_GCM_AAD = additional authentication data (optional)\n
+ * AAD length can have any positive value.\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
+ *
+ * @see yaca_context_set_property()
+ * @see yaca_context_get_property()
+ */
+ YACA_BCM_GCM,
+
+ /**
+ * Default CFB block cipher mode.
+ * 128-bit Initialization Vector for AES,
+ * 64-bit for other algorithms is mandatory.
+ */
+ YACA_BCM_CFB,
+
+ /**
+ * 1 bit CFB block cipher mode.
+ * 128-bit Initialization Vector for AES,
+ * 64-bit for other algorithms is mandatory.
+ */
+ YACA_BCM_CFB1,
+
+ /**
+ * 8 bits CFB block cipher mode.
+ * 128-bit Initialization Vector for AES,
+ * 64-bit for other algorithms is mandatory.
+ */
+ YACA_BCM_CFB8,
+
+ /**
+ * OFB block cipher mode.
+ * 128-bit Initialization Vector for AES,
+ * 64-bit for other algorithms is mandatory.
+ */
+ YACA_BCM_OFB,
+
+ /**
+ * 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
+ * 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
+ * - #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
+ * - #YACA_PROPERTY_CCM_AAD = additional authentication data (optional)\n
+ * AAD length can have any positive value.\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
+ * 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_encrypt_update() / yaca_seal_update() once for AAD (if used)
+ * and once for the plaintext.\n
+ * You can only call yaca_decrypt_update() / yaca_open_update() once for AAD (if used)
+ * 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
} yaca_block_cipher_mode_e;
/**
* @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,
-
- /** GCM Additional Authentication Data. Property type is a buffer (e.g. char*) */
- YACA_PROPERTY_GCM_AAD,
- /** GCM Tag. Property type is a buffer (e.g. char*) */
- YACA_PROPERTY_GCM_TAG,
- /** GCM Tag length in bytes. Property type is size_t. */
- YACA_PROPERTY_GCM_TAG_LEN,
-
- /** CCM Additional Authentication Data. Property type is a buffer (e.g. char*) */
- YACA_PROPERTY_CCM_AAD,
- /** CCM Tag. Property type is a buffer (e.g. char*) */
- YACA_PROPERTY_CCM_TAG,
- /** CCM Tag length in bytes. Property type is size_t. */
- YACA_PROPERTY_CCM_TAG_LEN,
-
- /** RC2 effective key bits, 1-1024, 1 bit resolution. Property type is size_t. */
- YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS,
+ /**
+ * 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,
+
+ /** GCM Additional Authentication Data. Property type is a buffer (e.g. char*) */
+ YACA_PROPERTY_GCM_AAD,
+ /** GCM Tag. Property type is a buffer (e.g. char*) */
+ YACA_PROPERTY_GCM_TAG,
+ /** GCM Tag length in bytes. Property type is size_t. */
+ YACA_PROPERTY_GCM_TAG_LEN,
+
+ /** CCM Additional Authentication Data. Property type is a buffer (e.g. char*) */
+ YACA_PROPERTY_CCM_AAD,
+ /** CCM Tag. Property type is a buffer (e.g. char*) */
+ YACA_PROPERTY_CCM_TAG,
+ /** CCM Tag length in bytes. Property type is size_t. */
+ YACA_PROPERTY_CCM_TAG_LEN,
+
+ /** RC2 effective key bits, 1-1024, 1 bit resolution. Property type is size_t. */
+ YACA_PROPERTY_RC2_EFFECTIVE_KEY_BITS,
} yaca_property_e;
+
/**
* @brief Enumeration for YACA paddings.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /**
- * No padding at all. This method assumes that the input data already has a proper length for
- * a given cryptographic operation (e.g. it has been padded by the client). Suitable for
- * symmetric encrypt/decrypt operations as well as low-level RSA operations.
- */
- YACA_PADDING_NONE = 0,
-
- /**
- * X9.31 padding. Suitable for RSA sign/verify operation. Not supported in low-level
- * RSA operations.
- */
- YACA_PADDING_X931,
-
- /**
- * PKCS #1 v1.5 padding. Suitable for RSA sign/verify and low-level RSA operations.
- * For low-level operations the input must be at least 11 bytes shorter than the key length.
- */
- YACA_PADDING_PKCS1,
-
- /**
- * PKCS #1 PSS padding. Suitable for RSA sign/verify operations. Not supported in low-level
- * RSA operations.
- */
- YACA_PADDING_PKCS1_PSS,
-
- /**
- * EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding parameter.
- * Suitable for low-level RSA public_encrypt/private_decrypt operations. For low-level
- * operations the input must be at least 42 bytes shorter than the key length.
- */
- YACA_PADDING_PKCS1_OAEP,
-
- /**
- * Removed in OpenSSL 3.0 and should not be used anymore.
- * For compatibility reason YACA_PADDING_PKCS1_SSLV23 is now equal to YACA_PADDING_PKCS1.
- *
- * PKCS #1 v1.5 padding with an SSL-specific modification that denotes that the party
- * is SSL3 capable. It is used for rollback attack detection in SSLv3. If during decryption it
- * turns out that both parties are using #YACA_PADDING_PKCS1_SSLV23 (both are communicating
- * using SSL2 and both are SSL3 capable) it is treated as a rollback attack and an error is
- * returned. Suitable for low-level RSA public_encrypt/private_decrypt operations. For
- * low-level operations the input must be at least 11 bytes shorter than the key length.
- */
- YACA_PADDING_PKCS1_SSLV23,
-
- /**
- * PKCS #7 padding. Suitable for symmetric encrypt/decrypt operation.
- */
- YACA_PADDING_PKCS7
+ /**
+ * No padding at all. This method assumes that the input data already has a proper length for
+ * a given cryptographic operation (e.g. it has been padded by the client). Suitable for
+ * symmetric encrypt/decrypt operations as well as low-level RSA operations.
+ */
+ YACA_PADDING_NONE = 0,
+
+ /**
+ * X9.31 padding. Suitable for RSA sign/verify operation. Not supported in low-level
+ * RSA operations.
+ */
+ YACA_PADDING_X931,
+
+ /**
+ * PKCS #1 v1.5 padding. Suitable for RSA sign/verify and low-level RSA operations.
+ * For low-level operations the input must be at least 11 bytes shorter than the key length.
+ */
+ YACA_PADDING_PKCS1,
+
+ /**
+ * PKCS #1 PSS padding. Suitable for RSA sign/verify operations. Not supported in low-level
+ * RSA operations.
+ */
+ YACA_PADDING_PKCS1_PSS,
+
+ /**
+ * EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding parameter.
+ * Suitable for low-level RSA public_encrypt/private_decrypt operations. For low-level
+ * operations the input must be at least 42 bytes shorter than the key length.
+ */
+ YACA_PADDING_PKCS1_OAEP,
+
+ /**
+ * Removed in OpenSSL 3.0 and should not be used anymore.
+ * For compatibility reason #YACA_PADDING_PKCS1_SSLV23 is now equal to #YACA_PADDING_PKCS1.
+ *
+ * PKCS #1 v1.5 padding with an SSL-specific modification that denotes that the party
+ * is SSL3 capable. It is used for rollback attack detection in SSLv3. If during decryption it
+ * turns out that both parties are using #YACA_PADDING_PKCS1_SSLV23 (both are communicating
+ * using SSL2 and both are SSL3 capable) it is treated as a rollback attack and an error is
+ * returned. Suitable for low-level RSA public_encrypt/private_decrypt operations. For
+ * low-level operations the input must be at least 11 bytes shorter than the key length.
+ */
+ YACA_PADDING_PKCS1_SSLV23,
+
+ /**
+ * PKCS #7 padding. Suitable for symmetric encrypt/decrypt operation.
+ */
+ YACA_PADDING_PKCS7
} yaca_padding_e;
/**
* @brief Enumeration for YACA key derivation functions.
+ *
* @since_tizen 3.0
*/
typedef enum {
- /**
- * ANSI X9.42 key derivation function,
- * (shared secret derived using Diffie-Helmann key exchange protocol).
- */
- YACA_KDF_X942,
-
- /**
- * ANSI X9.62 key derivation function,
- * (shared secret derived using EC Diffie-Helmann key exchange protocol).
- */
- YACA_KDF_X962,
+ /**
+ * ANSI X9.42 key derivation function,
+ * (shared secret derived using Diffie-Helmann key exchange protocol).
+ */
+ YACA_KDF_X942,
+
+ /**
+ * ANSI X9.62 key derivation function,
+ * (shared secret derived using EC Diffie-Helmann key exchange protocol).
+ */
+ YACA_KDF_X962,
} yaca_kdf_e;
#endif
-#endif /* YACA_TYPES_H */
+#endif /* __TIZEN_CORE_YACA_TYPES_H__ */
* @brief
*/
-#ifndef YACA_DEBUG_H
-#define YACA_DEBUG_H
+#ifndef __TIZEN_CORE_YACA_DEBUG_H__
+#define __TIZEN_CORE_YACA_DEBUG_H__
#include <openssl/err.h>
#endif
-#endif /* YACA_DEBUG_H */
+#endif /* __TIZEN_CORE_YACA_DEBUG_H__ */
projects / platform / core / security / yaca.git / commitdiff