le_secStore_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_secStore Secure Storage
   12  *
   13  * @ref le_secStore_interface.h "API Reference" <br>
   14  * @ref c_secStoreAdmin API
   15  *
   16  * <HR>
   17  *
   18  * This API for accessing secure storage.
   19  *
   20  * Secure storage can be used to store sensitive information like passwords, keys, certificates,
   21  * etc. All data in the secure storage is in an encrypted format. Each app using this API only has
   22  * access to its own secure storage data.
   23  *
   24  * App's items in secure storage have a name and a value. The item name is used to access the item's
   25  * value and can be maximum 255 characters.  The item name can contain path separators, '/', to
   26  * help organize an app's data.  Item names cannot contain a trailing separator.
   27  *
   28  * To create or update an item, use le_secStore_Write() to specify the item's name and value. If the
   29  * item doesn't exist, it'll be created. Each item can be a maximum of 8192 bytes.  If it's larger,
   30  * le_secStore_Write() will fail.
   31  *
   32  * Additionally, an app's total secure storage usage is limited by the maxSecureStorageBytes setting
   33  * that may be specified in the xdef files.  The maxSecureStorageBytes default is 8192 bytes.
   34  *
   35  * Writing to secure storage may also fail if the system-wide secure storage is out of memory.  The
   36  * system-wide secure storage memory amount is platform dependent
   37  * (see @ref platformConstraintsSecStorage).
   38  *
   39  * To read an item, use le_secStore_Read(), and specify the item's name. To delete an item, use
   40  * le_secStore_Delete().
   41  *
   42  * All the functions in this API are provided by the @b secStore service.
   43  *
   44  * Here's a code sample binding to this service:
   45  * @verbatim
   46    bindings:
   47    {
   48       clientExe.clientComponent.le_secStore -> secStore.le_secStore
   49    }
   50    @endverbatim
   51  *
   52  * Whenever the secure storage is modified, a timer of 300 seconds is started. When the timer
   53  * expires, a backup is performed to capture all changes since the previous backup. If the secure
   54  * storage is not modified, then the backup is not performed.
   55  * If corruption in the secure storage is detected, a restore is performed and the target device is
   56  * rebooted.
   57  *
   58  * <HR>
   59  *
   60  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   61  */
   62 /**
   63  * @file le_secStore_interface.h
   64  *
   65  * Legato @ref c_secStore API
   66  *
   67  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   68  */
   69 
   70 #ifndef LE_SECSTORE_INTERFACE_H_INCLUDE_GUARD
   71 #define LE_SECSTORE_INTERFACE_H_INCLUDE_GUARD
   72 
   73 
   74 #include "legato.h"
   75 
   76 //--------------------------------------------------------------------------------------------------
   77 /**
   78  *
   79  * Connect the current client thread to the service providing this API. Block until the service is
   80  * 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 //--------------------------------------------------------------------------------------------------
   89 void le_secStore_ConnectService
   90 (
   91     void
   92 );
   93 
   94 //--------------------------------------------------------------------------------------------------
   95 /**
   96  *
   97  * Try to connect the current client thread to the service providing this API. Return with an error
   98  * if the service is not available.
   99  *
  100  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  101  * called before any other functions in this API.  Normally, ConnectService is automatically called
  102  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  103  *
  104  * This function is created automatically.
  105  *
  106  * @return
  107  *  - LE_OK if the client connected successfully to the service.
  108  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  109  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  110  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  111  */
  112 //--------------------------------------------------------------------------------------------------
  113 le_result_t le_secStore_TryConnectService
  114 (
  115     void
  116 );
  117 
  118 //--------------------------------------------------------------------------------------------------
  119 /**
  120  *
  121  * Disconnect the current client thread from the service providing this API.
  122  *
  123  * Normally, this function doesn't need to be called. After this function is called, there's no
  124  * longer a connection to the service, and the functions in this API can't be used. For details, see
  125  * @ref apiFilesC_client.
  126  *
  127  * This function is created automatically.
  128  */
  129 //--------------------------------------------------------------------------------------------------
  130 void le_secStore_DisconnectService
  131 (
  132     void
  133 );
  134 
  135 
  136 //--------------------------------------------------------------------------------------------------
  137 /**
  138  * Maximum number of characters and byte storage size permitted for a secure storage item name.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 #define LE_SECSTORE_MAX_NAME_SIZE 255
  142 
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 #define LE_SECSTORE_MAX_NAME_BYTES 256
  148 
  149 
  150 //--------------------------------------------------------------------------------------------------
  151 /**
  152  * Maximum number of bytes for each item in secure storage.
  153  */
  154 //--------------------------------------------------------------------------------------------------
  155 #define LE_SECSTORE_MAX_ITEM_SIZE 8192
  156 
  157 //--------------------------------------------------------------------------------------------------
  158 /**
  159  * Writes an item to secure storage. If the item already exists, it'll be overwritten with
  160  * the new value. If the item doesn't already exist, it'll be created.
  161  *
  162  * @return
  163  *      LE_OK if successful.
  164  *      LE_NO_MEMORY if there isn't enough memory to store the item.
  165  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  166  *      LE_FAULT if there was some other error.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 le_result_t le_secStore_Write
  170 (
  171     const char* name,
  172         ///< [IN] Name of the secure storage item.
  173 
  174     const uint8_t* bufPtr,
  175         ///< [IN] Buffer containing the data to store.
  176 
  177     size_t bufNumElements
  178         ///< [IN]
  179 );
  180 
  181 //--------------------------------------------------------------------------------------------------
  182 /**
  183  * Reads an item from secure storage.
  184  *
  185  * @return
  186  *      LE_OK if successful.
  187  *      LE_OVERFLOW if the buffer is too small to hold the entire item. No data will be written to
  188  *                  the buffer in this case.
  189  *      LE_NOT_FOUND if the item doesn't exist.
  190  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  191  *      LE_FAULT if there was some other error.
  192  */
  193 //--------------------------------------------------------------------------------------------------
  194 le_result_t le_secStore_Read
  195 (
  196     const char* name,
  197         ///< [IN] Name of the secure storage item.
  198 
  199     uint8_t* bufPtr,
  200         ///< [OUT] Buffer to store the data in.
  201 
  202     size_t* bufNumElementsPtr
  203         ///< [INOUT]
  204 );
  205 
  206 //--------------------------------------------------------------------------------------------------
  207 /**
  208  * Deletes an item from secure storage.
  209  *
  210  * @return
  211  *      LE_OK if successful.
  212  *      LE_NOT_FOUND if the item doesn't exist.
  213  *      LE_UNAVAILABLE if the secure storage is currently unavailable.
  214  *      LE_FAULT if there was some other error.
  215  */
  216 //--------------------------------------------------------------------------------------------------
  217 le_result_t le_secStore_Delete
  218 (
  219     const char* name
  220         ///< [IN] Name of the secure storage item.
  221 );
  222 
  223 
  224 #endif // LE_SECSTORE_INTERFACE_H_INCLUDE_GUARD
  225 
le_secStore_Read
le_result_t le_secStore_Read(const char *name, uint8_t *bufPtr, size_t *bufNumElementsPtr)
le_result_t
le_result_t
Definition: le_basics.h:35
le_secStore_TryConnectService
le_result_t le_secStore_TryConnectService(void)
le_secStore_Write
le_result_t le_secStore_Write(const char *name, const uint8_t *bufPtr, size_t bufNumElements)
le_secStore_ConnectService
void le_secStore_ConnectService(void)
legato.h
le_secStore_Delete
le_result_t le_secStore_Delete(const char *name)
le_secStore_DisconnectService
void le_secStore_DisconnectService(void)