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  * 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 //--------------------------------------------------------------------------------------------------
  197 le_result_t le_iks_GetKey
  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 //--------------------------------------------------------------------------------------------------
  226 le_result_t le_iks_CreateKey
  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 //--------------------------------------------------------------------------------------------------
  255 le_result_t le_iks_CreateKeyByType
  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 //--------------------------------------------------------------------------------------------------
  277 le_result_t le_iks_GetKeyType
  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 //--------------------------------------------------------------------------------------------------
  295 le_result_t le_iks_GetKeySize
  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 //--------------------------------------------------------------------------------------------------
  313 le_result_t le_iks_IsKeySizeValid
  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 //--------------------------------------------------------------------------------------------------
  332 le_result_t le_iks_HasKeyValue
  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 //--------------------------------------------------------------------------------------------------
  368 le_result_t le_iks_SetKeyUpdateKey
  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 //--------------------------------------------------------------------------------------------------
  402 le_result_t le_iks_GenKeyValue
  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 //--------------------------------------------------------------------------------------------------
  440 le_result_t le_iks_ProvisionKeyValue
  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 //--------------------------------------------------------------------------------------------------
  465 le_result_t le_iks_SaveKey
  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 //--------------------------------------------------------------------------------------------------
  496 le_result_t le_iks_DeleteKey
  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 //--------------------------------------------------------------------------------------------------
  523 le_result_t le_iks_GetPubKeyValue
  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 //--------------------------------------------------------------------------------------------------
  547 le_result_t le_iks_GetDigest
  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 //--------------------------------------------------------------------------------------------------
  575 le_result_t le_iks_CreateDigest
  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 //--------------------------------------------------------------------------------------------------
  595 le_result_t le_iks_GetDigestSize
  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 //--------------------------------------------------------------------------------------------------
  631 le_result_t le_iks_SetDigestUpdateKey
  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 //--------------------------------------------------------------------------------------------------
  663 le_result_t le_iks_ProvisionDigest
  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 //--------------------------------------------------------------------------------------------------
  688 le_result_t le_iks_SaveDigest
  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 //--------------------------------------------------------------------------------------------------
  715 le_result_t le_iks_DeleteDigest
  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 //--------------------------------------------------------------------------------------------------
  737 le_result_t le_iks_GetDigestValue
  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 //--------------------------------------------------------------------------------------------------
  761 le_result_t le_iks_GetUpdateAuthChallenge
  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 //--------------------------------------------------------------------------------------------------
  789 le_result_t le_iks_GetWrappingKey
  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 //--------------------------------------------------------------------------------------------------
  809 le_result_t le_iks_CreateSession
  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 //--------------------------------------------------------------------------------------------------
  827 le_result_t le_iks_DeleteSession
  828 (
  829     uint64_t sessionRef
  830         ///< [IN] Session reference.
  831 );
  832 
  833 /** @} **/
  834 
  835 #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_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_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_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_DisconnectService
void le_iks_DisconnectService(void)
le_iks_GetWrappingKey
le_result_t le_iks_GetWrappingKey(uint8_t *bufPtr, size_t *bufSizePtr)
le_iks_ProvisionDigest
le_result_t le_iks_ProvisionDigest(uint64_t digestRef, const uint8_t *provPackagePtr, size_t provPackageSize)