le_iks_ecc_common.h

Go to the documentation of this file.
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
#define LE_SHARED
Definition: le_basics.h:287
le_result_t
Definition: le_basics.h:46
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860