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