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