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* LE_NONNULL path
  166         ///< [IN] Path to iterate over.
  167 );
  168 
  169 //--------------------------------------------------------------------------------------------------
  170 /**
  171  * Deletes an iterator.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 void secStoreAdmin_DeleteIter
  175 (
  176     secStoreAdmin_IterRef_t iterRef
  177         ///< [IN] Iterator reference.
  178 );
  179 
  180 //--------------------------------------------------------------------------------------------------
  181 /**
  182  * Go to the next entry in the iterator.  This should be called at least once before accessing the
  183  * entry.  After the first time this function is called successfully on an iterator the first entry
  184  * will be available.
  185  *
  186  * @return
  187  *      LE_OK if successful.
  188  *      LE_NOT_FOUND if there are no more entries available.
  189  */
  190 //--------------------------------------------------------------------------------------------------
  191 le_result_t secStoreAdmin_Next
  192 (
  193     secStoreAdmin_IterRef_t iterRef
  194         ///< [IN] Iterator reference.
  195 );
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Get the current entry's name.
  200  *
  201  * @return
  202  *      LE_OK if successful.
  203  *      LE_OVERFLOW if the buffer is too small to hold the entry name.
  204  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  205  */
  206 //--------------------------------------------------------------------------------------------------
  207 le_result_t secStoreAdmin_GetEntry
  208 (
  209     secStoreAdmin_IterRef_t iterRef,
  210         ///< [IN] Iterator reference.
  211     char* name,
  212         ///< [OUT] Buffer to store the entry name.
  213     size_t nameSize,
  214         ///< [IN]
  215     bool* isDirPtr
  216         ///< [OUT] True if the entry is a directory, false otherwise.
  217 );
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Writes a buffer of data into the specified path in secure storage.  If the item already exists,
  222  * it'll be overwritten with the new value. If the item doesn't already exist, it'll be created.
  223  *
  224  * @note
  225  *      The specified path must be an absolute path.
  226  *
  227  * @return
  228  *      LE_OK if successful.
  229  *      LE_NO_MEMORY if there isn't enough memory to store the item.
  230  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  231  *      LE_FAULT if there was some other error.
  232  */
  233 //--------------------------------------------------------------------------------------------------
  234 le_result_t secStoreAdmin_Write
  235 (
  236     const char* LE_NONNULL path,
  237         ///< [IN] Path of the secure storage item.
  238     const uint8_t* bufPtr,
  239         ///< [IN] Buffer containing the data to store.
  240     size_t bufSize
  241         ///< [IN]
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  * Reads an item from secure storage.
  247  *
  248  * @note
  249  *      The specified path must be an absolute path.
  250  *
  251  * @return
  252  *      LE_OK if successful.
  253  *      LE_OVERFLOW if the buffer is too small to hold the entire item. No data will be written to
  254  *                  the buffer in this case.
  255  *      LE_NOT_FOUND if the item doesn't exist.
  256  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  257  *      LE_FAULT if there was some other error.
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 le_result_t secStoreAdmin_Read
  261 (
  262     const char* LE_NONNULL path,
  263         ///< [IN] Path of the secure storage item.
  264     uint8_t* bufPtr,
  265         ///< [OUT] Buffer to store the data in.
  266     size_t* bufSizePtr
  267         ///< [INOUT]
  268 );
  269 
  270 //--------------------------------------------------------------------------------------------------
  271 /**
  272  * Copy the meta file to the specified path.
  273  *
  274  * @return
  275  *      LE_OK if successful.
  276  *      LE_NOT_FOUND if the meta file does not exist.
  277  *      LE_UNAVAILABLE if the sfs is currently unavailable.
  278  *      LE_FAULT if there was some other error.
  279  */
  280 //--------------------------------------------------------------------------------------------------
  281 le_result_t secStoreAdmin_CopyMetaTo
  282 (
  283     const char* LE_NONNULL path
  284         ///< [IN] Destination path of meta file copy.
  285 );
  286 
  287 //--------------------------------------------------------------------------------------------------
  288 /**
  289  * Recursively deletes all items under the specified path and the specified path from secure
  290  * storage.
  291  *
  292  * @note
  293  *      The specified path must be an absolute path.
  294  *
  295  * @return
  296  *      LE_OK if successful.
  297  *      LE_NOT_FOUND if the path doesn't exist.
  298  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  299  *      LE_FAULT if there was some other error.
  300  */
  301 //--------------------------------------------------------------------------------------------------
  302 le_result_t secStoreAdmin_Delete
  303 (
  304     const char* LE_NONNULL path
  305         ///< [IN] Path of the secure storage item.
  306 );
  307 
  308 //--------------------------------------------------------------------------------------------------
  309 /**
  310  * Gets the size, in bytes, of all items under the specified path.
  311  *
  312  * @note
  313  *      The specified path must be an absolute path.
  314  *
  315  * @return
  316  *      LE_OK if successful.
  317  *      LE_NOT_FOUND if the path doesn't exist.
  318  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  319  *      LE_FAULT if there was some other error.
  320  */
  321 //--------------------------------------------------------------------------------------------------
  322 le_result_t secStoreAdmin_GetSize
  323 (
  324     const char* LE_NONNULL path,
  325         ///< [IN] Path of the secure storage item.
  326     uint64_t* sizePtr
  327         ///< [OUT] Size in bytes of all items in the path.
  328 );
  329 
  330 //--------------------------------------------------------------------------------------------------
  331 /**
  332  * Gets the total space and the available free space in secure storage.
  333  *
  334  * @return
  335  *      LE_OK if successful.
  336  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  337  *      LE_FAULT if there was some other error.
  338  */
  339 //--------------------------------------------------------------------------------------------------
  340 le_result_t secStoreAdmin_GetTotalSpace
  341 (
  342     uint64_t* totalSizePtr,
  343         ///< [OUT] Total size, in bytes, of secure storage.
  344     uint64_t* freeSizePtr
  345         ///< [OUT] Free space, in bytes, in secure storage.
  346 );
  347 
  348 #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_GetEntry
le_result_t secStoreAdmin_GetEntry(secStoreAdmin_IterRef_t iterRef, char *name, size_t nameSize, bool *isDirPtr)
secStoreAdmin_Write
le_result_t secStoreAdmin_Write(const char *LE_NONNULL path, const uint8_t *bufPtr, size_t bufSize)
secStoreAdmin_Read
le_result_t secStoreAdmin_Read(const char *LE_NONNULL path, uint8_t *bufPtr, size_t *bufSizePtr)
secStoreAdmin_Delete
le_result_t secStoreAdmin_Delete(const char *LE_NONNULL path)
secStoreAdmin_GetSize
le_result_t secStoreAdmin_GetSize(const char *LE_NONNULL path, uint64_t *sizePtr)
secStoreAdmin_DeleteIter
void secStoreAdmin_DeleteIter(secStoreAdmin_IterRef_t iterRef)
secStoreAdmin_ConnectService
void secStoreAdmin_ConnectService(void)
legato.h
secStoreAdmin_Next
le_result_t secStoreAdmin_Next(secStoreAdmin_IterRef_t iterRef)
secStoreAdmin_CopyMetaTo
le_result_t secStoreAdmin_CopyMetaTo(const char *LE_NONNULL path)
secStoreAdmin_SetServerDisconnectHandler
void secStoreAdmin_SetServerDisconnectHandler(secStoreAdmin_DisconnectHandler_t disconnectHandler, void *contextPtr)
secStoreAdmin_CreateIter
secStoreAdmin_IterRef_t secStoreAdmin_CreateIter(const char *LE_NONNULL path)
le_secStore_interface.h
secStoreAdmin_GetTotalSpace
le_result_t secStoreAdmin_GetTotalSpace(uint64_t *totalSizePtr, uint64_t *freeSizePtr)
secStoreAdmin_DisconnectService
void secStoreAdmin_DisconnectService(void)