le_iks_aesGcm_common.h

Go to the documentation of this file.
1 
2 /*
3  * ====================== WARNING ======================
4  *
5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
6  * DO NOT MODIFY IN ANY WAY.
7  *
8  * ====================== WARNING ======================
9  */
10 /**
11  * @file le_iks_aesGcm_common.h
12  *
13  * Type definitions for le_iks_aesGcm.
14  *
15  */
16 #ifndef LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
17 #define LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
18 
19 
20 #include "legato.h"
21 
22 // Interface specific includes
23 #include "le_iks_common.h"
24 
25 #define IFGEN_LE_IKS_AESGCM_PROTOCOL_ID "7f26322ff3a7485b8eebb56e18f8d848"
26 #define IFGEN_LE_IKS_AESGCM_MSG_SIZE 8256
27 /** @addtogroup le_iks_aesGcm
28  * @{ **/
29 
30 
31 //--------------------------------------------------------------------------------------------------
32 /**
33  * Nonce sizes in bytes.
34  */
35 //--------------------------------------------------------------------------------------------------
36 #define LE_IKS_AESGCM_NONCE_SIZE 12
37 
38 //--------------------------------------------------------------------------------------------------
39 /**
40  * Tag sizes in bytes.
41  */
42 //--------------------------------------------------------------------------------------------------
43 #define LE_IKS_AESGCM_TAG_SIZE 16
44 
45 
46 //--------------------------------------------------------------------------------------------------
47 /**
48  * Get if this client bound locally.
49  */
50 //--------------------------------------------------------------------------------------------------
51 LE_SHARED bool ifgen_le_iks_aesGcm_HasLocalBinding
52 (
53  void
54 );
55 
56 
57 //--------------------------------------------------------------------------------------------------
58 /**
59  * Init data that is common across all threads
60  */
61 //--------------------------------------------------------------------------------------------------
62 LE_SHARED void ifgen_le_iks_aesGcm_InitCommonData
63 (
64  void
65 );
66 
67 
68 //--------------------------------------------------------------------------------------------------
69 /**
70  * Perform common initialization and open a session
71  */
72 //--------------------------------------------------------------------------------------------------
73 LE_SHARED le_result_t ifgen_le_iks_aesGcm_OpenSession
74 (
75  le_msg_SessionRef_t _ifgen_sessionRef,
76  bool isBlocking
77 );
78 
79 //--------------------------------------------------------------------------------------------------
80 /**
81  * Encrypt and integrity protect a packet with AES in GCM mode.
82  *
83  * GCM is an AEAD (Authenticated Encryption with Associated Data) which means that it provides both
84  * confidentiality and integrity protection for plaintext data and provides integrity protection for
85  * associated data. The associated data, also referred to as Additional Authenticated Data (AAD),
86  * is not encrypted but is integrity protected. The output of the encryption is a randomly chosen
87  * nonce, the ciphertext corresponding to the plaintext and an authentication tag. The
88  * authentication tag integrity protects the nonce, AAD and the ciphertext.
89  *
90  * ______________________
91  * | AAD, plaintext |
92  * ----------------------
93  * |
94  * V
95  * ______________________________
96  * | nonce, ciphertext, tag |
97  * ------------------------------
98  *
99  * This is especially useful in communication protocols where a packet's payload needs to be secret
100  * but the packet's header must be readable. In this case the packet's header is the AAD.
101  *
102  * The AAD and plaintext are optional but they cannot both be omitted. If the AAD is omitted then
103  * confidentiality and integrity is provided for just the plaintext. If the plaintext is omitted
104  * then integrity protection is provided for just the AAD.
105  *
106  * The ciphertext size is the same as the plaintext size and it is assumed that the ciphertextPtr
107  * buffer is at least plaintextSize bytes long.
108  *
109  * The tag size is always LE_IKS_AES_GCM_TAG_SIZE bytes and it is assumed that the tagPtr buffer is
110  * large enough to hold the tag.
111  *
112  * A random nonce is chosen for each invocation of this function. The nonce is passed out to the
113  * caller via noncePtr and is assumed to always be LE_IKS_AES_GCM_NONCE_SIZE bytes.
114  * The nonce does not need to be kept secret and can be passed in the clear.
115  *
116  * Nonce values must be unique for each invocation for the lifetime of the key. In other words a
117  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
118  * world. This is a critical security requirement but can be difficult to satisfy that is why
119  * keys should be rotated frequently.
120  *
121  * Repeated nonces in GCM are particularly problematic as they can be used to recover the integrity
122  * key.
123  *
124  * @return
125  * LE_OK if successful.
126  * LE_OUT_OF_RANGE if either the aadSize or plaintextSize is the wrong size.
127  * LE_BAD_PARAMETER if the key reference is invalid
128  * or if the key type is invalid
129  * or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
130  * they shouldn't be.
131  * LE_UNSUPPORTED if underlying resource does not support this operation.
132  * LE_FAULT if there was an internal error.
133  */
134 //--------------------------------------------------------------------------------------------------
135 LE_SHARED le_result_t ifgen_le_iks_aesGcm_EncryptPacket
136 (
137  le_msg_SessionRef_t _ifgen_sessionRef,
138  uint64_t keyRef,
139  ///< [IN] Key reference.
140  uint8_t* noncePtr,
141  ///< [OUT] Buffer to hold the nonce.
142  ///< Assumed to be NONCE_SIZE bytes.
143  size_t* nonceSizePtr,
144  ///< [INOUT]
145  const uint8_t* aadPtr,
146  ///< [IN] Additional authenticated data (AAD).
147  ///< NULL if not used.
148  size_t aadSize,
149  ///< [IN]
150  const uint8_t* plaintextPtr,
151  ///< [IN] Plaintext. NULL if not used.
152  size_t plaintextSize,
153  ///< [IN]
154  uint8_t* ciphertextPtr,
155  ///< [OUT] Buffer to hold the ciphertext.
156  size_t* ciphertextSizePtr,
157  ///< [INOUT]
158  uint8_t* tagPtr,
159  ///< [OUT] Buffer to hold the authentication tag.
160  ///< Assumed to be TAG_SIZE.
161  size_t* tagSizePtr
162  ///< [INOUT]
163 );
164 
165 //--------------------------------------------------------------------------------------------------
166 /**
167  * Decrypt and verify the integrity of a packet with AES in GCM mode.
168  *
169  * This function performs an integrity check of the AAD and the ciphertext and if the integrity
170  * passes provides the decrypted plaintext.
171  *
172  * The plaintext size is the same as the ciphertext size and it is assumed that the plaintextPtr
173  * buffer is at least ciphertextSize bytes long.
174  *
175  * The nonce, AAD, ciphertext and tag must be the values produced during encryption.
176  *
177  * ___________________________________
178  * | nonce, AAD, ciphertext, tag |
179  * -----------------------------------
180  * |
181  * V
182  * _________________
183  * | plaintext |
184  * -----------------
185  *
186  * @return
187  * LE_OK if successful.
188  * LE_OUT_OF_RANGE if either the aadSize or ciphertextSize is too large.
189  * LE_BAD_PARAMETER if the key reference is invalid
190  * or if the key type is invalid
191  * or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
192  * they shouldn't be.
193  * LE_UNSUPPORTED if underlying resource does not support this operation.
194  * LE_FAULT if the integrity check failed.
195  */
196 //--------------------------------------------------------------------------------------------------
197 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DecryptPacket
198 (
199  le_msg_SessionRef_t _ifgen_sessionRef,
200  uint64_t keyRef,
201  ///< [IN] Key reference.
202  const uint8_t* noncePtr,
203  ///< [IN] Nonce used to encrypt the packet.
204  ///< Assumed to be NONCE_SIZE bytes.
205  size_t nonceSize,
206  ///< [IN]
207  const uint8_t* aadPtr,
208  ///< [IN] Additional authenticated data (AAD).
209  ///< NULL if not used.
210  size_t aadSize,
211  ///< [IN]
212  const uint8_t* ciphertextPtr,
213  ///< [IN] Ciphertext. NULL if not used.
214  size_t ciphertextSize,
215  ///< [IN]
216  uint8_t* plaintextPtr,
217  ///< [OUT] Buffer to hold the plaintext.
218  size_t* plaintextSizePtr,
219  ///< [INOUT]
220  const uint8_t* tagPtr,
221  ///< [IN] Buffer to hold the authentication tag.
222  ///< Assumed to be TAG_SIZE.
223  size_t tagSize
224  ///< [IN]
225 );
226 
227 //--------------------------------------------------------------------------------------------------
228 /**
229  * Starts a process to encrypt and integrity protect a long packet with AES in GCM mode. This
230  * function is useful for encrypting and integrity protecting packets that are larger than
231  * MAX_PACKET_SIZE. Calling this function will cancel any previously started process using the
232  * same session.
233  *
234  * To encrypt a long packet the following sequence should be used:
235  *
236  * le_iks_aesGcm_StartEncrypt() // Start the encryption process.
237  * le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed.
238  * le_iks_aesGcm_Encrypt() // Call zero or more times until all plaintext is encrypted.
239  * le_iks_aesGcm_DoneEncrypt() // Complete process and obtain authentication tag.
240  *
241  * All AAD must be processed before plaintext processing begins.
242  *
243  * A random nonce is chosen for each invocation of this function. The nonce is passed out to the
244  * caller via noncePtr and is assumed to always be AES_GCM_NONCE_SIZE bytes.
245  * The nonce does not need to be kept secret and can be passed in the clear.
246  *
247  * Nonce values must be unique for each invocation for the lifetime of the key. In other words a
248  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
249  * world. This is a critical security requirement but can be difficult to satisfy. Therefore keys
250  * should be rotated frequently.
251  *
252  * @return
253  * LE_OK if successful.
254  * LE_BAD_PARAMETER if the session reference is invalid
255  * or if the key type is invalid
256  * or if noncePtr is NULL.
257  * LE_UNSUPPORTED if underlying resource does not support this operation.
258  * LE_FAULT if there was an internal error.
259  */
260 //--------------------------------------------------------------------------------------------------
261 LE_SHARED le_result_t ifgen_le_iks_aesGcm_StartEncrypt
262 (
263  le_msg_SessionRef_t _ifgen_sessionRef,
264  uint64_t session,
265  ///< [IN] Session reference.
266  uint8_t* noncePtr,
267  ///< [OUT] Buffer to hold the nonce.
268  ///< Assumed to be NONCE_SIZE bytes.
269  size_t* nonceSizePtr
270  ///< [INOUT]
271 );
272 
273 //--------------------------------------------------------------------------------------------------
274 /**
275  * Process a chunk of AAD (Additional Authenticated Data). Either le_iks_aesGcm_StartEncrypt() or
276  * le_iks_aesGcm_StartDecrypt() must have been previously called to start either an encryption or
277  * decryption process.
278  *
279  * @return
280  * LE_OK if successful.
281  * LE_BAD_PARAMETER if the session reference is invalid
282  * or if the key type is invalid
283  * or if aadChunkPtr is NULL.
284  * LE_OUT_OF_RANGE if aadChunkSize is too big.
285  * LE_UNSUPPORTED if underlying resource does not support this operation.
286  * LE_FAULT if an encryption or decryption process was not started or
287  * plaintext/ciphertext processing has already started.
288  */
289 //--------------------------------------------------------------------------------------------------
290 LE_SHARED le_result_t ifgen_le_iks_aesGcm_ProcessAad
291 (
292  le_msg_SessionRef_t _ifgen_sessionRef,
293  uint64_t session,
294  ///< [IN] Session reference.
295  const uint8_t* aadPtr,
296  ///< [IN] Additional authenticated data (AAD).
297  ///< NULL if not used.
298  size_t aadSize
299  ///< [IN]
300 );
301 
302 //--------------------------------------------------------------------------------------------------
303 /**
304  * Encrypt a chunk of plaintext. le_iks_aesGcm_StartEncrypt() must have been previously called to
305  * start an encryption process.
306  *
307  * @return
308  * LE_OK if successful.
309  * LE_BAD_PARAMETER if the session reference is invalid
310  * or if the key type is invalid
311  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
312  * LE_OUT_OF_RANGE if textSize is too big.
313  * LE_UNSUPPORTED if underlying resource does not support this operation.
314  * LE_FAULT if an encryption process has not started.
315  */
316 //--------------------------------------------------------------------------------------------------
317 LE_SHARED le_result_t ifgen_le_iks_aesGcm_Encrypt
318 (
319  le_msg_SessionRef_t _ifgen_sessionRef,
320  uint64_t session,
321  ///< [IN] Session reference.
322  const uint8_t* plaintextChunkPtr,
323  ///< [IN] Plaintext.
324  size_t plaintextChunkSize,
325  ///< [IN]
326  uint8_t* ciphertextChunkPtr,
327  ///< [OUT] Buffer to hold the ciphertext.
328  size_t* ciphertextChunkSizePtr
329  ///< [INOUT]
330 );
331 
332 //--------------------------------------------------------------------------------------------------
333 /**
334  * Complete encryption and calculate the authentication tag.
335  *
336  * @return
337  * LE_OK if successful.
338  * LE_BAD_PARAMETER if the session reference is invalid
339  * or if the key type is invalid
340  * or if tagPtr is NULL.
341  * LE_UNSUPPORTED if underlying resource does not support this operation.
342  * LE_FAULT if an encryption process has not started or no data
343  * (AAD and plaintext) has been processed.
344  */
345 //--------------------------------------------------------------------------------------------------
346 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DoneEncrypt
347 (
348  le_msg_SessionRef_t _ifgen_sessionRef,
349  uint64_t session,
350  ///< [IN] Session reference.
351  uint8_t* tagPtr,
352  ///< [OUT] Buffer to hold the authentication tag.
353  ///< Assumed to be TAG_SIZE.
354  size_t* tagSizePtr
355  ///< [INOUT]
356 );
357 
358 //--------------------------------------------------------------------------------------------------
359 /**
360  * Starts a process to decrypt and verify the integrity of a long packet with AES in GCM mode. This
361  * function is useful for decrypting and verifying packets that are larger than MAX_PACKET_SIZE.
362  * Calling this function will cancel any previously started process using the same session.
363  *
364  * To decrypt a long packet the following sequence should be used:
365  *
366  * le_iks_aesGcm_StartDecrypt() // Start the decryption process.
367  * le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed.
368  * le_iks_aesGcm_Decrypt() // Call zero or more times until all ciphertext is decrypted.
369  * le_iks_aesGcm_DoneDecrypt() // Complete decryption process.
370  *
371  * @warning
372  * While decrypting long packets in this 'streaming' fashion plaintext chunks are released to
373  * the caller before they are verified for integrity. Ie. the caller will not know the
374  * plaintext is correct until le_iks_aesGcm_DoneDecrypt() is called. The caller therefore must
375  * not release or make use of any plaintext chunks until after
376  * le_iks_aesGcm_DoneDecrypt() returns with LE_OK.
377  *
378  * @return
379  * LE_OK if successful.
380  * LE_BAD_PARAMETER if the session reference is invalid
381  * or if the key type is not valid
382  * or if noncePtr is NULL.
383  * LE_UNSUPPORTED if underlying resource does not support this operation.
384  * LE_FAULT if there was an internal error.
385  */
386 //--------------------------------------------------------------------------------------------------
387 LE_SHARED le_result_t ifgen_le_iks_aesGcm_StartDecrypt
388 (
389  le_msg_SessionRef_t _ifgen_sessionRef,
390  uint64_t session,
391  ///< [IN] Session reference.
392  const uint8_t* noncePtr,
393  ///< [IN] Nonce used to encrypt the packet.
394  ///< Assumed to be NONCE_SIZE bytes.
395  size_t nonceSize
396  ///< [IN]
397 );
398 
399 //--------------------------------------------------------------------------------------------------
400 /**
401  * Decrypt a chunk of ciphertext. le_iks_aesGcm_StartDecrypt() must have been previously called to
402  * start either a decryption process.
403  *
404  * @return
405  * LE_OK if successful.
406  * LE_BAD_PARAMETER if the session reference is invalid
407  * or if the key type is invalid
408  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
409  * LE_OUT_OF_RANGE if textSize is too big.
410  * LE_UNSUPPORTED if underlying resource does not support this operation.
411  * LE_FAULT if a decryption process has not started.
412  */
413 //--------------------------------------------------------------------------------------------------
414 LE_SHARED le_result_t ifgen_le_iks_aesGcm_Decrypt
415 (
416  le_msg_SessionRef_t _ifgen_sessionRef,
417  uint64_t session,
418  ///< [IN] Session reference.
419  const uint8_t* ciphertextChunkPtr,
420  ///< [IN] Ciphertext chunk. NULL if not used.
421  size_t ciphertextChunkSize,
422  ///< [IN]
423  uint8_t* plaintextChunkPtr,
424  ///< [OUT] Buffer to hold the plaintext chunk.
425  size_t* plaintextChunkSizePtr
426  ///< [INOUT]
427 );
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Complete decryption and verify the integrity.
432  *
433  * @return
434  * LE_OK if successful.
435  * LE_BAD_PARAMETER if the session reference is invalid
436  * or if the key type is invalid
437  * or if tagPtr is NULL.
438  * LE_UNSUPPORTED if underlying resource does not support this operation.
439  * LE_FAULT if a decryption process has not started
440  * or no data (AAD and ciphertext) has been processed
441  * or the integrity check failed.
442  */
443 //--------------------------------------------------------------------------------------------------
444 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DoneDecrypt
445 (
446  le_msg_SessionRef_t _ifgen_sessionRef,
447  uint64_t session,
448  ///< [IN] Session reference.
449  const uint8_t* tagPtr,
450  ///< [IN] Buffer to hold the authentication tag.
451  ///< Assumed to be TAG_SIZE.
452  size_t tagSize
453  ///< [IN]
454 );
455 /** @} **/
456 #endif // LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
#define LE_SHARED
Definition: le_basics.h:300
le_result_t
Definition: le_basics.h:46
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860