le_iks_aesCbc_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_aesCbc IoT Keystore AES CBC API
14  *
15  * @ref le_iks_aesCbc_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * Legato IoT Keystore APIs for performing AES encryption in CBC mode.
20  *
21  * <HR>
22  *
23  * Copyright (C) Sierra Wireless Inc.
24  */
25 /**
26  * @file le_iks_aesCbc_interface.h
27  *
28  * Legato @ref c_iks_aesCbc API
29  *
30  * Copyright (C) Sierra Wireless Inc.
31  */
32 
33 #ifndef LE_IKS_AESCBC_INTERFACE_H_INCLUDE_GUARD
34 #define LE_IKS_AESCBC_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_aesCbc_common.h"
44 /** @addtogroup le_iks_aesCbc le_iks_aesCbc API Reference
45  * @{
46  * @file le_iks_aesCbc_common.h
47  * @file le_iks_aesCbc_interface.h **/
48 //--------------------------------------------------------------------------------------------------
49 /**
50  * Type for handler called when a server disconnects.
51  */
52 //--------------------------------------------------------------------------------------------------
53 typedef void (*le_iks_aesCbc_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_aesCbc_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  * Starts a process to encrypt a message with AES in CBC mode. Calling this function will cancel
133  * any previously started process using the same session.
134  *
135  * To encrypt a message the following sequence should be used:
136  *
137  * le_iks_aesCbc_StartEncrypt() // Start the encryption process.
138  * le_iks_aesCbc_Encrypt() // Call zero or more times until all plaintext is encrypted.
139  *
140  * The initialization vector, IV, does not need to be kept secret but must be unpredictable. Thus
141  * the IV must be generated from a well seeded CPRNG each time this function is called.
142  *
143  * @return
144  * LE_OK if successful.
145  * LE_BAD_PARAMETER if the session reference is invalid
146  * or if the key type is invalid
147  * or if ivPtr is NULL.
148  * LE_UNSUPPORTED if underlying resource does not support this operation.
149  * LE_FAULT if there was an internal error.
150  */
151 //--------------------------------------------------------------------------------------------------
153 (
154  uint64_t session,
155  ///< [IN] Session reference.
156  const uint8_t* ivPtr,
157  ///< [IN] Initialization vector.
158  ///< Assumed to be IV_SIZE bytes.
159  size_t ivSize
160  ///< [IN]
161 );
162 
163 //--------------------------------------------------------------------------------------------------
164 /**
165  * Encrypt a chunk of plaintext. le_iks_aesCbc_StartEncrypt() must have been previously called. The
166  * plaintest must be a multiple of the block size. It is up to the caller to pad the plaintext as
167  * needed.
168  *
169  * @return
170  * LE_OK if successful.
171  * LE_BAD_PARAMETER if the session reference is invalid
172  * or if the key type is invalid
173  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
174  * LE_OUT_OF_RANGE if textSize is invalid.
175  * LE_UNSUPPORTED if underlying resource does not support this operation.
176  * LE_FAULT if an encryption process has not started.
177  */
178 //--------------------------------------------------------------------------------------------------
180 (
181  uint64_t session,
182  ///< [IN] Session reference.
183  const uint8_t* plaintextChunkPtr,
184  ///< [IN] Plaintext chunk.
185  size_t plaintextChunkSize,
186  ///< [IN]
187  uint8_t* ciphertextChunkPtr,
188  ///< [OUT] Buffer to hold the ciphertext chunk.
189  size_t* ciphertextChunkSizePtr
190  ///< [INOUT]
191 );
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  * Starts a process to decrypt a message with AES in CBC mode. Calling this function will cancel
196  * any previously started process using the same session.
197  *
198  * To decrypt a message the following sequence should be used:
199  *
200  * le_iks_aesCbc_StartDecrypt() // Start the decryption process.
201  * le_iks_aesCbc_Decrypt() // Call zero or more times until all ciphertext is decrypted.
202  *
203  * @return
204  * LE_OK if successful.
205  * LE_BAD_PARAMETER if the session reference is invalid
206  * or if the key type is invalid
207  * or if ivPtr is NULL.
208  * LE_UNSUPPORTED if underlying resource does not support this operation.
209  * LE_FAULT if there was an internal error.
210  */
211 //--------------------------------------------------------------------------------------------------
213 (
214  uint64_t session,
215  ///< [IN] Session reference.
216  const uint8_t* ivPtr,
217  ///< [IN] Initialization vector.
218  ///< Assumed to be AESCBC_IV_SIZE bytes.
219  size_t ivSize
220  ///< [IN]
221 );
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  * Decrypt a chunk of ciphertext. le_iks_aesCbc_StartDecrypt() must have been previously called to
226  * start a decryption process.
227  *
228  * @return
229  * LE_OK if successful.
230  * LE_BAD_PARAMETER if the session reference is invalid.
231  * or if the key type is invalid.
232  * or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
233  * LE_OUT_OF_RANGE if textSize is invalid.
234  * LE_UNSUPPORTED if underlying resource does not support this operation.
235  * LE_FAULT if a decryption process has not started.
236  */
237 //--------------------------------------------------------------------------------------------------
239 (
240  uint64_t session,
241  ///< [IN] Session reference.
242  const uint8_t* ciphertextChunkPtr,
243  ///< [IN] Ciphertext chunk.
244  size_t ciphertextChunkSize,
245  ///< [IN]
246  uint8_t* plaintextChunkPtr,
247  ///< [OUT] Buffer to hold the plaintext chunk.
248  size_t* plaintextChunkSizePtr
249  ///< [INOUT]
250 );
251 
252 /** @} **/
253 
254 #endif // LE_IKS_AESCBC_INTERFACE_H_INCLUDE_GUARD
void le_iks_aesCbc_DisconnectService(void)
le_result_t le_iks_aesCbc_TryConnectService(void)
le_result_t
Definition: le_basics.h:46
le_result_t le_iks_aesCbc_StartEncrypt(uint64_t session, const uint8_t *ivPtr, size_t ivSize)
le_result_t le_iks_aesCbc_StartDecrypt(uint64_t session, const uint8_t *ivPtr, size_t ivSize)
le_result_t le_iks_aesCbc_Decrypt(uint64_t session, const uint8_t *ciphertextChunkPtr, size_t ciphertextChunkSize, uint8_t *plaintextChunkPtr, size_t *plaintextChunkSizePtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
LE_FULL_API void le_iks_aesCbc_SetServerDisconnectHandler(le_iks_aesCbc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_iks_aesCbc_Encrypt(uint64_t session, const uint8_t *plaintextChunkPtr, size_t plaintextChunkSize, uint8_t *ciphertextChunkPtr, size_t *ciphertextChunkSizePtr)
void(* le_iks_aesCbc_DisconnectHandler_t)(void *)
Definition: le_iks_aesCbc_interface.h:53
void le_iks_aesCbc_ConnectService(void)