Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
sec_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief AES and random number security service API.
6  *
7  * Copyright (c) 2010-2019 Arm Ltd. All Rights Reserved.
8  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 #ifndef SEC_API_H
25 #define SEC_API_H
26 
27 #include "wsf_types.h"
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /*! \addtogroup STACK_SECURITY_API
34  * \{ */
35 
36 /**************************************************************************************************
37  Macros
38 **************************************************************************************************/
39 
40 /*! \brief CMAC algorithm key length. */
41 #define SEC_CMAC_KEY_LEN 16
42 
43 /*! \brief CMAC algorithm key length. */
44 #define SEC_AES_BLK_LEN 16
45 
46 /*! \brief CMAC algorithm result length. */
47 #define SEC_CMAC_HASH_LEN 16
48 
49 /*! \brief ECC algorithm key length. */
50 #define SEC_ECC_KEY_LEN 32
51 
52 /** \name CCM-Mode algorithm lengths
53  *
54  */
55 /**@{*/
56 #define SEC_CCM_KEY_LEN 16
57 #define SEC_CCM_MAX_ADDITIONAL_LEN ((1<<16) - (1<<8))
58 #define SEC_CCM_L 2
59 #define SEC_CCM_NONCE_LEN (15-SEC_CCM_L)
60 /**@}*/
61 
62 /*! \brief Invalid AES Token. */
63 #define SEC_TOKEN_INVALID 0xFF
64 
65 /**************************************************************************************************
66  Data Types
67 **************************************************************************************************/
68 
69 /*! \brief AES Security callback parameters structure. */
70 typedef struct
71 {
72  wsfMsgHdr_t hdr; /*!< Header. */
73  uint8_t *pCiphertext; /*!< Pointer to 16 bytes of ciphertext data. */
74 } secAes_t;
75 
76 /*! \brief CMAC Security callback parameters structure. */
77 typedef struct
78 {
79  wsfMsgHdr_t hdr; /*!< Header. */
80  uint8_t *pCiphertext; /*!< Pointer to 16 bytes of ciphertext data. */
81  uint8_t *pPlainText; /*!< Pointer to pPlaintext parameter passed to SecCmac. */
82 } secCmacMsg_t;
83 
84 /*! \brief CCM-Mode encrypt callback parameters structure. */
85 typedef struct
86 {
87  wsfMsgHdr_t hdr; /*!< Header. */
88  uint8_t *pCiphertext; /*!< Pointer to ciphertext data. */
89  uint16_t textLen; /*!< Length of pCiphertext in bytes. */
90 } secCcmEncMsg_t;
91 
92 /*! \brief CCM-Mode decrypt and authenticate callback parameters structure. */
93 typedef struct
94 {
95  wsfMsgHdr_t hdr; /*!< Header. */
96  uint8_t *pText; /*!< Pointer to decrypted text within result buffer. */
97  uint8_t *pResult; /*!< Pointer to result buffer (passed into SecCcmDec). */
98  uint16_t textLen; /*!< Length of pText in bytes. */
99  bool_t success; /*!< TRUE if message is authenticated. */
100 } secCcmDecMsg_t;
101 
102 /*! \brief Generic security callback parameters structure. */
103 typedef union
104 {
105  wsfMsgHdr_t hdr; /*!< Header. */
106  secAes_t aes; /*!< AES complete message. */
107  secCmacMsg_t cmac; /*!< CMAC complete message. */
108  secCcmEncMsg_t ccmEnc; /*!< CCM-Mode Encrypt complete message. */
109  secCcmDecMsg_t ccmDec; /*!< CCM-Mode Decrypt complete message. */
110 } secMsg_t;
111 
112 /*! \brief ECC Security public/private key pair. */
113 typedef struct
114 {
115  uint8_t pubKey_x[SEC_ECC_KEY_LEN]; /*!< x component of ECC public key. */
116  uint8_t pubKey_y[SEC_ECC_KEY_LEN]; /*!< y component of ECC public key. */
117  uint8_t privKey[SEC_ECC_KEY_LEN]; /*!< ECC private key. */
118 } secEccKey_t;
119 
120 /*! \brief ECC security DH Key shared secret. */
121 typedef struct
122 {
123  uint8_t secret[SEC_ECC_KEY_LEN]; /*!< DH Key Shared secret. */
124 } secEccSharedSec_t;
125 
126 
127 /*! \brief ECC Security callback parameters structure. */
128 typedef struct
129 {
130  wsfMsgHdr_t hdr; /*!< Header. */
131  union
132  {
133  secEccSharedSec_t sharedSecret; /*!< Shared secret. */
134  secEccKey_t key; /*!< ECC public/private key pair. */
135  bool_t keyValid; /*!< TRUE if ECC public/private key pair is valid. */
136  } data; /*!< ECC message data union. */
137 } secEccMsg_t;
138 
139 /*! \brief Block encryption function. */
140 typedef void (*SecBlkEncFunc_t)(uint8_t *pKey, uint8_t *pMessage, void *pParam);
141 
142 /**************************************************************************************************
143  Function Declarations
144 **************************************************************************************************/
145 
146 /** \name Security Initialization Functions
147  *
148  */
149 /**@{*/
150 
151 /*************************************************************************************************/
152 /*!
153  * \brief Initialize the security service. This function should only be called once
154  * upon system initialization.
155  *
156  * \return None.
157  */
158 /*************************************************************************************************/
159 void SecInit(void);
160 
161 /*************************************************************************************************/
162 /*!
163  * \brief Initialize the random number service. This function should only be called once
164  * upon system initialization.
165  *
166  * \return None.
167  */
168 /*************************************************************************************************/
169 void SecRandInit(void);
170 
171 /*************************************************************************************************/
172 /*!
173  * \brief Initialize the AES service. This function should only be called once
174  * upon system initialization.
175  *
176  * \return None.
177  */
178 /*************************************************************************************************/
179 void SecAesInit(void);
180 
181 /*************************************************************************************************/
182 /*!
183  * \brief Initialize the AES (reverse) service. This function should only be called once
184  * upon system initialization.
185  *
186  * \return None.
187  */
188 /*************************************************************************************************/
189 void SecAesRevInit(void);
190 
191 /*************************************************************************************************/
192 /*!
193  * \brief Called to initialize CMAC security. This function should only be called once
194  * upon system initialization.
195  *
196  * \return None.
197  */
198 /*************************************************************************************************/
199 void SecCmacInit(void);
200 
201 /*************************************************************************************************/
202 /*!
203  * \brief Called to initialize CCM security.
204  *
205  * \return None.
206  */
207 /*************************************************************************************************/
208 void SecCcmInit(void);
209 
210 /*************************************************************************************************/
211 /*!
212  * \brief Called to initialize ECC security. This function should only be called once
213  * upon system initialization.
214  *
215  * \return None.
216  */
217 /*************************************************************************************************/
218 void SecEccInit(void);
219 
220 /**@}*/
221 
222 /** \name Security AES, CMAC and CCM Functions
223  *
224  */
225 /**@{*/
226 
227 /*************************************************************************************************/
228 /*!
229  * \brief Execute an AES calculation. When the calculation completes, a WSF message will be
230  * sent to the specified handler. This function returns a token value that
231  * the client can use to match calls to this function with messages.
232  *
233  * \param pKey Pointer to 16 byte key.
234  * \param pPlaintext Pointer to 16 byte plaintext.
235  * \param handlerId WSF handler ID.
236  * \param param Client-defined parameter returned in message.
237  * \param event Event for client's WSF handler.
238  *
239  * \return Token value.
240  */
241 /*************************************************************************************************/
242 uint8_t SecAes(uint8_t *pKey, uint8_t *pPlaintext, wsfHandlerId_t handlerId,
243  uint16_t param, uint8_t event);
244 
245 /*************************************************************************************************/
246 /*!
247  * \brief Execute an AES calculation. When the calculation completes, a WSF message will be
248  * sent to the specified handler. This function returns a token value that
249  * the client can use to match calls to this function with messages. Note this version
250  * reverses the key and plaintext bytes.
251  *
252  * \param pKey Pointer to 16 byte key.
253  * \param pPlaintext Pointer to 16 byte plaintext.
254  * \param handlerId WSF handler ID.
255  * \param param Client-defined parameter returned in message.
256  * \param event Event for client's WSF handler.
257  *
258  * \return Token value.
259  */
260 /*************************************************************************************************/
261 uint8_t SecAesRev(uint8_t *pKey, uint8_t *pPlaintext, wsfHandlerId_t handlerId,
262  uint16_t param, uint8_t event);
263 
264 /*************************************************************************************************/
265 /*!
266  * \brief Execute the CMAC algorithm.
267  *
268  * \param pKey Key used in CMAC operation.
269  * \param pPlaintext Plain text buffer - buffer must persist until secCmacMsg_t callback.
270  * \param textLen Size of pPlaintext in bytes.
271  * \param handlerId WSF handler ID for client.
272  * \param param Optional parameter sent to client's WSF handler.
273  * \param event Event for client's WSF handler.
274  *
275  * \return TRUE if successful, else FALSE.
276  */
277 /*************************************************************************************************/
278 bool_t SecCmac(const uint8_t *pKey, uint8_t *pPlaintext, uint16_t textLen, wsfHandlerId_t handlerId,
279  uint16_t param, uint8_t event);
280 
281 /*************************************************************************************************/
282 /*!
283  * \brief Execute the CCM-Mode encryption algorithm.
284  *
285  * \param pKey Pointer to encryption key (SEC_CCM_KEY_LEN bytes).
286  * \param pNonce Pointer to nonce (SEC_CCM_NONCE_LEN bytes).
287  * \param pPlainText Pointer to text to encrypt.
288  * \param textLen Length of pPlainText in bytes.
289  * \param pClear Pointer to additional, unencrypted authentication text.
290  * \param clearLen Length of pClear in bytes.
291  * \param micLen Size of MIC in bytes (4, 8 or 16).
292  * \param pResult Buffer to hold result (returned in complete event).
293  * \param handlerId Task handler ID to receive complete event.
294  * \param param Optional parameter passed in complete event.
295  * \param event Event ID of complete event.
296 
297  * \return TRUE if successful, else FALSE.
298  */
299 /*************************************************************************************************/
300 bool_t SecCcmEnc(const uint8_t *pKey, uint8_t *pNonce, uint8_t *pPlainText, uint16_t textLen,
301  uint8_t *pClear, uint16_t clearLen, uint8_t micLen, uint8_t *pResult,
302  wsfHandlerId_t handlerId, uint16_t param, uint8_t event);
303 
304 /*************************************************************************************************/
305 /*!
306  * \brief Execute the CCM-Mode verify and decrypt algorithm.
307  *
308  * \param pKey Pointer to encryption key (SEC_CCM_KEY_LEN bytes).
309  * \param pNonce Pointer to nonce (SEC_CCM_NONCE_LEN bytes).
310  * \param pCypherText Pointer to text to decrypt.
311  * \param textLen Length of pCypherText in bytes.
312  * \param pClear Pointer to additional, unencrypted authentication text.
313  * \param clearLen Length of pClear in bytes.
314  * \param pMic Pointer to authentication digest.
315  * \param micLen Size of MIC in bytes (4, 8 or 16).
316  * \param pResult Buffer to hold result (returned in complete event).
317  * \param handlerId Task handler ID to receive complete event.
318  * \param param Optional parameter passed in complete event.
319  * \param event Event ID of complete event.
320  *
321  * \return TRUE if successful, else FALSE.
322  */
323 /*************************************************************************************************/
324 bool_t SecCcmDec(const uint8_t *pKey, uint8_t *pNonce, uint8_t *pCypherText, uint16_t textLen,
325  uint8_t *pClear, uint16_t clearLen, uint8_t *pMic, uint8_t micLen,
326  uint8_t *pResult, wsfHandlerId_t handlerId, uint16_t param, uint8_t event);
327 
328 /**@}*/
329 
330 /** \name Security ECC Functions
331  *
332  */
333 /**@{*/
334 
335 /*************************************************************************************************/
336 /*!
337  * \brief Generate an ECC key.
338  *
339  * \param handlerId WSF handler ID for client.
340  * \param param Optional parameter sent to client's WSF handler.
341  * \param event Event for client's WSF handler.
342  *
343  * \return TRUE if successful, else FALSE.
344  */
345 /*************************************************************************************************/
346 bool_t SecEccGenKey(wsfHandlerId_t handlerId, uint16_t param, uint8_t event);
347 
348 /*************************************************************************************************/
349 /*!
350  * \brief Generate an ECC key.
351  *
352  * \param pKey ECC Key structure.
353  * \param handlerId WSF handler ID for client.
354  * \param param Optional parameter sent to client's WSF handler.
355  * \param event Event for client's WSF handler.
356  *
357  * \return TRUE if successful, else FALSE.
358  */
359 /*************************************************************************************************/
360 bool_t SecEccGenSharedSecret(secEccKey_t *pKey, wsfHandlerId_t handlerId, uint16_t param, uint8_t event);
361 
362 /**@}*/
363 
364 /** \name Security Random Number Generator Functions
365  *
366  */
367 /**@{*/
368 
369 /*************************************************************************************************/
370 /*!
371  * \brief This function returns up to 16 bytes of random data to a buffer provided by the
372  * client.
373  *
374  * \param pRand Pointer to returned random data.
375  * \param randLen Length of random data.
376  *
377  * \return None.
378  */
379 /*************************************************************************************************/
380 void SecRand(uint8_t *pRand, uint8_t randLen);
381 
382 /**@}*/
383 
384 /*! \} */ /* STACK_SECURITY_API */
385 
386 #ifdef __cplusplus
387 };
388 #endif
389 
390 #endif /* SEC_API_H */
secCmacMsg_t::pPlainText
uint8_t * pPlainText
Definition: sec_api.h:81
secMsg_t::aes
secAes_t aes
Definition: sec_api.h:106
secEccMsg_t::keyValid
bool_t keyValid
Definition: sec_api.h:135
secAes_t::pCiphertext
uint8_t * pCiphertext
Definition: sec_api.h:73
secEccMsg_t
ECC Security callback parameters structure.
Definition: sec_api.h:128
SecAesInit
void SecAesInit(void)
Initialize the AES service. This function should only be called once upon system initialization.
secCcmDecMsg_t::textLen
uint16_t textLen
Definition: sec_api.h:98
SecAes
uint8_t SecAes(uint8_t *pKey, uint8_t *pPlaintext, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute an AES calculation. When the calculation completes, a WSF message will be sent to the specifi...
SecRand
void SecRand(uint8_t *pRand, uint8_t randLen)
This function returns up to 16 bytes of random data to a buffer provided by the client.
secAes_t
AES Security callback parameters structure.
Definition: sec_api.h:70
secEccMsg_t::key
secEccKey_t key
Definition: sec_api.h:134
SecCmac
bool_t SecCmac(const uint8_t *pKey, uint8_t *pPlaintext, uint16_t textLen, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute the CMAC algorithm.
secCmacMsg_t
CMAC Security callback parameters structure.
Definition: sec_api.h:77
secCmacMsg_t::pCiphertext
uint8_t * pCiphertext
Definition: sec_api.h:80
SecCcmInit
void SecCcmInit(void)
Called to initialize CCM security.
secMsg_t
Generic security callback parameters structure.
Definition: sec_api.h:103
secCcmDecMsg_t::success
bool_t success
Definition: sec_api.h:99
SecBlkEncFunc_t
void(* SecBlkEncFunc_t)(uint8_t *pKey, uint8_t *pMessage, void *pParam)
Block encryption function.
Definition: sec_api.h:140
secMsg_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:105
secMsg_t::ccmEnc
secCcmEncMsg_t ccmEnc
Definition: sec_api.h:108
secMsg_t::ccmDec
secCcmDecMsg_t ccmDec
Definition: sec_api.h:109
secCmacMsg_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:79
secCcmDecMsg_t::pText
uint8_t * pText
Definition: sec_api.h:96
secCcmDecMsg_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:95
SecRandInit
void SecRandInit(void)
Initialize the random number service. This function should only be called once upon system initializa...
SecInit
void SecInit(void)
Initialize the security service. This function should only be called once upon system initialization...
secEccMsg_t::sharedSecret
secEccSharedSec_t sharedSecret
Definition: sec_api.h:133
secEccMsg_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:130
secAes_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:72
secMsg_t::cmac
secCmacMsg_t cmac
Definition: sec_api.h:107
SecCmacInit
void SecCmacInit(void)
Called to initialize CMAC security. This function should only be called once upon system initializati...
SecCcmDec
bool_t SecCcmDec(const uint8_t *pKey, uint8_t *pNonce, uint8_t *pCypherText, uint16_t textLen, uint8_t *pClear, uint16_t clearLen, uint8_t *pMic, uint8_t micLen, uint8_t *pResult, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute the CCM-Mode verify and decrypt algorithm.
SecEccInit
void SecEccInit(void)
Called to initialize ECC security. This function should only be called once upon system initializatio...
SecEccGenKey
bool_t SecEccGenKey(wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Generate an ECC key.
secEccSharedSec_t
ECC security DH Key shared secret.
Definition: sec_api.h:121
SecCcmEnc
bool_t SecCcmEnc(const uint8_t *pKey, uint8_t *pNonce, uint8_t *pPlainText, uint16_t textLen, uint8_t *pClear, uint16_t clearLen, uint8_t micLen, uint8_t *pResult, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute the CCM-Mode encryption algorithm.
secEccKey_t
ECC Security public/private key pair.
Definition: sec_api.h:113
wsf_types.h
Platform-independent data types.
SecEccGenSharedSecret
bool_t SecEccGenSharedSecret(secEccKey_t *pKey, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Generate an ECC key.
wsfHandlerId_t
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:80
SecAesRev
uint8_t SecAesRev(uint8_t *pKey, uint8_t *pPlaintext, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute an AES calculation. When the calculation completes, a WSF message will be sent to the specifi...
secCcmEncMsg_t::textLen
uint16_t textLen
Definition: sec_api.h:89
secCcmEncMsg_t::hdr
wsfMsgHdr_t hdr
Definition: sec_api.h:87
SEC_ECC_KEY_LEN
#define SEC_ECC_KEY_LEN
ECC algorithm key length.
Definition: sec_api.h:50
secCcmDecMsg_t::pResult
uint8_t * pResult
Definition: sec_api.h:97
secCcmEncMsg_t
CCM-Mode encrypt callback parameters structure.
Definition: sec_api.h:85
secCcmDecMsg_t
CCM-Mode decrypt and authenticate callback parameters structure.
Definition: sec_api.h:93
secCcmEncMsg_t::pCiphertext
uint8_t * pCiphertext
Definition: sec_api.h:88
wsfMsgHdr_t
Common message structure passed to event handler.
Definition: wsf_os.h:106
SecAesRevInit
void SecAesRevInit(void)
Initialize the AES (reverse) service. This function should only be called once upon system initializa...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.