1 /***************************************************************************//**
2  * @file
3  * @brief Silicon Labs Secure Engine Manager key handling.
4  *******************************************************************************
5  * # License
6  * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b>
7  *******************************************************************************
8  *
9  * SPDX-License-Identifier: Zlib
10  *
11  * The licensor of this software is Silicon Laboratories Inc.
12  *
13  * This software is provided 'as-is', without any express or implied
14  * warranty. In no event will the authors be held liable for any damages
15  * arising from the use of this software.
16  *
17  * Permission is granted to anyone to use this software for any purpose,
18  * including commercial applications, and to alter it and redistribute it
19  * freely, subject to the following restrictions:
20  *
21  * 1. The origin of this software must not be misrepresented; you must not
22  *    claim that you wrote the original software. If you use this software
23  *    in a product, an acknowledgment in the product documentation would be
24  *    appreciated but is not required.
25  * 2. Altered source versions must be plainly marked as such, and must not be
26  *    misrepresented as being the original software.
27  * 3. This notice may not be removed or altered from any source distribution.
28  *
29  ******************************************************************************/
30 #ifndef SL_SE_MANAGER_KEY_HANDLING_H
31 #define SL_SE_MANAGER_KEY_HANDLING_H
32 
33 #include "sli_se_manager_features.h"
34 
35 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED)
36 
37 /// @addtogroup sl_se_manager
38 /// @{
39 
40 #include "sl_se_manager_types.h"
41 #include "sl_status.h"
42 #include <stdint.h>
43 #include <stdbool.h>
44 #include <stddef.h>
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 /***************************************************************************//**
51  * \addtogroup sl_se_manager_key_handling Key handling
52  *
53  * \brief Secure Engine key handling API.
54  *
55  * \details
56  *   API for using cryptographic keys with the SE. Contains functionality to
57  *   generate, import and export keys to and from protected types like wrapped
58  *   or volatile keys.
59  *
60  * \{
61  ******************************************************************************/
62 
63 // -----------------------------------------------------------------------------
64 // Prototypes
65 
66 /***************************************************************************//**
67  * @brief
68  *   Validate key descriptor.
69  *
70  * @details
71  *   Takes a key descriptor and checks if all required properties have been set
72  *   for the specific key type.
73  *
74  * @param[in] key
75  *   The key to validate.
76  *
77  * @return
78  *   Status code, @ref sl_status.h.
79  ******************************************************************************/
80 sl_status_t sl_se_validate_key(const sl_se_key_descriptor_t *key);
81 
82 /***************************************************************************//**
83  * @brief
84  *   Generate a random key adhering to the given key descriptor
85  *
86  * @details
87  *   The SE takes a key descriptor and generates a key with the given properties
88  *   in the location specified by the descriptor.
89  *
90  *   If the key size is not aligned to a multiple of words the key
91  *   representation is padded in front of the key.
92  *
93  * @param[in] cmd_ctx
94  *   Pointer to an SE command context object.
95  *
96  * @param[in] key_out
97  *   Description of the key to generate. Sets key parameters and describes the
98  *   storage location for the key.
99  *
100  * @return
101  *   Status code, @ref sl_status.h.
102  ******************************************************************************/
103 sl_status_t sl_se_generate_key(sl_se_command_context_t *cmd_ctx,
104                                const sl_se_key_descriptor_t *key_out);
105 
106 /***************************************************************************//**
107  * @brief
108  *   Import a key using the SE
109  *
110  * @details
111  *   Protect a key using the SE. Import a plaintext key and store it either in a
112  *   volatile slot or as a wrapped key.
113  *
114  * @param[in] cmd_ctx
115  *   Pointer to an SE command context object.
116  *
117  * @param[in] key_in
118  *   A plaintext key.
119  *
120  * @param[in] key_out
121  *   Either a volatile or a wrapped key with similar properties as key_in.
122  *
123  * @return
124  *   Status code, @ref sl_status.h.
125  ******************************************************************************/
126 sl_status_t sl_se_import_key(sl_se_command_context_t *cmd_ctx,
127                              const sl_se_key_descriptor_t *key_in,
128                              const sl_se_key_descriptor_t *key_out);
129 
130 /***************************************************************************//**
131  * @brief
132  *   Export a volatile or wrapped key back to plaintext
133  *
134  * @details
135  *   Attempt to have the SE export a volatile or wrapped key back to plaintext
136  *   if allowed.
137  *
138  * @param[in] cmd_ctx
139  *   Pointer to an SE command context object.
140  *
141  * @param[in] key_in
142  *   Either a volatile or a wrapped key with similar properties as key_out.
143  *
144  * @param[in] key_out
145  *   The exported key in plaintext.
146  *
147  * @return
148  *   Status code, @ref sl_status.h.
149  *   SL_STATUS_INVALID_PARAMETER if key does not exist.
150  ******************************************************************************/
151 sl_status_t sl_se_export_key(sl_se_command_context_t *cmd_ctx,
152                              const sl_se_key_descriptor_t *key_in,
153                              const sl_se_key_descriptor_t *key_out);
154 
155 /***************************************************************************//**
156  * @brief
157  *   Transfer a volatile or wrapped key to another protected storage.
158  *
159  * @details
160  *   Attempt to have the SE transfer a volatile or wrapped key if allowed.
161  *
162  * @note
163  *   The key stored in the source protected storage will not be deleted.
164  *
165  *   Transferring a key between the same volatile slot is not allowed.
166  *
167  * @param[in] cmd_ctx
168  *   Pointer to an SE command context object.
169  *
170  * @param[in] key_in
171  *   Either a volatile or a wrapped key with similar properties as key_out.
172  *
173  * @param[in] key_out
174  *   Either a volatile or a wrapped key with similar properties as key_in.
175  *
176  * @return
177  *   Status code, @ref sl_status.h.
178  *   SL_STATUS_INVALID_PARAMETER if key does not exist.
179  ******************************************************************************/
180 sl_status_t sl_se_transfer_key(sl_se_command_context_t *cmd_ctx,
181                                const sl_se_key_descriptor_t *key_in,
182                                const sl_se_key_descriptor_t *key_out);
183 
184 /***************************************************************************//**
185  * @brief
186  *   Export the public part of an ECC keypair
187  *
188  * @details
189  *   The output key must be specified to only contain a public key.
190  *
191  * @param[in] cmd_ctx
192  *   Pointer to an SE command context object.
193  *
194  * @param[in] key_in
195  *   An asymmetric key with either a private or public part.
196  *
197  * @param[out] key_out
198  *   Describes output key parameters. Should only be set to contain the public
199  *   part of the key.
200  *
201  * @return
202  *   Status code, @ref sl_status.h.
203  ******************************************************************************/
204 sl_status_t sl_se_export_public_key(sl_se_command_context_t *cmd_ctx,
205                                     const sl_se_key_descriptor_t *key_in,
206                                     const sl_se_key_descriptor_t *key_out);
207 
208 /***************************************************************************//**
209  * @brief
210  *   Delete a key from a volatile SE storage slot
211  *
212  * @details
213  *   The given key will be removed from the SE. The key descriptor is not
214  *   modified and can be used to generate a new key without any updates.
215  *
216  * @param[in] cmd_ctx
217  *   Pointer to an SE command context object.
218  *
219  * @param[in] key
220  *   Key to delete.
221  *
222  * @return
223  *   Status code, @ref sl_status.h.
224  ******************************************************************************/
225 sl_status_t sl_se_delete_key(sl_se_command_context_t *cmd_ctx,
226                              const sl_se_key_descriptor_t *key);
227 
228 /***************************************************************************//**
229  * @brief
230  *   Returns the required storage size for the given key
231  *
232  * @details
233  *   Finds the total storage size required for a given key. This includes
234  *   storage for the public and private part of asymmetric keys, as well as
235  *   overhead for wrapping keys.
236  *
237  * @param[in] key
238  *   The sl_se_key_descriptor_t to find the required storage size for.
239  *
240  * @param[out] storage_size
241  *   The required storage size in bytes.
242  *
243  * @return
244  *   Status code, @ref sl_status.h.
245  ******************************************************************************/
246 sl_status_t sl_se_get_storage_size(const sl_se_key_descriptor_t *key,
247                                    uint32_t *storage_size);
248 
249 #ifdef __cplusplus
250 }
251 #endif
252 
253 /** @} (end addtogroup sl_se_key) */
254 /** @} (end addtogroup sl_se) */
255 
256 #endif // defined(SLI_MAILBOX_COMMAND_SUPPORTED)
257 
258 #endif // SL_SE_MANAGER_KEY_HANDLING_H
259