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