Skip to content

Commit 4bf1cdb

Browse files
TofMassilia13320TofMassilia13320
committed
[refactor] STSELib 1.2.0 API change
1 parent d718f15 commit 4bf1cdb

9 files changed

Lines changed: 343 additions & 242 deletions

‎api/stse_symmetric_keys_management.c‎

Lines changed: 187 additions & 87 deletions
Large diffs are not rendered by default.

‎api/stse_symmetric_keys_management.h‎

Lines changed: 56 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -36,104 +36,116 @@
3636
*/
3737

3838
/**
39-
* \brief Host key provisioning in plaintext
40-
* \details This API perform host key provisioning in plaintext, \n
39+
* \brief Host secure channel keys provisioning in plaintext
40+
* \details This API perform host secure channel keys provisioning in plaintext, \n
4141
* it use the put attribute command if the device isn't a STSAFE-A120 \n
4242
* and it use the "write host key" command if it is a STSAFE-A120
43-
* \param[in] pSTSE Pointer to STSE Handler
44-
* \param[in] host_ecc_key_type Key type
45-
* \param[in] host_keys Pointer to the key structure
43+
* \param[in] pSTSE Pointer to STSE Handler
44+
* \param[in] host_mac_key Pointer to host MAC key (AES key structure) to be provisioned
45+
* \param[in] host_cipher_key Pointer to Host cipher key (AES key structure) to be provisioned
46+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host MAC key in secure storage
47+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host cipher key in secure storage
4648
* \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
4749
* \details \include{doc} stse_host_key_provisioning.dox
4850
*/
49-
stse_ReturnCode_t stse_host_key_provisioning(
51+
stse_ReturnCode_t stse_host_secure_channel_keys_provisioning(
5052
stse_Handle_t *pSTSE,
51-
stsafea_host_key_type_t host_ecc_key_type,
52-
stsafea_host_keys_t *host_keys);
53+
stse_aes_key_t *host_mac_key,
54+
stse_aes_key_t *host_cipher_key,
55+
PLAT_UI32 *host_mac_key_index,
56+
PLAT_UI32 *host_cipher_key_index);
5357

5458
/**
55-
* \brief Host key provisioning wrapped
56-
* \details This API perform host key provisioning with the key wrapped using a volatile KEK session
57-
* \param[in] pSTSE Pointer to STSE Handler
58-
* \param[in] host_key_type Key type
59-
* \param[in] host_keys Pointer to the key structure
59+
* \brief Host secure channel keys provisioning wrapped
60+
* \details This API perform host secure channel keys provisioning with the key wrapped using a volatile KEK session
61+
* \param[in] pSTSE Pointer to STSE Handler
62+
* \param[in] host_mac_key Pointer to host MAC key (AES key structure) to be provisioned
63+
* \param[in] host_cipher_key Pointer to Host cipher key (AES key structure) to be provisioned
6064
* \param[in] ecdhe_key_type ECC key type to use in KEK session
65+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host MAC key in secure storage
66+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host cipher key in secure storage
6167
* \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
6268
* \details \include{doc} stse_host_key_provisioning_wrapped.dox
6369
*/
64-
stse_ReturnCode_t stse_host_key_provisioning_wrapped(
70+
stse_ReturnCode_t stse_host_secure_channel_keys_provisioning_wrapped(
6571
stse_Handle_t *pSTSE,
66-
stsafea_host_key_type_t host_key_type,
67-
stsafea_host_keys_t *host_keys,
68-
stse_ecc_key_type_t ecdhe_key_type);
72+
stse_aes_key_t *host_mac_key,
73+
stse_aes_key_t *host_cipher_key,
74+
stse_ecc_key_type_t ecdhe_ecc_key_type,
75+
PLAT_UI32 *host_mac_key_index,
76+
PLAT_UI32 *host_cipher_key_index);
6977

7078
/**
71-
* \brief Host key provisioning wrapped and authenticated
72-
* \details This API perform host key provisioning with the key wrapped using an authenticated volatile KEK session
79+
* \brief Host secure channel keys provisioning wrapped and authenticated
80+
* \details This API perform host secure channel keys provisioning with the key wrapped using an authenticated volatile KEK session
7381
* \param[in] pSTSE Pointer to STSE Handler
74-
* \param[in] host_key_type Key type
75-
* \param[in] host_keys Pointer to the key structure
82+
* \param[in] host_mac_key Pointer to host MAC key (AES key structure) to be provisioned
83+
* \param[in] host_cipher_key Pointer to Host cipher key (AES key structure) to be provisioned
7684
* \param[in] ecdhe_key_type ECC key type to use in KEK session
7785
* \param[in] signature_public_key_slot_number Slot number of the public key used in authentication
7886
* \param[in] signature_hash_algo Hash algo used for the signature digest
7987
* \param[in] signature_private_key_type Key type of the private key used in authentication
8088
* \param[in] signature_private_key Private key used in authentication
89+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host MAC key in secure storage
90+
* \param[out] host_mac_key_index Pointer to the index assigned to the stored host cipher key in secure storage
8191
* \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
8292
* \details \include{doc} stse_host_key_provisioning_wrapped_authenticated.dox
8393
* \warning Few specific cryptographic library required to have public key concatenated to private key for EdDSA mechanism. In such case, pPrivate_key pointer shall reference concatenated key pair buffer's address.
8494
*/
85-
stse_ReturnCode_t stse_host_key_provisioning_wrapped_authenticated(
95+
stse_ReturnCode_t stse_host_secure_channel_keys_provisioning_wrapped_authenticated(
8696
stse_Handle_t *pSTSE,
87-
stsafea_host_key_type_t host_key_type,
88-
stsafea_host_keys_t *host_keys,
89-
stse_ecc_key_type_t ecdhe_key_type,
97+
stse_aes_key_t *host_mac_key,
98+
stse_aes_key_t *host_cipher_key,
99+
stse_ecc_key_type_t ecdhe_ecc_key_type,
90100
PLAT_UI8 signature_public_key_slot_number,
91101
stse_hash_algorithm_t signature_hash_algo,
92-
stse_ecc_key_type_t signature_private_key_type,
93-
PLAT_UI8 *signature_private_key);
102+
stse_ecc_key_type_t signature_private_ecc_key_type,
103+
PLAT_UI8 *signature_private_key,
104+
PLAT_UI32 *host_mac_key_index,
105+
PLAT_UI32 *host_cipher_key_index);
94106

95107
/**
96-
* \brief Host key establishment
97-
* \details This API establish host key (from STSAFE-A120)
108+
* \brief Host secure channel keys establishment
109+
* \details This API establish host secure channel keys (from STSAFE-A120)
98110
* \param[in] pSTSE Pointer to STSE Handler
99111
* \param[in] ecdh_key_type ECDH key pair type
100-
* \param[in] host_secure_channel_keys_type Host secure channel keys type
101-
* \param[in] host_mac_key Pointer to the host mac key buffer
102-
* \param[in] host_cipher_key Pointer to the host cipher key buffer
112+
* \param[in] host_secure_channel_keys_type Host secure channel keys type
113+
* \param[out] host_mac_key_index Index of the MAC key in platform secure storage to be used under the session
114+
* \param[out] host_cipher_key_index Index of the cipher key in platform secure storage to be used under the session
103115
* \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
104116
* \details \include{doc} stse_host_key_provisioning.dox
105117
*/
106-
stse_ReturnCode_t stse_establish_host_key(
118+
stse_ReturnCode_t stse_establish_host_secure_channel_keys(
107119
stse_Handle_t *pSTSE,
108120
stse_ecc_key_type_t ecdh_key_type,
109-
stsafea_host_key_type_t host_secure_channel_keys_type,
110-
PLAT_UI8 *host_mac_key,
111-
PLAT_UI8 *host_cipher_key);
121+
stse_aes_key_type_t host_secure_channel_keys_type,
122+
PLAT_UI32 *host_mac_key_index,
123+
PLAT_UI32 *host_cipher_key_index);
112124

113125
/**
114-
* \brief Host key establishment authenticated
115-
* \details This API establish host key after verifying entity signature (from STSAFE-A120)
126+
* \brief Host secure channel keys establishment authenticated
127+
* \details This API establish host secure channel keys after verifying entity signature (from STSAFE-A120)
116128
* \param[in] pSTSE Pointer to STSE Handler
117129
* \param[in] ecdh_key_type ECDH key pair type
118130
* \param[in] host_secure_channel_keys_type Host secure channel keys type
119131
* \param[in] tbs_hash_algo Hashing algorithm used for the signature
120132
* \param[in] tbs_public_key_slot Public key slot used for the signature
121133
* \param[in] tbs_private_key Private key associated to public key slot used for the signature
122-
* \param[in] host_mac_key Pointer to the host mac key buffer
123-
* \param[in] host_cipher_key Pointer to the host cipher key buffer
134+
* \param[out] host_mac_key_index Index of the MAC key in platform secure storage to be used under the session
135+
* \param[out] host_cipher_key_index Index of the cipher key in platform secure storage to be used under the session
124136
* \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
125137
* \details \include{doc} stse_host_key_provisioning.dox
126138
* \warning Few specific cryptographic library required to have public key concatenated to private key for EdDSA mechanism. In such case, pPrivate_key pointer shall reference concatenated key pair buffer's address.
127139
*/
128-
stse_ReturnCode_t stse_establish_host_key_authenticated(
140+
stse_ReturnCode_t stse_establish_host_secure_channel_keys_authenticated(
129141
stse_Handle_t *pSTSE,
130142
stse_ecc_key_type_t ecdh_key_type,
131-
stsafea_host_key_type_t host_secure_channel_keys_type,
143+
stse_aes_key_type_t host_secure_channel_keys_type,
132144
stse_hash_algorithm_t tbs_hash_algo,
133145
PLAT_UI8 tbs_public_key_slot,
134146
PLAT_UI8 *tbs_private_key,
135-
PLAT_UI8 *host_mac_key,
136-
PLAT_UI8 *host_cipher_key);
147+
PLAT_UI32 *host_mac_key_index,
148+
PLAT_UI32 *host_cipher_key_index);
137149

138150
/**
139151
* \brief Get symmetric key slot count

‎core/stse_generic_typedef.h‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,16 +108,19 @@ typedef enum stse_ecc_key_type_t {
108108
*/
109109
typedef enum stse_aes_key_type_t {
110110
STSE_AES_128_KT = 0x00,
111-
STSE_AES_256_KT
111+
STSE_AES_256_KT,
112+
STSE_AES_INVALID_KT
112113
} stse_aes_key_type_t;
113114

114115
/*!
115116
* \enum stse_aes_key_usage_t
116117
* \brief STSE AES key usage
117118
*/
118119
typedef enum stse_aes_key_usage_t {
119-
STSE_AES_KEY_USAGE_MAC = 0, /**< Key used for MAC operations (CMAC) */
120-
STSE_AES_KEY_USAGE_CIPHER /**< Key used for cipher operations (CBC, ECB) */
120+
STSE_AES_KEY_USAGE_MAC = 0, /**< Key used for host MAC operations */
121+
STSE_AES_KEY_USAGE_CIPHER, /**< Key used for host cipher operations */
122+
STSE_AES_KEY_USAGE_GENERIC_SECRET, /**< Generic secret: AES key with variable-length keys (from 16 to 32 bytes) */
123+
STSE_AES_KEY_USAGE_INVALID
121124
} stse_aes_key_usage_t;
122125

123126
/*!
@@ -173,6 +176,17 @@ typedef enum stse_cmd_protection_t {
173176
STSE_HOST_C_WRAP_R_WRAP /*!< Encrypted and authenticated command and response using HOST MAC and cipher Keys*/
174177
} stse_cmd_protection_t;
175178

179+
/*!
180+
* \struct stse_aes_key_t
181+
* \brief STSE AES key type
182+
*/
183+
typedef struct
184+
{
185+
stse_aes_key_type_t type;
186+
stse_aes_key_usage_t usage;
187+
PLAT_UI8 key[STSE_AES_256_KEY_SIZE];
188+
} stse_aes_key_t;
189+
176190
/*!
177191
* \struct stse_cmd_authorization_CR_t
178192
* \brief STSE commands authorization change request type

‎services/stsafea/stsafea_host_key_slot.c‎

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -155,17 +155,20 @@ stse_ReturnCode_t stsafea_query_host_key_v2(
155155
stsafea_cmd_timings[pSTSE->device_type][cmd_header]);
156156
}
157157

158-
stse_ReturnCode_t stsafea_put_attribute_host_key(
158+
stse_ReturnCode_t stsafea_put_attribute_host_secure_channel_keys(
159159
stse_Handle_t *pSTSE,
160-
stsafea_aes_128_host_keys_t *host_keys) {
160+
stse_aes_key_t *host_mac_key,
161+
stse_aes_key_t *host_cipher_key) {
161162
PLAT_UI8 cmd_header = STSAFEA_CMD_PUT_ATTRIBUTE;
162163

163164
/* - Check stsafe handler initialization */
164165
if (pSTSE == NULL) {
165166
return (STSE_SERVICE_HANDLER_NOT_INITIALISED);
166167
}
167168

168-
if (host_keys == NULL) {
169+
if (host_mac_key == NULL || host_cipher_key == NULL || host_mac_key->type != host_cipher_key->type ||
170+
host_mac_key->type != STSE_AES_128_KT || host_cipher_key->type != STSE_AES_128_KT ||
171+
host_mac_key->usage != STSE_AES_KEY_USAGE_MAC || host_cipher_key->usage != STSE_AES_KEY_USAGE_CIPHER) {
169172
return (STSE_SERVICE_INVALID_PARAMETER);
170173
}
171174

@@ -175,7 +178,8 @@ stse_ReturnCode_t stsafea_put_attribute_host_key(
175178
stse_frame_allocate(CmdFrame);
176179
stse_frame_element_allocate_push(&CmdFrame, eCmd_header, STSAFEA_HEADER_SIZE, &cmd_header);
177180
stse_frame_element_allocate_push(&CmdFrame, eSubject_tag, 1, &subject_tag);
178-
stse_frame_element_allocate_push(&CmdFrame, eHost_keys, sizeof(stsafea_aes_128_host_keys_t), (PLAT_UI8 *)host_keys);
181+
stse_frame_element_allocate_push(&CmdFrame, e_host_mac_key, STSE_AES_128_KEY_SIZE, host_mac_key->key);
182+
stse_frame_element_allocate_push(&CmdFrame, e_host_cipher_key, STSE_AES_128_KEY_SIZE, host_cipher_key->key);
179183

180184
stse_frame_allocate(RspFrame);
181185
stse_frame_element_allocate_push(&RspFrame, eRsp_header, STSAFEA_HEADER_SIZE, &rsp_header);
@@ -187,31 +191,34 @@ stse_ReturnCode_t stsafea_put_attribute_host_key(
187191
stsafea_cmd_timings[pSTSE->device_type][cmd_header]);
188192
}
189193

190-
stse_ReturnCode_t stsafea_host_key_provisioning(
194+
stse_ReturnCode_t stsafea_host_secure_channel_keys_provisioning(
191195
stse_Handle_t *pSTSE,
192-
stsafea_host_key_type_t key_type,
193-
stsafea_host_keys_t *host_keys) {
196+
stse_aes_key_t *host_mac_key,
197+
stse_aes_key_t *host_cipher_key) {
194198
PLAT_UI8 cmd_header[STSAFEA_EXT_HEADER_SIZE] = {STSAFEA_EXTENDED_COMMAND_PREFIX, STSAFEA_EXTENDED_CMD_WRITE_HOST_KEY_V2_PLAINTEXT};
195199

196200
/* - Check stsafe handler initialization */
197201
if (pSTSE == NULL) {
198202
return (STSE_SERVICE_HANDLER_NOT_INITIALISED);
199203
}
200204

201-
if (key_type == STSAFEA_AES_INVALID_HOST_KEY || host_keys == NULL) {
205+
if (host_mac_key == NULL || host_cipher_key == NULL || host_mac_key->type != host_cipher_key->type ||
206+
host_mac_key->type >= STSE_AES_INVALID_KT || host_cipher_key->type >= STSE_AES_INVALID_KT ||
207+
host_mac_key->usage != STSE_AES_KEY_USAGE_MAC || host_cipher_key->usage != STSE_AES_KEY_USAGE_CIPHER) {
202208
return (STSE_SERVICE_INVALID_PARAMETER);
203209
}
204210

205-
PLAT_UI8 host_keys_length = (key_type == STSAFEA_AES_128_HOST_KEY ? STSAFEA_HOST_AES_128_KEYS_SIZE : STSAFEA_HOST_AES_256_KEYS_SIZE);
211+
PLAT_UI8 host_keys_length = (host_mac_key->type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE;
206212

207213
PLAT_UI8 pPadding[3] = {0};
208214
PLAT_UI8 rsp_header;
209215

210216
stse_frame_allocate(CmdFrame);
211217
stse_frame_element_allocate_push(&CmdFrame, eCmd_header, STSAFEA_EXT_HEADER_SIZE, cmd_header);
212218
stse_frame_element_allocate_push(&CmdFrame, ePadding, 3, pPadding);
213-
stse_frame_element_allocate_push(&CmdFrame, eKey_type, 1, (PLAT_UI8 *)&key_type);
214-
stse_frame_element_allocate_push(&CmdFrame, eHost_keys, host_keys_length, (PLAT_UI8 *)host_keys);
219+
stse_frame_element_allocate_push(&CmdFrame, eKey_type, 1, (PLAT_UI8 *)host_mac_key->type);
220+
stse_frame_element_allocate_push(&CmdFrame, e_host_mac_key, host_keys_length, host_mac_key->key);
221+
stse_frame_element_allocate_push(&CmdFrame, e_host_cipher_key, host_keys_length, host_cipher_key->key);
215222

216223
stse_frame_allocate(RspFrame);
217224
stse_frame_element_allocate_push(&RspFrame, eRsp_header, STSAFEA_HEADER_SIZE, &rsp_header);
@@ -222,9 +229,9 @@ stse_ReturnCode_t stsafea_host_key_provisioning(
222229
&RspFrame);
223230
}
224231

225-
stse_ReturnCode_t stsafea_host_key_provisioning_wrapped(
232+
stse_ReturnCode_t stsafea_host_secure_channel_keys_provisioning_wrapped(
226233
stse_Handle_t *pSTSE,
227-
stsafea_host_key_type_t key_type,
234+
stse_aes_key_type_t key_type,
228235
PLAT_UI8 *pHost_key_envelope) {
229236
PLAT_UI8 cmd_header[STSAFEA_EXT_HEADER_SIZE] = {STSAFEA_EXTENDED_COMMAND_PREFIX, STSAFEA_EXTENDED_CMD_WRITE_HOST_KEY_V2_WRAPPED};
230237

@@ -233,11 +240,11 @@ stse_ReturnCode_t stsafea_host_key_provisioning_wrapped(
233240
return (STSE_SERVICE_HANDLER_NOT_INITIALISED);
234241
}
235242

236-
if (key_type == STSAFEA_AES_INVALID_HOST_KEY || pHost_key_envelope == NULL) {
243+
if (key_type > STSE_AES_INVALID_KT || pHost_key_envelope == NULL) {
237244
return (STSE_SERVICE_INVALID_PARAMETER);
238245
}
239246

240-
PLAT_UI8 host_keys_envelope_length = key_type == STSAFEA_AES_128_HOST_KEY ? STSAFEA_HOST_AES_128_KEYS_ENVELOPE_SIZE : STSAFEA_HOST_AES_256_KEYS_ENVELOPE_SIZE;
247+
PLAT_UI8 host_keys_envelope_length = (key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE;
241248

242249
PLAT_UI8 rsp_header;
243250

@@ -254,19 +261,19 @@ stse_ReturnCode_t stsafea_host_key_provisioning_wrapped(
254261
&RspFrame);
255262
}
256263

257-
stse_ReturnCode_t stsafea_establish_host_key(
264+
stse_ReturnCode_t stsafea_establish_host_secure_channel_keys(
258265
stse_Handle_t *pSTSE,
259266
stse_ecc_key_type_t host_ecdh_public_key_type,
260267
PLAT_UI8 *pPublic_key,
261-
stsafea_host_key_type_t host_keys_type) {
268+
stse_aes_key_type_t host_keys_type) {
262269
PLAT_UI8 cmd_header[STSAFEA_EXT_HEADER_SIZE] = {STSAFEA_EXTENDED_COMMAND_PREFIX, STSAFEA_EXTENDED_CMD_ESTABLISH_HOST_KEY_V2};
263270

264271
/* - Check stsafe handler initialization */
265272
if (pSTSE == NULL) {
266273
return (STSE_SERVICE_HANDLER_NOT_INITIALISED);
267274
}
268275

269-
if ((host_ecdh_public_key_type >= STSE_ECC_KT_INVALID) || (pPublic_key == NULL) || (host_keys_type >= STSAFEA_AES_INVALID_HOST_KEY)) {
276+
if ((host_ecdh_public_key_type >= STSE_ECC_KT_INVALID) || (pPublic_key == NULL) || (host_keys_type >= STSE_AES_INVALID_KT)) {
270277
return (STSE_SERVICE_INVALID_PARAMETER);
271278
}
272279

@@ -322,11 +329,11 @@ stse_ReturnCode_t stsafea_establish_host_key(
322329
&RspFrame);
323330
}
324331

325-
stse_ReturnCode_t stsafea_establish_host_key_authenticated(
332+
stse_ReturnCode_t stsafea_establish_host_secure_channel_keys_authenticated(
326333
stse_Handle_t *pSTSE,
327334
stse_ecc_key_type_t host_ecdh_public_key_type,
328335
PLAT_UI8 *pPublic_key,
329-
stsafea_host_key_type_t host_keys_type,
336+
stse_aes_key_type_t host_keys_type,
330337
PLAT_UI8 signature_public_key_slot,
331338
stse_ecc_key_type_t signature_public_key_type,
332339
stse_hash_algorithm_t signature_hash_algo,
@@ -339,7 +346,7 @@ stse_ReturnCode_t stsafea_establish_host_key_authenticated(
339346
}
340347

341348
if ((host_ecdh_public_key_type >= STSE_ECC_KT_INVALID) || (pPublic_key == NULL) ||
342-
(host_keys_type >= STSAFEA_AES_INVALID_HOST_KEY) || (signature_public_key_type >= STSE_ECC_KT_INVALID) ||
349+
(host_keys_type >= STSE_AES_INVALID_KT) || (signature_public_key_type >= STSE_ECC_KT_INVALID) ||
343350
(signature_hash_algo >= STSE_SHA_INVALID) || (pSignature == NULL)) {
344351
return (STSE_SERVICE_INVALID_PARAMETER);
345352
}

0 commit comments

Comments
 (0)