secStoreAdmin_interface.h

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