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