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