1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
/*
* Copyright (c) 2024 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License
*
*/
#ifndef __TIZEN_CORE_CKMC_EXTENDED_H__
#define __TIZEN_CORE_CKMC_EXTENDED_H__
#include <stddef.h>
#include <stdint.h>
#include <ckmc/ckmc-type.h>
#include <ckmc/ckmc-error.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @addtogroup CAPI_KEY_MANAGER_CLIENT_EXTENDED_MODULE
* @{
*/
/**
* @platform
* @brief Wraps concatenated key and data (key|data) with wrapping key and returns it to the client.
*
* @since_tizen 7.0
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.extended
*
* @remarks The wrapping key must be public RSA (#CKMC_KEY_RSA_PUBLIC).
* @remarks The key denoted by @a alias can only be #CKMC_KEY_AES.
* @remarks The key and the wrapping key must be stored in the same backend.
* @remarks The data size must be smaller or equal to:
* wrapping key size in bytes - key size in bytes -
* 2* hash function output size in bytes - 2.
* Example: for 3072 RSA wrapping key, 256 AES key and hash SHA384 the maximum
* data size is: 3072/8 - 256/8 - 2*384/8 - 2 = 254 bytes.
* @remarks Considering the data size limit it's recommended to use RSA key longer than
* @c 1024 bits.
* @remarks The @a ppwrapped_key should be released using ckmc_key_free().
*
* @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
* for details. Supported algorithms:
* - #CKMC_ALGO_RSA_OAEP
* @param[in] wrapping_key_alias The name of the wrapping key
* @param[in] wrapping_key_password An optional password of the wrapping key
* @param[in] alias The name of the key to be concatenated, wrapped and exported
* @param[in] password An optional password used to decrypt the key pointed by @a alias
* @param[in] data Data to be concatenated, wrapped and exported
* @param[out] ppwrapped_key The wrapped key.
*
* @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, the
* wrapping key or the key being wrapped
* @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
* algorithm parameter or data too long,
* @a wrapping_key_alias = NULL,
* @a alias = NULL, @a data = NULL,
* @a ppwrapped_key = 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_UNKNOWN @a wrapping_key_alias or @a alias does not exist
* @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
* @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
* @a wrapping_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_unwrap_concatenated_data()
* @see #ckmc_param_list_h
* @see #ckmc_raw_buffer_s
* @see #ckmc_key_s
*/
int ckmc_wrap_concatenated_data(const ckmc_param_list_h params,
const char *wrapping_key_alias,
const char *wrapping_key_password,
const char *alias,
const char *password,
const ckmc_raw_buffer_s *data,
ckmc_key_s **ppwrapped_key);
/**
* @platform
* @brief Unwraps concatenated key and data (key|data) with wrapping key.
* Splits to key (stored inside key manager) and data (returned to the client).
*
* @since_tizen 7.0
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.extended
*
* @remarks The wrapping key must be private RSA (#CKMC_KEY_RSA_PRIVATE).
* @remarks key_type in @a wrapped_key can only be #CKMC_KEY_AES.
* @remarks password in @a wrapped_key must be set to NULL. There's no need to additionally encrypt
* a wrapped key.
* @remarks The key denoted by @a alias can only be #CKMC_KEY_AES.
* @remarks If password in @a policy is provided, the stored key is additionally encrypted with it.
* @remarks If extractable in @a policy is set to false, the stored key may still be exported in a
* wrapped form.
* @remarks The @a ppdata 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_RSA_OAEP
* @param[in] wrapping_key_alias The name of the wrapping key
* @param[in] wrapping_key_password An optional password of the wrapping key
* @param[in] wrapped_key The wrapped key to be unwrapped, splitted and stored
* @param[in] alias The name of a key to be stored
* @param[in] size The size in bits of the key to be stored. @c 128, @c 192 and @c 256 are supported
* @param[in] policy The policy about how to store a key securely
* @param[out] ppdata The unwrapped data.
*
* @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, the
* wrapping key or to create the unwrapped key
* @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
* algorithm parameter or invalid key size,
* @a wrapping_key_alias = NULL, @a wrapped_key = NULL,
* @a alias = NULL, @a ppdata = 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_UNKNOWN @a wrapping_key_alias does not exist
* @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a alias already exists
* @retval #CKMC_ERROR_INVALID_FORMAT The format of @a wrapped_key is not valid
* @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
* @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
* @a wrapping_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_wrap_concatenated_data()
* @see #ckmc_param_list_h
* @see #ckmc_key_s
* @see #ckmc_policy_s
* @see #ckmc_raw_buffer_s
*/
int ckmc_unwrap_concatenated_data(const ckmc_param_list_h params,
const char *wrapping_key_alias,
const char *wrapping_key_password,
const ckmc_key_s *wrapped_key,
const char *alias,
size_t size,
const ckmc_policy_s policy,
ckmc_raw_buffer_s **ppdata);
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* __TIZEN_CORE_CKMC_EXTENDED_H__ */
|
