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