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