le_iks_aesGcm_common.h

    1 
    2 /*
    3  * ====================== WARNING ======================
    4  *
    5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    6  * DO NOT MODIFY IN ANY WAY.
    7  *
    8  * ====================== WARNING ======================
    9  */
   10 /**
   11  * @file le_iks_aesGcm_common.h
   12  *
   13  * Type definitions for le_iks_aesGcm.
   14  *
   15  */
   16 #ifndef LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
   17 #define LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 // Interface specific includes
   23 #include "le_iks_common.h"
   24 
   25 #define IFGEN_LE_IKS_AESGCM_PROTOCOL_ID "164ae5f9097db67c960177fbe1435998"
   26 #define IFGEN_LE_IKS_AESGCM_MSG_SIZE 8258
   27 /** @addtogroup le_iks_aesGcm
   28  *  @{ **/
   29 
   30 
   31 //--------------------------------------------------------------------------------------------------
   32 /**
   33  * Nonce sizes in bytes.
   34  */
   35 //--------------------------------------------------------------------------------------------------
   36 #define LE_IKS_AESGCM_NONCE_SIZE 12
   37 
   38 //--------------------------------------------------------------------------------------------------
   39 /**
   40  * Tag sizes in bytes.
   41  */
   42 //--------------------------------------------------------------------------------------------------
   43 #define LE_IKS_AESGCM_TAG_SIZE 16
   44 
   45 
   46 //--------------------------------------------------------------------------------------------------
   47 /**
   48  * Get if this client bound locally.
   49  */
   50 //--------------------------------------------------------------------------------------------------
   51 LE_SHARED bool ifgen_le_iks_aesGcm_HasLocalBinding
   52 (
   53     void
   54 );
   55 
   56 
   57 //--------------------------------------------------------------------------------------------------
   58 /**
   59  * Init data that is common across all threads
   60  */
   61 //--------------------------------------------------------------------------------------------------
   62 LE_SHARED void ifgen_le_iks_aesGcm_InitCommonData
   63 (
   64     void
   65 );
   66 
   67 
   68 //--------------------------------------------------------------------------------------------------
   69 /**
   70  * Perform common initialization and open a session
   71  */
   72 //--------------------------------------------------------------------------------------------------
   73 LE_SHARED le_result_t ifgen_le_iks_aesGcm_OpenSession
   74 (
   75     le_msg_SessionRef_t _ifgen_sessionRef,
   76     bool isBlocking
   77 );
   78 
   79 //--------------------------------------------------------------------------------------------------
   80 /**
   81  * Encrypt and integrity protect a packet with AES in GCM mode.
   82  *
   83  * GCM is an AEAD (Authenticated Encryption with Associated Data) which means that it provides both
   84  * confidentiality and integrity protection for plaintext data and provides integrity protection for
   85  * associated data.  The associated data, also referred to as Additional Authenticated Data (AAD),
   86  * is not encrypted but is integrity protected.  The output of the encryption is a randomly chosen
   87  * nonce, the ciphertext corresponding to the plaintext and an authentication tag.  The
   88  * authentication tag integrity protects the nonce, AAD and the ciphertext.
   89  *
   90  * ______________________
   91  * |   AAD, plaintext   |
   92  * ----------------------
   93  *           |
   94  *           V
   95  * ______________________________
   96  * |   nonce, ciphertext, tag   |
   97  * ------------------------------
   98  *
   99  * This is especially useful in communication protocols where a packet's payload needs to be secret
  100  * but the packet's header must be readable.  In this case the packet's header is the AAD.
  101  *
  102  * The AAD and plaintext are optional but they cannot both be omitted.  If the AAD is omitted then
  103  * confidentiality and integrity is provided for just the plaintext.  If the plaintext is omitted
  104  * then integrity protection is provided for just the AAD.
  105  *
  106  * The ciphertext size is the same as the plaintext size and it is assumed that the ciphertextPtr
  107  * buffer is at least plaintextSize bytes long.
  108  *
  109  * The tag size is always LE_IKS_AES_GCM_TAG_SIZE bytes and it is assumed that the tagPtr buffer is
  110  * large enough to hold the tag.
  111  *
  112  * A random nonce is chosen for each invocation of this function.  The nonce is passed out to the
  113  * caller via noncePtr and is assumed to always be LE_IKS_AES_GCM_NONCE_SIZE bytes.
  114  * The nonce does not need to be kept secret and can be passed in the clear.
  115  *
  116  * Nonce values must be unique for each invocation for the lifetime of the key.  In other words a
  117  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
  118  * world.  This is a critical security requirement but can be difficult to satisfy that is why
  119  * keys should be rotated frequently.
  120  *
  121  * Repeated nonces in GCM are particularly problematic as they can be used to recover the integrity
  122  * key.
  123  *
  124  * @return
  125  *      LE_OK if successful.
  126  *      LE_OUT_OF_RANGE if either the  aadSize or plaintextSize is the wrong size.
  127  *      LE_BAD_PARAMETER if the key reference is invalid
  128  *                       or if the key type is invalid
  129  *                       or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
  130  *                        they shouldn't be.
  131  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  132  *      LE_FAULT if there was an internal error.
  133  */
  134 //--------------------------------------------------------------------------------------------------
  135 LE_SHARED le_result_t ifgen_le_iks_aesGcm_EncryptPacket
  136 (
  137     le_msg_SessionRef_t _ifgen_sessionRef,
  138         uint64_t keyRef,
  139         ///< [IN] Key reference.
  140         uint8_t* noncePtr,
  141         ///< [OUT] Buffer to hold the nonce.
  142         ///<   Assumed to be NONCE_SIZE bytes.
  143         size_t* nonceSizePtr,
  144         ///< [INOUT]
  145         const uint8_t* aadPtr,
  146         ///< [IN] Additional authenticated data (AAD).
  147         ///<   NULL if not used.
  148         size_t aadSize,
  149         ///< [IN]
  150         const uint8_t* plaintextPtr,
  151         ///< [IN] Plaintext. NULL if not used.
  152         size_t plaintextSize,
  153         ///< [IN]
  154         uint8_t* ciphertextPtr,
  155         ///< [OUT] Buffer to hold the ciphertext.
  156         size_t* ciphertextSizePtr,
  157         ///< [INOUT]
  158         uint8_t* tagPtr,
  159         ///< [OUT] Buffer to hold the authentication tag.
  160         ///<   Assumed to be TAG_SIZE.
  161         size_t* tagSizePtr
  162         ///< [INOUT]
  163 );
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * Decrypt and verify the integrity of a packet with AES in GCM mode.
  168  *
  169  * This function performs an integrity check of the AAD and the ciphertext and if the integrity
  170  * passes provides the decrypted plaintext.
  171  *
  172  * The plaintext size is the same as the ciphertext size and it is assumed that the plaintextPtr
  173  * buffer is at least ciphertextSize bytes long.
  174  *
  175  * The nonce, AAD, ciphertext and tag must be the values produced during encryption.
  176  *
  177  * ___________________________________
  178  * |   nonce, AAD, ciphertext, tag   |
  179  * -----------------------------------
  180  *                  |
  181  *                  V
  182  *         _________________
  183  *         |   plaintext   |
  184  *         -----------------
  185  *
  186  * @return
  187  *      LE_OK if successful.
  188  *      LE_OUT_OF_RANGE if either the aadSize or ciphertextSize is too large.
  189  *      LE_BAD_PARAMETER if the key reference is invalid
  190  *                       or if the key type is invalid
  191  *                       or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when
  192  *                        they shouldn't be.
  193  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  194  *      LE_FAULT if the integrity check failed.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DecryptPacket
  198 (
  199     le_msg_SessionRef_t _ifgen_sessionRef,
  200         uint64_t keyRef,
  201         ///< [IN] Key reference.
  202         const uint8_t* noncePtr,
  203         ///< [IN] Nonce used to encrypt the packet.
  204         ///<   Assumed to be NONCE_SIZE bytes.
  205         size_t nonceSize,
  206         ///< [IN]
  207         const uint8_t* aadPtr,
  208         ///< [IN] Additional authenticated data (AAD).
  209         ///<   NULL if not used.
  210         size_t aadSize,
  211         ///< [IN]
  212         const uint8_t* ciphertextPtr,
  213         ///< [IN] Ciphertext. NULL if not used.
  214         size_t ciphertextSize,
  215         ///< [IN]
  216         uint8_t* plaintextPtr,
  217         ///< [OUT] Buffer to hold the plaintext.
  218         size_t* plaintextSizePtr,
  219         ///< [INOUT]
  220         const uint8_t* tagPtr,
  221         ///< [IN] Buffer to hold the authentication tag.
  222         ///<   Assumed to be TAG_SIZE.
  223         size_t tagSize
  224         ///< [IN]
  225 );
  226 
  227 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Starts a process to encrypt and integrity protect a long packet with AES in GCM mode.  This
  230  * function is useful for encrypting and integrity protecting packets that are larger than
  231  * MAX_PACKET_SIZE.  Calling this function will cancel any previously started process using the
  232  * same session.
  233  *
  234  * To encrypt a long packet the following sequence should be used:
  235  *
  236  * le_iks_aesGcm_StartEncrypt() // Start the encryption process.
  237  * le_iks_aesGcm_ProcessAad()   // Call zero or more times until all AAD data is processed.
  238  * le_iks_aesGcm_Encrypt()      // Call zero or more times until all plaintext is encrypted.
  239  * le_iks_aesGcm_DoneEncrypt()  // Complete process and obtain authentication tag.
  240  *
  241  * All AAD must be processed before plaintext processing begins.
  242  *
  243  * A random nonce is chosen for each invocation of this function.  The nonce is passed out to the
  244  * caller via noncePtr and is assumed to always be AES_GCM_NONCE_SIZE bytes.
  245  * The nonce does not need to be kept secret and can be passed in the clear.
  246  *
  247  * Nonce values must be unique for each invocation for the lifetime of the key.  In other words a
  248  * (key, nonce) pair must be unique for every invocation for all time and for all users in the
  249  * world.  This is a critical security requirement but can be difficult to satisfy.  Therefore keys
  250  * should be rotated frequently.
  251  *
  252  * @return
  253  *      LE_OK if successful.
  254  *      LE_BAD_PARAMETER if the session reference is invalid
  255  *                       or if the key type is invalid
  256  *                       or if noncePtr is NULL.
  257  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  258  *      LE_FAULT if there was an internal error.
  259  */
  260 //--------------------------------------------------------------------------------------------------
  261 LE_SHARED le_result_t ifgen_le_iks_aesGcm_StartEncrypt
  262 (
  263     le_msg_SessionRef_t _ifgen_sessionRef,
  264         uint64_t session,
  265         ///< [IN] Session reference.
  266         uint8_t* noncePtr,
  267         ///< [OUT] Buffer to hold the nonce.
  268         ///<   Assumed to be NONCE_SIZE bytes.
  269         size_t* nonceSizePtr
  270         ///< [INOUT]
  271 );
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * Process a chunk of AAD (Additional Authenticated Data).  Either le_iks_aesGcm_StartEncrypt() or
  276  * le_iks_aesGcm_StartDecrypt() must have been previously called to start either an encryption or
  277  * decryption process.
  278  *
  279  * @return
  280  *      LE_OK if successful.
  281  *      LE_BAD_PARAMETER if the session reference is invalid
  282  *                       or if the key type is invalid
  283  *                       or if aadChunkPtr is NULL.
  284  *      LE_OUT_OF_RANGE if aadChunkSize is too big.
  285  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  286  *      LE_FAULT if an encryption or decryption process was not started or
  287  *                            plaintext/ciphertext processing has already started.
  288  */
  289 //--------------------------------------------------------------------------------------------------
  290 LE_SHARED le_result_t ifgen_le_iks_aesGcm_ProcessAad
  291 (
  292     le_msg_SessionRef_t _ifgen_sessionRef,
  293         uint64_t session,
  294         ///< [IN] Session reference.
  295         const uint8_t* aadPtr,
  296         ///< [IN] Additional authenticated data (AAD).
  297         ///<   NULL if not used.
  298         size_t aadSize
  299         ///< [IN]
  300 );
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * Encrypt a chunk of plaintext.  le_iks_aesGcm_StartEncrypt() must have been previously called to
  305  * start an encryption process.
  306  *
  307  * @return
  308  *      LE_OK if successful.
  309  *      LE_BAD_PARAMETER if the session reference is invalid
  310  *                       or if the key type is invalid
  311  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  312  *      LE_OUT_OF_RANGE if textSize is too big.
  313  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  314  *      LE_FAULT if an encryption process has not started.
  315  */
  316 //--------------------------------------------------------------------------------------------------
  317 LE_SHARED le_result_t ifgen_le_iks_aesGcm_Encrypt
  318 (
  319     le_msg_SessionRef_t _ifgen_sessionRef,
  320         uint64_t session,
  321         ///< [IN] Session reference.
  322         const uint8_t* plaintextChunkPtr,
  323         ///< [IN] Plaintext.
  324         size_t plaintextChunkSize,
  325         ///< [IN]
  326         uint8_t* ciphertextChunkPtr,
  327         ///< [OUT] Buffer to hold the ciphertext.
  328         size_t* ciphertextChunkSizePtr
  329         ///< [INOUT]
  330 );
  331 
  332 //--------------------------------------------------------------------------------------------------
  333 /**
  334  * Complete encryption and calculate the authentication tag.
  335  *
  336  * @return
  337  *      LE_OK if successful.
  338  *      LE_BAD_PARAMETER if the session reference is invalid
  339  *                       or if the key type is invalid
  340  *                       or if tagPtr is NULL.
  341  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  342  *      LE_FAULT if an encryption process has not started or no data
  343  *                            (AAD and plaintext) has been processed.
  344  */
  345 //--------------------------------------------------------------------------------------------------
  346 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DoneEncrypt
  347 (
  348     le_msg_SessionRef_t _ifgen_sessionRef,
  349         uint64_t session,
  350         ///< [IN] Session reference.
  351         uint8_t* tagPtr,
  352         ///< [OUT] Buffer to hold the authentication tag.
  353         ///<   Assumed to be TAG_SIZE.
  354         size_t* tagSizePtr
  355         ///< [INOUT]
  356 );
  357 
  358 //--------------------------------------------------------------------------------------------------
  359 /**
  360  * Starts a process to decrypt and verify the integrity of a long packet with AES in GCM mode.  This
  361  * function is useful for decrypting and verifying packets that are larger than MAX_PACKET_SIZE.
  362  * Calling this function will cancel any previously started process using the same session.
  363  *
  364  * To decrypt a long packet the following sequence should be used:
  365  *
  366  * le_iks_aesGcm_StartDecrypt() // Start the decryption process.
  367  * le_iks_aesGcm_ProcessAad()   // Call zero or more times until all AAD data is processed.
  368  * le_iks_aesGcm_Decrypt()      // Call zero or more times until all ciphertext is decrypted.
  369  * le_iks_aesGcm_DoneDecrypt()  // Complete decryption process.
  370  *
  371  * @warning
  372  *      While decrypting long packets in this 'streaming' fashion plaintext chunks are released to
  373  *      the caller before they are verified for integrity.  Ie. the caller will not know the
  374  *      plaintext is correct until le_iks_aesGcm_DoneDecrypt() is called.  The caller therefore must
  375  *      not release or make use of any plaintext chunks until after
  376  *      le_iks_aesGcm_DoneDecrypt() returns with LE_OK.
  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 not valid
  382  *                       or if noncePtr is NULL.
  383  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  384  *      LE_FAULT if there was an internal error.
  385  */
  386 //--------------------------------------------------------------------------------------------------
  387 LE_SHARED le_result_t ifgen_le_iks_aesGcm_StartDecrypt
  388 (
  389     le_msg_SessionRef_t _ifgen_sessionRef,
  390         uint64_t session,
  391         ///< [IN] Session reference.
  392         const uint8_t* noncePtr,
  393         ///< [IN] Nonce used to encrypt the packet.
  394         ///<   Assumed to be NONCE_SIZE bytes.
  395         size_t nonceSize
  396         ///< [IN]
  397 );
  398 
  399 //--------------------------------------------------------------------------------------------------
  400 /**
  401  * Decrypt a chunk of ciphertext.  le_iks_aesGcm_StartDecrypt() must have been previously called to
  402  * start either a decryption process.
  403  *
  404  * @return
  405  *      LE_OK if successful.
  406  *      LE_BAD_PARAMETER if the session reference is invalid
  407  *                       or if the key type is invalid
  408  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  409  *      LE_OUT_OF_RANGE if textSize is too big.
  410  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  411  *      LE_FAULT if a decryption process has not started.
  412  */
  413 //--------------------------------------------------------------------------------------------------
  414 LE_SHARED le_result_t ifgen_le_iks_aesGcm_Decrypt
  415 (
  416     le_msg_SessionRef_t _ifgen_sessionRef,
  417         uint64_t session,
  418         ///< [IN] Session reference.
  419         const uint8_t* ciphertextChunkPtr,
  420         ///< [IN] Ciphertext chunk. NULL if not used.
  421         size_t ciphertextChunkSize,
  422         ///< [IN]
  423         uint8_t* plaintextChunkPtr,
  424         ///< [OUT] Buffer to hold the plaintext chunk.
  425         size_t* plaintextChunkSizePtr
  426         ///< [INOUT]
  427 );
  428 
  429 //--------------------------------------------------------------------------------------------------
  430 /**
  431  * Complete decryption and verify the integrity.
  432  *
  433  * @return
  434  *      LE_OK if successful.
  435  *      LE_BAD_PARAMETER if the session reference is invalid
  436  *                       or if the key type is invalid
  437  *                       or if tagPtr is NULL.
  438  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  439  *      LE_FAULT if a decryption process has not started
  440  *               or no data (AAD and ciphertext) has been processed
  441  *               or the integrity check failed.
  442  */
  443 //--------------------------------------------------------------------------------------------------
  444 LE_SHARED le_result_t ifgen_le_iks_aesGcm_DoneDecrypt
  445 (
  446     le_msg_SessionRef_t _ifgen_sessionRef,
  447         uint64_t session,
  448         ///< [IN] Session reference.
  449         const uint8_t* tagPtr,
  450         ///< [IN] Buffer to hold the authentication tag.
  451         ///<   Assumed to be TAG_SIZE.
  452         size_t tagSize
  453         ///< [IN]
  454 );
  455 /** @} **/
  456 #endif // LE_IKS_AESGCM_COMMON_H_INCLUDE_GUARD
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:287
le_result_t
le_result_t
Definition: le_basics.h:46
le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
legato.h
le_iks_common.h