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