From ee618de49c4f7c2afd1dcb0134fbbadcce952384 Mon Sep 17 00:00:00 2001 From: Dariusz Michaluk Date: Wed, 24 Aug 2016 10:38:58 +0200 Subject: [PATCH] Unify key and IV naming and length unit. Change-Id: Iff2bab3a9b7a59c224cff6007a6edda9e30c2d71 --- api/yaca/yaca_crypto.h | 3 +- api/yaca/yaca_encrypt.h | 11 +++---- api/yaca/yaca_key.h | 21 +++++++------ api/yaca/yaca_seal.h | 12 ++++---- api/yaca/yaca_simple.h | 4 +-- api/yaca/yaca_types.h | 78 ++++++++++++++++++++++++++----------------------- 6 files changed, 71 insertions(+), 58 deletions(-) diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index dfdbb8a..58c421d 100755 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -221,7 +221,8 @@ int yaca_context_set_property(yaca_context_h ctx, * @remarks The @a value has to be of type appropriate for given property. See #yaca_property_e * for details on corresponding types. * - * @remarks @a value_len can be NULL if returned @a value is a single object (i.e. not an array/buffer) + * @remarks @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 diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index d99db9b..97bfe58 100755 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -37,17 +37,18 @@ extern "C" { */ /** - * @brief Returns the recommended/default length of the IV for a given encryption configuration. + * @brief Returns the recommended/default length of the Initialization Vector + * for a given encryption configuration. * * @since_tizen 3.0 * * @remarks If returned iv_bit_len equals 0 that means that for this - * specific algorithm and its parameters IV is not used. + * 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 IV length in bits + * @param[out] iv_bit_len Recommended Initialization Vector length in bits * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -72,7 +73,7 @@ int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, * @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 + * @param[in] iv Initialization Vector that will be used * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -161,7 +162,7 @@ int yaca_encrypt_finalize(yaca_context_h ctx, * @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 + * @param[in] iv Initialization Vector that was used to encrypt the data * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 87e3b30..6f9a0f1 100755 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -18,7 +18,7 @@ /** * @file yaca_key.h - * @brief Advanced API for the key and IV handling. + * @brief Advanced API for the key and Initialization Vector handling. */ #ifndef YACA_KEY_H @@ -64,7 +64,7 @@ int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type); * * @since_tizen 3.0 * - * @remarks @a key can be any symmetric (including an IV) or + * @remarks @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 @@ -98,7 +98,7 @@ int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len); * @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, IV and DES keys RAW binary format and BASE64 encoded + * @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. * @@ -154,9 +154,10 @@ int yaca_key_import(yaca_key_type_e key_type, * @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 IV), for asymmetric keys it will export to their - * default ASN1 structure format (e.g. PKCS#1, SSLeay, PKCS#3). + * - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric keys + * (or Initialization Vector), for asymmetric keys it will + * export to their default ASN1 structure format + * (e.g. PKCS#1, SSLeay, PKCS#3). * - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys. * * @remarks The following file formats are supported: @@ -207,7 +208,7 @@ int yaca_key_export(const yaca_key_h key, size_t *data_len); /** - * @brief Generates a secure key or key generation parameters (or an initialization vector). + * @brief Generates a secure key or key generation parameters (or an Initialization Vector). * * @since_tizen 3.0 * @@ -323,7 +324,8 @@ int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params); * @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 + * to produce a symmetric key pass the secret to a key derivation function (KDF) + * or a message digest function * * @remarks The @a secret should be freed with yaca_free() * @@ -355,7 +357,8 @@ int yaca_key_derive_dh(const yaca_key_h prv_key, * @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 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() * diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index 380e55d..97f8544 100755 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -20,8 +20,9 @@ * @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 IV, - * then encrypts whole message using this key (and selected symmetric algorithm). + * @details Seal does more than just encrypt. It first generates the encryption key and + * Initialization Vector, then encrypts whole message using this key + * (and selected symmetric algorithm). * Finally it encrypts symmetric key with public key. */ @@ -41,7 +42,8 @@ extern "C" { */ /** - * @brief Initializes an asymmetric encryption context and generates symmetric key and IV. + * @brief Initializes an asymmetric encryption context and generates + * symmetric key and Initialization Vector. * * @remarks Generated symmetric key is encrypted with public key, * so can be ONLY used with yaca_open_initialize(). It can be exported, @@ -64,7 +66,7 @@ extern "C" { * @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 + * @param[out] iv Generated Initialization Vector that will be used * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -163,7 +165,7 @@ int yaca_seal_finalize(yaca_context_h ctx, * @param[in] sym_key_bit_len Symmetric key length (in bits) that was used for the encryption * @param[in] sym_key Symmetric key, encrypted with the public key, * that was used to encrypt the data - * @param[in] iv Initialization vector that was used for the encryption + * @param[in] iv Initialization Vector that was used for the encryption * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index 96c9d97..8f37875 100755 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -57,7 +57,7 @@ extern "C" { * @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] 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 @@ -96,7 +96,7 @@ int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, * @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] 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 diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h index 857710c..b361d4e 100755 --- a/api/yaca/yaca_types.h +++ b/api/yaca/yaca_types.h @@ -143,7 +143,7 @@ extern "C" { typedef struct yaca_context_s *yaca_context_h; /** - * @brief The handle of a key, an IV or a key generation parameters. + * @brief The handle of a key, an Initialization Vector or a key generation parameters. * * @since_tizen 3.0 */ @@ -178,7 +178,7 @@ typedef enum { } yaca_key_file_format_e; /** - * @brief Enumeration of YACA key types, IV is considered as key. + * @brief Enumeration of YACA key types, Initialization Vector is considered as key. * * @since_tizen 3.0 */ @@ -334,7 +334,7 @@ typedef enum { typedef enum { /** * AES encryption. - * - Supported key lengths: @c 128, @c 192 and @c 256. + * - Supported key lengths: @c 128, @c 192 and @c 256 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -352,7 +352,7 @@ typedef enum { /** * DES encryption. - * - Supported key lengths: @c 64. + * - Supported key lengths: @c 64 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -366,7 +366,7 @@ typedef enum { /** * 3DES 2-key encryption. - * - Supported key lengths: @c 128. + * - Supported key lengths: @c 128 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -379,7 +379,7 @@ typedef enum { /** * 3DES 3-key encryption. - * - Supported key lengths: @c 192. + * - Supported key lengths: @c 192 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -397,7 +397,7 @@ typedef enum { * 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. + * - Effective key bits property by default equals to 128 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -411,15 +411,15 @@ typedef enum { * RC4 encryption. * This is a variable key length cipher. * - Supported key lengths: 40–2048 bits in steps of 8 bits. - * No IV is used. - * This cipher doesn't support block cipher modes, use #YACA_BCM_NONE instead. + * - 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 key lengths: 40-128 bits in steps of 8 bits. * - Supported block cipher modes:\n * #YACA_BCM_CBC,\n * #YACA_BCM_OFB,\n @@ -438,16 +438,17 @@ typedef enum { typedef enum { /** * Used when algorithm doesn't support block ciphers modes. - * No IV is used. + * Initialization Vector is not used. */ YACA_BCM_NONE, /** * ECB block cipher mode. - * No IV is used. + * Initialization Vector is not used. * * By default the input data is padded using standard block padding (aka PKCS#5 padding). - * Padding can be disabled using yaca_context_set_property() and #YACA_PROPERTY_PADDING, #YACA_PADDING_NONE, + * 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. * #YACA_PROPERTY_PADDING can be set at the latest before the *_finalize() call. */ @@ -455,18 +456,19 @@ typedef enum { /** * CTR block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. */ YACA_BCM_CTR, /** * CBC block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. * * By default the input data is padded using standard block padding (aka PKCS#5 padding). - * Padding can be disabled using yaca_context_set_property() and #YACA_PROPERTY_PADDING, #YACA_PADDING_NONE, + * 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. * #YACA_PROPERTY_PADDING can be set at the latest before the *_finalize() call. */ @@ -474,15 +476,15 @@ typedef enum { /** * GCM block cipher mode. - * This is a variable IV length mode (recommended 96 bits IV). + * This is a variable Initialization Vector length mode (recommended 96-bits). * * Supported properties: * - #YACA_PROPERTY_GCM_TAG_LEN = GCM tag length\n * Supported tag lengths: @c 4, @c 8, @c 12, @c 13, @c 14, @c 15, @c 16, * (recommended 16 bytes tag).\n * Set after yaca_encrypt_finalize() / yaca_seal_finalize() and before - * yaca_context_get_property(#YACA_PROPERTY_GCM_TAG) - * in encryption / seal operation. The @a value should be a size_t variable.\n + * yaca_context_get_property(#YACA_PROPERTY_GCM_TAG) in encryption / seal operation.\n + * The @a value should be a size_t variable.\n * In decryption / open operation tag length is not set.\n\n * * - #YACA_PROPERTY_GCM_TAG = GCM tag\n @@ -501,42 +503,43 @@ typedef enum { /** * Default CFB block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. */ YACA_BCM_CFB, /** * 1 bit CFB block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. */ YACA_BCM_CFB1, /** * 8 bits CFB block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. */ YACA_BCM_CFB8, /** * OFB block cipher mode. - * 16-byte initialization vector for AES, - * 8-byte for other algorithms is mandatory. + * 128-bit Initialization Vector for AES, + * 64-bit for other algorithms is mandatory. */ YACA_BCM_OFB, /** * CBC-MAC Mode (AES). - * This is a variable IV length mode.\n - * Supported IV lengths: 56-104 bits in steps of 8 bits (recommended 56 bits IV).\n\n + * This is a variable Initialization Vector length mode.\n + * Supported Initialization Vector lengths: 56-104 bits in steps of 8 bits + * (recommended 56-bits).\n\n * * Supported properties: * - #YACA_PROPERTY_CCM_TAG_LEN = CCM tag length\n * Supported tag lengths: 4-16 bytes in steps of 2 bytes (recommended 12 bytes tag).\n * Set after yaca_encrypt_initialize() / yaca_seal_initialize() and before - * yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation. + * yaca_encrypt_update() / yaca_seal_update() in encryption / seal operation.\n * The @a value should be a size_t variable.\n * In decryption / open operation tag length is not set.\n\n * @@ -570,12 +573,15 @@ typedef enum { * * 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. - * Wrapped key can be a 128-bit key, a 192-bit key, or a 256-bit key. + * 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. - * Wrapped key can be a 128-bit DES key (two-key), or a 192-bit DES key (three-key). + * 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. * */ -- 2.7.4