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