secStoreAdmin_interface.h

    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 //--------------------------------------------------------------------------------------------------
   71 void secStoreAdmin_ConnectService
   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 //--------------------------------------------------------------------------------------------------
   96 le_result_t secStoreAdmin_TryConnectService
   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 //--------------------------------------------------------------------------------------------------
  109 void secStoreAdmin_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  127 void secStoreAdmin_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  163 secStoreAdmin_IterRef_t secStoreAdmin_CreateIter
  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 //--------------------------------------------------------------------------------------------------
  175 void secStoreAdmin_DeleteIter
  176 (
  177     secStoreAdmin_IterRef_t iterRef
  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 //--------------------------------------------------------------------------------------------------
  192 le_result_t secStoreAdmin_Next
  193 (
  194     secStoreAdmin_IterRef_t iterRef
  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 //--------------------------------------------------------------------------------------------------
  208 le_result_t secStoreAdmin_GetEntry
  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 //--------------------------------------------------------------------------------------------------
  235 le_result_t secStoreAdmin_Write
  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 //--------------------------------------------------------------------------------------------------
  262 le_result_t secStoreAdmin_Read
  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 //--------------------------------------------------------------------------------------------------
  284 le_result_t secStoreAdmin_CopyMetaTo
  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 //--------------------------------------------------------------------------------------------------
  306 le_result_t secStoreAdmin_Delete
  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 //--------------------------------------------------------------------------------------------------
  327 le_result_t secStoreAdmin_GetSize
  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 //--------------------------------------------------------------------------------------------------
  346 le_result_t secStoreAdmin_GetTotalSpace
  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
secStoreAdmin_IterRef_t
struct secStoreAdmin_Iter * secStoreAdmin_IterRef_t
Definition: secStoreAdmin_interface.h:151
secStoreAdmin_TryConnectService
le_result_t secStoreAdmin_TryConnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:35
secStoreAdmin_DisconnectHandler_t
void(* secStoreAdmin_DisconnectHandler_t)(void *)
Definition: secStoreAdmin_interface.h:56
secStoreAdmin_Delete
le_result_t secStoreAdmin_Delete(const char *path)
secStoreAdmin_GetEntry
le_result_t secStoreAdmin_GetEntry(secStoreAdmin_IterRef_t iterRef, char *name, size_t nameSize, bool *isDirPtr)
secStoreAdmin_CreateIter
secStoreAdmin_IterRef_t secStoreAdmin_CreateIter(const char *path)
secStoreAdmin_CopyMetaTo
le_result_t secStoreAdmin_CopyMetaTo(const char *path)
secStoreAdmin_Read
le_result_t secStoreAdmin_Read(const char *path, uint8_t *bufPtr, size_t *bufSizePtr)
secStoreAdmin_DeleteIter
void secStoreAdmin_DeleteIter(secStoreAdmin_IterRef_t iterRef)
secStoreAdmin_GetSize
le_result_t secStoreAdmin_GetSize(const char *path, uint64_t *sizePtr)
secStoreAdmin_Write
le_result_t secStoreAdmin_Write(const char *path, const uint8_t *bufPtr, size_t bufSize)
secStoreAdmin_ConnectService
void secStoreAdmin_ConnectService(void)
legato.h
secStoreAdmin_Next
le_result_t secStoreAdmin_Next(secStoreAdmin_IterRef_t iterRef)
secStoreAdmin_SetServerDisconnectHandler
void secStoreAdmin_SetServerDisconnectHandler(secStoreAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_secStore_interface.h
secStoreAdmin_GetTotalSpace
le_result_t secStoreAdmin_GetTotalSpace(uint64_t *totalSizePtr, uint64_t *freeSizePtr)
secStoreAdmin_DisconnectService
void secStoreAdmin_DisconnectService(void)