Internal Cryptographic Backend

Functions
TSS2_RC	iesys_crypto_hash_get_digest_size (TPM2_ALG_ID hashAlg, size_t *size)
TSS2_RC	iesys_cryptossl_hash_start (IESYS_CRYPTO_CONTEXT_BLOB **context, TPM2_ALG_ID hashAlg)
TSS2_RC	iesys_cryptossl_hash_update (IESYS_CRYPTO_CONTEXT_BLOB *context, const uint8_t *buffer, size_t size)
TSS2_RC	iesys_cryptossl_hash_update2b (IESYS_CRYPTO_CONTEXT_BLOB *context, TPM2B *b)
TSS2_RC	iesys_cryptossl_hash_finish (IESYS_CRYPTO_CONTEXT_BLOB **context, uint8_t *buffer, size_t *size)
TSS2_RC	iesys_cryptossl_hash_finish2b (IESYS_CRYPTO_CONTEXT_BLOB **context, TPM2B *b)
TSS2_RC	iesys_cryptossl_hmac_start (IESYS_CRYPTO_CONTEXT_BLOB **context, TPM2_ALG_ID hashAlg, const uint8_t *key, size_t size)
TSS2_RC	iesys_cryptossl_hmac_start2b (IESYS_CRYPTO_CONTEXT_BLOB **context, TPM2_ALG_ID hmacAlg, TPM2B *b)
TSS2_RC	iesys_cryptossl_hmac_update (IESYS_CRYPTO_CONTEXT_BLOB *context, const uint8_t *buffer, size_t size)
TSS2_RC	iesys_cryptossl_hmac_update2b (IESYS_CRYPTO_CONTEXT_BLOB *context, TPM2B *b)
TSS2_RC	iesys_cryptossl_hmac_finish (IESYS_CRYPTO_CONTEXT_BLOB **context, uint8_t *buffer, size_t *size)
TSS2_RC	iesys_cryptossl_hmac_finish2b (IESYS_CRYPTO_CONTEXT_BLOB **context, TPM2B *hmac)
void	iesys_cryptossl_hmac_abort (IESYS_CRYPTO_CONTEXT_BLOB **context)
TSS2_RC	iesys_crypto_pHash (TPM2_ALG_ID alg, const uint8_t rcBuffer[4], const uint8_t ccBuffer[4], const TPM2B_NAME *name1, const TPM2B_NAME *name2, const TPM2B_NAME *name3, const uint8_t *pBuffer, size_t pBuffer_size, uint8_t *pHash, size_t *pHash_size)
TSS2_RC	iesys_crypto_authHmac (TPM2_ALG_ID alg, uint8_t *hmacKey, size_t hmacKeySize, const uint8_t *pHash, size_t pHash_size, const TPM2B_NONCE *nonceNewer, const TPM2B_NONCE *nonceOlder, const TPM2B_NONCE *nonceDecrypt, const TPM2B_NONCE *nonceEncrypt, TPMA_SESSION sessionAttributes, TPM2B_AUTH *hmac)
TSS2_RC	iesys_cryptossl_random2b (TPM2B_NONCE *nonce, size_t num_bytes)
TSS2_RC	iesys_cryptossl_pk_encrypt (TPM2B_PUBLIC *pub_tpm_key, size_t in_size, BYTE *in_buffer, size_t max_out_size, BYTE *out_buffer, size_t *out_size, const char *label)
TSS2_RC	iesys_crypto_KDFaHmac (TPM2_ALG_ID alg, uint8_t *hmacKey, size_t hmacKeySize, uint32_t counter, const char *label, TPM2B_NONCE *contextU, TPM2B_NONCE *contextV, uint32_t bitlength, uint8_t *hmac, size_t *hmacSize)
TSS2_RC	iesys_crypto_KDFa (TPM2_ALG_ID hashAlg, uint8_t *hmacKey, size_t hmacKeySize, const char *label, TPM2B_NONCE *contextU, TPM2B_NONCE *contextV, uint32_t bitLength, uint32_t *counterInOut, BYTE *outKey, BOOL use_digest_size)
TSS2_RC	iesys_crypto_KDFe (TPM2_ALG_ID hashAlg, TPM2B_ECC_PARAMETER *Z, const char *label, TPM2B_ECC_PARAMETER *partyUInfo, TPM2B_ECC_PARAMETER *partyVInfo, UINT32 bit_size, BYTE *key)
TSS2_RC	iesys_xor_parameter_obfuscation (TPM2_ALG_ID hash_alg, uint8_t *key, size_t key_size, TPM2B_NONCE *contextU, TPM2B_NONCE *contextV, BYTE *data, size_t data_size)
TSS2_RC	iesys_cryptossl_get_ecdh_point (TPM2B_PUBLIC *key, size_t max_out_size, TPM2B_ECC_PARAMETER *Z, TPMS_ECC_POINT *Q, BYTE *out_buffer, size_t *out_size)

Detailed Description

The types and functions used internally by ESAPI for cryptographic operations. Multiple implementations of these functions may exist for different cryptographic backends.

Function Documentation

iesys_crypto_authHmac()

TSS2_RC iesys_crypto_authHmac	(	TPM2_ALG_ID	alg,
		uint8_t *	hmacKey,
		size_t	hmacKeySize,
		const uint8_t *	pHash,
		size_t	pHash_size,
		const TPM2B_NONCE *	nonceNewer,
		const TPM2B_NONCE *	nonceOlder,
		const TPM2B_NONCE *	nonceDecrypt,
		const TPM2B_NONCE *	nonceEncrypt,
		TPMA_SESSION	sessionAttributes,
		TPM2B_AUTH *	hmac
	)

Compute the HMAC for authorization.

Based on the session nonces, caller nonce, TPM nonce, if used encryption and decryption nonce, the command parameter hash, and the session attributes the HMAC used for authorization is computed.

Parameters

[in]	alg	The hash algorithm used for HMAC computation.
[in]	hmacKey	The HMAC key byte buffer.
[in]	hmacKeySize	The size of the HMAC key byte buffer.
[in]	pHash	The command parameter hash byte buffer.
[in]	pHash_size	The size of the command parameter hash byte buffer.
[in]	nonceNewer	The TPM nonce.
[in]	nonceOlder	The caller nonce.
[in]	nonceDecrypt	The decrypt nonce (NULL if not used).
[in]	nonceEncrypt	The encrypt nonce (NULL if not used).
[in]	sessionAttributes	The attributes used for the current authentication.
[out]	hmac	The computed HMAC.

Return values

TSS2_RC_SUCCESS	on success
TSS2_ESYS_RC_BAD_REFERENCE	If a pointer is invalid.

iesys_crypto_hash_get_digest_size()

TSS2_RC iesys_crypto_hash_get_digest_size	(	TPM2_ALG_ID	hashAlg,
		size_t *	size
	)

Provide the digest size for a given hash algorithm.

This function provides the size of the digest for a given hash algorithm.

Parameters

[in]	hashAlg	The hash algorithm to get the size for.
[out]	size	The side of a digest of the hash algorithm.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_VALUE	if hashAlg is unknown or unsupported.

iesys_crypto_KDFa()

TSS2_RC iesys_crypto_KDFa	(	TPM2_ALG_ID	hashAlg,
		uint8_t *	hmacKey,
		size_t	hmacKeySize,
		const char *	label,
		TPM2B_NONCE *	contextU,
		TPM2B_NONCE *	contextV,
		uint32_t	bitLength,
		uint32_t *	counterInOut,
		BYTE *	outKey,
		BOOL	use_digest_size
	)

KDFa Key derivation.

Except of ECDH this function is used for key derivation.

Parameters

[in]	hashAlg	The hash algorithm to use.
[in]	hmacKey	The hmacKey used in KDFa.
[in]	hmacKeySize	The size of the HMAC key.
[in]	label	Indicates the use of the produced key.
[in]	contextU,contextV	are used for construction of a binary string containing information related to the derived key.
[in]	bitLength	The size of generated key in bits.
[in,out]	counterInOut	Counter for the KDFa iterations. If set, the value will be used for the firt iteration step. The final counter value will be written to counterInOut.
[out]	outKey	Byte buffer for the derived key (caller-allocated).
[in]	use_digest_size	Indicate whether the digest size of hashAlg is used as size of the generated key or the bitLength parameter is used.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_VALUE	if hashAlg is unknown or unsupported.

iesys_crypto_KDFaHmac()

TSS2_RC iesys_crypto_KDFaHmac	(	TPM2_ALG_ID	alg,
		uint8_t *	hmacKey,
		size_t	hmacKeySize,
		uint32_t	counter,
		const char *	label,
		TPM2B_NONCE *	contextU,
		TPM2B_NONCE *	contextV,
		uint32_t	bitlength,
		uint8_t *	hmac,
		size_t *	hmacSize
	)

HMAC computation for inner loop of KDFa key derivation.

Except of ECDH this function is used for key derivation.

Parameters

[in]	alg	The algorithm used for the HMAC.
[in]	hmacKey	The hmacKey used in KDFa.
[in]	hmacKeySize	The size of the HMAC key.
[in]	counter	The curren iteration step.
[in]	label	Indicates the use of the produced key.
[in]	contextU,contextV	are used for construction of a binary string containing information related to the derived key.
[in]	bitlength	The size of the generated key in bits.
[out]	hmac	Byte buffer for the generated HMAC key (caller-allocated).
[out]	hmacSize	Size of the generated HMAC key.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_crypto_KDFe()

TSS2_RC iesys_crypto_KDFe	(	TPM2_ALG_ID	hashAlg,
		TPM2B_ECC_PARAMETER *	Z,
		const char *	label,
		TPM2B_ECC_PARAMETER *	partyUInfo,
		TPM2B_ECC_PARAMETER *	partyVInfo,
		UINT32	bit_size,
		BYTE *	key
	)

Compute KDFe as described in TPM spec part 1 C 6.1

Parameters

hashAlg	[in] The nameAlg of the recipient key.
Z	[in] the x coordinate (xP) of the product (P) of a public point and a private key.
label	[in] KDF label.
partyUInfo	[in] The x-coordinate of the secret exchange value (Qe,U).
partyVInfo	[in] The x-coordinate of a public key (Qs,V).
bit_size	[in] Bit size of generated key.
key	[out] Key buffer.

Return values

TSS2_RC_SUCCESS	on success
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters
TSS2_ESYS_RC_MEMORY	Memory cannot be allocated.

iesys_crypto_pHash()

TSS2_RC iesys_crypto_pHash	(	TPM2_ALG_ID	alg,
		const uint8_t	rcBuffer[4],
		const uint8_t	ccBuffer[4],
		const TPM2B_NAME *	name1,
		const TPM2B_NAME *	name2,
		const TPM2B_NAME *	name3,
		const uint8_t *	pBuffer,
		size_t	pBuffer_size,
		uint8_t *	pHash,
		size_t *	pHash_size
	)

Compute the command or response parameter hash.

These hashes are needed for the computation of the HMAC used for the authorization of commands, or for the HMAC used for checking the responses. The name parameters are only used for the command parameter hash (cp) and must be NULL for the computation of the response parameter rp hash (rp).

Parameters

[in]	alg	The hash algorithm.
[in]	rcBuffer	The response code in marshaled form.
[in]	ccBuffer	The command code in marshaled form.
[in]	name1,name2,name3	The names associated with the corresponding handle. Must be NULL if no handle is passed.
[in]	pBuffer	The byte buffer or the command or the response.
[in]	pBuffer_size	The size of the command or response.
[out]	pHash	The result digest.
[out]	pHash_size	The size of the result digest.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_cryptossl_get_ecdh_point()

TSS2_RC iesys_cryptossl_get_ecdh_point	(	TPM2B_PUBLIC *	key,
		size_t	max_out_size,
		TPM2B_ECC_PARAMETER *	Z,
		TPMS_ECC_POINT *	Q,
		BYTE *	out_buffer,
		size_t *	out_size
	)

Computation of ephemeral ECC key and shared secret Z.

According to the description in TPM spec part 1 C 6.1 a shared secret between application and TPM is computed (ECDH). An ephemeral ECC key and a TPM keyare used for the ECDH key exchange.

Parameters

[in]	key	The key to be used for ECDH key exchange.
[in]	max_out_size	the max size for the output of the public key of the computed ephemeral key.
[out]	Z	The computed shared secret.
[out]	Q	The public part of the ephemeral key in TPM format.
[out]	out_buffer	The public part of the ephemeral key will be marshaled to this buffer.
[out]	out_size	The size of the marshaled output.

Return values

TSS2_RC_SUCCESS	on success
TSS2_ESYS_RC_BAD_VALUE	The algorithm of key is not implemented.
TSS2_ESYS_RC_GENERAL_FAILURE	The internal crypto engine failed.

iesys_cryptossl_hash_finish()

TSS2_RC iesys_cryptossl_hash_finish	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		uint8_t *	buffer,
		size_t *	size
	)

Get the digest value of a digest object and close the context.

The digest value will written to a passed buffer and the resources of the digest object are released.

Parameters

[in,out]	context	The context of the digest object to be released
[out]	buffer	The buffer for the digest value (caller-allocated).
[out]	size	The size of the digest.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.
TSS2_ESYS_RC_GENERAL_FAILURE	for errors of the crypto library.

iesys_cryptossl_hash_finish2b()

TSS2_RC iesys_cryptossl_hash_finish2b	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		TPM2B *	b
	)

void iesys_cryptossl_hash_abort(IESYS_CRYPTO_CONTEXT_BLOB **context)

iesys_cryptossl_hash_start()

TSS2_RC iesys_cryptossl_hash_start	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		TPM2_ALG_ID	hashAlg
	)

Provide the context for the computation of a hash digest.

The context will be created and initialized according to the hash function.

Parameters

[out]	context	The created context (callee-allocated).
[in]	hashAlg	The hash algorithm for the creation of the context.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_VALUE	or TSS2_ESYS_RC_BAD_REFERENCE for invalid parameters.
TSS2_ESYS_RC_MEMORY	Memory cannot be allocated.
TSS2_ESYS_RC_GENERAL_FAILURE	for errors of the crypto library.

iesys_cryptossl_hash_update()

TSS2_RC iesys_cryptossl_hash_update	(	IESYS_CRYPTO_CONTEXT_BLOB *	context,
		const uint8_t *	buffer,
		size_t	size
	)

Update the digest value of a digest object from a byte buffer.

The context of a digest object will be updated according to the hash algorithm of the context. <

Parameters

[in,out]	context	The context of the digest object which will be updated.
[in]	buffer	The data for the update.
[in]	size	The size of the data buffer.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_cryptossl_hash_update2b()

TSS2_RC iesys_cryptossl_hash_update2b	(	IESYS_CRYPTO_CONTEXT_BLOB *	context,
		TPM2B *	b
	)

Update the digest value of a digest object from a TPM2B object.

The context of a digest object will be updated according to the hash algorithm of the context.

Parameters

[in,out]	context	The context of the digest object which will be updated.
[in]	b	The TPM2B object for the update.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_cryptossl_hmac_abort()

void iesys_cryptossl_hmac_abort

(

IESYS_CRYPTO_CONTEXT_BLOB **

context

)

Release the resources of an HAMC object.

The assigned resources will be released and the context will be set to NULL.

Parameters

[in,out]

context

The context of the HMAC object.

iesys_cryptossl_hmac_finish()

TSS2_RC iesys_cryptossl_hmac_finish	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		uint8_t *	buffer,
		size_t *	size
	)

Write the HMAC digest value to a byte buffer and close the context.

The digest value will written to a passed buffer and the resources of the HMAC object are released.

Parameters

[in,out]	context	The context of the HMAC object.
[out]	buffer	The buffer for the digest value (caller-allocated).
[out]	size	The size of the digest.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.
TSS2_ESYS_RC_BAD_SIZE	If the size passed is lower than the HMAC length.
TSS2_ESYS_RC_GENERAL_FAILURE	for errors of the crypto library.

iesys_cryptossl_hmac_finish2b()

TSS2_RC iesys_cryptossl_hmac_finish2b	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		TPM2B *	hmac
	)

Write the HMAC digest value to a TPM2B object and close the context.

The digest value will written to a passed TPM2B object and the resources of the HMAC object are released.

Parameters

[in,out]	context	The context of the HMAC object.
[out]	hmac	The buffer for the digest value (caller-allocated).

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.
TSS2_ESYS_RC_BAD_SIZE	if the size passed is lower than the HMAC length.
TSS2_ESYS_RC_GENERAL_FAILURE	for errors of the crypto library.

iesys_cryptossl_hmac_start()

TSS2_RC iesys_cryptossl_hmac_start	(	IESYS_CRYPTO_CONTEXT_BLOB **	context,
		TPM2_ALG_ID	hashAlg,
		const uint8_t *	key,
		size_t	size
	)

Provide the context an HMAC digest object from a byte buffer key.

The context will be created and initialized according to the hash function and the used HMAC key.

Parameters

[out]	context	The created context (callee-allocated).
[in]	hashAlg	The hash algorithm for the HMAC computation.
[in]	key	The byte buffer of the HMAC key.
[in]	size	The size of the HMAC key.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.
TSS2_ESYS_RC_MEMORY	Memory cannot be allocated.
TSS2_ESYS_RC_GENERAL_FAILURE	for errors of the crypto library.

iesys_cryptossl_hmac_update()

TSS2_RC iesys_cryptossl_hmac_update	(	IESYS_CRYPTO_CONTEXT_BLOB *	context,
		const uint8_t *	buffer,
		size_t	size
	)

Update and HMAC digest value from a byte buffer.

The context of a digest object will be updated according to the hash algorithm and the key of the context.

Parameters

[in,out]	context	The context of the digest object which will be updated.
[in]	buffer	The data for the update.
[in]	size	The size of the data buffer.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_cryptossl_hmac_update2b()

TSS2_RC iesys_cryptossl_hmac_update2b	(	IESYS_CRYPTO_CONTEXT_BLOB *	context,
		TPM2B *	b
	)

Update and HMAC digest value from a TPM2B object.

The context of a digest object will be updated according to the hash algorithm and the key of the context.

Parameters

[in,out]	context	The context of the digest object which will be updated.
[in]	b	The TPM2B object for the update.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.

iesys_cryptossl_pk_encrypt()

TSS2_RC iesys_cryptossl_pk_encrypt	(	TPM2B_PUBLIC *	pub_tpm_key,
		size_t	in_size,
		BYTE *	in_buffer,
		size_t	max_out_size,
		BYTE *	out_buffer,
		size_t *	out_size,
		const char *	label
	)

Encryption of a buffer using a public (RSA) key.

Encrypting a buffer using a public key is used for example during Esys_StartAuthSession in order to encrypt the salt value.

Parameters

[in]	pub_tpm_key	The key to be used for encryption.
[in]	in_size	The size of the buffer to be encrypted.
[in]	in_buffer	The data buffer to be encrypted.
[in]	max_out_size	The maximum size for the output encrypted buffer.
[out]	out_buffer	The encrypted buffer.
[out]	out_size	The size of the encrypted output.
[in]	label	The label used in the encryption scheme.

Return values

TSS2_RC_SUCCESS	on success
TSS2_ESYS_RC_BAD_VALUE	The algorithm of key is not implemented.
TSS2_ESYS_RC_GENERAL_FAILURE	The internal crypto engine failed.

iesys_cryptossl_random2b()

TSS2_RC iesys_cryptossl_random2b	(	TPM2B_NONCE *	nonce,
		size_t	num_bytes
	)

Compute random TPM2B data.

The random data will be generated and written to a passed TPM2B structure.

Parameters

[out]	nonce	The TPM2B structure for the random data (caller-allocated).
[in]	num_bytes	The number of bytes to be generated.

Return values

TSS2_RC_SUCCESS

on success.

NOTE: the TPM should not be used to obtain the random data

iesys_xor_parameter_obfuscation()

TSS2_RC iesys_xor_parameter_obfuscation	(	TPM2_ALG_ID	hash_alg,
		uint8_t *	key,
		size_t	key_size,
		TPM2B_NONCE *	contextU,
		TPM2B_NONCE *	contextV,
		BYTE *	data,
		size_t	data_size
	)

Encryption/Decryption using XOR obfuscation.

The application of this function to data encrypted with this function will produce the origin data. The key for XOR obfuscation will be derived with KDFa form the passed key the session nonces, and the hash algorithm.

Parameters

[in]	hash_alg	The algorithm used for key derivation.
[in]	key	key used for obfuscation
[in]	key_size	Key size in bits.
[in]	contextU,contextV	are used for construction of a binary string containing information related to the derived key.
[in,out]	data	Data to be encrypted/decrypted the result will be will be stored in this buffer.
[in]	data_size	size of data to be encrypted/decrypted.

Return values

TSS2_RC_SUCCESS	on success, or TSS2_ESYS_RC_BAD_VALUE and
TSS2_ESYS_RC_BAD_REFERENCE	for invalid parameters.