le_iks_common.h

    1 
    2 /*
    3  * ====================== WARNING ======================
    4  *
    5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    6  * DO NOT MODIFY IN ANY WAY.
    7  *
    8  * ====================== WARNING ======================
    9  */
   10 /**
   11  * @file le_iks_common.h
   12  *
   13  * Type definitions for le_iks.
   14  *
   15  */
   16 #ifndef LE_IKS_COMMON_H_INCLUDE_GUARD
   17 #define LE_IKS_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 #define IFGEN_LE_IKS_PROTOCOL_ID "d7981d4badb3498107234322e8c8f92e"
   23 #define IFGEN_LE_IKS_MSG_SIZE 4116
   24 /** @addtogroup le_iks
   25  *  @{ **/
   26 
   27 
   28 //--------------------------------------------------------------------------------------------------
   29 /**
   30  * Maximum possible key buffer size.
   31  */
   32 //--------------------------------------------------------------------------------------------------
   33 #define LE_IKS_MAX_KEY_SIZE 512
   34 
   35 //--------------------------------------------------------------------------------------------------
   36 /**
   37  * Maximum digest size in bytes.
   38  */
   39 //--------------------------------------------------------------------------------------------------
   40 #define LE_IKS_MAX_DIGEST_SIZE 64
   41 
   42 //--------------------------------------------------------------------------------------------------
   43 /**
   44  * Maximum buffer size, in bytes, for ASN1 structured, DER encoded keys/digests.
   45  */
   46 //--------------------------------------------------------------------------------------------------
   47 #define LE_IKS_MAX_ASN1_VAL_BUF_SIZE 3000
   48 
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Authenticated challenge size in bytes.
   52  */
   53 //--------------------------------------------------------------------------------------------------
   54 #define LE_IKS_CHALLENGE_SIZE 32
   55 
   56 //--------------------------------------------------------------------------------------------------
   57 /**
   58  * AES block size in bytes.
   59  */
   60 //--------------------------------------------------------------------------------------------------
   61 #define LE_IKS_AES_BLOCK_SIZE 16
   62 
   63 //--------------------------------------------------------------------------------------------------
   64 /**
   65  * Maximum size of the Key ID
   66  */
   67 //--------------------------------------------------------------------------------------------------
   68 #define LE_IKS_MAX_KEY_ID_SIZE 255
   69 
   70 //--------------------------------------------------------------------------------------------------
   71 /**
   72  */
   73 //--------------------------------------------------------------------------------------------------
   74 #define LE_IKS_MAX_KEY_ID_BYTES 256
   75 
   76 //--------------------------------------------------------------------------------------------------
   77 /**
   78  * Maximum size of the Digest ID
   79  */
   80 //--------------------------------------------------------------------------------------------------
   81 #define LE_IKS_MAX_DIGEST_ID_SIZE 255
   82 
   83 //--------------------------------------------------------------------------------------------------
   84 /**
   85  */
   86 //--------------------------------------------------------------------------------------------------
   87 #define LE_IKS_MAX_DIGEST_ID_BYTES 256
   88 
   89 //--------------------------------------------------------------------------------------------------
   90 /**
   91  * Maximum size of the authentication command
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 #define LE_IKS_MAX_AUTH_CMD_SIZE 4096
   95 
   96 //--------------------------------------------------------------------------------------------------
   97 /**
   98  * Maximum size of the provisioning package
   99  */
  100 //--------------------------------------------------------------------------------------------------
  101 #define LE_IKS_MAX_PROV_PACKAGE_SIZE 4096
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Maximum packet size.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 #define LE_IKS_MAX_PACKET_SIZE 4096
  109 
  110 //--------------------------------------------------------------------------------------------------
  111 /**
  112  * Maximum size, in bytes, of the module identifier.
  113  */
  114 //--------------------------------------------------------------------------------------------------
  115 #define LE_IKS_MAX_MODULE_ID_SIZE 50
  116 
  117 //--------------------------------------------------------------------------------------------------
  118 /**
  119  */
  120 //--------------------------------------------------------------------------------------------------
  121 #define LE_IKS_MAX_MODULE_ID_BYTES 51
  122 
  123 //--------------------------------------------------------------------------------------------------
  124 /**
  125  * Key usage.  This type can be used to conveniently create keys for different usages.  IOT Key
  126  * Store will select a default key type for the specified usage.
  127  */
  128 //--------------------------------------------------------------------------------------------------
  129 typedef enum
  130 {
  131     LE_IKS_KEY_USE_ENCRYPT = 0,
  132         ///< Symmetric encryption/decryption.
  133     LE_IKS_KEY_USE_ASYMM_ENCRYPT = 1,
  134         ///< Public key encryption.
  135     LE_IKS_KEY_USE_ASYMM_DECRYPT = 2,
  136         ///< Private key decryption.
  137     LE_IKS_KEY_USE_SIG_GENERATION = 3,
  138         ///< Signature generation.
  139     LE_IKS_KEY_USE_SIG_VERIFICATION = 4,
  140         ///< Signature verification.
  141     LE_IKS_KEY_USE_KEY_UPDATE = 5
  142         ///< Key Store key updates.
  143 }
  144 le_iks_KeyUsage_t;
  145 
  146 
  147 //--------------------------------------------------------------------------------------------------
  148 /**
  149  * Key types
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 typedef enum
  153 {
  154     LE_IKS_KEY_TYPE_AES_GCM = 1,
  155         ///< AES GCM.
  156     LE_IKS_KEY_TYPE_AES_CBC = 2,
  157         ///< AES CBC.
  158     LE_IKS_KEY_TYPE_AES_CMAC = 3,
  159         ///< AES CMAC.
  160     LE_IKS_KEY_TYPE_AES_MILENAGE_K = 4,
  161         ///< AES Milenage K.
  162     LE_IKS_KEY_TYPE_AES_MILENAGE_OPC = 5,
  163         ///< AES Milenage OPc.
  164     LE_IKS_KEY_TYPE_HMAC_SHA512 = 81,
  165         ///<
  166     LE_IKS_KEY_TYPE_HMAC_SHA384 = 82,
  167         ///<
  168     LE_IKS_KEY_TYPE_HMAC_SHA256 = 83,
  169         ///<
  170     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512 = 100,
  171         ///<
  172     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512 = 101,
  173         ///<
  174     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA384 = 102,
  175         ///<
  176     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA384 = 103,
  177         ///<
  178     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512_256 = 104,
  179         ///<
  180     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512_256 = 105,
  181         ///<
  182     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA256 = 106,
  183         ///<
  184     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA256 = 107,
  185         ///<
  186     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512_224 = 108,
  187         ///<
  188     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512_224 = 109,
  189         ///<
  190     LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA224 = 110,
  191         ///<
  192     LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA224 = 111,
  193         ///<
  194     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 = 125,
  195         ///<
  196     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512 = 126,
  197         ///<
  198     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA384 = 127,
  199         ///<
  200     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA384 = 128,
  201         ///<
  202     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512_256 = 129,
  203         ///<
  204     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512_256 = 130,
  205         ///<
  206     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA256 = 131,
  207         ///<
  208     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA256 = 132,
  209         ///<
  210     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512_224 = 133,
  211         ///<
  212     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512_224 = 134,
  213         ///<
  214     LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA224 = 135,
  215         ///<
  216     LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA224 = 136,
  217         ///<
  218     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512 = 150,
  219         ///<
  220     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA384 = 151,
  221         ///<
  222     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512_256 = 152,
  223         ///<
  224     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA256 = 153,
  225         ///<
  226     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512_224 = 154,
  227         ///<
  228     LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA224 = 155,
  229         ///<
  230     LE_IKS_KEY_TYPE_PRIV_ECDH = 200,
  231         ///<
  232     LE_IKS_KEY_TYPE_PUB_ECDH = 201,
  233         ///<
  234     LE_IKS_KEY_TYPE_PRIV_ECDSA = 220,
  235         ///<
  236     LE_IKS_KEY_TYPE_PUB_ECDSA = 221,
  237         ///<
  238     LE_IKS_KEY_TYPE_UPDATE_ECDSA = 240,
  239         ///<
  240     LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA512_GCM256 = 260,
  241         ///< Uses HKDF with SHA512 and AES GCM 256
  242     LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA512_GCM256 = 261,
  243         ///< Uses HKDF with SHA512 and AES GCM 256
  244     LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA256_GCM128 = 262,
  245         ///< Uses HKDF with SHA256 and AES GCM 128
  246     LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA256_GCM128 = 263
  247         ///< Uses HKDF with SHA256 and AES GCM 128
  248 }
  249 le_iks_KeyType_t;
  250 
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  * Hash function identifiers.
  255  *
  256  * @warning
  257  *      The values in this enum must not be changed.  The list may be amended but binary
  258  *      compatibility requires that the actual values never change.
  259  */
  260 //--------------------------------------------------------------------------------------------------
  261 typedef enum
  262 {
  263     LE_IKS_HASH_SHA512 = 0,
  264         ///<
  265     LE_IKS_HASH_SHA384 = 1,
  266         ///<
  267     LE_IKS_HASH_SHA512_256 = 2,
  268         ///<
  269     LE_IKS_HASH_SHA256 = 3,
  270         ///<
  271     LE_IKS_HASH_SHA512_224 = 4,
  272         ///<
  273     LE_IKS_HASH_SHA224 = 5
  274         ///<
  275 }
  276 le_iks_HashFunc_t;
  277 
  278 
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * Get if this client bound locally.
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 LE_SHARED bool ifgen_le_iks_HasLocalBinding
  286 (
  287     void
  288 );
  289 
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  * Init data that is common across all threads
  294  */
  295 //--------------------------------------------------------------------------------------------------
  296 LE_SHARED void ifgen_le_iks_InitCommonData
  297 (
  298     void
  299 );
  300 
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * Perform common initialization and open a session
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 LE_SHARED le_result_t ifgen_le_iks_OpenSession
  308 (
  309     le_msg_SessionRef_t _ifgen_sessionRef,
  310     bool isBlocking
  311 );
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  * Sets the module ID.  This module ID may be used to uniquely identify the module, device or chip
  316  * that this instance of the IOT Key Store is running in.  The module ID is not secret and should
  317  * generally not change for the life of the module.
  318  *
  319  * An update key can be set to delete the module ID.  If the update key is not set then the module
  320  * ID may be viewed as OTP (one-time programmable).
  321  *
  322  * @return
  323  *      LE_OK if successful.
  324  *      LE_BAD_PARAMETER if the update key reference is invalid
  325  *                       or if idPtr NULL or is invalid.
  326  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  327  *      LE_FAULT if the module ID has already been set
  328  *               or if there was an internal error.
  329  */
  330 //--------------------------------------------------------------------------------------------------
  331 LE_SHARED le_result_t ifgen_le_iks_SetModuleId
  332 (
  333     le_msg_SessionRef_t _ifgen_sessionRef,
  334         const char* LE_NONNULL idPtr,
  335         ///< [IN] Module ID.
  336         uint64_t keyRef
  337         ///< [IN] Key reference. NULL if not used.
  338 );
  339 
  340 //--------------------------------------------------------------------------------------------------
  341 /**
  342  * Gets the module ID.
  343  *
  344  * @return
  345  *      LE_OK if successful.
  346  *      LE_NOT_FOUND if the module ID has not been set.
  347  *      LE_BAD_PARAMETER if bufPtr is NULL.
  348  *      LE_OVERFLOW if the buffer is too small to hold the entire module ID.
  349  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  350  *      LE_FAULT if there was an internal error.
  351  */
  352 //--------------------------------------------------------------------------------------------------
  353 LE_SHARED le_result_t ifgen_le_iks_GetModuleId
  354 (
  355     le_msg_SessionRef_t _ifgen_sessionRef,
  356         char* idPtr,
  357         ///< [OUT] Module ID.
  358         size_t idPtrSize
  359         ///< [IN]
  360 );
  361 
  362 //--------------------------------------------------------------------------------------------------
  363 /**
  364  * Deletes the module ID.
  365  *
  366  * This function is only possible if an update key was set when the module ID was set.  The
  367  * authCmdPtr must contain a valid delete module ID command.  If the command is valid and authentic
  368  * then the module ID is deleted.  Once the module ID is deleted a new module ID may be set.
  369  *
  370  * @note
  371  *      See the comment block at the top of this page for the authenticated command format.
  372  *
  373  * @return
  374  *      LE_OK if successful.
  375  *      LE_NOT_FOUND if the module ID has not been set.
  376  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  377  *      LE_FAULT if there is no assigned update key or the authCmdPtr is not valid
  378  *               or if there was an internal error.
  379  */
  380 //--------------------------------------------------------------------------------------------------
  381 LE_SHARED le_result_t ifgen_le_iks_DeleteModuleId
  382 (
  383     le_msg_SessionRef_t _ifgen_sessionRef,
  384         const uint8_t* authCmdPtr,
  385         ///< [IN] Authenticated command buffer.
  386         size_t authCmdSize
  387         ///< [IN]
  388 );
  389 
  390 //--------------------------------------------------------------------------------------------------
  391 /**
  392  * Gets a reference to a key.
  393  *
  394  * @return
  395  *      LE_OK if successful.
  396  *      LE_BAD_PARAMETER if the keyId is invalid or keyRef is NULL.
  397  *      LE_NOT_FOUND if the key does not exist.
  398  *      LE_NO_MEMORY if there is not enough memory to retrieve the key.
  399  *      LE_FAULT if there was an internal error.
  400  */
  401 //--------------------------------------------------------------------------------------------------
  402 LE_SHARED le_result_t ifgen_le_iks_GetKey
  403 (
  404     le_msg_SessionRef_t _ifgen_sessionRef,
  405         const char* LE_NONNULL keyId,
  406         ///< [IN] Identifier string.
  407         uint64_t* keyRefPtr
  408         ///< [OUT] Key reference.
  409 );
  410 
  411 //--------------------------------------------------------------------------------------------------
  412 /**
  413  * Creates a new key.
  414  *
  415  * This is a convenient way to create a key for a specific usage.  This function will choose a
  416  * default key type to satisfy the specified usage.
  417  *
  418  * New keys initially have no value and cannot be used.  Key values can be set using either
  419  * le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().
  420  *
  421  * Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save
  422  * the key to persistent memory.
  423  *
  424  * @return
  425  *      LE_OK if successful.
  426  *      LE_BAD_PARAMETER if the keyId or keyUsage is invalid or if keyRef is NULL.
  427  *      LE_DUPLICATE if the keyId is already being used.
  428  *      LE_NO_MEMORY if there is not enough memory to create the key.
  429  *      LE_FAULT if there was an internal error.
  430  */
  431 //--------------------------------------------------------------------------------------------------
  432 LE_SHARED le_result_t ifgen_le_iks_CreateKey
  433 (
  434     le_msg_SessionRef_t _ifgen_sessionRef,
  435         const char* LE_NONNULL keyId,
  436         ///< [IN] Identifier string.
  437         le_iks_KeyUsage_t keyUsage,
  438         ///< [IN] Key usage.
  439         uint64_t* keyRefPtr
  440         ///< [OUT] Key reference.
  441 );
  442 
  443 //--------------------------------------------------------------------------------------------------
  444 /**
  445  * Creates a new key of a specific type.
  446  *
  447  * New keys initially have no value and cannot be used.  Key values can be set using either
  448  * le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().
  449  *
  450  * Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save
  451  * the key to persistent memory.
  452  *
  453  * @return
  454  *      LE_OK if successful.
  455  *      LE_BAD_PARAMETER if the keyId or keyType is invalid or if keyRef is NULL.
  456  *      LE_DUPLICATE if the keyId is already being used.
  457  *      LE_OUT_OF_RANGE if the key size is invalid.
  458  *      LE_NO_MEMORY if there is not enough memory to create the key.
  459  *      LE_FAULT if there was an internal error.
  460  */
  461 //--------------------------------------------------------------------------------------------------
  462 LE_SHARED le_result_t ifgen_le_iks_CreateKeyByType
  463 (
  464     le_msg_SessionRef_t _ifgen_sessionRef,
  465         const char* LE_NONNULL keyId,
  466         ///< [IN] Identifier string.
  467         le_iks_KeyType_t keyType,
  468         ///< [IN] Key type.
  469         uint32_t keySize,
  470         ///< [IN] Key size in bytes.
  471         uint64_t* keyRefPtr
  472         ///< [OUT] Key reference.
  473 );
  474 
  475 //--------------------------------------------------------------------------------------------------
  476 /**
  477  * Get the key type.
  478  *
  479  * @return
  480  *      LE_OK if successful.
  481  *      LE_BAD_PARAMETER if the key reference is invalid
  482  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  483  */
  484 //--------------------------------------------------------------------------------------------------
  485 LE_SHARED le_result_t ifgen_le_iks_GetKeyType
  486 (
  487     le_msg_SessionRef_t _ifgen_sessionRef,
  488         uint64_t keyRef,
  489         ///< [IN] Key reference.
  490         le_iks_KeyType_t* keyTypePtr
  491         ///< [OUT] Key type.
  492 );
  493 
  494 //--------------------------------------------------------------------------------------------------
  495 /**
  496  * Gets the key size in bytes.
  497  *
  498  * @return
  499  *      LE_OK if successful.
  500  *      LE_BAD_PARAMETER if the key reference is invalid
  501  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  502  */
  503 //--------------------------------------------------------------------------------------------------
  504 LE_SHARED le_result_t ifgen_le_iks_GetKeySize
  505 (
  506     le_msg_SessionRef_t _ifgen_sessionRef,
  507         uint64_t keyRef,
  508         ///< [IN] Key reference.
  509         uint32_t* keySizePtr
  510         ///< [OUT] Key size.
  511 );
  512 
  513 //--------------------------------------------------------------------------------------------------
  514 /**
  515  * Checks if the key size is valid.
  516  *
  517  * @return
  518  *      LE_OK if the key size is valid.
  519  *      LE_OUT_OF_RANGE if the key size is invalid.
  520  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  521  */
  522 //--------------------------------------------------------------------------------------------------
  523 LE_SHARED le_result_t ifgen_le_iks_IsKeySizeValid
  524 (
  525     le_msg_SessionRef_t _ifgen_sessionRef,
  526         le_iks_KeyType_t keyType,
  527         ///< [IN] Key type.
  528         uint32_t keySize
  529         ///< [IN] Key size.
  530 );
  531 
  532 //--------------------------------------------------------------------------------------------------
  533 /**
  534  * Checks if the key has a value.
  535  *
  536  * @return
  537  *      LE_OK if the key has a value.
  538  *      LE_BAD_PARAMETER if the key reference is invalid.
  539  *      LE_NOT_FOUND if the key has no value.
  540  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  541  */
  542 //--------------------------------------------------------------------------------------------------
  543 LE_SHARED le_result_t ifgen_le_iks_HasKeyValue
  544 (
  545     le_msg_SessionRef_t _ifgen_sessionRef,
  546         uint64_t keyRef
  547         ///< [IN] Key reference.
  548 );
  549 
  550 //--------------------------------------------------------------------------------------------------
  551 /**
  552  * Set an update key for the specified key.  The update key must be of type KEY_TYPE_KEY_UPDATE.
  553  * The update key can be used at a later time to perform authenticated updates of the specified key.
  554  * The same update key may be used for multiple keys and digests.
  555  *
  556  * @note
  557  *      Once an update key is assigned the key parameters can no longer be modified except through
  558  *      an authenticated update process.
  559  *
  560  *      Update keys can be assigned to themselves or other update keys.
  561  *
  562  * @warning
  563  *      It is strongly recommended to save the update key before assigning it to other keys/digests.
  564  *      Otherwise a sudden power loss could leave the update key reference pointing to a
  565  *      non-existing update key allowing a new update key to be created with the same ID but a
  566  *      different (unintended) value.
  567  *
  568  * @return
  569  *      LE_OK if successful.
  570  *      LE_BAD_PARAMETER if the key reference is invalid
  571  *                       or if the update key reference is invalid or does not have a value.
  572  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  573  *      LE_FAULT if an update key has already been set
  574  *               or if there was an internal error.
  575  */
  576 //--------------------------------------------------------------------------------------------------
  577 LE_SHARED le_result_t ifgen_le_iks_SetKeyUpdateKey
  578 (
  579     le_msg_SessionRef_t _ifgen_sessionRef,
  580         uint64_t keyRef,
  581         ///< [IN] Key reference.
  582         uint64_t updateKeyRef
  583         ///< [IN] Reference to an update key.
  584 );
  585 
  586 //--------------------------------------------------------------------------------------------------
  587 /**
  588  * Generate a key value.
  589  *
  590  * If the specified key has an assigned update key then the authCmdPtr must contain a generate key
  591  * command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(),
  592  * and is signed with the update private key.  If the command is valid and authentic then a new key
  593  * value is generated replacing the old value.
  594  *
  595  * If the specified key does not have an update key then the authCmdPtr is ignored.
  596  *
  597  * Public keys cannot be generated using this function.  They must be provisioned using
  598  * le_iks_ProvisionKeyValue().
  599  *
  600  * @note
  601  *      See the comment block at the top of this page for the authenticated command format.
  602  *
  603  * @return
  604  *      LE_OK if successful.
  605  *      LE_BAD_PARAMETER if the key reference is invalid
  606  *                       or if the key is a public key.
  607  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  608  *      LE_FAULT if there is an update key set and the authCmdPtr does not contain a
  609  *               valid authenticated command, or if there was an internal error.
  610  */
  611 //--------------------------------------------------------------------------------------------------
  612 LE_SHARED le_result_t ifgen_le_iks_GenKeyValue
  613 (
  614     le_msg_SessionRef_t _ifgen_sessionRef,
  615         uint64_t keyRef,
  616         ///< [IN] Key reference.
  617         const uint8_t* authCmdPtr,
  618         ///< [IN] Authenticated command buffer.
  619         size_t authCmdSize
  620         ///< [IN]
  621 );
  622 
  623 //--------------------------------------------------------------------------------------------------
  624 /**
  625  * Provision a key value.
  626  *
  627  * The provisioning package, provPackagePtr, must contain the key value to provision.
  628  *
  629  * Private key provisioning is not currently supported.
  630  *
  631  * If the key is a symmetric then the key value must be encrypted with the provisioning key.  If the
  632  * key is a public key the key value must be provided in plaintext.
  633  *
  634  * If the specified key does not have an assigned update key then the provPackagePtr is treated as a
  635  * buffer containing the key value.
  636  *
  637  * If the specified key has an assigned update key then the provPackagePtr must also contain a valid
  638  * authentication challenge and be signed with the assigned update key.
  639  *
  640  * @note
  641  *      See the comment block at the top of this page for the provisioning package format.
  642  *
  643  * @return
  644  *      LE_OK if successful.
  645  *      LE_BAD_PARAMETER if the key reference is invalid.
  646  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  647  *      LE_FAULT if the provPackagePtr is not validly encrypted and/or signed
  648  *               or if there was an internal error.
  649  */
  650 //--------------------------------------------------------------------------------------------------
  651 LE_SHARED le_result_t ifgen_le_iks_ProvisionKeyValue
  652 (
  653     le_msg_SessionRef_t _ifgen_sessionRef,
  654         uint64_t keyRef,
  655         ///< [IN] Key reference.
  656         const uint8_t* provPackagePtr,
  657         ///< [IN] Provisioning package.
  658         size_t provPackageSize
  659         ///< [IN]
  660 );
  661 
  662 //--------------------------------------------------------------------------------------------------
  663 /**
  664  * Saves a key to persistent storage.
  665  *
  666  * @note
  667  *      Previously saved keys that have been updated do not need to be re-saved.
  668  *
  669  * @return
  670  *      LE_OK if successful.
  671  *      LE_BAD_PARAMETER if the key reference is invalid.
  672  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  673  *      LE_FAULT if the key is already in persistent storage
  674  *               or if there was an internal error.
  675  */
  676 //--------------------------------------------------------------------------------------------------
  677 LE_SHARED le_result_t ifgen_le_iks_SaveKey
  678 (
  679     le_msg_SessionRef_t _ifgen_sessionRef,
  680         uint64_t keyRef
  681         ///< [IN] Key reference.
  682 );
  683 
  684 //--------------------------------------------------------------------------------------------------
  685 /**
  686  * Delete key.
  687  *
  688  * If the specified key has an assigned update key then the authCmdPtr must contain a delete key
  689  * command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(), and is
  690  * signed with the update private key.  If the command is valid and authentic then the key will be
  691  * deleted.
  692  *
  693  * If the specified key does not have an assigned update key then then authCmdPtr is ignored.
  694  *
  695  * @warning
  696  *      When deleting an update key, it is a good idea to delete all keys that depend on the update
  697  *      key first.  Otherwise the dependent keys will be left non-updatable.
  698  *
  699  * @note
  700  *      See the comment block at the top of this page for the authenticated command format.
  701  *
  702  * @return
  703  *      LE_OK if successful.
  704  *      LE_BAD_PARAMETER if the key reference is invalid.
  705  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  706  *      LE_FAULT if the key has an update key and the authCmdPtr is not valid.
  707  */
  708 //--------------------------------------------------------------------------------------------------
  709 LE_SHARED le_result_t ifgen_le_iks_DeleteKey
  710 (
  711     le_msg_SessionRef_t _ifgen_sessionRef,
  712         uint64_t keyRef,
  713         ///< [IN] Key reference.
  714         const uint8_t* authCmdPtr,
  715         ///< [IN] Authenticated command buffer.
  716         size_t authCmdSize
  717         ///< [IN]
  718 );
  719 
  720 //--------------------------------------------------------------------------------------------------
  721 /**
  722  * Get the public portion of an asymmetric key.
  723  *
  724  * The output will be in:
  725  *      - PKCS #1 format (DER encoded) for RSA keys.
  726  *      - ECPoint format defined in RFC5480 for ECC keys.
  727  *
  728  * @return
  729  *      LE_OK if successful.
  730  *      LE_BAD_PARAMETER if the key reference is invalid
  731  *                       or if the key is not an asymmetric key.
  732  *      LE_NOT_FOUND if the key reference does not have a value.
  733  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  734  *      LE_OVERFLOW if the supplied buffer is too small to hold the key value.
  735  */
  736 //--------------------------------------------------------------------------------------------------
  737 LE_SHARED le_result_t ifgen_le_iks_GetPubKeyValue
  738 (
  739     le_msg_SessionRef_t _ifgen_sessionRef,
  740         uint64_t keyRef,
  741         ///< [IN] Key reference.
  742         uint8_t* bufPtr,
  743         ///< [OUT] Buffer to hold key value.
  744         size_t* bufSizePtr
  745         ///< [INOUT]
  746 );
  747 
  748 //--------------------------------------------------------------------------------------------------
  749 /**
  750  * Gets a reference to a digest.
  751  *
  752  * Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.
  753  *
  754  * @return
  755  *      LE_OK if successful.
  756  *      LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL.
  757  *      LE_NOT_FOUND if the digest does not exist.
  758  *      LE_NO_MEMORY if there is not enough memory to retrieve the digest.
  759  *      LE_FAULT if there was an internal error.
  760  */
  761 //--------------------------------------------------------------------------------------------------
  762 LE_SHARED le_result_t ifgen_le_iks_GetDigest
  763 (
  764     le_msg_SessionRef_t _ifgen_sessionRef,
  765         const char* LE_NONNULL digestId,
  766         ///< [IN] Identifier string.
  767         uint64_t* digestRefPtr
  768         ///< [OUT] Digest reference.
  769 );
  770 
  771 //--------------------------------------------------------------------------------------------------
  772 /**
  773  * Creates a new digest.
  774  *
  775  * New digests initially have no value.  Digest values can be set using le_iks_ProvisionDigest().
  776  *
  777  * Created digests initially only exist in non-persistent memory, call le_iks_SaveDigest() to save
  778  * to persistent storage.
  779  *
  780  * Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.
  781  *
  782  * @return
  783  *      LE_OK if successful.
  784  *      LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL.
  785  *      LE_DUPLICATE if the digestId is already being used.
  786  *      LE_OUT_OF_RANGE if the digest size is invalid.
  787  *      LE_NO_MEMORY if there is not enough memory to create the digest.
  788  *      LE_FAULT if there was an internal error.
  789  */
  790 //--------------------------------------------------------------------------------------------------
  791 LE_SHARED le_result_t ifgen_le_iks_CreateDigest
  792 (
  793     le_msg_SessionRef_t _ifgen_sessionRef,
  794         const char* LE_NONNULL digestId,
  795         ///< [IN] Identifier string.
  796         uint32_t digestSize,
  797         ///< [IN] Digest size. Must be <= MAX_DIGEST_SIZE.
  798         uint64_t* digestRefPtr
  799         ///< [OUT] Digest reference.
  800 );
  801 
  802 //--------------------------------------------------------------------------------------------------
  803 /**
  804  * Gets the digest size in bytes.
  805  *
  806  * @return
  807  *      LE_OK if successful.
  808  *      LE_BAD_PARAMETER if the digest reference is invalid.
  809  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  810  */
  811 //--------------------------------------------------------------------------------------------------
  812 LE_SHARED le_result_t ifgen_le_iks_GetDigestSize
  813 (
  814     le_msg_SessionRef_t _ifgen_sessionRef,
  815         uint64_t digestRef,
  816         ///< [IN] Digest reference.
  817         uint32_t* digestSizePtr
  818         ///< [OUT] Digest size.
  819 );
  820 
  821 //--------------------------------------------------------------------------------------------------
  822 /**
  823  * Set an update key for the specified digest.  The update key must be of type
  824  * KEY_TYPE_KEY_UPDATE.  The update key can be used at a later time to perform authenticated
  825  * updates of the specified digest.  The same update key may be used for multiple keys and digests.
  826  *
  827  * @note
  828  *      Once an update key is assigned the digest parameters can no longer be modified except
  829  *      through an authenticated update process.
  830  *
  831  * @warning
  832  *      It is strongly recommended to save the update key before assigning it to other keys/digests.
  833  *      Otherwise a sudden power loss could leave the update key reference pointing to a
  834  *      non-existing update key allowing a new update key to be created with the same ID but a
  835  *      different (unintended) value.
  836  *
  837  * @return
  838  *      LE_OK if successful.
  839  *      LE_BAD_PARAMETER if the digest reference is invalid
  840  *                       or if the update key reference is invalid or does not have a value.
  841  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  842  *      LE_FAULT if an update key has already been set
  843  *               or if there was an internal error.
  844  */
  845 //--------------------------------------------------------------------------------------------------
  846 LE_SHARED le_result_t ifgen_le_iks_SetDigestUpdateKey
  847 (
  848     le_msg_SessionRef_t _ifgen_sessionRef,
  849         uint64_t digestRef,
  850         ///< [IN] Digest reference.
  851         uint64_t updateKeyRef
  852         ///< [IN] Reference to an update key.
  853 );
  854 
  855 //--------------------------------------------------------------------------------------------------
  856 /**
  857  * Provision a digest value.
  858  *
  859  * The provisioning package, provPackagePtr, must contain the digest value to provision.
  860  *
  861  * If the specified digest does not have an assigned update key then the provPackagePtr is treated
  862  * as a buffer containing the digest value.
  863  *
  864  * If the specified digest has an assigned update key then the provPackagePtr must also contain a
  865  * valid authentication challenge and be signed with the assigned update key.
  866  *
  867  * @note
  868  *      See the comment block at the top of this page for the provisioning package format.
  869  *
  870  * @return
  871  *      LE_OK if successful.
  872  *      LE_BAD_PARAMETER if the digest reference is invalid
  873  *                       or if the digest value is too long.
  874  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  875  *      LE_FAULT if the provPackagePtr does not have a valid signature
  876  *               or if there was an internal error.
  877  */
  878 //--------------------------------------------------------------------------------------------------
  879 LE_SHARED le_result_t ifgen_le_iks_ProvisionDigest
  880 (
  881     le_msg_SessionRef_t _ifgen_sessionRef,
  882         uint64_t digestRef,
  883         ///< [IN] Digest reference.
  884         const uint8_t* provPackagePtr,
  885         ///< [IN] Provisioning package.
  886         size_t provPackageSize
  887         ///< [IN]
  888 );
  889 
  890 //--------------------------------------------------------------------------------------------------
  891 /**
  892  * Saves a digest to persistent storage.
  893  *
  894  * @note
  895  *      Previously saved digests that have been updated do not need to be re-saved.
  896  *
  897  * @return
  898  *      LE_OK if successful.
  899  *      LE_BAD_PARAMETER if the digest reference is invalid
  900  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  901  *      LE_FAULT if the digest is already in persistent storage
  902  *               or if there was an internal error.
  903  */
  904 //--------------------------------------------------------------------------------------------------
  905 LE_SHARED le_result_t ifgen_le_iks_SaveDigest
  906 (
  907     le_msg_SessionRef_t _ifgen_sessionRef,
  908         uint64_t digestRef
  909         ///< [IN] Digest reference.
  910 );
  911 
  912 //--------------------------------------------------------------------------------------------------
  913 /**
  914  * Delete a digest.
  915  *
  916  * If the specified digest has an assigned update key then the authCmdPtr must contain a delete
  917  * digest command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge()
  918  * and is signed with the update private key.  If the command is valid and authentic then the digest
  919  * will be deleted.
  920  *
  921  * If the specified digest does not have an assigned update key then then authCmdPtr is ignored.
  922  *
  923  * @note
  924  *      See the comment block at the top of this page for the authenticated command format.
  925  *
  926  * @return
  927  *      LE_OK if successful.
  928  *      LE_BAD_PARAMETER if the digest reference is invalid
  929  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  930  *      LE_FAULT if the digest has an update key and the authCmdPtr is not valid.
  931  */
  932 //--------------------------------------------------------------------------------------------------
  933 LE_SHARED le_result_t ifgen_le_iks_DeleteDigest
  934 (
  935     le_msg_SessionRef_t _ifgen_sessionRef,
  936         uint64_t digestRef,
  937         ///< [IN] Digest reference.
  938         const uint8_t* authCmdPtr,
  939         ///< [IN] Authenticated command buffer.
  940         size_t authCmdSize
  941         ///< [IN]
  942 );
  943 
  944 //--------------------------------------------------------------------------------------------------
  945 /**
  946  * Get the digest value.
  947  *
  948  * @return
  949  *      LE_OK if successful.
  950  *      LE_BAD_PARAMETER if the digest reference is invalid.
  951  *      LE_NOT_FOUND if the digest reference does not have a value.
  952  *      LE_OVERFLOW if the supplied buffer is too small to hold the digest value.
  953  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  954  */
  955 //--------------------------------------------------------------------------------------------------
  956 LE_SHARED le_result_t ifgen_le_iks_GetDigestValue
  957 (
  958     le_msg_SessionRef_t _ifgen_sessionRef,
  959         uint64_t digestRef,
  960         ///< [IN] Digest reference.
  961         uint8_t* bufPtr,
  962         ///< [OUT] Buffer to hold the digest value.
  963         size_t* bufSizePtr
  964         ///< [INOUT]
  965 );
  966 
  967 //--------------------------------------------------------------------------------------------------
  968 /**
  969  * Get update authentication challenge.
  970  *
  971  * This challenge code must be included in any update commands created using the specified update
  972  * key.
  973  *
  974  * @return
  975  *      LE_OK if successful.
  976  *      LE_BAD_PARAMETER if the update key reference is invalid.
  977  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  978  *      LE_FAULT if there is an internal error.
  979  */
  980 //--------------------------------------------------------------------------------------------------
  981 LE_SHARED le_result_t ifgen_le_iks_GetUpdateAuthChallenge
  982 (
  983     le_msg_SessionRef_t _ifgen_sessionRef,
  984         uint64_t keyRef,
  985         ///< [IN] Key reference.
  986         uint8_t* bufPtr,
  987         ///< [OUT] Buffer to hold the authentication challenge.
  988         ///<   Assumed to be CHALLENGE_SIZE bytes.
  989         size_t* bufSizePtr
  990         ///< [INOUT]
  991 );
  992 
  993 //--------------------------------------------------------------------------------------------------
  994 /**
  995  * Get the provisioning key.  This is a public key that is internally generated by the IOT Key Store
  996  * and used to encrypt symmetric and private keys for provisioning into the IOT Key Store.  This key
  997  * can only be used for this purpose.
  998  *
  999  * @note
 1000  *      The key is provided in ASN.1 structured DER encoded format.  Refer to the comment at the
 1001  *      top of this file for details of the file format.
 1002  *
 1003  * @return
 1004  *      LE_OK if successful.
 1005  *      LE_OVERFLOW if the supplied buffer is too small.
 1006  *      LE_UNSUPPORTED if underlying resource does not support this operation.
 1007  *      LE_FAULT if there is an internal error.
 1008  */
 1009 //--------------------------------------------------------------------------------------------------
 1010 LE_SHARED le_result_t ifgen_le_iks_GetProvisionKey
 1011 (
 1012     le_msg_SessionRef_t _ifgen_sessionRef,
 1013         uint8_t* bufPtr,
 1014         ///< [OUT] Buffer to hold the provisioning key.
 1015         size_t* bufSizePtr
 1016         ///< [INOUT]
 1017 );
 1018 
 1019 //--------------------------------------------------------------------------------------------------
 1020 /**
 1021  * Create a session.
 1022  *
 1023  * @return
 1024  *      LE_OK if successful.
 1025  *      LE_BAD_PARAMETER if the key reference is invalid
 1026  *                       or if the key does not contain a key value or sessionRef is NULL.
 1027  *      LE_NO_MEMORY if there is not enough memory to create the session.
 1028  *      LE_FAULT if there was an internal error.
 1029  */
 1030 //--------------------------------------------------------------------------------------------------
 1031 LE_SHARED le_result_t ifgen_le_iks_CreateSession
 1032 (
 1033     le_msg_SessionRef_t _ifgen_sessionRef,
 1034         uint64_t keyRef,
 1035         ///< [IN] Key to use for this session.
 1036         uint64_t* sessionRefPtr
 1037         ///< [OUT] Session reference.
 1038 );
 1039 
 1040 //--------------------------------------------------------------------------------------------------
 1041 /**
 1042  * Delete a session.
 1043  *
 1044  * @return
 1045  *      LE_OK if successful.
 1046  *      LE_BAD_PARAMETER if the session reference is invalid.
 1047  *      LE_UNSUPPORTED if underlying resource does not support this operation.
 1048  */
 1049 //--------------------------------------------------------------------------------------------------
 1050 LE_SHARED le_result_t ifgen_le_iks_DeleteSession
 1051 (
 1052     le_msg_SessionRef_t _ifgen_sessionRef,
 1053         uint64_t sessionRef
 1054         ///< [IN] Session reference.
 1055 );
 1056 /** @} **/
 1057 #endif // LE_IKS_COMMON_H_INCLUDE_GUARD
le_iks_KeyUsage_t
le_iks_KeyUsage_t
Definition: le_iks_common.h:129
le_iks_HashFunc_t
le_iks_HashFunc_t
Definition: le_iks_common.h:261
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:300
LE_IKS_KEY_TYPE_AES_CMAC
AES CMAC. 
Definition: le_iks_common.h:158
le_result_t
le_result_t
Definition: le_basics.h:46
LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA256_GCM128
Uses HKDF with SHA256 and AES GCM 128. 
Definition: le_iks_common.h:246
LE_IKS_KEY_TYPE_AES_GCM
AES GCM. 
Definition: le_iks_common.h:154
LE_IKS_KEY_USE_SIG_VERIFICATION
Signature verification. 
Definition: le_iks_common.h:139
LE_IKS_KEY_USE_KEY_UPDATE
Key Store key updates. 
Definition: le_iks_common.h:141
LE_IKS_KEY_TYPE_AES_CBC
AES CBC. 
Definition: le_iks_common.h:156
LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA512_GCM256
Uses HKDF with SHA512 and AES GCM 256. 
Definition: le_iks_common.h:240
le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
LE_IKS_KEY_USE_ASYMM_DECRYPT
Private key decryption. 
Definition: le_iks_common.h:135
LE_IKS_KEY_USE_ASYMM_ENCRYPT
Public key encryption. 
Definition: le_iks_common.h:133
LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA256_GCM128
Uses HKDF with SHA256 and AES GCM 128. 
Definition: le_iks_common.h:244
legato.h
LE_IKS_KEY_USE_SIG_GENERATION
Signature generation. 
Definition: le_iks_common.h:137
LE_IKS_KEY_TYPE_AES_MILENAGE_OPC
AES Milenage OPc. 
Definition: le_iks_common.h:162
le_iks_KeyType_t
le_iks_KeyType_t
Definition: le_iks_common.h:152
LE_IKS_KEY_TYPE_AES_MILENAGE_K
AES Milenage K. 
Definition: le_iks_common.h:160
LE_IKS_KEY_USE_ENCRYPT
Symmetric encryption/decryption. 
Definition: le_iks_common.h:131
LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA512_GCM256
Uses HKDF with SHA512 and AES GCM 256. 
Definition: le_iks_common.h:242