{
#endif
+/** \enum KM_ParamsMagic
+ * \brief Param magic is a control value that appears before data to
+ * verify data integrity.
+ */
typedef enum KM_ParamsMagic {
- PSMagic_SymmetricInput = 0x542345,
- PSMagic_InputData = 0x575445,
- PSMagic_PwdData = 0x707764,
- PSMagic_IVData = 0x445234,
- PSMagic_AEData = 0x810891,
- PSMagic_OutData = 0x721513,
- PSMagic_TagData = 0x721513,
- PSMagic_KeyId = 0x946704
+ PSMagic_SymmetricInput = 0x542345, ///< Control value for serialized header
+ PSMagic_InputData = 0x575445, ///< Control value for serialized input data
+ PSMagic_PwdData = 0x707764, ///< Control value for serialized password
+ PSMagic_IVData = 0x445234, ///< Control value for serialized IV
+ PSMagic_AEData = 0x810891, ///< Control value for serialized authorized
+ PSMagic_OutData = 0x721513, ///< Control value for serialized output data
+ PSMagic_TagData = 0x721513, ///< Control value for serialized tag
+ PSMagic_KeyId = 0x946704 ///< Control value for serialized key id
} KM_PSMagic;
+/** \struct KM_Data_
+ * \brief KM_Data_ is a basic structure for data serialization.
+ * More complex strucures extend KM_Data_.
+ * \typedef KM_Data
+ * Defining simple type of structure KM_Data_.
+ */
typedef struct KM_Data_ {
- uint32_t magic;
- uint32_t data_size;
- void *data;
+ uint32_t magic; ///< control value that confirms data integrity.
+ uint32_t data_size; ///< size of data
+ void *data; ///< pointer to data buffer
} KM_Data;
+
+/** \typedef KM_InputData
+ * \brief Defines structure type for data that is input to TA commands.
+ * KM_InputData inherited after KM_Data
+ */
typedef struct KM_Data_ KM_InputData;
+/** \typedef KM_OutData
+ * \brief Defines structure type for data that is output to TA commands.
+ * KM_OutData inherited after KM_Data
+ */
typedef struct KM_Data_ KM_OutData;
+/** \typedef KM_IVData
+ * \brief Defines structure type for data that is IV data needed for encryption/decryption.
+ * KM_IVData inherited after KM_Data
+ */
typedef struct KM_Data_ KM_IVData;
+/** \typedef KM_KeyId
+ * \brief Defines structure type for data that represents key object identifier.
+ * Maximum length of object identifier is 64 bytes.
+ * KM_KeyId inherited after KM_Data
+ */
typedef struct KM_Data_ KM_KeyId;
+/** \typedef KM_TagData
+ * \brief Defines structure type for data that represents tag from encryption/decryption.
+ * KM_TagData inherited after KM_Data
+ */
typedef struct KM_Data_ KM_TagData;
+/** \typedef KM_AEData
+ * \brief Defines structure type for data that are necessary for authenticated
+ * encryption/decryption. KM_AEData extends KM_Data with /val tag_len and /val payload_len.
+ */
typedef struct KM_AEData_ {
- KM_Data aad;
+ KM_Data aad; ///< store additional authentication data
uint32_t tag_len;
uint32_t payload_len;
} KM_AEData;
+/** \struct KM_PwdData_
+ * \brief Structure contains data necessary to protect data with password.
+ * \typedef KM_PwdData
+ * \brief Defines simple type of KM_PwdData_ structure.
+ *
+ */
typedef struct KM_PwdData_ {
uint32_t magic;
uint32_t pwd_size;
void *tag;
} KM_PwdData;
+/** \struct KM_SymmetricInput_
+ * \brief Serialized data header. This structure allows to find data based on KM_Data
+ * in buffer.
+ * \typedef KM_SymmentricInput
+ * Defines type of KM_SymmetricInput_ structure.
+ */
typedef struct KM_SymmetricInput_ {
- uint32_t magic;
- uint32_t buffer_size;
- uint32_t key_id_data_offset;
- uint32_t input_data_offset;
- uint32_t pwd_data_offset;
- uint32_t iv_data_offset;
- uint32_t ae_data_offset;
- uint32_t out_data_offset;
- uint32_t tag_data_offset;
- uint32_t global_offset;
+ uint32_t magic; ///< magic for testing data integrity
+ uint32_t buffer_size; ///< total buffer size
+ uint32_t key_id_data_offset; ///< offset of key id data in buffer
+ uint32_t input_data_offset; ///< offset of input data in buffer
+ uint32_t pwd_data_offset; ///< offset of pwd data in buffer
+ uint32_t iv_data_offset; ///< offset of iv data in buffer
+ uint32_t ae_data_offset; ///< offset of authentication encryption data in buffer
+ uint32_t out_data_offset; ///< offset of output data in buffer
+ uint32_t tag_data_offset; ///< offset of tag data in buffer
+ uint32_t global_offset; ///< offset of free data in buffer
} KM_SymmetricInput;
+/** \struct KM_BufferSizeDesc_
+ * \brief Structure used to count buffer size needed to serialization.
+ * \typedef KM_BufferSizeDesc
+ * \bierf Defines simple type for structure KM_BufferSizeDesc_.
+ */
typedef struct KM_BufferSizeDesc_ {
uint32_t input_size;
uint32_t with_pwd_data;
uint32_t key_id_size;
} KM_BufferSizeDesc;
+/** \fn KM_ParamsDump
+ * \brief Function prints all data found in serialized buffer. (offsets, sizes)
+ *
+ * \param[in] input reference to serialized data header \ref KM_SymmetricInput
+ * \param[in] input_data reference to \ref KM_InputData structure
+ * \param[in] pwd_data reference to \ref KM_PwdData structure
+ * \param[in] iv_data reference to \ref KM_IVData structure
+ * \param[in] key_data reference to \ref KM_KeyId structure
+ * \param[in] ae_data reference to \ref KM_AEData structure
+ * \param[in] out_data reference to \ref KM_OutData structure
+ * \param[in] tag_data reference to \ref KM_TagData structure
+ */
void KM_ParamsDump(KM_SymmetricInput *input, KM_InputData *input_data, KM_PwdData* pwd_data,
KM_IVData *iv_data, KM_KeyId *key_data, KM_AEData *ae_data,
KM_OutData *out_data, KM_TagData *tag_data);
+
+/** \fn KM_GetSerializedBufferRealSize
+ * \brief Function returns information about buffer size that was used.
+ *
+ * \param[in] buffer reference to serialized data header \ref KM_SymmetricInput
+ *
+ * \return 0 if failed; buffer size if successful
+ */
uint32_t KM_GetSerializedBufferRealSize(KM_SymmetricInput *buffer);
+
+/** \fn KM_CalcBufferSize
+ * \brief Function calculates buffer size needed to store serialized data.
+ *
+ * \param[in] desc reference to /ref KM_BufferSizeDesc
+ * \return buffer size needed
+ */
uint32_t KM_CalcBufferSize(KM_BufferSizeDesc desc);
+/** \fn KM_ParamsDeserializationInit
+ * \brief Function deserializes data header in buffer
+ *
+ * \param[in] buffer reference to buffer with data
+ * \param[in] buffer_size buffer size
+ * \param[out] out reference to \ref KM_SymmetricInput reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializationInit(void *buffer, uint32_t buffer_size, KM_SymmetricInput **out);
+
+/** \fn KM_ParamsDeserializeInputData
+ * \brief Function deserializes \ref KM_InputData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_InputData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeInputData(KM_SymmetricInput *self, KM_InputData **out);
+
+/** \fn KM_ParamsDeserializeIVData
+ * \brief Function deserializes \ref KM_IVData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_IVData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeIVData(KM_SymmetricInput *self, KM_IVData **out);
+
+/** \fn KM_ParamsDeserializeAEData
+ * \brief Function deserializes \ref KM_AEData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_AEData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeAEData(KM_SymmetricInput *self, KM_AEData **out);
+
+/** \fn KM_ParamsDeserializeOutData
+ * \brief Function deserializes \ref KM_OutData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_OutData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeOutData(KM_SymmetricInput *self, KM_OutData **out);
+
+/** \fn KM_ParamsDeserializeTagData
+ * \brief Function deserializes \ref KM_TagData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_TagData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeTagData(KM_SymmetricInput *self, KM_TagData **out);
+
+/** \fn KM_ParamsDeserializeKeyId
+ * \brief Function deserializes \ref KM_KeyId from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_KeyId reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializeKeyId(KM_SymmetricInput *self, KM_KeyId **out);
+
+/** \fn KM_ParamsDeserializePwdData
+ * \brief Function deserializes \ref KM_PwdData from \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[out] out reference to \ref KM_PwdData reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsDeserializePwdData(KM_SymmetricInput *self, KM_PwdData **out);
+/** \fn KM_ParamsSerializationInit
+ * \brief Function serializes \ref KM_SymmetricInput as header in buffer
+ *
+ * \param[in] buffer reference to buffer with data
+ * \param[in] buffer_size buffer size
+ * \param[out] out reference to \ref KM_SymmetricInput reference
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializationInit(void *buffer, uint32_t buffer_size, KM_SymmetricInput **out);
+
+/** \fn KM_ParamsSerializeInputData
+ * \brief Function serializes input data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] data reference to input data buffer
+ * \param[in] data_size input data size
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeInputData(KM_SymmetricInput *self, const void *data, uint32_t data_size);
+
+/** \fn KM_ParamsSerializeIVData
+ * \brief Function serializes IV data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] data reference to IV data buffer
+ * \param[in] data_size IV data size
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeIVData(KM_SymmetricInput *self, const void *data, uint32_t data_size);
+
+/** \fn KM_ParamsSerializeAEData
+ * \brief Function serializes authentication encryption data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] tagLen tag length
+ * \param[in] payloadLen payload length
+ * \param[in] aad Authentication Additional Data buffer
+ * \param[in] add_sie Authentication Additional Data buffer size
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeAEData(KM_SymmetricInput *self, uint32_t tagLen, uint32_t payloadLen,
const void *aad, uint32_t aad_size);
+
+/** \fn KM_ParamsSerializeOutData
+ * \brief Function serializes output data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] data reference to output data buffer
+ * \param[in] data_size output data size
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeOutData(KM_SymmetricInput *self, const void *data, uint32_t data_size);
+
+/** \fn KM_ParamsSerializeTagData
+ * \brief Function serializes tag data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] data reference to tag data buffer
+ * \param[in] data_size tag data size
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeTagData(KM_SymmetricInput *self, const void *data, uint32_t data_size);
+
+/** \fn KM_ParamsSerializeKeyId
+ * \brief Function serializes key id data in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] data reference to key id data buffer
+ * \param[in] data_size key id data size (up to 64 bytes)
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializeKeyId(KM_SymmetricInput *self, const void *data, uint32_t data_size);
+
+/** \fn KM_ParamsSerializePwdData
+ * \brief Function serializes data needed to encrpyt/decrypt data with password
+ * in \ref KM_SymmetricInput
+ *
+ * \param[in] self reference to \ref KM_SymmetricInput
+ * \param[in] pwd reference to password buffer
+ * \param[in] pwd_size password buffer size
+ * \param[in] iv reference to IV buffer
+ * \param[in] iv_size IV buffer size
+ * \param[in] tag reference to tag bufer
+ * \param[in] tag_size tag buffer size
+ * \param[in] derive_len_bits length of derive key in bits
+ * \param[in] it_count derive key iterations
+ * \param[in] tag_len_bits tag size in bits
+ *
+ * \return 0 if successful; -1 if failed
+ */
int KM_ParamsSerializePwdData(KM_SymmetricInput *self, const void *pwd, uint32_t pwd_size,
const void *iv, uint32_t iv_size, const void *tag, uint32_t tag_size,
uint32_t derive_len_bits, uint32_t it_count, uint32_t tag_len_bits);
#ifndef __KM_TA_DEFINES_H__
#define __KM_TA_DEFINES_H__
+/** \enum tz_command
+ * \brief tz_command contains list of commands that can be called from key-manager-ta
+ *
+ * Each enum corresponds to specific function called on key-manager-ta. Information
+ * about necessary arguments You can get below.
+ */
typedef enum {
CMD_NOP = 0,
- CMD_GENERATE_KEY,
- CMD_IMPORT_KEY,
- CMD_IMPORT_ENCRYPTED_KEY,
- CMD_ENCRYPT,
- CMD_DECRYPT,
- CMD_SIGN,
- CMD_VERIFY,
- CMD_GENERATE_IV,
- CMD_GENERATE_KEY_PWD,
- CMD_DESTROY_KEY,
+ CMD_GENERATE_KEY, ///< Generate random key.
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [0].value.b - key size in bits
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [1].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with key id
+
+ CMD_IMPORT_KEY, ///< Key Manager TA import key from normal world
+ ///< TA will encrypt key with password if provided
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [0].value.b - key size in bits
+ ///< [1].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeInputData with key
+ ///< KM_ParamsSerializePwdData with password (optional)
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [2].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with key id
+
+ CMD_IMPORT_ENCRYPTED_KEY, ///< Key Manager TA import encrypted key from
+ ///< normal world. Not implemented
+
+ CMD_ENCRYPT, ///< TA encrypt provided data with key
+ ///< Form of encryption depends on algorithm type
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [1].memref - reference to serialized buffer:
+ ///<
+ ///< For ALGO_AES_GCM:
+ ///< KM_ParamsSerializeInputData with data to encrypt
+ ///< KM_ParamsSerializeIVData with iv of key
+ ///< KM_ParamsSerializePwdData with password to key
+ ///< necessary if key is encryted
+ ///< KM_ParamsSerializeKeyId with key id
+ ///<
+ ///< For ALGO_RSA:
+ ///< KM_ParamsSerializeInputData with data to encrypt
+ ///< KM_ParamsSerializeKeyId with key id
+ ///<
+ ///< For other algorithms:
+ ///< KM_ParamsSerializeInputData with data to encrypt
+ ///< KM_ParamsSerializeIVData with iv of key
+ ///< KM_ParamsSerializePwdData with password to key
+ ///< necessary if key is encryted
+ ///< KM_ParamsSerializeKeyId with key id
+ ///<
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [2].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with encrypted data
+ ///< For ALGO_AES_GCM:
+ ///< KM_ParamsSerializeTagData with tag
+ ///<
+
+ CMD_DECRYPT, ///< TA decrypt provided data with key
+ ///< Form of decryption depends on algorithm type
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [1].memref - reference to serialized buffer:
+ ///< For ALGO_AES_GCM:
+ ///< KM_ParamsSerializeInputData with data to decrypt
+ ///< KM_ParamsSerializeIVData with iv of key
+ ///< KM_ParamsSerializePwdData with password to key
+ ///< necessary if key is encryted
+ ///< KM_ParamsSerializeKeyId with key id
+ ///< KM_ParamsSerializeTagData with tag from encryption
+ ///<
+ ///< For ALGO_RSA:
+ ///< KM_ParamsSerializeInputData with data to encrypt
+ ///< KM_ParamsSerializeKeyId with key id
+ ///<
+ ///< For other algorithms (symmetric):
+ ///< KM_ParamsSerializeInputData with data to encrypt
+ ///< KM_ParamsSerializeIVData with iv of key
+ ///< KM_ParamsSerializePwdData with password to key
+ ///< necessary if key is encryted
+ ///< KM_ParamsSerializeKeyId with key id
+ ///<
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [2].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with decrypted data
+ ///<
+
+ CMD_SIGN, ///< TA sign data
+ ///< Only for ALGO_RSA_SV|ALGO_DSA_SV|ALGO_ECDSA_SV
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [0].value.b - hash type (tz_hash_type)
+ ///< [1].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeInputData with data to sign
+ ///< KM_ParamsSerializeKeyId with key id
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [2].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with signed data
+
+ CMD_VERIFY, ///< TA verify signature
+ ///<
+ ///< Not implemented
+
+ CMD_GENERATE_IV, ///< TA generate random IV
+ ///< No parameters necessary.
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [1].memref - reference to iv data:
+
+ CMD_GENERATE_KEY_PWD, ///< TA generate random key and encrypt it with password
+ ///< Parameters:
+ ///< [0].value.a - algorithm type (tz_algo_type)
+ ///< [0].value.b - key size in bits
+ ///< [1].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializePwdData with password to
+ ///< key enctryption
+ ///<
+ ///< Output:
+ ///< [0].value.a - return code
+ ///< [2].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializeOutData with key id
+ ///< KM_ParamsSerializeTagData with tag from encryption
+
+ CMD_DESTROY_KEY, ///< Ta destroy key from storage
+ ///< Parameters:
+ ///< [1].memref - reference to serialized buffer:
+ ///< KM_ParamsSerializePwdData with password to
+ ///< key encryption
+ ///<
+ ///< Output:
+ ///< [0].value.a - return code
+
} tz_command;
+/** \enum tz_algo_type
+ * \brief tz_algo_type contains algorithms definitions
+ *
+ * Each enum corresponds to algorithm and action that will be taken.
+ * Algorithms with suffix GEN should be used to key generations.
+ * Algorithms with suffix SV should be used to data signing/verification with key.
+ * Other algorithms should be used to encryption/decrytpion.
+ */
typedef enum {
ALGO_NONE = 0,
ALGO_AES_CTR,
ALGO_ECDSA_SV,
} tz_algo_type;
+/** \enum tz_hash_type
+ * \brief tz_hash_type contains hash function definitions
+ *
+ * Each enum corresponds to hash function that will be used to asymmetric operations.
+ */
typedef enum {
HASH_SHA1,
HASH_SHA256,
projects / platform / core / security / trusted / key-manager-ta.git / commitdiff