le_iks_aesGcm_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_aesGcm IoT Keystore AES GCM API
14  *
15  * @ref le_iks_aesGcm_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This module provides APIs for performing AES encryption in GCM mode.
20  *
21  * <HR>
22  *
23  * Copyright (C) Sierra Wireless Inc.
24  */
25 /**
26  * @file le_iks_aesGcm_interface.h
27  *
28  * Legato @ref c_iks API
29  *
30  * Copyright (C) Sierra Wireless Inc.
31  */
32 
33 #ifndef LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
34 #define LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
35 
36 
37 #include "legato.h"
38 
39 // Interface specific includes
40 #include "le_iks_interface.h"
41 
42 // Internal includes for this interface
43 #include "le_iks_aesGcm_common.h"
44 /** @addtogroup le_iks_aesGcm le_iks_aesGcm API Reference
45  * @{
46  * @file le_iks_aesGcm_common.h
47  * @file le_iks_aesGcm_interface.h **/
48 //--------------------------------------------------------------------------------------------------
49 /**
50  * Type for handler called when a server disconnects.
51  */
52 //--------------------------------------------------------------------------------------------------
53 typedef void (*le_iks_aesGcm_DisconnectHandler_t)(void *);
54 
55 //--------------------------------------------------------------------------------------------------
56 /**
57  *
58  * Connect the current client thread to the service providing this API. Block until the service is
59  * available.
60  *
61  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
62  * called before any other functions in this API. Normally, ConnectService is automatically called
63  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
64  *
65  * This function is created automatically.
66  */
67 //--------------------------------------------------------------------------------------------------
69 (
70  void
71 );
72 
73 //--------------------------------------------------------------------------------------------------
74 /**
75  *
76  * Try to connect the current client thread to the service providing this API. Return with an error
77  * if the service is not available.
78  *
79  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
80  * called before any other functions in this API. Normally, ConnectService is automatically called
81  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
82  *
83  * This function is created automatically.
84  *
85  * @return
86  * - LE_OK if the client connected successfully to the service.
87  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
88  * bound.
89  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
90  * - LE_COMM_ERROR if the Service Directory cannot be reached.
91  */
92 //--------------------------------------------------------------------------------------------------
94 (
95  void
96 );
97 
98 //--------------------------------------------------------------------------------------------------
99 /**
100  * Set handler called when server disconnection is detected.
101  *
102  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
103  * to continue without exiting, it should call longjmp() from inside the handler.
104  */
105 //--------------------------------------------------------------------------------------------------
107 (
108  le_iks_aesGcm_DisconnectHandler_t disconnectHandler,
109  void *contextPtr
110 );
111 
112 //--------------------------------------------------------------------------------------------------
113 /**
114  *
115  * Disconnect the current client thread from the service providing this API.
116  *
117  * Normally, this function doesn't need to be called. After this function is called, there's no
118  * longer a connection to the service, and the functions in this API can't be used. For details, see
119  * @ref apiFilesC_client.
120  *
121  * This function is created automatically.
122  */
123 //--------------------------------------------------------------------------------------------------
125 (
126  void
127 );
128 
129 
130 //--------------------------------------------------------------------------------------------------
131 /**
132  * Encrypt and integrity protect a packet with AES in GCM mode.
133  *
134  * GCM is an AEAD (Authenticated Encryption with Associated Data) which means that it provides both
135  * confidentiality and integrity protection for plaintext data and provides integrity protection for
136  * associated data. The associated data, also referred to as Additional Authenticated Data (AAD),
137  * is not encrypted but is integrity protected. The output of the encryption is a randomly chosen
138  * nonce, the ciphertext corresponding to the plaintext and an authentication tag. The
139  * authentication tag integrity protects the nonce, AAD and the ciphertext.
140  *
141  * ______________________
142  * | AAD, plaintext |
143  * ----------------------
144  * |
145  * V
146  * ______________________________
147  * | nonce, ciphertext, tag |
148  * ------------------------------
149  *
150  * This is especially useful in communication protocols where a packet's payload needs to be secret
151  * but the packet's header must be readable. In this case the packet's header is the AAD.
152  *
153  * The AAD and plaintext are optional but they cannot both be omitted. If the AAD is omitted then
154  * confidentiality and integrity is provided for just the plaintext. If the plaintext is omitted
155  * then integrity protection is provided for just the AAD.
156  *
157  * The ciphertext size is the same as the plaintext size and it is assumed that the ciphertextPtr
158  * buffer is at least plaintextSize bytes long.
159  *
160  * The tag size is always LE_IKS_AES_GCM_TAG_SIZE bytes and it is assumed that the tagPtr buffer is
161  * large enough to hold the tag.
162  *
163  * A random nonce is chosen for each invocation of this function. The nonce is passed out to the
164  * caller via noncePtr and is assumed to always be LE_IKS_AES_GCM_NONCE_SIZE bytes.
165  * The nonce does not need to be kept secret and can be passed in the clear.
166  *
167  * Nonce values must be unique for each invocation for the lifetime of the key. In other words a
168  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
169  * world. This is a critical security requirement but can be difficult to satisfy that is why
170  * keys should be rotated frequently.
171  *
172  * Repeated nonces in GCM are particularly problematic as they can be used to recover the integrity
173  * key.
174  *
175  * @return
176  * LE_OK if successful.
177  * LE_OUT_OF_RANGE if either the aadSize or plaintextSize is the wrong size.
178  * LE_BAD_PARAMETER if the key reference is invalid
179  * or if the key type is invalid
180  * or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
181  * they shouldn't be.
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 keyRef,
189  ///< [IN] Key reference.
190  uint8_t* noncePtr,
191  ///< [OUT] Buffer to hold the nonce.
192  ///< Assumed to be NONCE_SIZE bytes.
193  size_t* nonceSizePtr,
194  ///< [INOUT]
195  const uint8_t* aadPtr,
196  ///< [IN] Additional authenticated data (AAD).
197  ///< NULL if not used.
198  size_t aadSize,
199  ///< [IN]
200  const uint8_t* plaintextPtr,
201  ///< [IN] Plaintext. NULL if not used.
202  size_t plaintextSize,
203  ///< [IN]
204  uint8_t* ciphertextPtr,
205  ///< [OUT] Buffer to hold the ciphertext.
206  size_t* ciphertextSizePtr,
207  ///< [INOUT]
208  uint8_t* tagPtr,
209  ///< [OUT] Buffer to hold the authentication tag.
210  ///< Assumed to be TAG_SIZE.
211  size_t* tagSizePtr
212  ///< [INOUT]
213 );
214 
215 //--------------------------------------------------------------------------------------------------
216 /**
217  * Decrypt and verify the integrity of a packet with AES in GCM mode.
218  *
219  * This function performs an integrity check of the AAD and the ciphertext and if the integrity
220  * passes provides the decrypted plaintext.
221  *
222  * The plaintext size is the same as the ciphertext size and it is assumed that the plaintextPtr
223  * buffer is at least ciphertextSize bytes long.
224  *
225  * The nonce, AAD, ciphertext and tag must be the values produced during encryption.
226  *
227  * ___________________________________
228  * | nonce, AAD, ciphertext, tag |
229  * -----------------------------------
230  * |
231  * V
232  * _________________
233  * | plaintext |
234  * -----------------
235  *
236  * @return
237  * LE_OK if successful.
238  * LE_OUT_OF_RANGE if either the aadSize or ciphertextSize is too large.
239  * LE_BAD_PARAMETER if the key reference is invalid
240  * or if the key type is invalid
241  * or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
242  * they shouldn't be.
243  * LE_UNSUPPORTED if underlying resource does not support this operation.
244  * LE_FAULT if the integrity check failed.
245  */
246 //--------------------------------------------------------------------------------------------------
248 (
249  uint64_t keyRef,
250  ///< [IN] Key reference.
251  const uint8_t* noncePtr,
252  ///< [IN] Nonce used to encrypt the packet.
253  ///< Assumed to be NONCE_SIZE bytes.
254  size_t nonceSize,
255  ///< [IN]
256  const uint8_t* aadPtr,
257  ///< [IN] Additional authenticated data (AAD).
258  ///< NULL if not used.
259  size_t aadSize,
260  ///< [IN]
261  const uint8_t* ciphertextPtr,
262  ///< [IN] Ciphertext. NULL if not used.
263  size_t ciphertextSize,
264  ///< [IN]
265  uint8_t* plaintextPtr,
266  ///< [OUT] Buffer to hold the plaintext.
267  size_t* plaintextSizePtr,
268  ///< [INOUT]
269  const uint8_t* tagPtr,
270  ///< [IN] Buffer to hold the authentication tag.
271  ///< Assumed to be TAG_SIZE.
272  size_t tagSize
273  ///< [IN]
274 );
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Starts a process to encrypt and integrity protect a long packet with AES in GCM mode. This
279  * function is useful for encrypting and integrity protecting packets that are larger than
280  * MAX_PACKET_SIZE. Calling this function will cancel any previously started process using the
281  * same session.
282  *
283  * To encrypt a long packet the following sequence should be used:
284  *
285  * le_iks_aesGcm_StartEncrypt() // Start the encryption process.
286  * le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed.
287  * le_iks_aesGcm_Encrypt() // Call zero or more times until all plaintext is encrypted.
288  * le_iks_aesGcm_DoneEncrypt() // Complete process and obtain authentication tag.
289  *
290  * All AAD must be processed before plaintext processing begins.
291  *
292  * A random nonce is chosen for each invocation of this function. The nonce is passed out to the
293  * caller via noncePtr and is assumed to always be AES_GCM_NONCE_SIZE bytes.
294  * The nonce does not need to be kept secret and can be passed in the clear.
295  *
296  * Nonce values must be unique for each invocation for the lifetime of the key. In other words a
297  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
298  * world. This is a critical security requirement but can be difficult to satisfy. Therefore keys
299  * should be rotated frequently.
300  *
301  * @return
302  * LE_OK if successful.
303  * LE_BAD_PARAMETER if the session reference is invalid
304  * or if the key type is invalid
305  * or if noncePtr is NULL.
306  * LE_UNSUPPORTED if underlying resource does not support this operation.
307  * LE_FAULT if there was an internal error.
308  */
309 //--------------------------------------------------------------------------------------------------
311 (
312  uint64_t session,
313  ///< [IN] Session reference.
314  uint8_t* noncePtr,
315  ///< [OUT] Buffer to hold the nonce.
316  ///< Assumed to be NONCE_SIZE bytes.
317  size_t* nonceSizePtr
318  ///< [INOUT]
319 );
320 
321 //--------------------------------------------------------------------------------------------------
322 /**
323  * Process a chunk of AAD (Additional Authenticated Data). Either le_iks_aesGcm_StartEncrypt() or
324  * le_iks_aesGcm_StartDecrypt() must have been previously called to start either an encryption or
325  * decryption process.
326  *
327  * @return
328  * LE_OK if successful.
329  * LE_BAD_PARAMETER if the session reference is invalid
330  * or if the key type is invalid
331  * or if aadChunkPtr is NULL.
332  * LE_OUT_OF_RANGE if aadChunkSize is too big.
333  * LE_UNSUPPORTED if underlying resource does not support this operation.
334  * LE_FAULT if an encryption or decryption process was not started or
335  * plaintext/ciphertext processing has already started.
336  */
337 //--------------------------------------------------------------------------------------------------
339 (
340  uint64_t session,
341  ///< [IN] Session reference.
342  const uint8_t* aadPtr,
343  ///< [IN] Additional authenticated data (AAD).
344  ///< NULL if not used.
345  size_t aadSize
346  ///< [IN]
347 );
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Encrypt a chunk of plaintext. le_iks_aesGcm_StartEncrypt() must have been previously called to
352  * start an encryption process.
353  *
354  * @return
355  * LE_OK if successful.
356  * LE_BAD_PARAMETER if the session reference is invalid
357  * or if the key type is invalid
358  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
359  * LE_OUT_OF_RANGE if textSize is too big.
360  * LE_UNSUPPORTED if underlying resource does not support this operation.
361  * LE_FAULT if an encryption process has not started.
362  */
363 //--------------------------------------------------------------------------------------------------
365 (
366  uint64_t session,
367  ///< [IN] Session reference.
368  const uint8_t* plaintextChunkPtr,
369  ///< [IN] Plaintext.
370  size_t plaintextChunkSize,
371  ///< [IN]
372  uint8_t* ciphertextChunkPtr,
373  ///< [OUT] Buffer to hold the ciphertext.
374  size_t* ciphertextChunkSizePtr
375  ///< [INOUT]
376 );
377 
378 //--------------------------------------------------------------------------------------------------
379 /**
380  * Complete encryption and calculate the authentication tag.
381  *
382  * @return
383  * LE_OK if successful.
384  * LE_BAD_PARAMETER if the session reference is invalid
385  * or if the key type is invalid
386  * or if tagPtr is NULL.
387  * LE_UNSUPPORTED if underlying resource does not support this operation.
388  * LE_FAULT if an encryption process has not started or no data
389  * (AAD and plaintext) has been processed.
390  */
391 //--------------------------------------------------------------------------------------------------
393 (
394  uint64_t session,
395  ///< [IN] Session reference.
396  uint8_t* tagPtr,
397  ///< [OUT] Buffer to hold the authentication tag.
398  ///< Assumed to be TAG_SIZE.
399  size_t* tagSizePtr
400  ///< [INOUT]
401 );
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Starts a process to decrypt and verify the integrity of a long packet with AES in GCM mode. This
406  * function is useful for decrypting and verifying packets that are larger than MAX_PACKET_SIZE.
407  * Calling this function will cancel any previously started process using the same session.
408  *
409  * To decrypt a long packet the following sequence should be used:
410  *
411  * le_iks_aesGcm_StartDecrypt() // Start the decryption process.
412  * le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed.
413  * le_iks_aesGcm_Decrypt() // Call zero or more times until all ciphertext is decrypted.
414  * le_iks_aesGcm_DoneDecrypt() // Complete decryption process.
415  *
416  * @warning
417  * While decrypting long packets in this 'streaming' fashion plaintext chunks are released to
418  * the caller before they are verified for integrity. Ie. the caller will not know the
419  * plaintext is correct until le_iks_aesGcm_DoneDecrypt() is called. The caller therefore must
420  * not release or make use of any plaintext chunks until after
421  * le_iks_aesGcm_DoneDecrypt() returns with LE_OK.
422  *
423  * @return
424  * LE_OK if successful.
425  * LE_BAD_PARAMETER if the session reference is invalid
426  * or if the key type is not valid
427  * or if noncePtr is NULL.
428  * LE_UNSUPPORTED if underlying resource does not support this operation.
429  * LE_FAULT if there was an internal error.
430  */
431 //--------------------------------------------------------------------------------------------------
433 (
434  uint64_t session,
435  ///< [IN] Session reference.
436  const uint8_t* noncePtr,
437  ///< [IN] Nonce used to encrypt the packet.
438  ///< Assumed to be NONCE_SIZE bytes.
439  size_t nonceSize
440  ///< [IN]
441 );
442 
443 //--------------------------------------------------------------------------------------------------
444 /**
445  * Decrypt a chunk of ciphertext. le_iks_aesGcm_StartDecrypt() must have been previously called to
446  * start either a decryption process.
447  *
448  * @return
449  * LE_OK if successful.
450  * LE_BAD_PARAMETER if the session reference is invalid
451  * or if the key type is invalid
452  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
453  * LE_OUT_OF_RANGE if textSize is too big.
454  * LE_UNSUPPORTED if underlying resource does not support this operation.
455  * LE_FAULT if a decryption process has not started.
456  */
457 //--------------------------------------------------------------------------------------------------
459 (
460  uint64_t session,
461  ///< [IN] Session reference.
462  const uint8_t* ciphertextChunkPtr,
463  ///< [IN] Ciphertext chunk. NULL if not used.
464  size_t ciphertextChunkSize,
465  ///< [IN]
466  uint8_t* plaintextChunkPtr,
467  ///< [OUT] Buffer to hold the plaintext chunk.
468  size_t* plaintextChunkSizePtr
469  ///< [INOUT]
470 );
471 
472 //--------------------------------------------------------------------------------------------------
473 /**
474  * Complete decryption and verify the integrity.
475  *
476  * @return
477  * LE_OK if successful.
478  * LE_BAD_PARAMETER if the session reference is invalid
479  * or if the key type is invalid
480  * or if tagPtr is NULL.
481  * LE_UNSUPPORTED if underlying resource does not support this operation.
482  * LE_FAULT if a decryption process has not started
483  * or no data (AAD and ciphertext) has been processed
484  * or the integrity check failed.
485  */
486 //--------------------------------------------------------------------------------------------------
488 (
489  uint64_t session,
490  ///< [IN] Session reference.
491  const uint8_t* tagPtr,
492  ///< [IN] Buffer to hold the authentication tag.
493  ///< Assumed to be TAG_SIZE.
494  size_t tagSize
495  ///< [IN]
496 );
497 
498 /** @} **/
499 
500 #endif // LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
void(* le_iks_aesGcm_DisconnectHandler_t)(void *)
Definition: le_iks_aesGcm_interface.h:53
le_result_t le_iks_aesGcm_EncryptPacket(uint64_t keyRef, uint8_t *noncePtr, size_t *nonceSizePtr, const uint8_t *aadPtr, size_t aadSize, const uint8_t *plaintextPtr, size_t plaintextSize, uint8_t *ciphertextPtr, size_t *ciphertextSizePtr, uint8_t *tagPtr, size_t *tagSizePtr)
le_result_t le_iks_aesGcm_DoneEncrypt(uint64_t session, uint8_t *tagPtr, size_t *tagSizePtr)
le_result_t
Definition: le_basics.h:46
void le_iks_aesGcm_ConnectService(void)
le_result_t le_iks_aesGcm_Encrypt(uint64_t session, const uint8_t *plaintextChunkPtr, size_t plaintextChunkSize, uint8_t *ciphertextChunkPtr, size_t *ciphertextChunkSizePtr)
le_result_t le_iks_aesGcm_StartDecrypt(uint64_t session, const uint8_t *noncePtr, size_t nonceSize)
le_result_t le_iks_aesGcm_ProcessAad(uint64_t session, const uint8_t *aadPtr, size_t aadSize)
le_result_t le_iks_aesGcm_DecryptPacket(uint64_t keyRef, const uint8_t *noncePtr, size_t nonceSize, const uint8_t *aadPtr, size_t aadSize, const uint8_t *ciphertextPtr, size_t ciphertextSize, uint8_t *plaintextPtr, size_t *plaintextSizePtr, const uint8_t *tagPtr, size_t tagSize)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_iks_aesGcm_Decrypt(uint64_t session, const uint8_t *ciphertextChunkPtr, size_t ciphertextChunkSize, uint8_t *plaintextChunkPtr, size_t *plaintextChunkSizePtr)
le_result_t le_iks_aesGcm_DoneDecrypt(uint64_t session, const uint8_t *tagPtr, size_t tagSize)
void le_iks_aesGcm_DisconnectService(void)
le_result_t le_iks_aesGcm_StartEncrypt(uint64_t session, uint8_t *noncePtr, size_t *nonceSizePtr)
le_result_t le_iks_aesGcm_TryConnectService(void)
LE_FULL_API void le_iks_aesGcm_SetServerDisconnectHandler(le_iks_aesGcm_DisconnectHandler_t disconnectHandler, void *contextPtr)