2 * Copyright (c) 2023 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
20 #include <ckmc/ckmc-type.h>
23 * @brief Derives a common symmetric key using ECDH and KBKDF.
27 * @remarks The derived key will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
28 * @remarks The function first generates a shared secret using ECDH and temporarily stores it in
29 * key-manager. Then it derives a symmetric key from it, stores it in key-manager too and
30 * removes the shared secret.
31 * @remarks Shared secret length and KBKDF algorithm parameters are fixed in the code.
32 * @remarks To simplify the API, it is assumed that the private key alias does not use a custom
35 * @param[in] private_key_alias Alias of the private key to be used in ECDH
36 * @param[in] raw_public_key Peer's public key in DER format to be used in ECDH
37 * @param[in] raw_public_key_len Length of the @a raw_public_key
38 * @param[in] new_key_alias The name under which the new key will be known in key-manager
40 * @return @c 0 on success, otherwise a negative error value
42 * @retval #CKMC_ERROR_NONE Successful
43 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a private_key_alias = NULL,
44 * @a raw_public_key = NULL, @a new_key_alias = NULL)
45 * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
46 * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a private_key_alias does not exist
47 * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
48 * @retval #CKMC_ERROR_INVALID_FORMAT The format of @a raw_public_key is not valid
49 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
50 * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
51 * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a private_key_alias
52 * needed a password and none was given
53 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
55 * @pre User is already logged in to key-manager.
57 * @see ckmc_key_derive()
59 int ckmew_key_agreement(const char *private_key_alias,
60 const unsigned char *raw_public_key,
61 size_t raw_public_key_len,
62 const char *new_key_alias);
65 * @brief Derives a symmetric key from a password using PBKFD2 and stores it in key-manager
69 * @remarks The password is temporarily stored in key-manager. It is deleted after key derivation
71 * @remarks The key-manager's policy for storing the derived key is fixed in the code.
72 * @remarks The number of PBKDF2 iteration is fixed in the code.
74 * @param[in] password The password to derive the key from
75 * @param[in] salt The salt used for PBKDF2
76 * @param[in] salt_len Length of the @a salt
77 * @param[in] new_key_len The desired length of the derived key
78 * @param[in] new_key_alias The name under which the new key will be known in key-manager
80 * @return @c 0 on success, otherwise a negative error value
82 * @retval #CKMC_ERROR_NONE Successful
83 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a password = NULL or
85 * @retval #CKMC_ERROR_NOT_SUPPORTED Unsupported key length
86 * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
87 * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
88 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
89 * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
90 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
92 * @pre User is already logged in to key-manager.
94 * @see ckmc_key_derive()
96 int ckmew_key_derive_pbkdf2(const char *password,
97 const unsigned char *salt,
100 const char *new_key_alias);
107 * @brief Constructs OCF certificate chain and returns it
109 * @privlevel platform
110 * @privilege %http://tizen.org/privilege/devicecertificate
112 * @remarks The @a cert_chain should be freed using free().
114 * @param[out] cert_chain Certificate chain in binary, will be allocated by the library
115 * @param[out] cert_chain_len The total length of certificate chain
117 * @return #DCM_ERROR_NONE on success, otherwise a negative error value
119 * @retval #DCM_ERROR_NONE Successful
120 * @retval #DCM_ERROR_INVALID_PARAMETER Input parameter is invalid
121 * @retval #DCM_ERROR_OUT_OF_MEMORY Out of memory during processing
122 * @retval #DCM_ERROR_PERMISSION_DENIED Failed to access device certificate manager
123 * @retval #DCM_ERROR_NOT_SUPPORTED Feature needed to run API is not supported
124 * @retval #DCM_ERROR_SOCKET Socket error between client and server
125 * @retval #DCM_ERROR_NO_DATA No certificate chain available
126 * @retval #DCM_ERROR_UNKNOWN Unknown error
128 int ckmew_get_ocf_cert_chain(char **cert_chain, size_t *cert_chain_len);
135 * @brief Signs given public key with OCF using E2EE signing scheme.
137 * @privlevel platform
138 * @privilege %http://tizen.org/privilege/devicecertificate
140 * @remarks The public key will be retrieved from key-manager.
141 * @remarks It is assumed that the public key is not encrypted with a custom password in
142 * key-manager and thus there's no need to pass additional argument.
144 * @param[in] public_key_alias Alias of the public key to be signed
145 * @param[out] message The E2EE message composed from public key and E2EE prefixes. It has to be
146 * freed using ckmc_buffer_free()
147 * @param[out] signature The OCF signature calculated for @a message. It has to be
148 * freed using ckmc_buffer_free()
150 * @return #DCM_ERROR_NONE on success, otherwise a negative error value
152 * @retval #DCM_ERROR_NONE Successful
153 * @retval #DCM_ERROR_INVALID_PARAMETER Input parameter is invalid
154 * @retval #DCM_ERROR_OUT_OF_MEMORY Out of memory during processing
155 * @retval #DCM_ERROR_PERMISSION_DENIED Failed to access device certificate manager
156 * @retval #DCM_ERROR_NOT_SUPPORTED Feature needed to run API is not supported
157 * @retval #DCM_ERROR_SOCKET Socket error between client and server
158 * @retval #DCM_ERROR_NO_DATA If OCF or public key are not available
159 * @retval #DCM_ERROR_UNKNOWN Unknown error
160 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
161 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
162 * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
163 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
164 * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
165 * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
166 * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
168 int ckmew_sign_with_ocf(const char *public_key_alias,
169 ckmc_raw_buffer_s **message,
170 ckmc_raw_buffer_s **signature);