secStoreAdmin_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_secStoreAdmin Secure Storage Admin
14  *
15  * @ref secStoreAdmin_interface.h "API Reference" <br>
16  * @ref c_secStore API
17  *
18  * <HR>
19  *
20  * This API provides administrative control for secure storage. It gives the rights to read, write
21  * and delete files recorded in the SFS Legato tree. This API should be used with extreme caution.
22  *
23  * @caution The full API should only be used by privileged users
24  *
25  * Secure storage allows privileged users (e.g: administrators) to provision secure storage data by
26  * storing sensitive info like passwords, keys, certificates, etc. All data in the secure storage
27  * is in an encrypted format. It also allows privileged users to debug stored data issues.
28  *
29  * @note This API is mostly disabled by default in Legato Framework for security concerns. Only
30  * few functions remains to get non sensitive information about secure storage. In order
31  * to make the secure storage admin API fully available, Legato has be to be compiled using a
32  * special flag: SECSTOREADMIN=1 make
33  *
34  * Two functions are enabled by default whether the flag SECSTOREADMIN is set or not:
35  * - secStoreAdmin_GetTotalSpace(): gets total space and available free space in secure storage.
36  * - secStoreAdmin_GetSize(): gets the size, in bytes, of all items under the specified path
37  *
38  * <HR>
39  *
40  * Copyright (C) Sierra Wireless Inc.
41  */
42 /**
43  * @file secStoreAdmin_interface.h
44  *
45  * Legato @ref c_secStoreAdmin API
46  *
47  * Copyright (C) Sierra Wireless Inc.
48  */
49 
50 #ifndef SECSTOREADMIN_INTERFACE_H_INCLUDE_GUARD
51 #define SECSTOREADMIN_INTERFACE_H_INCLUDE_GUARD
52 
53 
54 #include "legato.h"
55 
56 // Interface specific includes
57 #include "le_secStore_interface.h"
58 
59 
60 //--------------------------------------------------------------------------------------------------
61 /**
62  * Type for handler called when a server disconnects.
63  */
64 //--------------------------------------------------------------------------------------------------
65 typedef void (*secStoreAdmin_DisconnectHandler_t)(void *);
66 
67 //--------------------------------------------------------------------------------------------------
68 /**
69  *
70  * Connect the current client thread to the service providing this API. Block until the service is
71  * available.
72  *
73  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
74  * called before any other functions in this API. Normally, ConnectService is automatically called
75  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
76  *
77  * This function is created automatically.
78  */
79 //--------------------------------------------------------------------------------------------------
81 (
82  void
83 );
84 
85 //--------------------------------------------------------------------------------------------------
86 /**
87  *
88  * Try to connect the current client thread to the service providing this API. Return with an error
89  * if the service is not available.
90  *
91  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
92  * called before any other functions in this API. Normally, ConnectService is automatically called
93  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
94  *
95  * This function is created automatically.
96  *
97  * @return
98  * - LE_OK if the client connected successfully to the service.
99  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
100  * bound.
101  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
102  * - LE_COMM_ERROR if the Service Directory cannot be reached.
103  */
104 //--------------------------------------------------------------------------------------------------
106 (
107  void
108 );
109 
110 //--------------------------------------------------------------------------------------------------
111 /**
112  * Set handler called when server disconnection is detected.
113  *
114  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
115  * to continue without exiting, it should call longjmp() from inside the handler.
116  */
117 //--------------------------------------------------------------------------------------------------
119 (
120  secStoreAdmin_DisconnectHandler_t disconnectHandler,
121  void *contextPtr
122 );
123 
124 //--------------------------------------------------------------------------------------------------
125 /**
126  *
127  * Disconnect the current client thread from the service providing this API.
128  *
129  * Normally, this function doesn't need to be called. After this function is called, there's no
130  * longer a connection to the service, and the functions in this API can't be used. For details, see
131  * @ref apiFilesC_client.
132  *
133  * This function is created automatically.
134  */
135 //--------------------------------------------------------------------------------------------------
137 (
138  void
139 );
140 
141 
142 //--------------------------------------------------------------------------------------------------
143 /**
144  * Maximum number of characters and byte storage size permitted for a path.
145  */
146 //--------------------------------------------------------------------------------------------------
147 #define SECSTOREADMIN_MAX_PATH_SIZE 511
148 
149 //--------------------------------------------------------------------------------------------------
150 /**
151  */
152 //--------------------------------------------------------------------------------------------------
153 #define SECSTOREADMIN_MAX_PATH_BYTES 512
154 
155 //--------------------------------------------------------------------------------------------------
156 /**
157  * Iterator to list entries in secure storage.
158  */
159 //--------------------------------------------------------------------------------------------------
160 typedef struct secStoreAdmin_Iter* secStoreAdmin_IterRef_t;
161 
162 
163 //--------------------------------------------------------------------------------------------------
164 /**
165  * Create an iterator for listing entries in secure storage under the specified path.
166  *
167  * @return
168  * An iterator reference if successful.
169  * NULL if the secure storage is currently unavailable.
170  */
171 //--------------------------------------------------------------------------------------------------
173 (
174  const char* LE_NONNULL path
175  ///< [IN] Path to iterate over.
176 );
177 
178 //--------------------------------------------------------------------------------------------------
179 /**
180  * Deletes an iterator.
181  */
182 //--------------------------------------------------------------------------------------------------
184 (
186  ///< [IN] Iterator reference.
187 );
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  * Go to the next entry in the iterator. This should be called at least once before accessing the
192  * entry. After the first time this function is called successfully on an iterator the first entry
193  * will be available.
194  *
195  * @return
196  * LE_OK if successful.
197  * LE_NOT_FOUND if there are no more entries available.
198  */
199 //--------------------------------------------------------------------------------------------------
201 (
203  ///< [IN] Iterator reference.
204 );
205 
206 //--------------------------------------------------------------------------------------------------
207 /**
208  * Get the current entry's name.
209  *
210  * @return
211  * LE_OK if successful.
212  * LE_OVERFLOW if the buffer is too small to hold the entry name.
213  * LE_UNAVAILABLE if the secure storage is currently unavailable.
214  */
215 //--------------------------------------------------------------------------------------------------
217 (
218  secStoreAdmin_IterRef_t iterRef,
219  ///< [IN] Iterator reference.
220  char* name,
221  ///< [OUT] Buffer to store the entry name.
222  size_t nameSize,
223  ///< [IN]
224  bool* isDirPtr
225  ///< [OUT] True if the entry is a directory, false otherwise.
226 );
227 
228 //--------------------------------------------------------------------------------------------------
229 /**
230  * Writes a buffer of data into the specified path in secure storage. If the item already exists,
231  * it'll be overwritten with the new value. If the item doesn't already exist, it'll be created.
232  *
233  * @note
234  * The specified path must be an absolute path.
235  *
236  * @return
237  * LE_OK if successful.
238  * LE_NO_MEMORY if there isn't enough memory to store the item.
239  * LE_UNAVAILABLE if the secure storage is currently unavailable.
240  * LE_FAULT if there was some other error.
241  */
242 //--------------------------------------------------------------------------------------------------
244 (
245  const char* LE_NONNULL path,
246  ///< [IN] Path of the secure storage item.
247  const uint8_t* bufPtr,
248  ///< [IN] Buffer containing the data to store.
249  size_t bufSize
250  ///< [IN]
251 );
252 
253 //--------------------------------------------------------------------------------------------------
254 /**
255  * Reads an item from secure storage.
256  *
257  * @note
258  * The specified path must be an absolute path.
259  *
260  * @return
261  * LE_OK if successful.
262  * LE_OVERFLOW if the buffer is too small to hold the entire item. No data will be written to
263  * the buffer in this case.
264  * LE_NOT_FOUND if the item doesn't exist.
265  * LE_UNAVAILABLE if the secure storage is currently unavailable.
266  * LE_FAULT if there was some other error.
267  */
268 //--------------------------------------------------------------------------------------------------
270 (
271  const char* LE_NONNULL path,
272  ///< [IN] Path of the secure storage item.
273  uint8_t* bufPtr,
274  ///< [OUT] Buffer to store the data in.
275  size_t* bufSizePtr
276  ///< [INOUT]
277 );
278 
279 //--------------------------------------------------------------------------------------------------
280 /**
281  * Copy the meta file to the specified path.
282  *
283  * @return
284  * LE_OK if successful.
285  * LE_NOT_FOUND if the meta file does not exist.
286  * LE_UNAVAILABLE if the sfs is currently unavailable.
287  * LE_FAULT if there was some other error.
288  */
289 //--------------------------------------------------------------------------------------------------
291 (
292  const char* LE_NONNULL path
293  ///< [IN] Destination path of meta file copy.
294 );
295 
296 //--------------------------------------------------------------------------------------------------
297 /**
298  * Recursively deletes all items under the specified path and the specified path from secure
299  * storage.
300  *
301  * @note
302  * The specified path must be an absolute path.
303  *
304  * @return
305  * LE_OK if successful.
306  * LE_NOT_FOUND if the path doesn't exist.
307  * LE_UNAVAILABLE if the secure storage is currently unavailable.
308  * LE_FAULT if there was some other error.
309  */
310 //--------------------------------------------------------------------------------------------------
312 (
313  const char* LE_NONNULL path
314  ///< [IN] Path of the secure storage item.
315 );
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Gets the size, in bytes, of all items under the specified path.
320  *
321  * @note
322  * The specified path must be an absolute path.
323  *
324  * @return
325  * LE_OK if successful.
326  * LE_NOT_FOUND if the path doesn't exist.
327  * LE_UNAVAILABLE if the secure storage is currently unavailable.
328  * LE_FAULT if there was some other error.
329  */
330 //--------------------------------------------------------------------------------------------------
332 (
333  const char* LE_NONNULL path,
334  ///< [IN] Path of the secure storage item.
335  uint64_t* sizePtr
336  ///< [OUT] Size in bytes of all items in the path.
337 );
338 
339 //--------------------------------------------------------------------------------------------------
340 /**
341  * Gets the total space and the available free space in secure storage.
342  *
343  * @return
344  * LE_OK if successful.
345  * LE_UNAVAILABLE if the secure storage is currently unavailable.
346  * LE_FAULT if there was some other error.
347  */
348 //--------------------------------------------------------------------------------------------------
350 (
351  uint64_t* totalSizePtr,
352  ///< [OUT] Total size, in bytes, of secure storage.
353  uint64_t* freeSizePtr
354  ///< [OUT] Free space, in bytes, in secure storage.
355 );
356 
357 #endif // SECSTOREADMIN_INTERFACE_H_INCLUDE_GUARD
struct secStoreAdmin_Iter * secStoreAdmin_IterRef_t
Definition: secStoreAdmin_interface.h:160
le_result_t secStoreAdmin_TryConnectService(void)
le_result_t
Definition: le_basics.h:35
void(* secStoreAdmin_DisconnectHandler_t)(void *)
Definition: secStoreAdmin_interface.h:65
le_result_t secStoreAdmin_GetEntry(secStoreAdmin_IterRef_t iterRef, char *name, size_t nameSize, bool *isDirPtr)
le_result_t secStoreAdmin_Write(const char *LE_NONNULL path, const uint8_t *bufPtr, size_t bufSize)
le_result_t secStoreAdmin_Read(const char *LE_NONNULL path, uint8_t *bufPtr, size_t *bufSizePtr)
le_result_t secStoreAdmin_Delete(const char *LE_NONNULL path)
le_result_t secStoreAdmin_GetSize(const char *LE_NONNULL path, uint64_t *sizePtr)
void secStoreAdmin_DeleteIter(secStoreAdmin_IterRef_t iterRef)
void secStoreAdmin_ConnectService(void)
le_result_t secStoreAdmin_Next(secStoreAdmin_IterRef_t iterRef)
le_result_t secStoreAdmin_CopyMetaTo(const char *LE_NONNULL path)
void secStoreAdmin_SetServerDisconnectHandler(secStoreAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
secStoreAdmin_IterRef_t secStoreAdmin_CreateIter(const char *LE_NONNULL path)
le_result_t secStoreAdmin_GetTotalSpace(uint64_t *totalSizePtr, uint64_t *freeSizePtr)
void secStoreAdmin_DisconnectService(void)