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 // Internal includes for this interface
60 #include "secStoreAdmin_common.h"
61 //--------------------------------------------------------------------------------------------------
62 /**
63  * Type for handler called when a server disconnects.
64  */
65 //--------------------------------------------------------------------------------------------------
66 typedef void (*secStoreAdmin_DisconnectHandler_t)(void *);
67 
68 //--------------------------------------------------------------------------------------------------
69 /**
70  *
71  * Connect the current client thread to the service providing this API. Block until the service is
72  * available.
73  *
74  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
75  * called before any other functions in this API. Normally, ConnectService is automatically called
76  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
77  *
78  * This function is created automatically.
79  */
80 //--------------------------------------------------------------------------------------------------
82 (
83  void
84 );
85 
86 //--------------------------------------------------------------------------------------------------
87 /**
88  *
89  * Try to connect the current client thread to the service providing this API. Return with an error
90  * if the service is not available.
91  *
92  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
93  * called before any other functions in this API. Normally, ConnectService is automatically called
94  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
95  *
96  * This function is created automatically.
97  *
98  * @return
99  * - LE_OK if the client connected successfully to the service.
100  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
101  * bound.
102  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
103  * - LE_COMM_ERROR if the Service Directory cannot be reached.
104  */
105 //--------------------------------------------------------------------------------------------------
107 (
108  void
109 );
110 
111 //--------------------------------------------------------------------------------------------------
112 /**
113  * Set handler called when server disconnection is detected.
114  *
115  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
116  * to continue without exiting, it should call longjmp() from inside the handler.
117  */
118 //--------------------------------------------------------------------------------------------------
120 (
121  secStoreAdmin_DisconnectHandler_t disconnectHandler,
122  void *contextPtr
123 );
124 
125 //--------------------------------------------------------------------------------------------------
126 /**
127  *
128  * Disconnect the current client thread from the service providing this API.
129  *
130  * Normally, this function doesn't need to be called. After this function is called, there's no
131  * longer a connection to the service, and the functions in this API can't be used. For details, see
132  * @ref apiFilesC_client.
133  *
134  * This function is created automatically.
135  */
136 //--------------------------------------------------------------------------------------------------
138 (
139  void
140 );
141 
142 
143 //--------------------------------------------------------------------------------------------------
144 /**
145  * Iterator to list entries in secure storage.
146  */
147 //--------------------------------------------------------------------------------------------------
148 
149 
150 //--------------------------------------------------------------------------------------------------
151 /**
152  * Create an iterator for listing entries in secure storage under the specified path.
153  *
154  * @return
155  * An iterator reference if successful.
156  * NULL if the secure storage is currently unavailable.
157  */
158 //--------------------------------------------------------------------------------------------------
159 secStoreAdmin_IterRef_t secStoreAdmin_CreateIter
160 (
161  const char* LE_NONNULL path
162  ///< [IN] Path to iterate over.
163 );
164 
165 //--------------------------------------------------------------------------------------------------
166 /**
167  * Deletes an iterator.
168  */
169 //--------------------------------------------------------------------------------------------------
171 (
172  secStoreAdmin_IterRef_t iterRef
173  ///< [IN] Iterator reference.
174 );
175 
176 //--------------------------------------------------------------------------------------------------
177 /**
178  * Go to the next entry in the iterator. This should be called at least once before accessing the
179  * entry. After the first time this function is called successfully on an iterator the first entry
180  * will be available.
181  *
182  * @return
183  * LE_OK if successful.
184  * LE_NOT_FOUND if there are no more entries available.
185  */
186 //--------------------------------------------------------------------------------------------------
188 (
189  secStoreAdmin_IterRef_t iterRef
190  ///< [IN] Iterator reference.
191 );
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  * Get the current entry's name.
196  *
197  * @return
198  * LE_OK if successful.
199  * LE_OVERFLOW if the buffer is too small to hold the entry name.
200  * LE_UNAVAILABLE if the secure storage is currently unavailable.
201  */
202 //--------------------------------------------------------------------------------------------------
204 (
205  secStoreAdmin_IterRef_t iterRef,
206  ///< [IN] Iterator reference.
207  char* name,
208  ///< [OUT] Buffer to store the entry name.
209  size_t nameSize,
210  ///< [IN]
211  bool* isDirPtr
212  ///< [OUT] True if the entry is a directory, false otherwise.
213 );
214 
215 //--------------------------------------------------------------------------------------------------
216 /**
217  * Writes a buffer of data into the specified path in secure storage. If the item already exists,
218  * it'll be overwritten with the new value. If the item doesn't already exist, it'll be created.
219  *
220  * @note
221  * The specified path must be an absolute path.
222  *
223  * @return
224  * LE_OK if successful.
225  * LE_NO_MEMORY if there isn't enough memory to store the item.
226  * LE_UNAVAILABLE if the secure storage is currently unavailable.
227  * LE_FAULT if there was some other error.
228  */
229 //--------------------------------------------------------------------------------------------------
231 (
232  const char* LE_NONNULL path,
233  ///< [IN] Path of the secure storage item.
234  const uint8_t* bufPtr,
235  ///< [IN] Buffer containing the data to store.
236  size_t bufSize
237  ///< [IN]
238 );
239 
240 //--------------------------------------------------------------------------------------------------
241 /**
242  * Reads an item from secure storage.
243  *
244  * @note
245  * The specified path must be an absolute path.
246  *
247  * @return
248  * LE_OK if successful.
249  * LE_OVERFLOW if the buffer is too small to hold the entire item. No data will be written to
250  * the buffer in this case.
251  * LE_NOT_FOUND if the item doesn't exist.
252  * LE_UNAVAILABLE if the secure storage is currently unavailable.
253  * LE_FAULT if there was some other error.
254  */
255 //--------------------------------------------------------------------------------------------------
257 (
258  const char* LE_NONNULL path,
259  ///< [IN] Path of the secure storage item.
260  uint8_t* bufPtr,
261  ///< [OUT] Buffer to store the data in.
262  size_t* bufSizePtr
263  ///< [INOUT]
264 );
265 
266 //--------------------------------------------------------------------------------------------------
267 /**
268  * Copy the meta file to the specified path.
269  *
270  * @return
271  * LE_OK if successful.
272  * LE_NOT_FOUND if the meta file does not exist.
273  * LE_UNAVAILABLE if the sfs is currently unavailable.
274  * LE_FAULT if there was some other error.
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  const char* LE_NONNULL path
280  ///< [IN] Destination path of meta file copy.
281 );
282 
283 //--------------------------------------------------------------------------------------------------
284 /**
285  * Recursively deletes all items under the specified path and the specified path from secure
286  * storage.
287  *
288  * @note
289  * The specified path must be an absolute path.
290  *
291  * @return
292  * LE_OK if successful.
293  * LE_NOT_FOUND if the path doesn't exist.
294  * LE_UNAVAILABLE if the secure storage is currently unavailable.
295  * LE_FAULT if there was some other error.
296  */
297 //--------------------------------------------------------------------------------------------------
299 (
300  const char* LE_NONNULL path
301  ///< [IN] Path of the secure storage item.
302 );
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Gets the size, in bytes, of all items under the specified path.
307  *
308  * @note
309  * The specified path must be an absolute path.
310  *
311  * @return
312  * LE_OK if successful.
313  * LE_NOT_FOUND if the path doesn't exist.
314  * LE_UNAVAILABLE if the secure storage is currently unavailable.
315  * LE_FAULT if there was some other error.
316  */
317 //--------------------------------------------------------------------------------------------------
319 (
320  const char* LE_NONNULL path,
321  ///< [IN] Path of the secure storage item.
322  uint64_t* sizePtr
323  ///< [OUT] Size in bytes of all items in the path.
324 );
325 
326 //--------------------------------------------------------------------------------------------------
327 /**
328  * Gets the total space and the available free space in secure storage.
329  *
330  * @return
331  * LE_OK if successful.
332  * LE_UNAVAILABLE if the secure storage is currently unavailable.
333  * LE_FAULT if there was some other error.
334  */
335 //--------------------------------------------------------------------------------------------------
337 (
338  uint64_t* totalSizePtr,
339  ///< [OUT] Total size, in bytes, of secure storage.
340  uint64_t* freeSizePtr
341  ///< [OUT] Free space, in bytes, in secure storage.
342 );
343 
344 #endif // SECSTOREADMIN_INTERFACE_H_INCLUDE_GUARD
void(* secStoreAdmin_DisconnectHandler_t)(void *)
Definition: secStoreAdmin_interface.h:66
le_result_t
Definition: le_basics.h:35
le_result_t secStoreAdmin_TryConnectService(void)
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_GetSize(const char *LE_NONNULL path, uint64_t *sizePtr)
le_result_t secStoreAdmin_CopyMetaTo(const char *LE_NONNULL path)
secStoreAdmin_IterRef_t secStoreAdmin_CreateIter(const char *LE_NONNULL path)
void secStoreAdmin_DeleteIter(secStoreAdmin_IterRef_t iterRef)
void secStoreAdmin_DisconnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t secStoreAdmin_Delete(const char *LE_NONNULL path)
le_result_t secStoreAdmin_Next(secStoreAdmin_IterRef_t iterRef)
LE_FULL_API void secStoreAdmin_SetServerDisconnectHandler(secStoreAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t secStoreAdmin_GetTotalSpace(uint64_t *totalSizePtr, uint64_t *freeSizePtr)
void secStoreAdmin_ConnectService(void)