diff options
Diffstat (limited to 'api/yaca/yaca_simple.h')
| -rw-r--r-- | api/yaca/yaca_simple.h | 332 |
1 files changed, 134 insertions, 198 deletions
diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index 97a9826..7328c7c 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -16,317 +16,253 @@ * limitations under the License */ + /** - * @file yaca_simple.h - * @brief Simple API. - * - * @details This is simple API. - * Design constraints: - * - All operations are single-shot (no streaming possible) - * - Context is not used - * - Only digest, signatures and symmetric ciphers are supported - * - Disabling PKCS#7 padding for ECB and CBC chaining is not supported - * - Changing the default PKCS#1 padding for sign/verify is not supported - * - GCM and CCM chaining is not supported - * - RC2 effective key bits property is not supported - * - All outputs are allocated by the library + * @file yaca_simple.h + * @brief Simple API. + * @details This is simple API. + * Design constraints: + * - All operations are single-shot (no streaming possible) + * - Context is not used + * - Only digest, signatures and symmetric ciphers are supported + * - Disabling PKCS#7 padding for ECB and CBC chaining is not supported + * - Changing the default PKCS#1 padding for sign/verify is not supported + * - GCM and CCM chaining is not supported + * - RC2 effective key bits property is not supported + * - All outputs are allocated by the library */ + #ifndef YACA_SIMPLE_H #define YACA_SIMPLE_H + #include <stddef.h> #include <yaca_types.h> + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_YACA_SIMPLE_MODULE * @{ */ + /** - * @brief Encrypts data using a symmetric cipher. - * + * @brief Encrypts data using a symmetric cipher. * @since_tizen 3.0 - * - * @remarks yaca_simple_encrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. - * - * @remarks The @a ciphertext should be freed using yaca_free(). - * - * @remarks The @a plaintext can be NULL but then @a plaintext_len must be 0. - * - * @param[in] algo Encryption algorithm (select #YACA_ENCRYPT_AES if unsure) - * @param[in] bcm Chaining mode (select #YACA_BCM_CBC if unsure) - * @param[in] sym_key Symmetric encryption key (see yaca_key.h for key generation functions) - * @param[in] iv Initialization Vector - * @param[in] plaintext Plaintext to be encrypted - * @param[in] plaintext_len Length of the plaintext - * @param[out] ciphertext Encrypted data, will be allocated by the library - * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks yaca_simple_encrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. + * @remarks The @a ciphertext should be freed using yaca_free(). + * @remarks The @a plaintext can be NULL but then @a plaintext_len must be 0. + * @param[in] algo Encryption algorithm (select #YACA_ENCRYPT_AES if unsure) + * @param[in] bcm Chaining mode (select #YACA_BCM_CBC if unsure) + * @param[in] sym_key Symmetric encryption key (see yaca_key.h for key generation functions) + * @param[in] iv Initialization Vector + * @param[in] plaintext Plaintext to be encrypted + * @param[in] plaintext_len Length of the plaintext + * @param[out] ciphertext Encrypted data, will be allocated by the library + * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_simple_decrypt() * @see yaca_free() */ -int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, - yaca_block_cipher_mode_e bcm, - const yaca_key_h sym_key, - const yaca_key_h iv, - const char *plaintext, - size_t plaintext_len, - char **ciphertext, - size_t *ciphertext_len); +int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, const char *plaintext, + size_t plaintext_len, char **ciphertext, size_t *ciphertext_len); + /** - * @brief Decrypts data using a symmetric cipher. - * + * @brief Decrypts data using a symmetric cipher. * @since_tizen 3.0 - * - * @remarks yaca_simple_decrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. - * - * @remarks The @a plaintext should be freed using yaca_free(). - * - * @remarks The @a ciphertext can be NULL but then @a ciphertext_len must be 0. - * - * @param[in] algo Decryption algorithm that was used to encrypt the data - * @param[in] bcm Chaining mode that was used to encrypt the data - * @param[in] sym_key Symmetric encryption key that was used to encrypt the data - * @param[in] iv Initialization Vector that was used to encrypt the data - * @param[in] ciphertext Ciphertext to be decrypted - * @param[in] ciphertext_len Length of ciphertext - * @param[out] plaintext Decrypted data, will be allocated by the library - * @param[out] plaintext_len Length of the decrypted data - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks yaca_simple_decrypt() doesn't support #YACA_BCM_GCM and #YACA_BCM_CCM. + * @remarks The @a plaintext should be freed using yaca_free(). + * @remarks The @a ciphertext can be NULL but then @a ciphertext_len must be 0. + * @param[in] algo Decryption algorithm that was used to encrypt the data + * @param[in] bcm Chaining mode that was used to encrypt the data + * @param[in] sym_key Symmetric encryption key that was used to encrypt the data + * @param[in] iv Initialization Vector that was used to encrypt the data + * @param[in] ciphertext Ciphertext to be decrypted + * @param[in] ciphertext_len Length of ciphertext + * @param[out] plaintext Decrypted data, will be allocated by the library + * @param[out] plaintext_len Length of the decrypted data + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo, @a bcm, @a sym_key or @a iv) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_encrypt_algorithm_e * @see #yaca_block_cipher_mode_e * @see yaca_simple_encrypt() * @see yaca_free() */ -int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, - yaca_block_cipher_mode_e bcm, - const yaca_key_h sym_key, - const yaca_key_h iv, - const char *ciphertext, - size_t ciphertext_len, - char **plaintext, - size_t *plaintext_len); +int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, yaca_block_cipher_mode_e bcm, const yaca_key_h sym_key, const yaca_key_h iv, const char *ciphertext, + size_t ciphertext_len, char **plaintext, size_t *plaintext_len); + /** - * @brief Calculates a digest of a message. - * + * @brief Calculates a digest of a message. * @since_tizen 3.0 - * - * @remarks The @a digest should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure) - * @param[in] message Message from which the digest is to be calculated - * @param[in] message_len Length of the message - * @param[out] digest Message digest, will be allocated by the library - * @param[out] digest_len Length of message digest (depends on algorithm) - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a digest should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure) + * @param[in] message Message from which the digest is to be calculated + * @param[in] message_len Length of the message + * @param[out] digest Message digest, will be allocated by the library + * @param[out] digest_len Length of message digest (depends on algorithm) + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, * invalid @a algo) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_digest_algorithm_e * @see yaca_free() */ -int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, - const char *message, - size_t message_len, - char **digest, - size_t *digest_len); +int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, const char *message, size_t message_len, char **digest, size_t *digest_len); + /** - * @brief Creates a signature using asymmetric private key. - * + * @brief Creates a signature using asymmetric private key. * @since_tizen 3.0 - * - * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than - * #YACA_KEY_LENGTH_512BIT. - * - * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. - * - * @remarks The @a signature should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] prv_key Private key that will be used, algorithm is - * deduced based on key type, supported key types: - * - #YACA_KEY_TYPE_RSA_PRIV, - * - #YACA_KEY_TYPE_DSA_PRIV, - * - #YACA_KEY_TYPE_EC_PRIV - * @param[in] message Message to be signed - * @param[in] message_len Length of the message - * @param[out] signature Message signature, will be allocated by the library - * @param[out] signature_len Length of the signature - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For #YACA_DIGEST_SHA384 and #YACA_DIGEST_SHA512 the RSA key size must be bigger than + * #YACA_KEY_LENGTH_512BIT. + * @remarks Using of #YACA_DIGEST_MD5 algorithm for DSA and ECDSA operations is prohibited. + * @remarks The @a signature should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] prv_key Private key that will be used, algorithm is + * deduced based on key type, supported key types: + * - #YACA_KEY_TYPE_RSA_PRIV, + * - #YACA_KEY_TYPE_DSA_PRIV, + * - #YACA_KEY_TYPE_EC_PRIV + * @param[in] message Message to be signed + * @param[in] message_len Length of the message + * @param[out] signature Message signature, will be allocated by the library + * @param[out] signature_len Length of the signature + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo or @a prv_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_digest_algorithm_e * @see yaca_simple_verify_signature() * @see yaca_free() */ -int yaca_simple_calculate_signature(yaca_digest_algorithm_e algo, - const yaca_key_h prv_key, - const char *message, - size_t message_len, - char **signature, - size_t *signature_len); +int yaca_simple_calculate_signature(yaca_digest_algorithm_e algo, const yaca_key_h prv_key, const char *message, size_t message_len, char **signature, size_t *signature_len); + /** - * @brief Verifies a signature using asymmetric public key. - * + * @brief Verifies a signature using asymmetric public key. * @since_tizen 3.0 - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] pub_key Public key that will be used, algorithm is - * deduced based on key type, supported key types: - * - #YACA_KEY_TYPE_RSA_PUB, - * - #YACA_KEY_TYPE_DSA_PUB, - * - #YACA_KEY_TYPE_EC_PUB - * @param[in] message Message - * @param[in] message_len Length of the message - * @param[in] signature Message signature to be verified - * @param[in] signature_len Length of the signature - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] pub_key Public key that will be used, algorithm is + * deduced based on key type, supported key types: + * - #YACA_KEY_TYPE_RSA_PUB, + * - #YACA_KEY_TYPE_DSA_PUB, + * - #YACA_KEY_TYPE_EC_PUB + * @param[in] message Message + * @param[in] message_len Length of the message + * @param[in] signature Message signature to be verified + * @param[in] signature_len Length of the signature + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo or @a pub_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error * @retval #YACA_ERROR_DATA_MISMATCH The verification failed - * * @see #yaca_key_type_e * @see #yaca_digest_algorithm_e * @see yaca_simple_calculate_signature() */ -int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, - const yaca_key_h pub_key, - const char *message, - size_t message_len, - const char *signature, - size_t signature_len); +int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, const yaca_key_h pub_key, const char *message, size_t message_len, const char *signature, size_t signature_len); + /** - * @brief Calculates a HMAC of given message using symmetric key. - * + * @brief Calculates a HMAC of given message using symmetric key. * @since_tizen 3.0 - * - * @remarks For verification, calculate message HMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a mac should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Digest algorithm that will be used - * @param[in] sym_key Key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * @param[in] message Message to calculate HMAC from - * @param[in] message_len Length of the message - * @param[out] mac MAC, will be allocated by the library - * @param[out] mac_len Length of the MAC - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message HMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a mac should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Digest algorithm that will be used + * @param[in] sym_key Key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @param[in] message Message to calculate HMAC from + * @param[in] message_len Length of the message + * @param[out] mac MAC, will be allocated by the library + * @param[out] mac_len Length of the MAC + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo or @a sym_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_digest_algorithm_e * @see yaca_memcmp() * @see yaca_free() */ -int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, - const yaca_key_h sym_key, - const char *message, - size_t message_len, - char **mac, - size_t *mac_len); +int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, const yaca_key_h sym_key, const char *message, size_t message_len, char **mac, size_t *mac_len); + /** - * @brief Calculates a CMAC of given message using symmetric key. - * + * @brief Calculates a CMAC of given message using symmetric key. * @since_tizen 3.0 - * - * @remarks For verification, calculate message CMAC and compare with received MAC using - * yaca_memcmp(). - * - * @remarks The @a mac should be freed using yaca_free(). - * - * @remarks The @a message can be NULL but then @a message_len must be 0. - * - * @param[in] algo Encryption algorithm that will be used - * @param[in] sym_key Key that will be used, supported key types: - * - #YACA_KEY_TYPE_SYMMETRIC, - * - #YACA_KEY_TYPE_DES - * @param[in] message Message to calculate CMAC from - * @param[in] message_len Length of the message - * @param[out] mac MAC, will be allocated by the library - * @param[out] mac_len Length of the MAC - * - * @return #YACA_ERROR_NONE on success, negative on error + * @remarks For verification, calculate message CMAC and compare with received MAC using yaca_memcmp(). + * @remarks The @a mac should be freed using yaca_free(). + * @remarks The @a message can be NULL but then @a message_len must be 0. + * @param[in] algo Encryption algorithm that will be used + * @param[in] sym_key Key that will be used, supported key types: + * - #YACA_KEY_TYPE_SYMMETRIC, + * - #YACA_KEY_TYPE_DES + * @param[in] message Message to calculate CMAC from + * @param[in] message_len Length of the message + * @param[out] mac MAC, will be allocated by the library + * @param[out] mac_len Length of the MAC + * @return #YACA_ERROR_NONE on success, + * negative on error * @retval #YACA_ERROR_NONE Successful * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0 * invalid @a algo or @a sym_key) * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error * @retval #YACA_ERROR_INTERNAL Internal error - * * @see #yaca_key_type_e * @see #yaca_encrypt_algorithm_e * @see yaca_memcmp() * @see yaca_free() */ -int yaca_simple_calculate_cmac(yaca_encrypt_algorithm_e algo, - const yaca_key_h sym_key, - const char *message, - size_t message_len, - char **mac, - size_t *mac_len); +int yaca_simple_calculate_cmac(yaca_encrypt_algorithm_e algo, const yaca_key_h sym_key, const char *message, size_t message_len, char **mac, size_t *mac_len); + /** * @} */ + #ifdef __cplusplus } /* extern */ #endif + #endif /* YACA_SIMPLE_H */ |