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