PQC API draft

Change-Id: I6260b0d410e26af5c42c60a54c62c8b776822cd4

diff --git a/src/include/ckmc/ckmc-extended.h b/src/include/ckmc/ckmc-extended.h
index 005f3f276c2eb72a65b8aa9bb2183abe88a47cb6..fddd40c283329dba9a9026078a58359d2b1642f9 100644 (file)
--- a/src/include/ckmc/ckmc-extended.h
+++ b/src/include/ckmc/ckmc-extended.h
@@ -196,6 +196,243 @@ int ckmc_unwrap_concatenated_data(const ckmc_param_list_h params,
                                   ckmc_raw_buffer_s **ppdata);
 
 
+/**
+ * @platform
+ * @brief Creates private/public key pair based on Key-Encapsulation Mechanism (KEM) type and stores
+ *        them inside key manager based on each policy.
+ *
+ * @since_tizen 7.0
+ * @privlevel platform
+ * @privilege %http://tizen.org/privilege/keymanager.extended
+ *
+ * @remarks If password in @a policy_private_key or @a policy_public_key is provided, the stored key
+ *          is additionally encrypted with it.
+ * @remarks Currently supported KEM types are: #CKMC_ML_KEM_768, #CKMC_ML_KEM_1024.
+ *
+ * @param[in] kem_type The type of KEM key to be created
+ * @param[in] private_key_alias The name of private key to be stored
+ * @param[in] public_key_alias The name of public key to be stored
+ * @param[in] policy_private_key Private key storing policy
+ * @param[in] policy_public_key Public key storing policy
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
+ *                                       algorithm parameter, @a private_key_alias = NULL,
+ *                                       @a public_key_alias = NULL)
+ * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
+ * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
+ * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
+ * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
+ *
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
+ *
+ * @see ckmc_encapsulate_key()
+ * @see ckmc_decapsulate_key()
+ * @see #ckmc_kem_type_e
+ * @see #ckmc_policy_s
+ */
+int ckmc_create_key_pair_kem(const ckmc_kem_type_e kem_type,
+                             const char *private_key_alias,
+                             const char *public_key_alias,
+                             const ckmc_policy_s policy_private_key,
+                             const ckmc_policy_s policy_public_key);
+
+
+/**
+ * @platform
+ * @brief Generates a random shared secret, encapsulates it using a public KEM key and produces a
+ *        ciphertext. The ciphertext is returned and the shared secret is stored inside key
+ *        manager using the shared secret alias and the policy provided.
+ *
+ * @since_tizen 7.0
+ * @privlevel platform
+ * @privilege %http://tizen.org/privilege/keymanager.extended
+ *
+ * @remarks The key used for encapsulation must be public KEM type key (#CKMC_KEY_KEM_PUBLIC).
+ * @remarks The KEM type used in key pair creation and encapsulation/decapsulation must be the same.
+ * @remarks The supported format of the shared secret is a 32-byte #CKMC_KEY_AES key.
+ * @remarks If policy contains password when storing a public key, the same password should be
+ *          provided.
+ * @remarks If password in @a shared_secret_policy is provided, the stored key is additionally
+ *          encrypted with it.
+ * @remarks The @a ppciphertext should be released using ckmc_buffer_free().
+ *
+ * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
+ *                   for details. Supported algorithms:
+ *                   - #CKMC_ALGO_KEM
+ * @param[in] public_key_alias Alias of the public KEM type key to be used for encapsulation
+ * @param[in] public_key_password An optional password used in decrypting a key value
+ * @param[in] shared_secret_alias Alias to store the shared secret
+ * @param[in] shared_secret_policy Shared secret storing policy
+ * @param[out] ppciphertext Ciphertext
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
+ *                                       algorithm parameter, @a public_key_alias = NULL,
+ *                                       @a shared_secret_alias = NULL)
+ * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
+ * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
+ * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a public_key_alias does not exist
+ * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a shared_secret_alias already exist
+ * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Public key decryption failed because
+ *                                           @a public_key_password is incorrect
+ * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
+ *
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
+ *
+ * @code
+ * ckmc_param_list_h params;               // Initialized elsewhere
+ * ckmc_policy_s shared_secret_policy;     // Initialized elsewhere
+ * ckmc_raw_buffer_s *ppciphertext;
+ * int ret = ckmc_encapsulate_key(params,
+ *                                "public_key_alias",
+ *                                "public_key_password",
+ *                                "shared_secret_alias",
+ *                                shared_secret_policy,
+ *                                &ppciphertext);
+ *  ...
+ * ckmc_buffer_free(ppciphertext);
+ * @endcode
+ *
+ * @see ckmc_create_key_pair_kem()
+ * @see ckmc_decapsulate_key()
+ * @see ckmc_key_derive_hybrid()
+ * @see #ckmc_param_list_h
+ * @see #ckmc_policy_s
+ * @see #ckmc_raw_buffer_s
+ */
+int ckmc_encapsulate_key(const ckmc_param_list_h params,
+                         const char *public_key_alias,
+                         const char *public_key_password,
+                         const char *shared_secret_alias,
+                         const ckmc_policy_s shared_secret_policy,
+                         ckmc_raw_buffer_s **ppciphertext);
+
+
+/**
+ * @platform
+ * @brief Decapsulates the shared secret from the ciphertext and KEM type private key.
+ *        The shared secret is stored inside key manager using the shared secret alias and
+ *        the policy provided.
+ *
+ * @since_tizen 7.0
+ * @privlevel platform
+ * @privilege %http://tizen.org/privilege/keymanager.extended
+ *
+ * @remarks The key used for decapsulation must be private KEM type key (#CKMC_KEY_KEM_PRIVATE).
+ * @remarks The KEM type used in key pair creation and encapsulation/decapsulation must be the same.
+ * @remarks The supported format of the shared secret is a 32-byte #CKMC_KEY_AES key.
+ * @remarks If policy contains password when storing a private key, the same password should be
+ *          provided.
+ * @remarks If password in @a shared_secret_policy is provided, the stored key is additionally
+ *          encrypted with it.
+ *
+ * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
+ *                   for details. Supported algorithms:
+ *                   - #CKMC_ALGO_KEM
+ * @param[in] private_key_alias Alias of the private KEM type key to be used for decapsulation
+ * @param[in] private_key_password An optional password used in decrypting a key value
+ * @param[in] shared_secret_alias Alias to store the shared secret
+ * @param[in] shared_secret_policy Shared secret storing policy
+ * @param[in] ciphertext Ciphertext
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
+ *                                       algorithm parameter, @a private_key_alias = NULL,
+ *                                       @a shared_secret_alias = NULL, @a ciphertext = NULL)
+ * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
+ * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
+ * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a private_key_alias does not exist
+ * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a shared_secret_alias already exist
+ * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Private key decryption failed because
+ *                                           @a private_key_password is incorrect
+ * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
+ *
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
+ *
+ * @see ckmc_create_key_pair_kem()
+ * @see ckmc_encapsulate_key()
+ * @see ckmc_key_derive_hybrid()
+ * @see #ckmc_param_list_h
+ * @see #ckmc_policy_s
+ * @see #ckmc_raw_buffer_s
+ */
+int ckmc_decapsulate_key(const ckmc_param_list_h params,
+                         const char *private_key_alias,
+                         const char *private_key_password,
+                         const char *shared_secret_alias,
+                         const ckmc_policy_s shared_secret_policy,
+                         const ckmc_raw_buffer_s *ciphertext);
+
+
+/**
+ * @platform
+ * @brief Derives a new key from another two concatenated keys/secrets (first|second) with a given
+ *        algorithm and stores it inside key manager using a new key alias and policy.
+ *
+ * @since_tizen 7.0
+ * @privlevel platform
+ * @privilege %http://tizen.org/privilege/keymanager.extended
+ *
+ * @remarks The key/secret, pointed to by @a first_secret_alias and @a second_secret_alias must be
+ *          a binary data or a symmetric key (#CKMC_KEY_AES).
+ * @remarks The derived key pointed to by @a new_key_alias will be a symmetric one. It will be
+ *          stored as a #CKMC_KEY_AES.
+ * @remarks In this method, AES-type keys can be hybridized with KEM-type secrets derived
+ *          from encapsulation/decapsulation methods.
+ * @remarks If policy contains password when storing a key/secret, the same password should be
+ *          provided.
+ * @remarks If password in @a new_key_policy is provided, the stored key is additionally
+ *          encrypted with it.
+ *
+ * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
+ *                   for details. Supported algorithms:
+ *                   - #CKMC_ALGO_KBKDF
+ * @param[in] first_secret_alias Alias of the first key/secret to use as an input
+ * @param[in] first_secret_password Optional password of the first key/secret used as an input
+ * @param[in] second_secret_alias Alias of the second key/secret to use as an input
+ * @param[in] second_secret_password Optional password of the second key/secret used as an input
+ * @param[in] new_key_alias Alias to store the new derived key/secret
+ * @param[in] new_key_policy Policy used to store the new derived key/secret
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
+ *                                       algorithm parameter, @a first_secret_alias = NULL,
+ *                                       @a second_secret_alias = NULL, @a new_key_alias = NULL)
+ * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
+ * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
+ * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a first_secret_alias or @a second_secret_alias
+ *                                      does not exist
+ * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exist
+ * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because @a first_secret_password
+ *                                           or @a second_secret_password is incorrect
+ * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
+ *
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
+ *
+ * @see ckmc_create_key_pair_kem()
+ * @see ckmc_encapsulate_key()
+ * @see ckmc_decapsulate_key()
+ * @see #ckmc_param_list_h
+ * @see #ckmc_policy_s
+ */
+int ckmc_key_derive_hybrid(const ckmc_param_list_h params,
+                           const char *first_secret_alias,
+                           const char *first_secret_password,
+                           const char *second_secret_alias,
+                           const char *second_secret_password,
+                           const char *new_key_alias,
+                           const ckmc_policy_s new_key_policy);
+
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index 6fc00d0946683623b5c236397b037810572bbad2..28cb10b060f84c101204d01d9cb62ccdfc0c819f 100644 (file)
--- a/src/include/ckmc/ckmc-manager.h
+++ b/src/include/ckmc/ckmc-manager.h
@@ -980,6 +980,7 @@ int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_A
  * @see ckmc_create_key_pair_rsa()
  * @see ckmc_create_key_pair_dsa()
  * @see ckmc_create_key_pair_ecdsa()
+ * @see ckmc_create_key_pair_kem()
  */
 int ckmc_remove_alias(const char *alias);
 

diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h
index 9a08dd3fd1738665307188bf9ad0f86d8627e7f7..9a5e52db02978d4fcae97245f7a596439c2a6d91 100644 (file)
--- a/src/include/ckmc/ckmc-type.h
+++ b/src/include/ckmc/ckmc-type.h
@@ -98,9 +98,21 @@ typedef enum __ckmc_key_type {
        CKMC_KEY_DSA_PUBLIC, /**< DSA public key */
        CKMC_KEY_DSA_PRIVATE, /**< DSA private key */
        CKMC_KEY_AES, /**< AES key */
+       CKMC_KEY_KEM_PUBLIC, /**< KEM public key (Since 7.0) */
+       CKMC_KEY_KEM_PRIVATE /**< KEM private key (Since 7.0) */
 } ckmc_key_type_e;
 
 
+/**
+ * @brief Enumeration for KEM types.
+ * @since_tizen 7.0
+ */
+typedef enum __ckmc_kem_type {
+       CKMC_ML_KEM_768 = 0,
+       CKMC_ML_KEM_1024
+} ckmc_kem_type_e;
+
+
 /**
  * @brief Enumeration for data format.
  * @since_tizen 2.3
@@ -337,6 +349,8 @@ typedef enum __ckmc_param_name {
                                       #CKMC_PARAM_KBKDF_FIXED_INPUT. (Since 6.0) */
 
        CKMC_PARAM_ECDH_PUBKEY, /**< buffer - EC public key in DER form (see #ckmc_key_s) (Since 6.0) */
+
+       CKMC_PARAM_KEM_TYPE, /**< integer - specifies the KEM type (see #ckmc_kem_type_e) (Since 7.0) */
 } ckmc_param_name_e;
 
 /**
@@ -467,6 +481,11 @@ typedef enum __ckmc_algo_type {
                      Supported parameters (all are required):
                      - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_ECDH,
                      - #CKMC_PARAM_ECDH_PUBKEY = peer's public key (see #ckmc_key_s) */
+
+       CKMC_ALGO_KEM,  /**< KEM algorithm
+                    Supported parameters:
+                     - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_KEM (mandatory),
+                     - #CKMC_PARAM_KEM_TYPE = the type of KEM (see #ckmc_kem_type_e) (mandatory) */
 } ckmc_algo_type_e;
 
 /**

diff --git a/src/manager/client-capi/ckmc-manager.cpp b/src/manager/client-capi/ckmc-manager.cpp
index e0c3be2b73cae74c386717f1b5d56c51b44c28c8..bf1219f8211584118de8858bd7ada848fac31b10 100644 (file)
--- a/src/manager/client-capi/ckmc-manager.cpp
+++ b/src/manager/client-capi/ckmc-manager.cpp
@@ -1359,4 +1359,76 @@ int ckmc_unwrap_concatenated_data(const ckmc_param_list_h params,
 
        return ret;
        EXCEPTION_GUARD_END
+}
+
+KEY_MANAGER_CAPI
+int ckmc_create_key_pair_kem(const ckmc_kem_type_e kem_type,
+                             const char *private_key_alias,
+                             const char *public_key_alias,
+                             const ckmc_policy_s policy_private_key,
+                             const ckmc_policy_s policy_public_key)
+{
+       (void) kem_type;
+       (void) private_key_alias;
+       (void) public_key_alias;
+       (void) policy_private_key;
+       (void) policy_public_key;
+
+       return CKMC_ERROR_NONE;
+}
+
+KEY_MANAGER_CAPI
+int ckmc_encapsulate_key(const ckmc_param_list_h params,
+                         const char *public_key_alias,
+                         const char *public_key_password,
+                         const char *shared_secret_alias,
+                         const ckmc_policy_s shared_secret_policy,
+                         ckmc_raw_buffer_s **ppciphertext)
+{
+       (void) params;
+       (void) public_key_alias;
+       (void) public_key_password;
+       (void) shared_secret_alias;
+       (void) shared_secret_policy;
+       (void) ppciphertext;
+
+       return CKMC_ERROR_NONE;
+}
+
+KEY_MANAGER_CAPI
+int ckmc_decapsulate_key(const ckmc_param_list_h params,
+                         const char *private_key_alias,
+                         const char *private_key_password,
+                         const char *shared_secret_alias,
+                         const ckmc_policy_s shared_secret_policy,
+                         const ckmc_raw_buffer_s *ciphertext)
+{
+       (void) params;
+       (void) private_key_alias;
+       (void) private_key_password;
+       (void) shared_secret_alias;
+       (void) shared_secret_policy;
+       (void) ciphertext;
+
+       return CKMC_ERROR_NONE;
+}
+
+KEY_MANAGER_CAPI
+int ckmc_key_derive_hybrid(const ckmc_param_list_h params,
+                           const char *first_secret_alias,
+                           const char *first_secret_password,
+                           const char *second_secret_alias,
+                           const char *second_secret_password,
+                           const char *new_key_alias,
+                           const ckmc_policy_s new_key_policy)
+{
+       (void) params;
+       (void) first_secret_alias;
+       (void) first_secret_password;
+       (void) second_secret_alias;
+       (void) second_secret_password;
+       (void) new_key_alias;
+       (void) new_key_policy;
+
+       return CKMC_ERROR_NONE;
 }
\ No newline at end of file