le_iks_aesMilenage_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_iks_aesMilenage IoT Keystore AES Milenage API
14  *
15  * @ref le_iks_aesMilenage_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This module provides APIs for performing Milenage authentication and key derivation using AES as
20  * the PRP.
21  *
22  * <HR>
23  *
24  * Copyright (C) Sierra Wireless Inc.
25  */
26 /**
27  * @file le_iks_aesMilenage_interface.h
28  *
29  * Legato @ref c_iks API
30  *
31  * Copyright (C) Sierra Wireless Inc.
32  */
33 
34 #ifndef LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
35 #define LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
36 
37 
38 #include "legato.h"
39 
40 // Interface specific includes
41 #include "le_iks_interface.h"
42 
43 // Internal includes for this interface
45 /** @addtogroup le_iks_aesMilenage le_iks_aesMilenage API Reference
46  * @{
47  * @file le_iks_aesMilenage_common.h
48  * @file le_iks_aesMilenage_interface.h **/
49 //--------------------------------------------------------------------------------------------------
50 /**
51  * Type for handler called when a server disconnects.
52  */
53 //--------------------------------------------------------------------------------------------------
55 
56 //--------------------------------------------------------------------------------------------------
57 /**
58  *
59  * Connect the current client thread to the service providing this API. Block until the service is
60  * available.
61  *
62  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
63  * called before any other functions in this API. Normally, ConnectService is automatically called
64  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
65  *
66  * This function is created automatically.
67  */
68 //--------------------------------------------------------------------------------------------------
70 (
71  void
72 );
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  *
77  * Try to connect the current client thread to the service providing this API. Return with an error
78  * if the service is not available.
79  *
80  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
81  * called before any other functions in this API. Normally, ConnectService is automatically called
82  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
83  *
84  * This function is created automatically.
85  *
86  * @return
87  * - LE_OK if the client connected successfully to the service.
88  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
89  * bound.
90  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
91  * - LE_COMM_ERROR if the Service Directory cannot be reached.
92  */
93 //--------------------------------------------------------------------------------------------------
95 (
96  void
97 );
98 
99 //--------------------------------------------------------------------------------------------------
100 /**
101  * Set handler called when server disconnection is detected.
102  *
103  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
104  * to continue without exiting, it should call longjmp() from inside the handler.
105  */
106 //--------------------------------------------------------------------------------------------------
108 (
109  le_iks_aesMilenage_DisconnectHandler_t disconnectHandler,
110  void *contextPtr
111 );
112 
113 //--------------------------------------------------------------------------------------------------
114 /**
115  *
116  * Disconnect the current client thread from the service providing this API.
117  *
118  * Normally, this function doesn't need to be called. After this function is called, there's no
119  * longer a connection to the service, and the functions in this API can't be used. For details, see
120  * @ref apiFilesC_client.
121  *
122  * This function is created automatically.
123  */
124 //--------------------------------------------------------------------------------------------------
126 (
127  void
128 );
129 
130 
131 //--------------------------------------------------------------------------------------------------
132 /**
133  * Calculates the network authentication code MAC-A using the Milenage algorithm set with AES-128 as
134  * the block cipher. Implements the Milenage function f1.
135  *
136  * @return
137  * LE_OK if successful.
138  * LE_BAD_PARAMETER if either K or OPc reference is invalid
139  * or if either K or OPc key type is invalid
140  * or if either randPtr, amfPtr, sqnPtr, or macaPtr is NULL.
141  * LE_UNSUPPORTED if underlying resource does not support this operation.
142  * LE_FAULT if there was an internal error.
143  */
144 //--------------------------------------------------------------------------------------------------
146 (
147  uint64_t kRef,
148  ///< [IN] Reference to K.
149  uint64_t opcRef,
150  ///< [IN] Reference to OPc.
151  const uint8_t* randPtr,
152  ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
153  size_t randSize,
154  ///< [IN]
155  const uint8_t* amfPtr,
156  ///< [IN] Authentication management field, AMF.
157  ///< Assumed to be AMF_SIZE bytes.
158  size_t amfSize,
159  ///< [IN]
160  const uint8_t* sqnPtr,
161  ///< [IN] Sequence number, SQN.
162  ///< Assumed to be SQN_SIZE bytes.
163  size_t sqnSize,
164  ///< [IN]
165  uint8_t* macaPtr,
166  ///< [OUT] Buffer to hold the network authentication code.
167  ///< Assumed to be MACA_SIZE bytes.
168  size_t* macaSizePtr
169  ///< [INOUT]
170 );
171 
172 //--------------------------------------------------------------------------------------------------
173 /**
174  * Calculates the re-synchronisation authentication code MAC-S using the Milenage algorithm set with
175  * AES-128 as the block cipher. Implements the Milenage function f1*.
176  *
177  * @return
178  * LE_OK if successful.
179  * LE_BAD_PARAMETER if either K or OPc reference is invalid
180  * or if either K or OPc key type is invalid
181  * or if either randPtr, amfPtr, sqnPtr, or macsPtr is NULL.
182  * LE_UNSUPPORTED if underlying resource does not support this operation.
183  * LE_FAULT if there was an internal error.
184  */
185 //--------------------------------------------------------------------------------------------------
187 (
188  uint64_t kRef,
189  ///< [IN] Reference to K.
190  uint64_t opcRef,
191  ///< [IN] Reference to OPc.
192  const uint8_t* randPtr,
193  ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
194  size_t randSize,
195  ///< [IN]
196  const uint8_t* amfPtr,
197  ///< [IN] Authentication management field, AMF.
198  ///< Assumed to be AMF_SIZE bytes.
199  size_t amfSize,
200  ///< [IN]
201  const uint8_t* sqnPtr,
202  ///< [IN] Sequence number, SQN.
203  ///< Assumed to be SQN_SIZE bytes.
204  size_t sqnSize,
205  ///< [IN]
206  uint8_t* macsPtr,
207  ///< [OUT] Buffer to hold the re-sync authentication code.
208  ///< Assumed to be MACS_SIZE bytes.
209  size_t* macsSizePtr
210  ///< [INOUT]
211 );
212 
213 //--------------------------------------------------------------------------------------------------
214 /**
215  * Derives authentication response and keys using the Milenage algorithm set with AES-128 as the
216  * block cipher. Implements the Milenage functions f2, f3, f4, f5.
217  *
218  * @return
219  * LE_OK if successful.
220  * LE_BAD_PARAMETER if either K or OPc reference is invalid
221  * or if either K or OPc key type is invalid
222  * or if either randPtr, resPtr, ckPtr, ikPtr or akPtr is NULL.
223  * LE_UNSUPPORTED if underlying resource does not support this operation.
224  * LE_FAULT if there was an internal error.
225  */
226 //--------------------------------------------------------------------------------------------------
228 (
229  uint64_t kRef,
230  ///< [IN] Reference to K.
231  uint64_t opcRef,
232  ///< [IN] Reference to OPc.
233  const uint8_t* randPtr,
234  ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
235  size_t randSize,
236  ///< [IN]
237  uint8_t* resPtr,
238  ///< [OUT] Buffer to hold the authentication response RES.
239  ///< Assumed to be RES_SIZE bytes.
240  size_t* resSizePtr,
241  ///< [INOUT]
242  uint8_t* ckPtr,
243  ///< [OUT] Buffer to hold the confidentiality key CK.
244  ///< Assumed to be CK_SIZE bytes.
245  size_t* ckSizePtr,
246  ///< [INOUT]
247  uint8_t* ikPtr,
248  ///< [OUT] Buffer to hold the integrity key IK.
249  ///< Assumed to be IK_SIZE bytes.
250  size_t* ikSizePtr,
251  ///< [INOUT]
252  uint8_t* akPtr,
253  ///< [OUT] Buffer to hold the anonymity key AK.
254  ///< Assumed to be AK_SIZE bytes.
255  size_t* akSizePtr
256  ///< [INOUT]
257 );
258 
259 //--------------------------------------------------------------------------------------------------
260 /**
261  * Derives the anonymity key for the re-synchronisation message using the Milenage algorithm set
262  * with AES-128 as the block cipher. Implements the Milenage functions f5*.
263  *
264  * @return
265  * LE_OK if successful.
266  * LE_BAD_PARAMETER if either K or OPc reference is invalid
267  * or if either K or OPc key type is invalid
268  * or if either randPtr or akPtr is NULL.
269  * LE_UNSUPPORTED if underlying resource does not support this operation.
270  * LE_FAULT if there was an internal error.
271  */
272 //--------------------------------------------------------------------------------------------------
274 (
275  uint64_t kRef,
276  ///< [IN] Reference to K.
277  uint64_t opcRef,
278  ///< [IN] Reference to OPc.
279  const uint8_t* randPtr,
280  ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
281  size_t randSize,
282  ///< [IN]
283  uint8_t* akPtr,
284  ///< [OUT] Buffer to hold the anonymity key AK.
285  ///< Assumed to be AK_SIZE bytes.
286  size_t* akSizePtr
287  ///< [INOUT]
288 );
289 
290 //--------------------------------------------------------------------------------------------------
291 /**
292  * Derive an OPc value from the specified K and the internal OP value.
293  *
294  * @note
295  * This function is generally not used in devices as most OPc values are derived in a factory
296  * or network setting.
297  *
298  * @return
299  * LE_OK if successful.
300  * LE_BAD_PARAMETER if OP reference is invalid
301  * or if kPtr, opcPtr is NULL.
302  * LE_FAULT if there was an internal error.
303  */
304 //--------------------------------------------------------------------------------------------------
306 (
307  uint64_t opRef,
308  ///< [IN] Reference to OP key.
309  const uint8_t* kPtr,
310  ///< [IN] K.
311  size_t kSize,
312  ///< [IN]
313  uint8_t* opcPtr,
314  ///< [OUT] Buffer to hold the OPc value.
315  size_t* opcSizePtr
316  ///< [INOUT]
317 );
318 
319 /** @} **/
320 
321 #endif // LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
void(* le_iks_aesMilenage_DisconnectHandler_t)(void *)
Definition: le_iks_aesMilenage_interface.h:54
le_result_t
Definition: le_basics.h:46
void le_iks_aesMilenage_DisconnectService(void)
le_result_t le_iks_aesMilenage_TryConnectService(void)
LE_FULL_API void le_iks_aesMilenage_SetServerDisconnectHandler(le_iks_aesMilenage_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_iks_aesMilenage_GetMacS(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, const uint8_t *amfPtr, size_t amfSize, const uint8_t *sqnPtr, size_t sqnSize, uint8_t *macsPtr, size_t *macsSizePtr)
le_result_t le_iks_aesMilenage_GetMacA(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, const uint8_t *amfPtr, size_t amfSize, const uint8_t *sqnPtr, size_t sqnSize, uint8_t *macaPtr, size_t *macaSizePtr)
void le_iks_aesMilenage_ConnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_iks_aesMilenage_GetKeys(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, uint8_t *resPtr, size_t *resSizePtr, uint8_t *ckPtr, size_t *ckSizePtr, uint8_t *ikPtr, size_t *ikSizePtr, uint8_t *akPtr, size_t *akSizePtr)
le_result_t le_iks_aesMilenage_DeriveOpc(uint64_t opRef, const uint8_t *kPtr, size_t kSize, uint8_t *opcPtr, size_t *opcSizePtr)
le_result_t le_iks_aesMilenage_GetAk(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, uint8_t *akPtr, size_t *akSizePtr)