le_iks_aesCmac_interface.h

Go to the documentation of this file.
    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_iks_aesCmac IoT Keystore AES CBC API
   14  *
   15  * @ref le_iks_aesCmac_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * Legato IoT Keystore APIs for generating and verifying message authentication codes using AES in
   20  * CMAC mode.
   21  *
   22  * <HR>
   23  *
   24  * Copyright (C) Sierra Wireless Inc.
   25  */
   26 /**
   27  * @file le_iks_aesCmac_interface.h
   28  *
   29  * Legato @ref c_iks_aesCmac API
   30  *
   31  * Copyright (C) Sierra Wireless Inc.
   32  */
   33 
   34 #ifndef LE_IKS_AESCMAC_INTERFACE_H_INCLUDE_GUARD
   35 #define LE_IKS_AESCMAC_INTERFACE_H_INCLUDE_GUARD
   36 
   37 
   38 #include "legato.h"
   39 
   40 // Interface specific includes
   41 #include "le_iks_interface.h"
   42 
   43 // Internal includes for this interface
   44 #include "le_iks_aesCmac_common.h"
   45 /** @addtogroup le_iks_aesCmac le_iks_aesCmac API Reference
   46  * @{
   47  * @file le_iks_aesCmac_common.h
   48  * @file le_iks_aesCmac_interface.h **/
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Type for handler called when a server disconnects.
   52  */
   53 //--------------------------------------------------------------------------------------------------
   54 typedef void (*le_iks_aesCmac_DisconnectHandler_t)(void *);
   55 
   56 //--------------------------------------------------------------------------------------------------
   57 /**
   58  *
   59  * Connect the current client thread to the service providing this API. Block until the service is
   60  * available.
   61  *
   62  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   63  * called before any other functions in this API.  Normally, ConnectService is automatically called
   64  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   65  *
   66  * This function is created automatically.
   67  */
   68 //--------------------------------------------------------------------------------------------------
   69 void le_iks_aesCmac_ConnectService
   70 (
   71     void
   72 );
   73 
   74 //--------------------------------------------------------------------------------------------------
   75 /**
   76  *
   77  * Try to connect the current client thread to the service providing this API. Return with an error
   78  * if the service is not available.
   79  *
   80  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   81  * called before any other functions in this API.  Normally, ConnectService is automatically called
   82  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   83  *
   84  * This function is created automatically.
   85  *
   86  * @return
   87  *  - LE_OK if the client connected successfully to the service.
   88  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
   89  *    bound.
   90  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   91  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 le_result_t le_iks_aesCmac_TryConnectService
   95 (
   96     void
   97 );
   98 
   99 //--------------------------------------------------------------------------------------------------
  100 /**
  101  * Set handler called when server disconnection is detected.
  102  *
  103  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  104  * to continue without exiting, it should call longjmp() from inside the handler.
  105  */
  106 //--------------------------------------------------------------------------------------------------
  107 LE_FULL_API void le_iks_aesCmac_SetServerDisconnectHandler
  108 (
  109     le_iks_aesCmac_DisconnectHandler_t disconnectHandler,
  110     void *contextPtr
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Disconnect the current client thread from the service providing this API.
  117  *
  118  * Normally, this function doesn't need to be called. After this function is called, there's no
  119  * longer a connection to the service, and the functions in this API can't be used. For details, see
  120  * @ref apiFilesC_client.
  121  *
  122  * This function is created automatically.
  123  */
  124 //--------------------------------------------------------------------------------------------------
  125 void le_iks_aesCmac_DisconnectService
  126 (
  127     void
  128 );
  129 
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  * Process message chunks.  This function may be called multiple times to process the entire
  134  * message but once a message has been completely processed and le_iks_aesCmac_Done() or
  135  * le_iks_aesCmac_Verify() has been called this function should not be called again with the same
  136  * session.
  137  *
  138  * @return
  139  *      LE_OK if successful.
  140  *      LE_BAD_PARAMETER if the session reference is invalid
  141  *                       or if the key type is invalid
  142  *                       or if msgChunkPtr is NULL.
  143  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  144  *      LE_FAULT if no more messages can be processed, ie. le_iks_aesCmac_Done() or
  145  *               le_iks_aesCmac_Verify() has already been called,
  146  *               or if there was an internal error.
  147  */
  148 //--------------------------------------------------------------------------------------------------
  149 le_result_t le_iks_aesCmac_ProcessChunk
  150 (
  151     uint64_t session,
  152         ///< [IN] Session reference.
  153     const uint8_t* msgChunkPtr,
  154         ///< [IN] Message chunk.
  155         ///< Must be <= MAX_PACKET_SIZE.
  156     size_t msgChunkSize
  157         ///< [IN]
  158 );
  159 
  160 //--------------------------------------------------------------------------------------------------
  161 /**
  162  * Complete message processing and get the processed message's authentication tag.
  163  *
  164  * The maximum size of the authentication tag is MAX_TAG_SIZE.  If the supplied buffer is
  165  * smaller than the maximum tag size then the tag will be truncated.  However, all tags produced
  166  * using the same key must use the same tag size.  It is up to the caller to ensure this.
  167  *
  168  * @return
  169  *      LE_OK if successful.
  170  *      LE_BAD_PARAMETER if the session reference is invalid
  171  *                       or if the key type is invalid
  172  *                       or if bufPtr is NULL.
  173  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  174  *      LE_FAULT if no message was processed or le_iks_aesCmac_Done() or
  175  *               le_iks_aesCmac_Verify() has already been called,
  176  *               or if there was an internal error.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 le_result_t le_iks_aesCmac_Done
  180 (
  181     uint64_t session,
  182         ///< [IN] Session reference.
  183     uint8_t* tagBufPtr,
  184         ///< [OUT] Buffer to hold the authentication tag.
  185     size_t* tagBufSizePtr
  186         ///< [INOUT]
  187 );
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * Complete message processing and compare the resulting authentication tag with the supplied tag.
  192  *
  193  * The maximum size of the authentication tag is MAX_TAG_SIZE.  If the supplied tag is
  194  * smaller than the maximum tag size then only the first tagSize bytes of the tag is compared.
  195  * However, all tags produced using the same key must use the same tag size.  It is up to the caller
  196  * to ensure this.
  197  *
  198  * @return
  199  *      LE_OK if the specified tag matches the calculated message tag.
  200  *      LE_BAD_PARAMETER if the session reference is invalid
  201  *                       or if the key type is invalid
  202  *                         or if tagPtr is NULL or tagSize is zero.
  203  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  204  *      LE_FAULT if the specified tag does not match the calculated message tag,
  205  *               or if no message was processed or le_iks_aesCmac_Done() or
  206  *               or le_iks_aesCmac_Verify() has already been called,
  207  *               or if there was an internal error.
  208  */
  209 //--------------------------------------------------------------------------------------------------
  210 le_result_t le_iks_aesCmac_Verify
  211 (
  212     uint64_t session,
  213         ///< [IN] Session reference.
  214     const uint8_t* tagBufPtr,
  215         ///< [IN] Authentication tag to check against.
  216     size_t tagBufSize
  217         ///< [IN]
  218 );
  219 
  220 /** @} **/
  221 
  222 #endif // LE_IKS_AESCMAC_INTERFACE_H_INCLUDE_GUARD
le_iks_aesCmac_Verify
le_result_t le_iks_aesCmac_Verify(uint64_t session, const uint8_t *tagBufPtr, size_t tagBufSize)


le_result_t
le_result_t
Definition: le_basics.h:46


le_iks_aesCmac_common.h


le_iks_aesCmac_ConnectService
void le_iks_aesCmac_ConnectService(void)


le_iks_aesCmac_DisconnectService
void le_iks_aesCmac_DisconnectService(void)


le_iks_aesCmac_SetServerDisconnectHandler
LE_FULL_API void le_iks_aesCmac_SetServerDisconnectHandler(le_iks_aesCmac_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_iks_aesCmac_ProcessChunk
le_result_t le_iks_aesCmac_ProcessChunk(uint64_t session, const uint8_t *msgChunkPtr, size_t msgChunkSize)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_iks_aesCmac_DisconnectHandler_t
void(* le_iks_aesCmac_DisconnectHandler_t)(void *)
Definition: le_iks_aesCmac_interface.h:54


le_iks_interface.h


le_iks_aesCmac_TryConnectService
le_result_t le_iks_aesCmac_TryConnectService(void)


le_iks_aesCmac_Done
le_result_t le_iks_aesCmac_Done(uint64_t session, uint8_t *tagBufPtr, size_t *tagBufSizePtr)