le_iks_interface.h

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