*
* @since_tizen 3.0
*
- * @remarks For elliptic curves @a key_bit_len returns values from #yaca_key_bit_length_ec_e
+ * @remarks For Diffie-Helmann @a key_bit_len returns prime length in bits. Values
+ * used to generate the key/parammeters 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
* @retval #YACA_ERROR_INTERNAL Internal error
*
* @see #yaca_key_bit_length_e
+ * @see #yaca_key_bit_length_dh_rfc_e
* @see #yaca_key_bit_length_ec_e
*/
int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len);
/**
- * @brief Imports a key.
+ * @brief Imports a key or key generation parameters.
*
* @since_tizen 3.0
*
+ * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred
+ * in the documentation of this function key generator parameters are also included.
+ *
* @remarks This function imports a key trying to match it to the @a key_type specified.
* It should autodetect both the key format and the file format.
*
* binary format are supported.
* For asymmetric keys PEM and DER file formats are supported.
*
- * @remarks Asymmetric keys can be in PKCS#1 or SSleay key formats (for RSA and
- * DSA respectively). Asymmetric private keys can also be in PKCS#8
- * format. Additionally it is possible to import public RSA key from
- * X509 certificate.
+ * @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
yaca_key_h *key);
/**
- * @brief Exports a key to arbitrary format. Export may fail if key is HW-based.
+ * @brief Exports a key or key generation parameters to arbitrary format.
*
* @since_tizen 3.0
*
+ * @remarks Everywhere where either a key (of any type) or an asymmetric key is referred
+ * in the documentation of this function key generator parameters are also included.
+ *
* @remarks This function exports the key to an arbitrary key format and key file format.
*
* @remarks For key formats two values are allowed:
* - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric
- * keys (or IV), for asymmetric keys it will choose PKCS#1
- * for RSA keys and SSLeay for DSA keys.
+ * 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_PKCS8: this will only work for private asymmetric keys.
*
* @remarks The following file formats are supported:
* file formats). If no password is provided the #YACA_ERROR_INVALID_PARAMETER will
* be returned. The encryption algorithm used in this case is PBE with DES-CBC.
*
- * @remakrs Encryption is not supported for the symmetric and public keys in all their
- * supported formats. If a password is provided in such case the
- * #YACA_ERROR_INVALID_PARAMETER will be returned.
+ * @remarks Encryption is not supported for the symmetric, public keys and key generation
+ * parameters in all their supported formats. If a password is provided in such
+ * case the #YACA_ERROR_INVALID_PARAMETER will be returned.
*
* @param[in] key Key to be exported
* @param[in] key_fmt Format of the key
size_t *data_len);
/**
- * @brief Generates a secure key (or an initialization vector).
+ * @brief Generates a secure key or key generation parameters (or an initialization vector).
*
* @since_tizen 3.0
*
- * @remarks This function is used to generate symmetric and private asymmetric keys.
+ * @remarks This function is used to generate symmetric keys, private asymmetric keys
+ * or key generation parameters for key types that support them (DSA, DH and EC).
*
* @remarks Supported key lengths:
* - RSA: length >= 256bits
* - DSA: length >= 512bits, multiple of 64
- * - EC: @a key_bit_len takes values from #yaca_key_bit_length_ec_e
+ * - DH: a value taken from #yaca_key_bit_length_dh_rfc_e or
+ * (YACA_KEY_LENGTH_DH_GENERATOR_* | prime_length_in_bits),
+ * where prime_length_in_bits can be any positive number
+ * - EC: a value taken from #yaca_key_bit_length_ec_e
*
* @remarks The @a key should be released using yaca_key_destroy()
*
*
* @see #yaca_key_type_e
* @see #yaca_key_bit_length_e
+ * @see #yaca_key_bit_length_dh_rfc_e
+ * @see #YACA_KEY_LENGTH_DH_GENERATOR_2
+ * @see #YACA_KEY_LENGTH_DH_GENERATOR_5
* @see #yaca_key_bit_length_ec_e
* @see yaca_key_destroy()
*/
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 The @a key should be released using yaca_key_destroy()
+ *
+ * @param[in] params Pre-generated parameters
+ * @param[out] prv_key Newly generated private key
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL or incorrect @a params
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see yaca_key_destroy()
+ * @see yaca_key_generate()
+ * @see yaca_key_extract_parameters()
+ */
+int yaca_key_generate_from_parameters(const yaca_key_h params, yaca_key_h *prv_key);
+
+/**
* @brief Extracts public key from a private one.
*
* @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
+ * @param[in] prv_key Private key to extract the public one from
+ * @param[out] pub_key Extracted public key
*
* @return #YACA_ERROR_NONE on success, negative on error
* @retval #YACA_ERROR_NONE Successful
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_key should be released using yaca_key_destroy()
+ *
+ * @param[in] key A key to extract the parameters from
+ * @param[out] params Extracted parameters
+ *
+ * @return #YACA_ERROR_NONE on success, negative on error
+ * @retval #YACA_ERROR_NONE Successful
+ * @retval #YACA_ERROR_INVALID_PARAMETER @a key is of invalid type or @a params is NULL
+ * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
+ * @retval #YACA_ERROR_INTERNAL Internal error
+ *
+ * @see yaca_key_generate()
+ * @see yaca_key_generate_from_parameters()
+ * @see yaca_key_import()
+ * @see yaca_key_destroy()
+ */
+int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params);
+
+/**
* @brief Release the key created by the library. Passing YACA_KEY_NULL is allowed.
*
* @since_tizen 3.0
/* The format of the unsigned int used to indicate key_bit_len is as follows:
*
* Bits indicating a type:
- * bits 31-30 (2 bits) indicate key_length type:
- * 00(0) - regular type for RSA, DSA and DH
- * 01(1) - elliptic curve
+ * bits 31-28 (4 bits) indicate key_length type:
+ * 0000(0) - regular type for RSA, DSA
+ * 0001(1) - DH with specified generator
+ * 0010(2) - DH with RFC 5114
+ * 0011(3) - elliptic curve
* remaining combinations reserved
*
* Bits for a regular type:
- * bits 29-0 (30 bits) indicate length of the key in bits
+ * bits 27-0 (28 bits) indicate length of the key in bits
+ *
+ * Bits for a DH with specified generator number:
+ * bits 27-24 (4 bits) indicate DH generator
+ * 0000(0) - generator 2
+ * 0001(1) - generator 5
+ * remaining combinations reserved
+ * bits 23-16 (8 bits) reserved
+ * bits 15-0 (16 bits) length of the safe prime in bits
+ *
+ * Bits for a DH with RFC 5114:
+ * bits 27-24 (4 bits) indicate a bit subgroup:
+ * 0000(0) - 160
+ * 0001(1) - 224
+ * 0010(2) - 256
+ * remaining combinations reserved
+ * bits 23-16 (8 bits) reserved
+ * bits 15-0 (16 bits) length of the safe prime in bits
*
* Bits for an elliptic curve type:
- * bits 29-26 (4 bits) indicate type of an elliptic curve:
+ * bits 27-24 (4 bits) indicate type of an elliptic curve:
* 0000(0) - X9.62 Prime
* 0001(1) - SECP
* 0010(2) - SECT
* 0011(3) - Brainpool
* remaining combinations reserved (c2pnb, c2tnb, c2onb...)
- * bits 25-22 (4 bits) indicate a letter:
+ * bits 23-20 (4 bits) indicate a letter:
* 0000(0) - v
* 0001(1) - r
* 0010(2) - k
* 0011(3) - t
* remaining combinations reserved (w...)
- * bits 21-18 (4 bits) indicate a number:
+ * bits 19-16 (4 bits) indicate a number:
* 0000(0) - 1
* 0001(1) - 2
* 0010(2) - 3
* 0011(3) - 4
* remaining combinations reserved
- * bits 17-0 (18 bits) - length of the prime field in bits
+ * bits 15-0 (16 bits) - length of the prime field in bits
+ *
+ * Those bits are used for DH and EC. For any other keys key_bit_len can be passed just
+ * as a number of bits (4 most significant bits set to 0000, 28 bits for bit length).
+ *
+ * In any case those defines are not be used directly.
*
- * For now this is mostly used for elliptic curves. For any other keys key_bit_len can be
- * passed just as a number of bits (2 most significant bits set to 00, 30 bits for bit length).
+ * For DH keys use YACA_KEY_LENGTH_DH_GENERATOR_* or'ed with safe prime length.
+ * Alternatively one can use values from yaca_key_bit_length_dh_rfc_e enum to use
+ * RFC 5114 parameters.
*
- * For elliptic curves don't use those defines directly, use enums in yaca_key_bit_length_ec_e.
- * Not all combinations are valid and other valid combinations are not guaranteed to be
- * implemented (they most surely aren't).
+ * For elliptic curves use values from yaca_key_bit_length_ec_e enum.
*/
/** @cond Don't include those defines in doxygen, they are not to be used directly */
-#define YACA_KEY_LEN_TYPE_MASK (3U << 30)
-#define YACA_KEY_LEN_TYPE_REGULAR (0U << 30)
-#define YACA_KEY_LEN_TYPE_EC (1U << 30)
-
-#define YACA_KEY_LEN_EC_PRIME (0U << 26)
-#define YACA_KEY_LEN_EC_SECP (1U << 26)
-#define YACA_KEY_LEN_EC_SECT (2U << 26)
-#define YACA_KEY_LEN_EC_BRAINPOOL (3U << 26)
-
-#define YACA_KEY_LEN_EC_V (0U << 22)
-#define YACA_KEY_LEN_EC_R (1U << 22)
-#define YACA_KEY_LEN_EC_K (2U << 22)
-#define YACA_KEY_LEN_EC_T (3U << 22)
-
-#define YACA_KEY_LEN_EC_1 (0U << 18)
-#define YACA_KEY_LEN_EC_2 (1U << 18)
-#define YACA_KEY_LEN_EC_3 (2U << 18)
-#define YACA_KEY_LEN_EC_4 (3U << 18)
+/* types */
+#define YACA_INTERNAL_KEYLEN_TYPE_MASK (0xF << 28)
+#define YACA_INTERNAL_KEYLEN_TYPE_BITS (0U << 28)
+#define YACA_INTERNAL_KEYLEN_TYPE_DH (1U << 28)
+#define YACA_INTERNAL_KEYLEN_TYPE_DH_RFC (2U << 28)
+#define YACA_INTERNAL_KEYLEN_TYPE_EC (3U << 28)
+
+/* DH type */
+#define YACA_INTERNAL_KEYLEN_DH_GEN_MASK (0xF << 24)
+#define YACA_INTERNAL_KEYLEN_DH_GEN_2 (0U << 24)
+#define YACA_INTERNAL_KEYLEN_DH_GEN_5 (1U << 24)
+
+#define YACA_INTERNAL_KEYLEN_DH_PRIME_MASK (0xFFFF << 0)
+
+/* DH_RFC type */
+#define YACA_INTERNAL_KEYLEN_DH_RFC_MASK (0xF << 24)
+#define YACA_INTERNAL_KEYLEN_DH_RFC_160 (0U << 24)
+#define YACA_INTERNAL_KEYLEN_DH_RFC_224 (1U << 24)
+#define YACA_INTERNAL_KEYLEN_DH_RFC_256 (2U << 24)
+
+/* EC type */
+#define YACA_INTERNAL_KEYLEN_EC_PRIME (0U << 24)
+#define YACA_INTERNAL_KEYLEN_EC_SECP (1U << 24)
+#define YACA_INTERNAL_KEYLEN_EC_SECT (2U << 24)
+#define YACA_INTERNAL_KEYLEN_EC_BRAINPOOL (3U << 24)
+
+#define YACA_INTERNAL_KEYLEN_EC_V (0U << 20)
+#define YACA_INTERNAL_KEYLEN_EC_R (1U << 20)
+#define YACA_INTERNAL_KEYLEN_EC_K (2U << 20)
+#define YACA_INTERNAL_KEYLEN_EC_T (3U << 20)
+
+#define YACA_INTERNAL_KEYLEN_EC_1 (0U << 16)
+#define YACA_INTERNAL_KEYLEN_EC_2 (1U << 16)
+#define YACA_INTERNAL_KEYLEN_EC_3 (2U << 16)
+#define YACA_INTERNAL_KEYLEN_EC_4 (3U << 16)
/** @endcond */
/**
typedef struct yaca_context_s *yaca_context_h;
/**
- * @brief The key handle.
+ * @brief The handle of a key, an IV or a key generation parameters.
*
* @since_tizen 3.0
*/
/** 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
+ 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_e;
/**
*/
typedef enum {
/** Elliptic curve prime192v1 */
- YACA_KEY_LENGTH_EC_PRIME192V1 = YACA_KEY_LEN_TYPE_EC | YACA_KEY_LEN_EC_PRIME | YACA_KEY_LEN_EC_V | YACA_KEY_LEN_EC_1 | 192U,
+ YACA_KEY_LENGTH_EC_PRIME192V1 = YACA_INTERNAL_KEYLEN_TYPE_EC | YACA_INTERNAL_KEYLEN_EC_PRIME | YACA_INTERNAL_KEYLEN_EC_V | YACA_INTERNAL_KEYLEN_EC_1 | 192U,
/** Elliptic curve prime256v1 */
- YACA_KEY_LENGTH_EC_PRIME256V1 = YACA_KEY_LEN_TYPE_EC | YACA_KEY_LEN_EC_PRIME | YACA_KEY_LEN_EC_V | YACA_KEY_LEN_EC_1 | 256U,
+ YACA_KEY_LENGTH_EC_PRIME256V1 = YACA_INTERNAL_KEYLEN_TYPE_EC | YACA_INTERNAL_KEYLEN_EC_PRIME | YACA_INTERNAL_KEYLEN_EC_V | YACA_INTERNAL_KEYLEN_EC_1 | 256U,
/** Elliptic curve secp256k1 */
- YACA_KEY_LENGTH_EC_SECP256K1 = YACA_KEY_LEN_TYPE_EC | YACA_KEY_LEN_EC_SECP | YACA_KEY_LEN_EC_K | YACA_KEY_LEN_EC_1 | 256U,
+ YACA_KEY_LENGTH_EC_SECP256K1 = YACA_INTERNAL_KEYLEN_TYPE_EC | YACA_INTERNAL_KEYLEN_EC_SECP | YACA_INTERNAL_KEYLEN_EC_K | YACA_INTERNAL_KEYLEN_EC_1 | 256U,
/** Elliptic curve secp384r1 */
- YACA_KEY_LENGTH_EC_SECP384R1 = YACA_KEY_LEN_TYPE_EC | YACA_KEY_LEN_EC_SECP | YACA_KEY_LEN_EC_R | YACA_KEY_LEN_EC_1 | 384U,
+ YACA_KEY_LENGTH_EC_SECP384R1 = YACA_INTERNAL_KEYLEN_TYPE_EC | YACA_INTERNAL_KEYLEN_EC_SECP | YACA_INTERNAL_KEYLEN_EC_R | YACA_INTERNAL_KEYLEN_EC_1 | 384U,
/** Elliptic curve secp521r1 */
- YACA_KEY_LENGTH_EC_SECP521R1 = YACA_KEY_LEN_TYPE_EC | YACA_KEY_LEN_EC_SECP | YACA_KEY_LEN_EC_R | YACA_KEY_LEN_EC_1 | 521U
+ YACA_KEY_LENGTH_EC_SECP521R1 = YACA_INTERNAL_KEYLEN_TYPE_EC | YACA_INTERNAL_KEYLEN_EC_SECP | YACA_INTERNAL_KEYLEN_EC_R | YACA_INTERNAL_KEYLEN_EC_1 | 521U
} yaca_key_bit_length_ec_e;
/**
+ * @brief A value indicating generator equal 2 for DH parameters.
+ * To be or'ed with safe prime length in bits. Prime length is recommended
+ * to be 2048 bits or higher.
+ */
+#define YACA_KEY_LENGTH_DH_GENERATOR_2 (YACA_INTERNAL_KEYLEN_TYPE_DH | YACA_INTERNAL_KEYLEN_DH_GEN_2)
+/**
+ * @brief A value indicating generator equal 5 for DH parameters.
+ * To be or'ed with safe prime length in bits. Prime length is recommended
+ * to be 2048 bits or higher.
+ */
+#define YACA_KEY_LENGTH_DH_GENERATOR_5 (YACA_INTERNAL_KEYLEN_TYPE_DH | YACA_INTERNAL_KEYLEN_DH_GEN_5)
+
+/**
+ * @brief Enumeration of 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_INTERNAL_KEYLEN_TYPE_DH_RFC | YACA_INTERNAL_KEYLEN_DH_RFC_160 | 1024U,
+ /** RFC 5114 DH parameters 2048_224 */
+ YACA_KEY_LENGTH_DH_RFC_2048_224 = YACA_INTERNAL_KEYLEN_TYPE_DH_RFC | YACA_INTERNAL_KEYLEN_DH_RFC_224 | 2048U,
+ /** RFC 5114 DH parameters 2048_256 */
+ YACA_KEY_LENGTH_DH_RFC_2048_256 = YACA_INTERNAL_KEYLEN_TYPE_DH_RFC | YACA_INTERNAL_KEYLEN_DH_RFC_256 | 2048U
+} yaca_key_bit_length_dh_rfc_e;
+
+/**
* @brief Enumeration of YACA message digest algorithms.
*
* @since_tizen 3.0
projects / platform / core / security / yaca.git / commitdiff