*/
/**
- * @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
* @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
* @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
/**
* @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
*
* @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
* @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.
*
* @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:
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
*
* @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()
*
* @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()
*
* @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.
*/
*/
/**
- * @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,
* @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
* @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
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
*/
} 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
*/
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
/**
* 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
/**
* 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
/**
* 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
* 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
* 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
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.
*/
/**
* 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.
*/
/**
* 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
/**
* 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
*
*
* 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.
*
*/
projects / platform / core / security / yaca.git / commitdiff