Cordio Stack and Cordio Profiles  r2p3-02rel0
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-2018 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 /*! \brief Invalid AES Token */
45 #define SEC_TOKEN_INVALID 0xFF
46 
47 /**************************************************************************************************
48  Data Types
49 **************************************************************************************************/
50 /*! \brief AES Security callback parameters structure */
51 typedef struct
52 {
53  wsfMsgHdr_t hdr; /*!< \brief header */
54  uint8_t *pCiphertext; /*!< \brief pointer to 16 bytes of ciphertext data */
55 } secMsg_t;
56 
57 /*! \brief AES Security callback are the same as secMsg_t */
59 
60 /*! \brief CMAC Security callback are the same as secMsg_t */
62 
63 /*! \brief ECC Security public/private key pair */
64 typedef struct
65 {
66  uint8_t pubKey_x[SEC_ECC_KEY_LEN]; /*!< \brief x component of ECC public key */
67  uint8_t pubKey_y[SEC_ECC_KEY_LEN]; /*!< \brief y component of ECC public key */
68  uint8_t privKey[SEC_ECC_KEY_LEN]; /*!< \brief ecc private key */
69 } secEccKey_t;
70 
71 /*! \brief ECC security DH Key shared secret */
72 typedef struct
73 {
74  uint8_t secret[SEC_ECC_KEY_LEN]; /*!< \brief DH Key Shared secret */
76 
77 
78 /*! \brief ECC Security callback parameters structure */
79 typedef struct
80 {
81  wsfMsgHdr_t hdr; /*!< \brief header */
82  union
83  {
84  secEccSharedSec_t sharedSecret; /*!< \brief shared secret */
85  secEccKey_t key; /*!< \brief ECC public/private key pair */
86  } data; /*!< \brief ECC message data union */
87 } secEccMsg_t;
88 
89 
90 /**************************************************************************************************
91  Function Declarations
92 **************************************************************************************************/
93 
94 /** \name Security Initialization Functions
95  *
96  */
97 /**@{*/
98 
99 /*************************************************************************************************/
100 /*!
101  * \brief Initialize the security service. This function should only be called once
102  * upon system initialization.
103  *
104  * \return None.
105  */
106 /*************************************************************************************************/
107 void SecInit(void);
108 
109 /*************************************************************************************************/
110 /*!
111  * \brief Initialize the random number service. This function should only be called once
112  * upon system initialization.
113  *
114  * \return None.
115  */
116 /*************************************************************************************************/
117 void SecRandInit(void);
118 
119 /*************************************************************************************************/
120 /*!
121  * \brief Initialize the AES service. This function should only be called once
122  * upon system initialization.
123  *
124  * \return None.
125  */
126 /*************************************************************************************************/
127 void SecAesInit(void);
128 
129 /*************************************************************************************************/
130 /*!
131  * \brief Called to initialize CMAC security. This function should only be called once
132  * upon system initialization.
133  *
134  * \return None.
135  */
136 /*************************************************************************************************/
137 void SecCmacInit(void);
138 
139 /*************************************************************************************************/
140 /*!
141  * \brief Called to initialize ECC security. This function should only be called once
142  * upon system initialization.
143  *
144  * \return None.
145  */
146 /*************************************************************************************************/
147 void SecEccInit(void);
148 
149 /**@}*/
150 
151 /** \name Security AES and CMAC Functions
152  *
153  */
154 /**@{*/
155 
156 /*************************************************************************************************/
157 /*!
158  * \brief Execute an AES calculation. When the calculation completes, a WSF message will be
159  * sent to the specified handler. This function returns a token value that
160  * the client can use to match calls to this function with messages.
161  *
162  * \param pKey Pointer to 16 byte key.
163  * \param pPlaintext Pointer to 16 byte plaintext.
164  * \param handlerId WSF handler ID.
165  * \param param Client-defined parameter returned in message.
166  * \param event Event for client's WSF handler.
167  *
168  * \return Token value.
169  */
170 /*************************************************************************************************/
171 uint8_t SecAes(uint8_t *pKey, uint8_t *pPlaintext, wsfHandlerId_t handlerId,
172  uint16_t param, uint8_t event);
173 
174 /*************************************************************************************************/
175 /*!
176  * \brief Execute the CMAC algorithm.
177  *
178  * \param pKey Key used in CMAC operation.
179  * \param pPlaintext Data to perform CMAC operation over
180  * \param textLen Size of pPlaintext in bytes.
181  * \param handlerId WSF handler ID for client.
182  * \param param Optional parameter sent to client's WSF handler.
183  * \param event Event for client's WSF handler.
184  *
185  * \return TRUE if successful, else FALSE.
186  */
187 /*************************************************************************************************/
188 bool_t SecCmac(const uint8_t *pKey, uint8_t *pPlaintext, uint8_t textLen, wsfHandlerId_t handlerId,
189  uint16_t param, uint8_t event);
190 
191 /**@}*/
192 
193 /** \name Security ECC Functions
194  *
195  */
196 /**@{*/
197 
198 /*************************************************************************************************/
199 /*!
200  * \brief Generate an ECC key.
201  *
202  * \param handlerId WSF handler ID for client.
203  * \param param Optional parameter sent to client's WSF handler.
204  * \param event Event for client's WSF handler.
205  *
206  * \return TRUE if successful, else FALSE.
207  */
208 /*************************************************************************************************/
209 bool_t SecEccGenKey(wsfHandlerId_t handlerId, uint16_t param, uint8_t event);
210 
211 /*************************************************************************************************/
212 /*!
213  * \brief Generate an ECC key.
214  *
215  * \param pKey ECC Key structure.
216  * \param handlerId WSF handler ID for client.
217  * \param param Optional parameter sent to client's WSF handler.
218  * \param event Event for client's WSF handler.
219  *
220  * \return TRUE if successful, else FALSE.
221  */
222 /*************************************************************************************************/
224 
225 /**@}*/
226 
227 /** \name Security Random Number Generator Functions
228  *
229  */
230 /**@{*/
231 
232 /*************************************************************************************************/
233 /*!
234  * \brief This function returns up to 16 bytes of random data to a buffer provided by the
235  * client.
236  *
237  * \param pRand Pointer to returned random data.
238  * \param randLen Length of random data.
239  *
240  * \return None.
241  */
242 /*************************************************************************************************/
243 void SecRand(uint8_t *pRand, uint8_t randLen);
244 
245 /**@}*/
246 
247 /*! \} */ /* STACK_SECURITY_API */
248 
249 #ifdef __cplusplus
250 };
251 #endif
252 
253 #endif /* SEC_API_H */
secEccSharedSec_t sharedSecret
shared secret
Definition: sec_api.h:84
ECC Security callback parameters structure.
Definition: sec_api.h:79
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.
uint8_t bool_t
Boolean data type.
Definition: wsf_types.h:78
bool_t SecCmac(const uint8_t *pKey, uint8_t *pPlaintext, uint8_t textLen, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Execute the CMAC algorithm.
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...
wsfMsgHdr_t hdr
header
Definition: sec_api.h:53
wsfMsgHdr_t hdr
header
Definition: sec_api.h:81
void SecCmacInit(void)
Called to initialize CMAC security. This function should only be called once upon system initializati...
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:72
ECC Security public/private key pair.
Definition: sec_api.h:64
Platform-independent data types.
bool_t SecEccGenSharedSecret(secEccKey_t *pKey, wsfHandlerId_t handlerId, uint16_t param, uint8_t event)
Generate an ECC key.
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:74
uint8_t * pCiphertext
pointer to 16 bytes of ciphertext data
Definition: sec_api.h:54
AES Security callback parameters structure.
Definition: sec_api.h:51
#define SEC_ECC_KEY_LEN
ECC algorithm key length.
Definition: sec_api.h:42
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
Common message structure passed to event handler.
Definition: wsf_os.h:97
secMsg_t secAes_t
AES Security callback are the same as secMsg_t.
Definition: sec_api.h:58
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
secEccKey_t key
ECC public/private key pair.
Definition: sec_api.h:85
secMsg_t secCmacMsg_t
CMAC Security callback are the same as secMsg_t.
Definition: sec_api.h:61