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