le_iks_aesGcm_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_aesGcm IoT Keystore AES GCM API
   14  *
   15  * @ref le_iks_aesGcm_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This module provides APIs for performing AES encryption in GCM mode.
   20  *
   21  * <HR>
   22  *
   23  * Copyright (C) Sierra Wireless Inc.
   24  */
   25 /**
   26  * @file le_iks_aesGcm_interface.h
   27  *
   28  * Legato @ref c_iks API
   29  *
   30  * Copyright (C) Sierra Wireless Inc.
   31  */
   32 
   33 #ifndef LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
   34 #define LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
   35 
   36 
   37 #include "legato.h"
   38 
   39 // Interface specific includes
   40 #include "le_iks_interface.h"
   41 
   42 // Internal includes for this interface
   43 #include "le_iks_aesGcm_common.h"
   44 /** @addtogroup le_iks_aesGcm le_iks_aesGcm API Reference
   45  * @{
   46  * @file le_iks_aesGcm_common.h
   47  * @file le_iks_aesGcm_interface.h **/
   48 //--------------------------------------------------------------------------------------------------
   49 /**
   50  * Type for handler called when a server disconnects.
   51  */
   52 //--------------------------------------------------------------------------------------------------
   53 typedef void (*le_iks_aesGcm_DisconnectHandler_t)(void *);
   54 
   55 //--------------------------------------------------------------------------------------------------
   56 /**
   57  *
   58  * Connect the current client thread to the service providing this API. Block until the service is
   59  * available.
   60  *
   61  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   62  * called before any other functions in this API.  Normally, ConnectService is automatically called
   63  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   64  *
   65  * This function is created automatically.
   66  */
   67 //--------------------------------------------------------------------------------------------------
   68 void le_iks_aesGcm_ConnectService
   69 (
   70     void
   71 );
   72 
   73 //--------------------------------------------------------------------------------------------------
   74 /**
   75  *
   76  * Try to connect the current client thread to the service providing this API. Return with an error
   77  * if the service is not available.
   78  *
   79  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   80  * called before any other functions in this API.  Normally, ConnectService is automatically called
   81  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   82  *
   83  * This function is created automatically.
   84  *
   85  * @return
   86  *  - LE_OK if the client connected successfully to the service.
   87  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
   88  *    bound.
   89  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   90  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
   91  */
   92 //--------------------------------------------------------------------------------------------------
   93 le_result_t le_iks_aesGcm_TryConnectService
   94 (
   95     void
   96 );
   97 
   98 //--------------------------------------------------------------------------------------------------
   99 /**
  100  * Set handler called when server disconnection is detected.
  101  *
  102  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  103  * to continue without exiting, it should call longjmp() from inside the handler.
  104  */
  105 //--------------------------------------------------------------------------------------------------
  106 LE_FULL_API void le_iks_aesGcm_SetServerDisconnectHandler
  107 (
  108     le_iks_aesGcm_DisconnectHandler_t disconnectHandler,
  109     void *contextPtr
  110 );
  111 
  112 //--------------------------------------------------------------------------------------------------
  113 /**
  114  *
  115  * Disconnect the current client thread from the service providing this API.
  116  *
  117  * Normally, this function doesn't need to be called. After this function is called, there's no
  118  * longer a connection to the service, and the functions in this API can't be used. For details, see
  119  * @ref apiFilesC_client.
  120  *
  121  * This function is created automatically.
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 void le_iks_aesGcm_DisconnectService
  125 (
  126     void
  127 );
  128 
  129 
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * Encrypt and integrity protect a packet with AES in GCM mode.
  133  *
  134  * GCM is an AEAD (Authenticated Encryption with Associated Data) which means that it provides both
  135  * confidentiality and integrity protection for plaintext data and provides integrity protection for
  136  * associated data.  The associated data, also referred to as Additional Authenticated Data (AAD),
  137  * is not encrypted but is integrity protected.  The output of the encryption is a randomly chosen
  138  * nonce, the ciphertext corresponding to the plaintext and an authentication tag.  The
  139  * authentication tag integrity protects the nonce, AAD and the ciphertext.
  140  *
  141  * ______________________
  142  * |   AAD, plaintext   |
  143  * ----------------------
  144  *           |
  145  *           V
  146  * ______________________________
  147  * |   nonce, ciphertext, tag   |
  148  * ------------------------------
  149  *
  150  * This is especially useful in communication protocols where a packet's payload needs to be secret
  151  * but the packet's header must be readable.  In this case the packet's header is the AAD.
  152  *
  153  * The AAD and plaintext are optional but they cannot both be omitted.  If the AAD is omitted then
  154  * confidentiality and integrity is provided for just the plaintext.  If the plaintext is omitted
  155  * then integrity protection is provided for just the AAD.
  156  *
  157  * The ciphertext size is the same as the plaintext size and it is assumed that the ciphertextPtr
  158  * buffer is at least plaintextSize bytes long.
  159  *
  160  * The tag size is always LE_IKS_AES_GCM_TAG_SIZE bytes and it is assumed that the tagPtr buffer is
  161  * large enough to hold the tag.
  162  *
  163  * A random nonce is chosen for each invocation of this function.  The nonce is passed out to the
  164  * caller via noncePtr and is assumed to always be LE_IKS_AES_GCM_NONCE_SIZE bytes.
  165  * The nonce does not need to be kept secret and can be passed in the clear.
  166  *
  167  * Nonce values must be unique for each invocation for the lifetime of the key.  In other words a
  168  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
  169  * world.  This is a critical security requirement but can be difficult to satisfy that is why
  170  * keys should be rotated frequently.
  171  *
  172  * Repeated nonces in GCM are particularly problematic as they can be used to recover the integrity
  173  * key.
  174  *
  175  * @return
  176  *      LE_OK if successful.
  177  *      LE_OUT_OF_RANGE if either the  aadSize or plaintextSize is the wrong size.
  178  *      LE_BAD_PARAMETER if the key reference is invalid
  179  *                       or if the key type is invalid
  180  *                       or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
  181  *                        they shouldn't be.
  182  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  183  *      LE_FAULT if there was an internal error.
  184  */
  185 //--------------------------------------------------------------------------------------------------
  186 le_result_t le_iks_aesGcm_EncryptPacket
  187 (
  188     uint64_t keyRef,
  189         ///< [IN] Key reference.
  190     uint8_t* noncePtr,
  191         ///< [OUT] Buffer to hold the nonce.
  192         ///<   Assumed to be NONCE_SIZE bytes.
  193     size_t* nonceSizePtr,
  194         ///< [INOUT]
  195     const uint8_t* aadPtr,
  196         ///< [IN] Additional authenticated data (AAD).
  197         ///<   NULL if not used.
  198     size_t aadSize,
  199         ///< [IN]
  200     const uint8_t* plaintextPtr,
  201         ///< [IN] Plaintext. NULL if not used.
  202     size_t plaintextSize,
  203         ///< [IN]
  204     uint8_t* ciphertextPtr,
  205         ///< [OUT] Buffer to hold the ciphertext.
  206     size_t* ciphertextSizePtr,
  207         ///< [INOUT]
  208     uint8_t* tagPtr,
  209         ///< [OUT] Buffer to hold the authentication tag.
  210         ///<   Assumed to be TAG_SIZE.
  211     size_t* tagSizePtr
  212         ///< [INOUT]
  213 );
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * Decrypt and verify the integrity of a packet with AES in GCM mode.
  218  *
  219  * This function performs an integrity check of the AAD and the ciphertext and if the integrity
  220  * passes provides the decrypted plaintext.
  221  *
  222  * The plaintext size is the same as the ciphertext size and it is assumed that the plaintextPtr
  223  * buffer is at least ciphertextSize bytes long.
  224  *
  225  * The nonce, AAD, ciphertext and tag must be the values produced during encryption.
  226  *
  227  * ___________________________________
  228  * |   nonce, AAD, ciphertext, tag   |
  229  * -----------------------------------
  230  *                  |
  231  *                  V
  232  *         _________________
  233  *         |   plaintext   |
  234  *         -----------------
  235  *
  236  * @return
  237  *      LE_OK if successful.
  238  *      LE_OUT_OF_RANGE if either the aadSize or ciphertextSize is too large.
  239  *      LE_BAD_PARAMETER if the key reference is invalid
  240  *                       or if the key type is invalid
  241  *                       or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
  242  *                        they shouldn't be.
  243  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  244  *      LE_FAULT if the integrity check failed.
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 le_result_t le_iks_aesGcm_DecryptPacket
  248 (
  249     uint64_t keyRef,
  250         ///< [IN] Key reference.
  251     const uint8_t* noncePtr,
  252         ///< [IN] Nonce used to encrypt the packet.
  253         ///<   Assumed to be NONCE_SIZE bytes.
  254     size_t nonceSize,
  255         ///< [IN]
  256     const uint8_t* aadPtr,
  257         ///< [IN] Additional authenticated data (AAD).
  258         ///<   NULL if not used.
  259     size_t aadSize,
  260         ///< [IN]
  261     const uint8_t* ciphertextPtr,
  262         ///< [IN] Ciphertext. NULL if not used.
  263     size_t ciphertextSize,
  264         ///< [IN]
  265     uint8_t* plaintextPtr,
  266         ///< [OUT] Buffer to hold the plaintext.
  267     size_t* plaintextSizePtr,
  268         ///< [INOUT]
  269     const uint8_t* tagPtr,
  270         ///< [IN] Buffer to hold the authentication tag.
  271         ///<   Assumed to be TAG_SIZE.
  272     size_t tagSize
  273         ///< [IN]
  274 );
  275 
  276 //--------------------------------------------------------------------------------------------------
  277 /**
  278  * Starts a process to encrypt and integrity protect a long packet with AES in GCM mode.  This
  279  * function is useful for encrypting and integrity protecting packets that are larger than
  280  * MAX_PACKET_SIZE.  Calling this function will cancel any previously started process using the
  281  * same session.
  282  *
  283  * To encrypt a long packet the following sequence should be used:
  284  *
  285  * le_iks_aesGcm_StartEncrypt() // Start the encryption process.
  286  * le_iks_aesGcm_ProcessAad()   // Call zero or more times until all AAD data is processed.
  287  * le_iks_aesGcm_Encrypt()      // Call zero or more times until all plaintext is encrypted.
  288  * le_iks_aesGcm_DoneEncrypt()  // Complete process and obtain authentication tag.
  289  *
  290  * All AAD must be processed before plaintext processing begins.
  291  *
  292  * A random nonce is chosen for each invocation of this function.  The nonce is passed out to the
  293  * caller via noncePtr and is assumed to always be AES_GCM_NONCE_SIZE bytes.
  294  * The nonce does not need to be kept secret and can be passed in the clear.
  295  *
  296  * Nonce values must be unique for each invocation for the lifetime of the key.  In other words a
  297  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
  298  * world.  This is a critical security requirement but can be difficult to satisfy.  Therefore keys
  299  * should be rotated frequently.
  300  *
  301  * @return
  302  *      LE_OK if successful.
  303  *      LE_BAD_PARAMETER if the session reference is invalid
  304  *                       or if the key type is invalid
  305  *                       or if noncePtr is NULL.
  306  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  307  *      LE_FAULT if there was an internal error.
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 le_result_t le_iks_aesGcm_StartEncrypt
  311 (
  312     uint64_t session,
  313         ///< [IN] Session reference.
  314     uint8_t* noncePtr,
  315         ///< [OUT] Buffer to hold the nonce.
  316         ///<   Assumed to be NONCE_SIZE bytes.
  317     size_t* nonceSizePtr
  318         ///< [INOUT]
  319 );
  320 
  321 //--------------------------------------------------------------------------------------------------
  322 /**
  323  * Process a chunk of AAD (Additional Authenticated Data).  Either le_iks_aesGcm_StartEncrypt() or
  324  * le_iks_aesGcm_StartDecrypt() must have been previously called to start either an encryption or
  325  * decryption process.
  326  *
  327  * @return
  328  *      LE_OK if successful.
  329  *      LE_BAD_PARAMETER if the session reference is invalid
  330  *                       or if the key type is invalid
  331  *                       or if aadChunkPtr is NULL.
  332  *      LE_OUT_OF_RANGE if aadChunkSize is too big.
  333  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  334  *      LE_FAULT if an encryption or decryption process was not started or
  335  *                            plaintext/ciphertext processing has already started.
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 le_result_t le_iks_aesGcm_ProcessAad
  339 (
  340     uint64_t session,
  341         ///< [IN] Session reference.
  342     const uint8_t* aadPtr,
  343         ///< [IN] Additional authenticated data (AAD).
  344         ///<   NULL if not used.
  345     size_t aadSize
  346         ///< [IN]
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Encrypt a chunk of plaintext.  le_iks_aesGcm_StartEncrypt() must have been previously called to
  352  * start an encryption process.
  353  *
  354  * @return
  355  *      LE_OK if successful.
  356  *      LE_BAD_PARAMETER if the session reference is invalid
  357  *                       or if the key type is invalid
  358  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  359  *      LE_OUT_OF_RANGE if textSize is too big.
  360  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  361  *      LE_FAULT if an encryption process has not started.
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 le_result_t le_iks_aesGcm_Encrypt
  365 (
  366     uint64_t session,
  367         ///< [IN] Session reference.
  368     const uint8_t* plaintextChunkPtr,
  369         ///< [IN] Plaintext.
  370     size_t plaintextChunkSize,
  371         ///< [IN]
  372     uint8_t* ciphertextChunkPtr,
  373         ///< [OUT] Buffer to hold the ciphertext.
  374     size_t* ciphertextChunkSizePtr
  375         ///< [INOUT]
  376 );
  377 
  378 //--------------------------------------------------------------------------------------------------
  379 /**
  380  * Complete encryption and calculate the authentication tag.
  381  *
  382  * @return
  383  *      LE_OK if successful.
  384  *      LE_BAD_PARAMETER if the session reference is invalid
  385  *                       or if the key type is invalid
  386  *                       or if tagPtr is NULL.
  387  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  388  *      LE_FAULT if an encryption process has not started or no data
  389  *                            (AAD and plaintext) has been processed.
  390  */
  391 //--------------------------------------------------------------------------------------------------
  392 le_result_t le_iks_aesGcm_DoneEncrypt
  393 (
  394     uint64_t session,
  395         ///< [IN] Session reference.
  396     uint8_t* tagPtr,
  397         ///< [OUT] Buffer to hold the authentication tag.
  398         ///<   Assumed to be TAG_SIZE.
  399     size_t* tagSizePtr
  400         ///< [INOUT]
  401 );
  402 
  403 //--------------------------------------------------------------------------------------------------
  404 /**
  405  * Starts a process to decrypt and verify the integrity of a long packet with AES in GCM mode.  This
  406  * function is useful for decrypting and verifying packets that are larger than MAX_PACKET_SIZE.
  407  * Calling this function will cancel any previously started process using the same session.
  408  *
  409  * To decrypt a long packet the following sequence should be used:
  410  *
  411  * le_iks_aesGcm_StartDecrypt() // Start the decryption process.
  412  * le_iks_aesGcm_ProcessAad()   // Call zero or more times until all AAD data is processed.
  413  * le_iks_aesGcm_Decrypt()      // Call zero or more times until all ciphertext is decrypted.
  414  * le_iks_aesGcm_DoneDecrypt()  // Complete decryption process.
  415  *
  416  * @warning
  417  *      While decrypting long packets in this 'streaming' fashion plaintext chunks are released to
  418  *      the caller before they are verified for integrity.  Ie. the caller will not know the
  419  *      plaintext is correct until le_iks_aesGcm_DoneDecrypt() is called.  The caller therefore must
  420  *      not release or make use of any plaintext chunks until after
  421  *      le_iks_aesGcm_DoneDecrypt() returns with LE_OK.
  422  *
  423  * @return
  424  *      LE_OK if successful.
  425  *      LE_BAD_PARAMETER if the session reference is invalid
  426  *                       or if the key type is not valid
  427  *                       or if noncePtr is NULL.
  428  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  429  *      LE_FAULT if there was an internal error.
  430  */
  431 //--------------------------------------------------------------------------------------------------
  432 le_result_t le_iks_aesGcm_StartDecrypt
  433 (
  434     uint64_t session,
  435         ///< [IN] Session reference.
  436     const uint8_t* noncePtr,
  437         ///< [IN] Nonce used to encrypt the packet.
  438         ///<   Assumed to be NONCE_SIZE bytes.
  439     size_t nonceSize
  440         ///< [IN]
  441 );
  442 
  443 //--------------------------------------------------------------------------------------------------
  444 /**
  445  * Decrypt a chunk of ciphertext.  le_iks_aesGcm_StartDecrypt() must have been previously called to
  446  * start either a decryption process.
  447  *
  448  * @return
  449  *      LE_OK if successful.
  450  *      LE_BAD_PARAMETER if the session reference is invalid
  451  *                       or if the key type is invalid
  452  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  453  *      LE_OUT_OF_RANGE if textSize is too big.
  454  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  455  *      LE_FAULT if a decryption process has not started.
  456  */
  457 //--------------------------------------------------------------------------------------------------
  458 le_result_t le_iks_aesGcm_Decrypt
  459 (
  460     uint64_t session,
  461         ///< [IN] Session reference.
  462     const uint8_t* ciphertextChunkPtr,
  463         ///< [IN] Ciphertext chunk. NULL if not used.
  464     size_t ciphertextChunkSize,
  465         ///< [IN]
  466     uint8_t* plaintextChunkPtr,
  467         ///< [OUT] Buffer to hold the plaintext chunk.
  468     size_t* plaintextChunkSizePtr
  469         ///< [INOUT]
  470 );
  471 
  472 //--------------------------------------------------------------------------------------------------
  473 /**
  474  * Complete decryption and verify the integrity.
  475  *
  476  * @return
  477  *      LE_OK if successful.
  478  *      LE_BAD_PARAMETER if the session reference is invalid
  479  *                       or if the key type is invalid
  480  *                       or if tagPtr is NULL.
  481  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  482  *      LE_FAULT if a decryption process has not started
  483  *               or no data (AAD and ciphertext) has been processed
  484  *               or the integrity check failed.
  485  */
  486 //--------------------------------------------------------------------------------------------------
  487 le_result_t le_iks_aesGcm_DoneDecrypt
  488 (
  489     uint64_t session,
  490         ///< [IN] Session reference.
  491     const uint8_t* tagPtr,
  492         ///< [IN] Buffer to hold the authentication tag.
  493         ///<   Assumed to be TAG_SIZE.
  494     size_t tagSize
  495         ///< [IN]
  496 );
  497 
  498 /** @} **/
  499 
  500 #endif // LE_IKS_AESGCM_INTERFACE_H_INCLUDE_GUARD
le_iks_aesGcm_DisconnectHandler_t
void(* le_iks_aesGcm_DisconnectHandler_t)(void *)
Definition: le_iks_aesGcm_interface.h:53
le_iks_aesGcm_common.h
le_iks_aesGcm_EncryptPacket
le_result_t le_iks_aesGcm_EncryptPacket(uint64_t keyRef, uint8_t *noncePtr, size_t *nonceSizePtr, const uint8_t *aadPtr, size_t aadSize, const uint8_t *plaintextPtr, size_t plaintextSize, uint8_t *ciphertextPtr, size_t *ciphertextSizePtr, uint8_t *tagPtr, size_t *tagSizePtr)
le_iks_aesGcm_DoneEncrypt
le_result_t le_iks_aesGcm_DoneEncrypt(uint64_t session, uint8_t *tagPtr, size_t *tagSizePtr)
le_result_t
le_result_t
Definition: le_basics.h:46
le_iks_aesGcm_ConnectService
void le_iks_aesGcm_ConnectService(void)
le_iks_aesGcm_Encrypt
le_result_t le_iks_aesGcm_Encrypt(uint64_t session, const uint8_t *plaintextChunkPtr, size_t plaintextChunkSize, uint8_t *ciphertextChunkPtr, size_t *ciphertextChunkSizePtr)
le_iks_aesGcm_StartDecrypt
le_result_t le_iks_aesGcm_StartDecrypt(uint64_t session, const uint8_t *noncePtr, size_t nonceSize)
le_iks_aesGcm_ProcessAad
le_result_t le_iks_aesGcm_ProcessAad(uint64_t session, const uint8_t *aadPtr, size_t aadSize)
le_iks_aesGcm_DecryptPacket
le_result_t le_iks_aesGcm_DecryptPacket(uint64_t keyRef, const uint8_t *noncePtr, size_t nonceSize, const uint8_t *aadPtr, size_t aadSize, const uint8_t *ciphertextPtr, size_t ciphertextSize, uint8_t *plaintextPtr, size_t *plaintextSizePtr, const uint8_t *tagPtr, size_t tagSize)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_iks_aesGcm_Decrypt
le_result_t le_iks_aesGcm_Decrypt(uint64_t session, const uint8_t *ciphertextChunkPtr, size_t ciphertextChunkSize, uint8_t *plaintextChunkPtr, size_t *plaintextChunkSizePtr)
le_iks_aesGcm_DoneDecrypt
le_result_t le_iks_aesGcm_DoneDecrypt(uint64_t session, const uint8_t *tagPtr, size_t tagSize)
le_iks_interface.h
le_iks_aesGcm_DisconnectService
void le_iks_aesGcm_DisconnectService(void)
le_iks_aesGcm_StartEncrypt
le_result_t le_iks_aesGcm_StartEncrypt(uint64_t session, uint8_t *noncePtr, size_t *nonceSizePtr)
le_iks_aesGcm_TryConnectService
le_result_t le_iks_aesGcm_TryConnectService(void)
le_iks_aesGcm_SetServerDisconnectHandler
LE_FULL_API void le_iks_aesGcm_SetServerDisconnectHandler(le_iks_aesGcm_DisconnectHandler_t disconnectHandler, void *contextPtr)