le_iks_interface.h

Go to the documentation of this file.
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 IoT Keystore Key Management API
14  *
15  * @ref le_iks_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * IOT Key Store's key and digest management API.
20  *
21  * The IOT Key Store can be used to store cryptographic keys as well as cryptographic hash digests.
22  * This module provides APIs for creating, configuring, updating and saving keys and digests.
23  *
24  * Keys can be created with either le_iks_CreateKey() or le_iks_CreateKeyByType().
25  *
26  * A newly created key does not have a key value. A key value can either be generated using
27  * le_iks_GenKeyValue() or provisioned using le_iks_ProvisionKeyValue().
28  *
29  * Keys are initially created in non-persistent memory only and can be saved to persistent storage
30  * using le_iks_SaveKey(). Short-lived, ephemeral keys should not be saved to persistent storage.
31  *
32  * Previously, created keys can be retrieved using the le_iks_GetKey() function.
33  *
34  * Key modifications (using le_iks_GenKeyValue(), le_iks_ProvisionKeyValue(), etc.) and deletions
35  * (le_iks_DeleteKey()) may be performed freely unless the key is assigned an update key.
36  *
37  * Once an update key is assigned, key modification and deletion may only be performed using an
38  * authenticated command that is signed with the private portion of the update key. The private
39  * portion of the update key should be held securely off target. To ensure freshness and uniqueness
40  * of authenticated commands an authentication challenge must be obtained using
41  * le_iks_GetUpdateAuthChallenge() and incorporated into the command. The authentication challenges
42  * are specific to each update key and is refreshed only once a challenge is consumed.
43  *
44  * Private and symmetric key values cannot be read out of the IOT Key Store while public key values
45  * can be extracted with le_iks_GetPubKeyValue().
46  *
47  * Digest management is very similar to key management and most of the functions are analogous to
48  * the key management functions.
49  *
50  * Key and digest identifiers may only contain alphanumeric characters, the hyphen '-' and
51  * underscore '_' characters.
52  *
53  * <HR>
54  *
55  * Copyright (C) Sierra Wireless Inc.
56  */
57 /**
58  * @file le_iks_interface.h
59  *
60  * Legato @ref c_iks API
61  *
62  * Copyright (C) Sierra Wireless Inc.
63  */
64 
65 #ifndef LE_IKS_INTERFACE_H_INCLUDE_GUARD
66 #define LE_IKS_INTERFACE_H_INCLUDE_GUARD
67 
68 
69 #include "legato.h"
70 
71 // Internal includes for this interface
72 #include "le_iks_common.h"
73 /** @addtogroup le_iks le_iks API Reference
74  * @{
75  * @file le_iks_common.h
76  * @file le_iks_interface.h **/
77 //--------------------------------------------------------------------------------------------------
78 /**
79  * Type for handler called when a server disconnects.
80  */
81 //--------------------------------------------------------------------------------------------------
82 typedef void (*le_iks_DisconnectHandler_t)(void *);
83 
84 //--------------------------------------------------------------------------------------------------
85 /**
86  *
87  * Connect the current client thread to the service providing this API. Block until the service is
88  * available.
89  *
90  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
91  * called before any other functions in this API. Normally, ConnectService is automatically called
92  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
93  *
94  * This function is created automatically.
95  */
96 //--------------------------------------------------------------------------------------------------
98 (
99  void
100 );
101 
102 //--------------------------------------------------------------------------------------------------
103 /**
104  *
105  * Try to connect the current client thread to the service providing this API. Return with an error
106  * if the service is not available.
107  *
108  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
109  * called before any other functions in this API. Normally, ConnectService is automatically called
110  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
111  *
112  * This function is created automatically.
113  *
114  * @return
115  * - LE_OK if the client connected successfully to the service.
116  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
117  * bound.
118  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
119  * - LE_COMM_ERROR if the Service Directory cannot be reached.
120  */
121 //--------------------------------------------------------------------------------------------------
123 (
124  void
125 );
126 
127 //--------------------------------------------------------------------------------------------------
128 /**
129  * Set handler called when server disconnection is detected.
130  *
131  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
132  * to continue without exiting, it should call longjmp() from inside the handler.
133  */
134 //--------------------------------------------------------------------------------------------------
136 (
137  le_iks_DisconnectHandler_t disconnectHandler,
138  void *contextPtr
139 );
140 
141 //--------------------------------------------------------------------------------------------------
142 /**
143  *
144  * Disconnect the current client thread from the service providing this API.
145  *
146  * Normally, this function doesn't need to be called. After this function is called, there's no
147  * longer a connection to the service, and the functions in this API can't be used. For details, see
148  * @ref apiFilesC_client.
149  *
150  * This function is created automatically.
151  */
152 //--------------------------------------------------------------------------------------------------
154 (
155  void
156 );
157 
158 
159 //--------------------------------------------------------------------------------------------------
160 /**
161  * Key usage. This type can be used to conveniently create keys for different usages. IOT Key
162  * Store will select a default key type for the specified usage.
163  */
164 //--------------------------------------------------------------------------------------------------
165 
166 
167 //--------------------------------------------------------------------------------------------------
168 /**
169  * Key types
170  */
171 //--------------------------------------------------------------------------------------------------
172 
173 
174 //--------------------------------------------------------------------------------------------------
175 /**
176  * Hash function identifiers.
177  *
178  * @warning
179  * The values in this enum must not be changed. The list may be amended but binary
180  * compatibility requires that the actual values never change.
181  */
182 //--------------------------------------------------------------------------------------------------
183 
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  * Gets a reference to a key.
188  *
189  * @return
190  * LE_OK if successful.
191  * LE_BAD_PARAMETER if the keyId is invalid or keyRef is NULL.
192  * LE_NOT_FOUND if the key does not exist.
193  * LE_NO_MEMORY if there is not enough memory to retrieve the key.
194  * LE_FAULT if there was an internal error.
195  */
196 //--------------------------------------------------------------------------------------------------
198 (
199  const char* LE_NONNULL keyId,
200  ///< [IN] Identifier string.
201  uint64_t* keyRefPtr
202  ///< [OUT] Key reference.
203 );
204 
205 //--------------------------------------------------------------------------------------------------
206 /**
207  * Creates a new key.
208  *
209  * This is a convenient way to create a key for a specific usage. This function will choose a
210  * default key type to satisfy the specified usage.
211  *
212  * New keys initially have no value and cannot be used. Key values can be set using either
213  * le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().
214  *
215  * Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save
216  * the key to persistent memory.
217  *
218  * @return
219  * LE_OK if successful.
220  * LE_BAD_PARAMETER if the keyId or keyUsage is invalid or if keyRef is NULL.
221  * LE_DUPLICATE if the keyId is already being used.
222  * LE_NO_MEMORY if there is not enough memory to create the key.
223  * LE_FAULT if there was an internal error.
224  */
225 //--------------------------------------------------------------------------------------------------
227 (
228  const char* LE_NONNULL keyId,
229  ///< [IN] Identifier string.
230  le_iks_KeyUsage_t keyUsage,
231  ///< [IN] Key usage.
232  uint64_t* keyRefPtr
233  ///< [OUT] Key reference.
234 );
235 
236 //--------------------------------------------------------------------------------------------------
237 /**
238  * Creates a new key of a specific type.
239  *
240  * New keys initially have no value and cannot be used. Key values can be set using either
241  * le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().
242  *
243  * Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save
244  * the key to persistent memory.
245  *
246  * @return
247  * LE_OK if successful.
248  * LE_BAD_PARAMETER if the keyId or keyType is invalid or if keyRef is NULL.
249  * LE_DUPLICATE if the keyId is already being used.
250  * LE_OUT_OF_RANGE if the key size is invalid.
251  * LE_NO_MEMORY if there is not enough memory to create the key.
252  * LE_FAULT if there was an internal error.
253  */
254 //--------------------------------------------------------------------------------------------------
256 (
257  const char* LE_NONNULL keyId,
258  ///< [IN] Identifier string.
259  le_iks_KeyType_t keyType,
260  ///< [IN] Key type.
261  uint32_t keySize,
262  ///< [IN] Key size in bytes.
263  uint64_t* keyRefPtr
264  ///< [OUT] Key reference.
265 );
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * Get the key type.
270  *
271  * @return
272  * LE_OK if successful.
273  * LE_BAD_PARAMETER if the key reference is invalid
274  * LE_UNSUPPORTED if underlying resource does not support this operation.
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  uint64_t keyRef,
280  ///< [IN] Key reference.
281  le_iks_KeyType_t* keyTypePtr
282  ///< [OUT] Key type.
283 );
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Gets the key size in bytes.
288  *
289  * @return
290  * LE_OK if successful.
291  * LE_BAD_PARAMETER if the key reference is invalid
292  * LE_UNSUPPORTED if underlying resource does not support this operation.
293  */
294 //--------------------------------------------------------------------------------------------------
296 (
297  uint64_t keyRef,
298  ///< [IN] Key reference.
299  uint32_t* keySizePtr
300  ///< [OUT] Key size.
301 );
302 
303 //--------------------------------------------------------------------------------------------------
304 /**
305  * Checks if the key size is valid.
306  *
307  * @return
308  * LE_OK if the key size is valid.
309  * LE_OUT_OF_RANGE if the key size is invalid.
310  * LE_UNSUPPORTED if underlying resource does not support this operation.
311  */
312 //--------------------------------------------------------------------------------------------------
314 (
315  le_iks_KeyType_t keyType,
316  ///< [IN] Key type.
317  uint32_t keySize
318  ///< [IN] Key size.
319 );
320 
321 //--------------------------------------------------------------------------------------------------
322 /**
323  * Checks if the key has a value.
324  *
325  * @return
326  * LE_OK if the key has a value.
327  * LE_BAD_PARAMETER if the key reference is invalid.
328  * LE_NOT_FOUND if the key has no value.
329  * LE_UNSUPPORTED if underlying resource does not support this operation.
330  */
331 //--------------------------------------------------------------------------------------------------
333 (
334  uint64_t keyRef
335  ///< [IN] Key reference.
336 );
337 
338 //--------------------------------------------------------------------------------------------------
339 /**
340  * Set an update key for the specified key. The update key must be of type KEY_TYPE_KEY_UPDATE.
341  * The update key can be used at a later time to perform authenticated updates of the specified key.
342  * The same update key may be used for multiple keys and digests.
343  *
344  * The key can be made not updatable by setting the updateKeyRef parameter to zero. Warning, this
345  * is a one-time, one-way operation.
346  *
347  * @note
348  * Once an update key is assigned the key parameters can no longer be modified except through
349  * an authenticated update process.
350  *
351  * Update keys can be assigned to themselves or other update keys.
352  *
353  * @warning
354  * It is strongly recommended to save the update key before assigning it to other keys/digests.
355  * Otherwise a sudden power loss could leave the update key reference pointing to a
356  * non-existing update key allowing a new update key to be created with the same ID but a
357  * different (unintended) value.
358  *
359  * @return
360  * LE_OK if successful.
361  * LE_BAD_PARAMETER if the key reference is invalid
362  * or if the update key reference is invalid or does not have a value.
363  * LE_UNSUPPORTED if underlying resource does not support this operation.
364  * LE_FAULT if an update key has already been set
365  * or if there was an internal error.
366  */
367 //--------------------------------------------------------------------------------------------------
369 (
370  uint64_t keyRef,
371  ///< [IN] Key reference.
372  uint64_t updateKeyRef
373  ///< [IN] Reference to an update key. 0 for not updatable.
374 );
375 
376 //--------------------------------------------------------------------------------------------------
377 /**
378  * Generate a key value.
379  *
380  * If the specified key has an assigned update key then the authCmdPtr must contain a generate key
381  * command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(),
382  * and is signed with the update private key. If the command is valid and authentic then a new key
383  * value is generated replacing the old value.
384  *
385  * If the specified key does not have an update key then the authCmdPtr is ignored.
386  *
387  * Public keys cannot be generated using this function. They must be provisioned using
388  * le_iks_ProvisionKeyValue().
389  *
390  * @note
391  * See the comment block at the top of this page for the authenticated command format.
392  *
393  * @return
394  * LE_OK if successful.
395  * LE_BAD_PARAMETER if the key reference is invalid
396  * or if the key is a public key.
397  * LE_UNSUPPORTED if underlying resource does not support this operation.
398  * LE_FAULT if there is an update key set and the authCmdPtr does not contain a
399  * valid authenticated command, or if there was an internal error.
400  */
401 //--------------------------------------------------------------------------------------------------
403 (
404  uint64_t keyRef,
405  ///< [IN] Key reference.
406  const uint8_t* authCmdPtr,
407  ///< [IN] Authenticated command buffer.
408  size_t authCmdSize
409  ///< [IN]
410 );
411 
412 //--------------------------------------------------------------------------------------------------
413 /**
414  * Provision a key value.
415  *
416  * The provisioning package, provPackagePtr, must contain the key value to provision.
417  *
418  * Private key provisioning is not currently supported.
419  *
420  * If the key is a symmetric then the key value must be wrapped with the wrapping key. If the
421  * key is a public key the key value must be provided in plaintext.
422  *
423  * If the specified key does not have an assigned update key then the provPackagePtr is treated as a
424  * buffer containing the key value.
425  *
426  * If the specified key has an assigned update key then the provPackagePtr must also contain a valid
427  * authentication challenge and be signed with the assigned update key.
428  *
429  * @note
430  * See the comment block at the top of this page for the provisioning package format.
431  *
432  * @return
433  * LE_OK if successful.
434  * LE_BAD_PARAMETER if the key reference is invalid.
435  * LE_UNSUPPORTED if underlying resource does not support this operation.
436  * LE_FAULT if the provPackagePtr is not validly encrypted and/or signed
437  * or if there was an internal error.
438  */
439 //--------------------------------------------------------------------------------------------------
441 (
442  uint64_t keyRef,
443  ///< [IN] Key reference.
444  const uint8_t* provPackagePtr,
445  ///< [IN] Provisioning package.
446  size_t provPackageSize
447  ///< [IN]
448 );
449 
450 //--------------------------------------------------------------------------------------------------
451 /**
452  * Saves a key to persistent storage.
453  *
454  * @note
455  * Previously saved keys that have been updated do not need to be re-saved.
456  *
457  * @return
458  * LE_OK if successful.
459  * LE_BAD_PARAMETER if the key reference is invalid.
460  * LE_UNSUPPORTED if underlying resource does not support this operation.
461  * LE_FAULT if the key is already in persistent storage
462  * or if there was an internal error.
463  */
464 //--------------------------------------------------------------------------------------------------
466 (
467  uint64_t keyRef
468  ///< [IN] Key reference.
469 );
470 
471 //--------------------------------------------------------------------------------------------------
472 /**
473  * Delete key.
474  *
475  * If the specified key has an assigned update key then the authCmdPtr must contain a delete key
476  * command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(), and is
477  * signed with the update private key. If the command is valid and authentic then the key will be
478  * deleted.
479  *
480  * If the specified key does not have an assigned update key then then authCmdPtr is ignored.
481  *
482  * @warning
483  * When deleting an update key, it is a good idea to delete all keys that depend on the update
484  * key first. Otherwise the dependent keys will be left non-updatable.
485  *
486  * @note
487  * See the comment block at the top of this page for the authenticated command format.
488  *
489  * @return
490  * LE_OK if successful.
491  * LE_BAD_PARAMETER if the key reference is invalid.
492  * LE_UNSUPPORTED if underlying resource does not support this operation.
493  * LE_FAULT if the key has an update key and the authCmdPtr is not valid.
494  */
495 //--------------------------------------------------------------------------------------------------
497 (
498  uint64_t keyRef,
499  ///< [IN] Key reference.
500  const uint8_t* authCmdPtr,
501  ///< [IN] Authenticated command buffer.
502  size_t authCmdSize
503  ///< [IN]
504 );
505 
506 //--------------------------------------------------------------------------------------------------
507 /**
508  * Get the public portion of an asymmetric key.
509  *
510  * The output will be in:
511  * - PKCS #1 format (DER encoded) for RSA keys.
512  * - ECPoint format defined in RFC5480 for ECC keys.
513  *
514  * @return
515  * LE_OK if successful.
516  * LE_BAD_PARAMETER if the key reference is invalid
517  * or if the key is not an asymmetric key.
518  * LE_NOT_FOUND if the key reference does not have a value.
519  * LE_UNSUPPORTED if underlying resource does not support this operation.
520  * LE_OVERFLOW if the supplied buffer is too small to hold the key value.
521  */
522 //--------------------------------------------------------------------------------------------------
524 (
525  uint64_t keyRef,
526  ///< [IN] Key reference.
527  uint8_t* bufPtr,
528  ///< [OUT] Buffer to hold key value.
529  size_t* bufSizePtr
530  ///< [INOUT]
531 );
532 
533 //--------------------------------------------------------------------------------------------------
534 /**
535  * Gets a reference to a digest.
536  *
537  * Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.
538  *
539  * @return
540  * LE_OK if successful.
541  * LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL.
542  * LE_NOT_FOUND if the digest does not exist.
543  * LE_NO_MEMORY if there is not enough memory to retrieve the digest.
544  * LE_FAULT if there was an internal error.
545  */
546 //--------------------------------------------------------------------------------------------------
548 (
549  const char* LE_NONNULL digestId,
550  ///< [IN] Identifier string.
551  uint64_t* digestRefPtr
552  ///< [OUT] Digest reference.
553 );
554 
555 //--------------------------------------------------------------------------------------------------
556 /**
557  * Creates a new digest.
558  *
559  * New digests initially have no value. Digest values can be set using le_iks_ProvisionDigest().
560  *
561  * Created digests initially only exist in non-persistent memory, call le_iks_SaveDigest() to save
562  * to persistent storage.
563  *
564  * Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.
565  *
566  * @return
567  * LE_OK if successful.
568  * LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL.
569  * LE_DUPLICATE if the digestId is already being used.
570  * LE_OUT_OF_RANGE if the digest size is invalid.
571  * LE_NO_MEMORY if there is not enough memory to create the digest.
572  * LE_FAULT if there was an internal error.
573  */
574 //--------------------------------------------------------------------------------------------------
576 (
577  const char* LE_NONNULL digestId,
578  ///< [IN] Identifier string.
579  uint32_t digestSize,
580  ///< [IN] Digest size. Must be <= MAX_DIGEST_SIZE.
581  uint64_t* digestRefPtr
582  ///< [OUT] Digest reference.
583 );
584 
585 //--------------------------------------------------------------------------------------------------
586 /**
587  * Gets the digest size in bytes.
588  *
589  * @return
590  * LE_OK if successful.
591  * LE_BAD_PARAMETER if the digest reference is invalid.
592  * LE_UNSUPPORTED if underlying resource does not support this operation.
593  */
594 //--------------------------------------------------------------------------------------------------
596 (
597  uint64_t digestRef,
598  ///< [IN] Digest reference.
599  uint32_t* digestSizePtr
600  ///< [OUT] Digest size.
601 );
602 
603 //--------------------------------------------------------------------------------------------------
604 /**
605  * Set an update key for the specified digest. The update key must be of type
606  * KEY_TYPE_KEY_UPDATE. The update key can be used at a later time to perform authenticated
607  * updates of the specified digest. The same update key may be used for multiple keys and digests.
608  *
609  * The digest can be made not updatable by setting the updateKeyRef parameter to zero. Warning,
610  * this is a one-time, one-way operation.
611  *
612  * @note
613  * Once an update key is assigned the digest parameters can no longer be modified except
614  * through an authenticated update process.
615  *
616  * @warning
617  * It is strongly recommended to save the update key before assigning it to other keys/digests.
618  * Otherwise a sudden power loss could leave the update key reference pointing to a
619  * non-existing update key allowing a new update key to be created with the same ID but a
620  * different (unintended) value.
621  *
622  * @return
623  * LE_OK if successful.
624  * LE_BAD_PARAMETER if the digest reference is invalid
625  * or if the update key reference is invalid or does not have a value.
626  * LE_UNSUPPORTED if underlying resource does not support this operation.
627  * LE_FAULT if an update key has already been set
628  * or if there was an internal error.
629  */
630 //--------------------------------------------------------------------------------------------------
632 (
633  uint64_t digestRef,
634  ///< [IN] Digest reference.
635  uint64_t updateKeyRef
636  ///< [IN] Reference to an update key. 0 for not updatable.
637 );
638 
639 //--------------------------------------------------------------------------------------------------
640 /**
641  * Provision a digest value.
642  *
643  * The provisioning package, provPackagePtr, must contain the digest value to provision.
644  *
645  * If the specified digest does not have an assigned update key then the provPackagePtr is treated
646  * as a buffer containing the digest value.
647  *
648  * If the specified digest has an assigned update key then the provPackagePtr must also contain a
649  * valid authentication challenge and be signed with the assigned update key.
650  *
651  * @note
652  * See the comment block at the top of this page for the provisioning package format.
653  *
654  * @return
655  * LE_OK if successful.
656  * LE_BAD_PARAMETER if the digest reference is invalid
657  * or if the digest value is too long.
658  * LE_UNSUPPORTED if underlying resource does not support this operation.
659  * LE_FAULT if the provPackagePtr does not have a valid signature
660  * or if there was an internal error.
661  */
662 //--------------------------------------------------------------------------------------------------
664 (
665  uint64_t digestRef,
666  ///< [IN] Digest reference.
667  const uint8_t* provPackagePtr,
668  ///< [IN] Provisioning package.
669  size_t provPackageSize
670  ///< [IN]
671 );
672 
673 //--------------------------------------------------------------------------------------------------
674 /**
675  * Saves a digest to persistent storage.
676  *
677  * @note
678  * Previously saved digests that have been updated do not need to be re-saved.
679  *
680  * @return
681  * LE_OK if successful.
682  * LE_BAD_PARAMETER if the digest reference is invalid
683  * LE_UNSUPPORTED if underlying resource does not support this operation.
684  * LE_FAULT if the digest is already in persistent storage
685  * or if there was an internal error.
686  */
687 //--------------------------------------------------------------------------------------------------
689 (
690  uint64_t digestRef
691  ///< [IN] Digest reference.
692 );
693 
694 //--------------------------------------------------------------------------------------------------
695 /**
696  * Delete a digest.
697  *
698  * If the specified digest has an assigned update key then the authCmdPtr must contain a delete
699  * digest command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge()
700  * and is signed with the update private key. If the command is valid and authentic then the digest
701  * will be deleted.
702  *
703  * If the specified digest does not have an assigned update key then then authCmdPtr is ignored.
704  *
705  * @note
706  * See the comment block at the top of this page for the authenticated command format.
707  *
708  * @return
709  * LE_OK if successful.
710  * LE_BAD_PARAMETER if the digest reference is invalid
711  * LE_UNSUPPORTED if underlying resource does not support this operation.
712  * LE_FAULT if the digest has an update key and the authCmdPtr is not valid.
713  */
714 //--------------------------------------------------------------------------------------------------
716 (
717  uint64_t digestRef,
718  ///< [IN] Digest reference.
719  const uint8_t* authCmdPtr,
720  ///< [IN] Authenticated command buffer.
721  size_t authCmdSize
722  ///< [IN]
723 );
724 
725 //--------------------------------------------------------------------------------------------------
726 /**
727  * Get the digest value.
728  *
729  * @return
730  * LE_OK if successful.
731  * LE_BAD_PARAMETER if the digest reference is invalid.
732  * LE_NOT_FOUND if the digest reference does not have a value.
733  * LE_OVERFLOW if the supplied buffer is too small to hold the digest value.
734  * LE_UNSUPPORTED if underlying resource does not support this operation.
735  */
736 //--------------------------------------------------------------------------------------------------
738 (
739  uint64_t digestRef,
740  ///< [IN] Digest reference.
741  uint8_t* bufPtr,
742  ///< [OUT] Buffer to hold the digest value.
743  size_t* bufSizePtr
744  ///< [INOUT]
745 );
746 
747 //--------------------------------------------------------------------------------------------------
748 /**
749  * Get update authentication challenge.
750  *
751  * This challenge code must be included in any update commands created using the specified update
752  * key.
753  *
754  * @return
755  * LE_OK if successful.
756  * LE_BAD_PARAMETER if the update key reference is invalid.
757  * LE_UNSUPPORTED if underlying resource does not support this operation.
758  * LE_FAULT if there is an internal error.
759  */
760 //--------------------------------------------------------------------------------------------------
762 (
763  uint64_t keyRef,
764  ///< [IN] Key reference.
765  uint8_t* bufPtr,
766  ///< [OUT] Buffer to hold the authentication challenge.
767  ///< Assumed to be CHALLENGE_SIZE bytes.
768  size_t* bufSizePtr
769  ///< [INOUT]
770 );
771 
772 //--------------------------------------------------------------------------------------------------
773 /**
774  * Get the wrapping key. This is a public key that is internally generated by the IOT Key Store
775  * and used to encrypt (wrap) symmetric and private keys for provisioning into the IOT Key Store.
776  * This key can only be used for this purpose.
777  *
778  * @note
779  * The key is provided in ASN.1 structured DER encoded format. Refer to the comment at the
780  * top of this file for details of the file format.
781  *
782  * @return
783  * LE_OK if successful.
784  * LE_OVERFLOW if the supplied buffer is too small.
785  * LE_UNSUPPORTED if underlying resource does not support this operation.
786  * LE_FAULT if there is an internal error.
787  */
788 //--------------------------------------------------------------------------------------------------
790 (
791  uint8_t* bufPtr,
792  ///< [OUT] Buffer to hold the wrapping key.
793  size_t* bufSizePtr
794  ///< [INOUT]
795 );
796 
797 //--------------------------------------------------------------------------------------------------
798 /**
799  * Create a session.
800  *
801  * @return
802  * LE_OK if successful.
803  * LE_BAD_PARAMETER if the key reference is invalid
804  * or if the key does not contain a key value or sessionRef is NULL.
805  * LE_NO_MEMORY if there is not enough memory to create the session.
806  * LE_FAULT if there was an internal error.
807  */
808 //--------------------------------------------------------------------------------------------------
810 (
811  uint64_t keyRef,
812  ///< [IN] Key to use for this session.
813  uint64_t* sessionRefPtr
814  ///< [OUT] Session reference.
815 );
816 
817 //--------------------------------------------------------------------------------------------------
818 /**
819  * Delete a session.
820  *
821  * @return
822  * LE_OK if successful.
823  * LE_BAD_PARAMETER if the session reference is invalid.
824  * LE_UNSUPPORTED if underlying resource does not support this operation.
825  */
826 //--------------------------------------------------------------------------------------------------
828 (
829  uint64_t sessionRef
830  ///< [IN] Session reference.
831 );
832 
833 /** @} **/
834 
835 #endif // LE_IKS_INTERFACE_H_INCLUDE_GUARD
le_result_t le_iks_GenKeyValue(uint64_t keyRef, const uint8_t *authCmdPtr, size_t authCmdSize)
le_iks_KeyUsage_t
Definition: le_iks_common.h:129
void(* le_iks_DisconnectHandler_t)(void *)
Definition: le_iks_interface.h:82
le_result_t le_iks_ProvisionKeyValue(uint64_t keyRef, const uint8_t *provPackagePtr, size_t provPackageSize)
le_result_t
Definition: le_basics.h:46
le_result_t le_iks_HasKeyValue(uint64_t keyRef)
le_result_t le_iks_DeleteDigest(uint64_t digestRef, const uint8_t *authCmdPtr, size_t authCmdSize)
le_result_t le_iks_CreateKeyByType(const char *LE_NONNULL keyId, le_iks_KeyType_t keyType, uint32_t keySize, uint64_t *keyRefPtr)
le_result_t le_iks_CreateKey(const char *LE_NONNULL keyId, le_iks_KeyUsage_t keyUsage, uint64_t *keyRefPtr)
le_result_t le_iks_GetDigestSize(uint64_t digestRef, uint32_t *digestSizePtr)
le_result_t le_iks_IsKeySizeValid(le_iks_KeyType_t keyType, uint32_t keySize)
le_result_t le_iks_SetKeyUpdateKey(uint64_t keyRef, uint64_t updateKeyRef)
le_result_t le_iks_SaveKey(uint64_t keyRef)
le_result_t le_iks_CreateSession(uint64_t keyRef, uint64_t *sessionRefPtr)
le_result_t le_iks_CreateDigest(const char *LE_NONNULL digestId, uint32_t digestSize, uint64_t *digestRefPtr)
le_result_t le_iks_GetPubKeyValue(uint64_t keyRef, uint8_t *bufPtr, size_t *bufSizePtr)
le_result_t le_iks_GetKeySize(uint64_t keyRef, uint32_t *keySizePtr)
void le_iks_ConnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_iks_GetDigest(const char *LE_NONNULL digestId, uint64_t *digestRefPtr)
le_result_t le_iks_DeleteKey(uint64_t keyRef, const uint8_t *authCmdPtr, size_t authCmdSize)
le_result_t le_iks_GetUpdateAuthChallenge(uint64_t keyRef, uint8_t *bufPtr, size_t *bufSizePtr)
le_result_t le_iks_DeleteSession(uint64_t sessionRef)
le_result_t le_iks_GetKeyType(uint64_t keyRef, le_iks_KeyType_t *keyTypePtr)
le_result_t le_iks_TryConnectService(void)
le_iks_KeyType_t
Definition: le_iks_common.h:152
le_result_t le_iks_GetKey(const char *LE_NONNULL keyId, uint64_t *keyRefPtr)
le_result_t le_iks_SetDigestUpdateKey(uint64_t digestRef, uint64_t updateKeyRef)
le_result_t le_iks_GetDigestValue(uint64_t digestRef, uint8_t *bufPtr, size_t *bufSizePtr)
le_result_t le_iks_SaveDigest(uint64_t digestRef)
LE_FULL_API void le_iks_SetServerDisconnectHandler(le_iks_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_iks_DisconnectService(void)
le_result_t le_iks_GetWrappingKey(uint8_t *bufPtr, size_t *bufSizePtr)
le_result_t le_iks_ProvisionDigest(uint64_t digestRef, const uint8_t *provPackagePtr, size_t provPackageSize)