le_iks_ecc_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_ecc_common.h
   12  *
   13  * Type definitions for le_iks_ecc.
   14  *
   15  */
   16 #ifndef LE_IKS_ECC_COMMON_H_INCLUDE_GUARD
   17 #define LE_IKS_ECC_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_ECC_PROTOCOL_ID "64c57ce3f398cf5036d4e48d3de25766"
   26 #define IFGEN_LE_IKS_ECC_MSG_SIZE 9319
   27 /** @addtogroup le_iks_ecc
   28  *  @{ **/
   29 
   30 
   31 //--------------------------------------------------------------------------------------------------
   32 /**
   33  * Maximum serialized ECC key size.
   34  */
   35 //--------------------------------------------------------------------------------------------------
   36 #define LE_IKS_ECC_MAX_SERIAL_KEY_SIZE 1025
   37 
   38 //--------------------------------------------------------------------------------------------------
   39 /**
   40  * Maximum signature size.
   41  */
   42 //--------------------------------------------------------------------------------------------------
   43 #define LE_IKS_ECC_MAX_SIGNATURE_SIZE 1024
   44 
   45 //--------------------------------------------------------------------------------------------------
   46 /**
   47  * Maximum tag size.
   48  */
   49 //--------------------------------------------------------------------------------------------------
   50 #define LE_IKS_ECC_MAX_TAG_SIZE 64
   51 
   52 
   53 //--------------------------------------------------------------------------------------------------
   54 /**
   55  * Get if this client bound locally.
   56  */
   57 //--------------------------------------------------------------------------------------------------
   58 LE_SHARED bool ifgen_le_iks_ecc_HasLocalBinding
   59 (
   60     void
   61 );
   62 
   63 
   64 //--------------------------------------------------------------------------------------------------
   65 /**
   66  * Init data that is common across all threads
   67  */
   68 //--------------------------------------------------------------------------------------------------
   69 LE_SHARED void ifgen_le_iks_ecc_InitCommonData
   70 (
   71     void
   72 );
   73 
   74 
   75 //--------------------------------------------------------------------------------------------------
   76 /**
   77  * Perform common initialization and open a session
   78  */
   79 //--------------------------------------------------------------------------------------------------
   80 LE_SHARED le_result_t ifgen_le_iks_ecc_OpenSession
   81 (
   82     le_msg_SessionRef_t _ifgen_sessionRef,
   83     bool isBlocking
   84 );
   85 
   86 //--------------------------------------------------------------------------------------------------
   87 /**
   88  * Generate a shared secret between an ECC private key and an ECC public key.
   89  *
   90  * The private key must be of type LE_IKS_KEY_TYPE_PRIV_ECDH and the public must be of type
   91  * LE_IKS_KEY_TYPE_PUB_ECDH or LE_IKS_KEY_TYPE_PRIV_ECDH.
   92  *
   93  * This function may be used as part of a key exchange protocol.  The shared secret is unpredictable
   94  * (assuming the private portions of both keys are kept secret) but not uniformly distributed and
   95  * should not be used directly as a cryptographic key.
   96  *
   97  * The shared secret is in the format specified by SEC 1, that is the x component of the shared
   98  * point converted to an octet string.
   99  *
  100  * If the buffer is too small to hold the shared secret the shared secret will be truncated to fit.
  101  *
  102  * @return
  103  *      LE_OK if successful.
  104  *      LE_BAD_PARAMETER if either key reference is invalid
  105  *                       or if either key type is invalid
  106  *                       or if two key sizes do not match
  107  *                       or if the secretPtr or secretSizePtr is NULL.
  108  *      LE_FAULT if there was an internal error.
  109  */
  110 //--------------------------------------------------------------------------------------------------
  111 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecdh_GetSharedSecret
  112 (
  113     le_msg_SessionRef_t _ifgen_sessionRef,
  114         uint64_t privKeyRef,
  115         ///< [IN] Private key reference.
  116         uint64_t pubKeyRef,
  117         ///< [IN] Publid Key reference.
  118         uint8_t* secretPtr,
  119         ///< [OUT] Buffer to hold the shared secret.
  120         size_t* secretSizePtr
  121         ///< [INOUT]
  122 );
  123 
  124 //--------------------------------------------------------------------------------------------------
  125 /**
  126  * Generate an ECDSA signature on the hash digest of a message.
  127  *
  128  * The key must be a LE_IKS_KEY_TYPE_PRIV_ECDSA key.
  129  *
  130  * The signature is the concatenation of the r and s values (r||s).  The size of the signature is
  131  * twice the key size.  For example if the key is 256 bits in size then the signature will be 64
  132  * bytes.  Note that when the key size is 521 bits, zero-valued high-order padding bits are added to
  133  * the signature values r and s resulting in a signature of 132 bytes.
  134  *
  135  * The hash function used to generate the message digest should be chosen to match the security
  136  * strength of the signing key.  For example, if the key size is 256 bits then SHA256 (or its
  137  * equivalent) should be used.
  138  *
  139  * @return
  140  *      LE_OK if successful.
  141  *      LE_BAD_PARAMETER if the key reference is invalid
  142  *                       or if the key type is invalid
  143  *                       or if digestPtr, signaturePtr or signatureSizePtr are NULL
  144  *      LE_OVERFLOW if the signature buffer is too small.
  145  *      LE_FAULT if there was an internal error.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecdsa_GenSig
  149 (
  150     le_msg_SessionRef_t _ifgen_sessionRef,
  151         uint64_t keyRef,
  152         ///< [IN] Key reference.
  153         const uint8_t* digestPtr,
  154         ///< [IN] Digest to sign.
  155         size_t digestSize,
  156         ///< [IN]
  157         uint8_t* signaturePtr,
  158         ///< [OUT] Buffer to hold the signature.
  159         size_t* signatureSizePtr
  160         ///< [INOUT]
  161 );
  162 
  163 //--------------------------------------------------------------------------------------------------
  164 /**
  165  * Verifies a signature of the hash digest of a message with ECDSA.
  166  *
  167  * The key must be either a LE_IKS_KEY_TYPE_PUB_ECDSA or LE_IKS_KEY_TYPE_PRIV_ECDSA key.
  168  *
  169  * The signature is the concatenation of the r and s values (r||s).  The size of the signature is
  170  * twice the key size.  For example if the key is 256 bits in size then the signature will be 64
  171  * bytes.  Note that when the key size is 521 bits, zero-valued high-order padding bits are added to
  172  * the signature values r and s resulting in a signature of 132 bytes.
  173  *
  174  * @return
  175  *      LE_OK if successful.
  176  *      LE_BAD_PARAMETER if the key reference is invalid
  177  *                       or if the key type is invalid
  178  *                       or if either digestPtr or signaturePtr are NULL.
  179  *      LE_FORMAT_ERROR if signatureSize is incorrect.
  180  *      LE_FAULT if the signature is not valid.
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecdsa_VerifySig
  184 (
  185     le_msg_SessionRef_t _ifgen_sessionRef,
  186         uint64_t keyRef,
  187         ///< [IN] Key reference.
  188         const uint8_t* digestPtr,
  189         ///< [IN] Digest of the message.
  190         size_t digestSize,
  191         ///< [IN]
  192         const uint8_t* signaturePtr,
  193         ///< [IN] Signature of the message.
  194         size_t signatureSize
  195         ///< [IN]
  196 );
  197 
  198 //--------------------------------------------------------------------------------------------------
  199 /**
  200  * Encrypts and integrity protects a short message with ECIES (Elliptic Curve Integrated
  201  * Encryption System).
  202  *
  203  * Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to
  204  * encrypt messages that can only be decrypted with the holder of the private key.  Hybrid
  205  * encryption is usually accomplished by using a symmetric encryption system to bulk encrypt
  206  * the message and then using the asymmetric encryption system to encrypt the symmetric key.
  207  *
  208  * ECIES provides hybrid encryption through a method that is more efficient than manually performing
  209  * the two step process described above.  Broadly speaking, ECIES performs a key agreement to
  210  * generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF
  211  * (Key Derivation Function).  The symmetric key is then used to bulk encrypt the message.
  212  *
  213  * This implementation of ECIES generally follows the SEC 1 standard but supports modernized
  214  * algorithms for the KDF and bulk encryption.
  215  *
  216  * @return
  217  *      LE_OK if successful.
  218  *      LE_BAD_PARAMETER if the key reference is invalid
  219  *                       or if the key type is invalid.
  220  *                       or if either labelPtr, plaintextPtr, ciphertextPtr, ephemKeyPtr,
  221  *                         ephemKeySizePtr, tagPtr is NULL when they shouldn't be.
  222  *      LE_OUT_OF_RANGE if the labelSize, textSize, tagSize is invalid.
  223  *      LE_OVERFLOW if the ephemKeyPtr buffer is too small.
  224  *      LE_FAULT if there was an internal error.
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_EncryptPacket
  228 (
  229     le_msg_SessionRef_t _ifgen_sessionRef,
  230         uint64_t keyRef,
  231         ///< [IN] Key reference.
  232         const uint8_t* labelPtr,
  233         ///< [IN] Label. NULL if not used.
  234         size_t labelSize,
  235         ///< [IN]
  236         const uint8_t* plaintextPtr,
  237         ///< [IN] Plaintext chunk. NULL if not used.
  238         size_t plaintextSize,
  239         ///< [IN]
  240         uint8_t* ciphertextPtr,
  241         ///< [OUT] Buffer to hold the ciphertext chunk.
  242         size_t* ciphertextSizePtr,
  243         ///< [INOUT]
  244         uint8_t* ephemKeyPtr,
  245         ///< [OUT] Serialized ephemeral public key.
  246         size_t* ephemKeySizePtr,
  247         ///< [INOUT]
  248         uint8_t* tagPtr,
  249         ///< [OUT] Buffer to hold the authentication tag.
  250         size_t* tagSizePtr
  251         ///< [INOUT]
  252 );
  253 
  254 //--------------------------------------------------------------------------------------------------
  255 /**
  256  * Decrypts and checks the integrity of a short message with ECIES (Elliptic Curve Integrated
  257  * Encryption System).
  258  *
  259  * Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to
  260  * encrypt messages that can only be decrypted with the holder of the private key.  Hybrid
  261  * encryption is usually accomplished by using a symmetric encryption system to bulk encrypt
  262  * the message and then using the asymmetric encryption system to encrypt the symmetric key.
  263  *
  264  * ECIES provides hybrid encryption through a method that is more efficient than manually performing
  265  * the two step process described above.  Broadly speaking, ECIES performs a key agreement to
  266  * generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF
  267  * (Key Derivation Function).  The symmetric key is then used to bulk encrypt the message.
  268  *
  269  * This implementation of ECIES generally follows the SEC 1 standard but supports modernized
  270  * algorithms for the KDF and bulk encryption.
  271  *
  272  * @return
  273  *      LE_OK if successful.
  274  *      LE_BAD_PARAMETER if the key reference is invalid
  275  *                       or if the key reference is invalid
  276  *                       or if either the ephemKeyPtr, plaintextPtr,
  277  *                         ciphertextPtr, tagPtr is NULL.
  278  *      LE_OUT_OF_RANGE if the labelSize, textSize, tagSize is invalid.
  279  *      LE_OVERFLOW if plaintextPtr buffer is too small.
  280  *      LE_FAULT if there was an internal error.
  281  */
  282 //--------------------------------------------------------------------------------------------------
  283 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_DecryptPacket
  284 (
  285     le_msg_SessionRef_t _ifgen_sessionRef,
  286         uint64_t keyRef,
  287         ///< [IN] Key reference.
  288         const uint8_t* labelPtr,
  289         ///< [IN] Label. NULL if not used.
  290         size_t labelSize,
  291         ///< [IN]
  292         const uint8_t* ephemKeyPtr,
  293         ///< [IN] Serialized ephemeral public key.
  294         size_t ephemKeySize,
  295         ///< [IN]
  296         const uint8_t* ciphertextPtr,
  297         ///< [IN] Ciphertext chunk.
  298         size_t ciphertextSize,
  299         ///< [IN]
  300         uint8_t* plaintextPtr,
  301         ///< [OUT] Buffer to hold the plaintext chunk.
  302         size_t* plaintextSizePtr,
  303         ///< [INOUT]
  304         const uint8_t* tagPtr,
  305         ///< [IN] Authentication tag.
  306         size_t tagSize
  307         ///< [IN]
  308 );
  309 
  310 //--------------------------------------------------------------------------------------------------
  311 /**
  312  * Starts a process to encrypt and integrity protect a message with ECIES (Elliptic Curve Integrated
  313  * Encryption System).
  314  *
  315  * Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to
  316  * encrypt messages that can only be decrypted with the holder of the private key.  Hybrid
  317  * encryption is usually accomplished by using a symmetric encryption system to bulk encrypt
  318  * the message and then using the asymmetric encryption system to encrypt the symmetric key.
  319  *
  320  * This implementation of ECIES generally follows the SEC 1 standard but supports modernized
  321  * algorithms for the KDF and bulk encryption.
  322  *
  323  * To encrypt a long packet the following sequence should be used:
  324  *
  325  * Ecies_StartEncrypt()  // Start the encryption process.
  326  * Ecies_Encrypt()       // Call zero or more times until all plaintext is encrypted.
  327  * Ecies_DoneEncrypt()   // Complete the process and obtain the authentication tag.
  328  *
  329  * Calling this function will cancel any previously started process using the same session.
  330  *
  331  * The session must have been created with the public key used for encryption.
  332  *
  333  * An optional label associated with the message can be added.
  334  *
  335  * The public portion of the ephemeral key used during the encrytion process is stored in the
  336  * ephemKeyPtr buffer.  It is encoded as an ECPoint as described in RFC5480.
  337  *
  338  * @return
  339  *      LE_OK if successful.
  340  *      LE_BAD_PARAMETER if the session reference is invalid
  341  *                       or if the key type is invalid
  342  *                       or if either labelPtr, ephemKeyPtr, ephemKeySizePtr is NULL
  343  *                          when they shouldn't be.
  344  *      LE_OUT_OF_RANGE if the labelSize is invalid.
  345  *      LE_OVERFLOW if any of the output buffers are too small.
  346  *      LE_FAULT if there was an internal error.
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_StartEncrypt
  350 (
  351     le_msg_SessionRef_t _ifgen_sessionRef,
  352         uint64_t session,
  353         ///< [IN] Session reference.
  354         const uint8_t* labelPtr,
  355         ///< [IN] Label. NULL if not used.
  356         size_t labelSize,
  357         ///< [IN]
  358         uint8_t* ephemKeyPtr,
  359         ///< [OUT] Serialized ephemeral public key.
  360         size_t* ephemKeySizePtr
  361         ///< [INOUT]
  362 );
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Encrypt a chunk of plaintext.  Ecies_StartEncrypt() must have been previously called to
  367  * start an encryption process.
  368  *
  369  * @return
  370  *      LE_OK if successful.
  371  *      LE_BAD_PARAMETER if the session reference is invalid
  372  *                       or if the key type is invalid
  373  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  374  *      LE_OUT_OF_RANGE if textSize is too big.
  375  *      LE_FAULT if an encryption process has not started.
  376  */
  377 //--------------------------------------------------------------------------------------------------
  378 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_Encrypt
  379 (
  380     le_msg_SessionRef_t _ifgen_sessionRef,
  381         uint64_t session,
  382         ///< [IN] Session reference.
  383         const uint8_t* plaintextChunkPtr,
  384         ///< [IN] Plaintext chunk. NULL if not used.
  385         size_t plaintextChunkSize,
  386         ///< [IN]
  387         uint8_t* ciphertextChunkPtr,
  388         ///< [OUT] Buffer to hold the ciphertext chunk.
  389         size_t* ciphertextChunkSizePtr
  390         ///< [INOUT]
  391 );
  392 
  393 //--------------------------------------------------------------------------------------------------
  394 /**
  395  * Complete encryption and calculate the authentication tag.
  396  *
  397  * The maximum tag size depends on the symmetric algorithm used.  If the supplied buffer is
  398  * larger than or equal to the maximum authentication tag size then the full authentication tag is
  399  * copied to the buffer and the rest of the buffer is left unmodified.  If the supplied buffer is
  400  * smaller than the maximum tag size then the tag will be truncated.  However, all tags produced
  401  * using the same key must use the same tag size.  It is up to the caller to ensure this.
  402  *
  403  * @return
  404  *      LE_OK if successful.
  405  *      LE_BAD_PARAMETER if the session reference is invalid
  406  *                       or if the key type is invalid
  407  *                       or if tagPtr is NULL.
  408  *      LE_OUT_OF_RANGE if tagSize if invalud.
  409  *      LE_OVERFLOW if the tagPtr buffer is too small.
  410  *      LE_FAULT if an encryption process has not started or no data has been processed.
  411  */
  412 //--------------------------------------------------------------------------------------------------
  413 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_DoneEncrypt
  414 (
  415     le_msg_SessionRef_t _ifgen_sessionRef,
  416         uint64_t session,
  417         ///< [IN] Session reference.
  418         uint8_t* tagPtr,
  419         ///< [OUT] Buffer to hold the authentication tag.
  420         size_t* tagSizePtr
  421         ///< [INOUT]
  422 );
  423 
  424 //--------------------------------------------------------------------------------------------------
  425 /**
  426  * Starts a process to decrypt and check the integrity of a message with ECIES (Elliptic Curve
  427  * Integrated Encryption System).
  428  *
  429  * Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to
  430  * encrypt (possibly long) messages that can only be decrypted with the holder of the private key.
  431  * Hybrid encryption is usually accomplished by using a symmetric encryption system to bulk encrypt
  432  * the message and then using the asymmetric encryption system to encrypt the symmetric key.
  433  *
  434  * ECIES provides hybrid encryption through a method that is more efficient than manually performing
  435  * the two step process described above.  Broadly speaking, ECIES performs a key agreement to
  436  * generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF
  437  * (Key Derivation Function).  The symmetric key is then used to bulk encrypt the message.
  438  *
  439  * This implementation of ECIES generally follows the SEC 1 standard but supports modernized
  440  * algorithms for the KDF and bulk encryption.
  441  *
  442  * To decrypt a long packet the following sequence should be used:
  443  *
  444  * Ecies_StartDecrypt()  // Start the decryption process.
  445  * Ecies_Decrypt()       // Call zero or more times until all ciphertext is decrypted.
  446  * Ecies_DoneDecrypt()   // Complete the process and check the authentication tag.
  447  *
  448  * Calling this function will cancel any previously started process using the same session.
  449  *
  450  * The same label and ephemeral public key used for encryption must be provided.
  451  *
  452  * @warning
  453  *      While decrypting long packets in this 'streaming' fashion plaintext chunks are released to
  454  *      the caller before they are verified for integrity.  Ie. the caller will not know the
  455  *      plaintext is correct until DoneDecrypt() is called.  The caller therefore must
  456  *      not release or make use of any plaintext chunks until after DoneDecrypt() returns
  457  *      with LE_OK.
  458  *
  459  * @return
  460  *      LE_OK if successful.
  461  *      LE_BAD_PARAMETER if the session reference is invalid
  462  *                       or if the session key type or ephemeral key is invalid
  463  *                       or if the ephemKeyPtr is NULL.
  464  *      LE_OUT_OF_RANGE if either the labelSize or ephemKeySize is invalid.
  465  *      LE_FAULT if there was an internal error.
  466  */
  467 //--------------------------------------------------------------------------------------------------
  468 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_StartDecrypt
  469 (
  470     le_msg_SessionRef_t _ifgen_sessionRef,
  471         uint64_t session,
  472         ///< [IN] Session reference.
  473         const uint8_t* labelPtr,
  474         ///< [IN] Label. NULL if not used.
  475         size_t labelSize,
  476         ///< [IN]
  477         const uint8_t* ephemKeyPtr,
  478         ///< [IN] Serialized ephemeral public key.
  479         size_t ephemKeySize
  480         ///< [IN]
  481 );
  482 
  483 //--------------------------------------------------------------------------------------------------
  484 /**
  485  * Decrypt a chunk of ciphertext.  Ecies_StartDecrypt() must have been previously called to
  486  * start a decryption process.
  487  *
  488  * @return
  489  *      LE_OK if successful.
  490  *      LE_BAD_PARAMETER if the session reference is invalid
  491  *                       or if the key type is invalid
  492  *                       or if plaintextChunkPtr or ciphertextChunkPtr is NULL.
  493  *      LE_OUT_OF_RANGE if textSize is invalid.
  494  *      LE_FAULT if a decryption process has not started.
  495  */
  496 //--------------------------------------------------------------------------------------------------
  497 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_Decrypt
  498 (
  499     le_msg_SessionRef_t _ifgen_sessionRef,
  500         uint64_t session,
  501         ///< [IN] Session reference.
  502         const uint8_t* ciphertextChunkPtr,
  503         ///< [IN] Ciphertext chunk.
  504         size_t ciphertextChunkSize,
  505         ///< [IN]
  506         uint8_t* plaintextChunkPtr,
  507         ///< [OUT] Buffer to hold the plaintext chunk.
  508         size_t* plaintextChunkSizePtr
  509         ///< [INOUT]
  510 );
  511 
  512 //--------------------------------------------------------------------------------------------------
  513 /**
  514  * Complete decryption and verify the integrity.
  515  *
  516  * @return
  517  *      LE_OK if successful.
  518  *      LE_BAD_PARAMETER if the session reference is invalid
  519  *                       or if the key type is invalid
  520  *                       or if tagPtr is NULL.
  521  *      LE_OUT_OF_RANGE if tagSize is invalid.
  522  *      LE_FAULT if a decryption process has not started or no data has been processed
  523  *               or the integrity check failed.
  524  */
  525 //--------------------------------------------------------------------------------------------------
  526 LE_SHARED le_result_t ifgen_le_iks_ecc_Ecies_DoneDecrypt
  527 (
  528     le_msg_SessionRef_t _ifgen_sessionRef,
  529         uint64_t session,
  530         ///< [IN] Session reference.
  531         const uint8_t* tagPtr,
  532         ///< [IN] Authentication tag.
  533         size_t tagSize
  534         ///< [IN]
  535 );
  536 /** @} **/
  537 #endif // LE_IKS_ECC_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