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