Internal Cryptographic Backend

Functions
TSS2_RC	get_crl_from_cert (X509 *cert, X509_CRL **crl)
TSS2_RC	ifapi_cert_to_pem (const uint8_t *certBuffer, size_t certBufferSize, char **pemCert, TPM2_ALG_ID *certAlgorithmId, TPM2B_PUBLIC *tpmPublic)
void	ifapi_crypto_hash_abort (IFAPI_CRYPTO_CONTEXT_BLOB **context)
TSS2_RC	ifapi_crypto_hash_finish (IFAPI_CRYPTO_CONTEXT_BLOB **context, uint8_t *digest, size_t *digestSize)
TSS2_RC	ifapi_crypto_hash_start (IFAPI_CRYPTO_CONTEXT_BLOB **context, TPM2_ALG_ID hashAlgorithm)
TSS2_RC	ifapi_crypto_hash_update (IFAPI_CRYPTO_CONTEXT_BLOB *context, const uint8_t *buffer, size_t size)
TSS2_RC	ifapi_der_sig_to_tpm (const TPMT_PUBLIC *tpmPublic, const unsigned char *signature, size_t signatureSize, TPMI_ALG_HASH hashAlgorithm, TPMT_SIGNATURE *tpmSignature)
TSS2_RC	ifapi_get_hash_alg_for_size (uint16_t size, TPMI_ALG_HASH *hashAlgorithm)
TPM2_RC	ifapi_get_profile_sig_scheme (const IFAPI_PROFILE *profile, const TPMT_PUBLIC *tpmPublic, TPMT_SIG_SCHEME *signatureScheme)
TSS2_RC	ifapi_get_public_from_pem_cert (const char *pem_cert, TPM2B_PUBLIC *tpm_public)
TPM2_ALG_ID	ifapi_get_signature_algorithm_from_pem (const char *pemKey)
TSS2_RC	ifapi_get_tpm2b_public_from_pem (const char *pemKey, TPM2B_PUBLIC *tpmPublic)
TSS2_RC	ifapi_get_tpm_key_fingerprint (const TPM2B_PUBLIC *tpmPublicKey, TPMI_ALG_HASH hashAlg, TPM2B_DIGEST *fingerprint)
size_t	ifapi_hash_get_digest_size (TPM2_ALG_ID hashAlgorithm)
TSS2_RC	ifapi_initialize_sign_public (TPM2_ALG_ID signatureAlgorithm, TPM2B_PUBLIC *public)
TSS2_RC	ifapi_pub_pem_key_from_tpm (const TPM2B_PUBLIC *tpmPublicKey, char **pemKey, int *pemKeySize)
TSS2_RC	ifapi_tpm_ecc_sig_to_der (const TPMT_SIGNATURE *tpmSignature, uint8_t **signature, size_t *signatureSize)
TSS2_RC	ifapi_verify_ek_cert (char *root_cert_pem, char *intermed_cert_pem, char *ek_cert_pem)
TSS2_RC	ifapi_verify_signature (const IFAPI_OBJECT *keyObject, const uint8_t *signature, size_t signatureSize, const uint8_t *digest, size_t digestSize)
TSS2_RC	ifapi_verify_signature_quote (const IFAPI_OBJECT *keyObject, const uint8_t *signature, size_t signatureSize, const uint8_t *digest, size_t digestSize, const TPMT_SIG_SCHEME *signatureScheme)

Detailed Description

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

Function Documentation

get_crl_from_cert()

TSS2_RC get_crl_from_cert	(	X509 *	cert,
		X509_CRL **	crl
	)

Get url to download crl from certificate.

Return values

TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_NO_CERT	if an error did occur during certificate downloading.

ifapi_cert_to_pem()

TSS2_RC ifapi_cert_to_pem	(	const uint8_t *	certBuffer,
		size_t	certBufferSize,
		char **	pemCert,
		TPM2_ALG_ID *	certAlgorithmId,
		TPM2B_PUBLIC *	tpmPublic
	)

Converts a TPM certificate buffer to the PEM format.

Parameters

[in]	certBuffer	A byte buffer holding the certificate
[in]	certBufferSize	The size of certBuffer in bytes
[out]	pemCert	A byte buffer where the PEM-formatted certificate is stored
[out]	certAlgorithmId	The key type of the certified key
[out]	tpmPublic	The public key of the certificate in TPM format.

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if certBuffer or pemCert is NULL
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_BAD_VALUE	if the certificate is invalid
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library

ifapi_crypto_hash_abort()

void ifapi_crypto_hash_abort

(

IFAPI_CRYPTO_CONTEXT_BLOB **

context

)

Aborts a hash operation and finalizes the hash context. It will be set to NULL.

Parameters

[in,out]

context

The context of the digest object.

ifapi_crypto_hash_finish()

TSS2_RC ifapi_crypto_hash_finish	(	IFAPI_CRYPTO_CONTEXT_BLOB **	context,
		uint8_t *	digest,
		size_t *	digestSize
	)

Gets the digest value from a hash context and closes it.

Parameters

[in,out]	context	The hash context that is released
[out]	digest	The buffer for the digest value
[out]	digestSize	The size of digest in bytes. Can be NULL

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if context or digest is NULL
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library

ifapi_crypto_hash_start()

TSS2_RC ifapi_crypto_hash_start	(	IFAPI_CRYPTO_CONTEXT_BLOB **	context,
		TPM2_ALG_ID	hashAlgorithm
	)

Starts the computation of a hash digest.

Parameters

[out]	context	The created hash context (callee-allocated).
[in]	hashAlgorithm	The TSS hash identifier for the hash algorithm to use.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_VALUE	if hashAlgorithm is invalid
TSS2_FAPI_RC_BAD_REFERENCE	if context is NULL
TSS2_FAPI_RC_MEMORY	if memory cannot be allocated
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library

ifapi_crypto_hash_update()

TSS2_RC ifapi_crypto_hash_update	(	IFAPI_CRYPTO_CONTEXT_BLOB *	context,
		const uint8_t *	buffer,
		size_t	size
	)

Updates the digest value of a hash object with data from a byte buffer.

Parameters

[in,out]	context	The hash context that will be updated
[in]	buffer	The data for the update
[in]	size	The size of data in bytes

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_REFERENCE	for invalid parameters.
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library

ifapi_der_sig_to_tpm()

TSS2_RC ifapi_der_sig_to_tpm	(	const TPMT_PUBLIC *	tpmPublic,
		const unsigned char *	signature,
		size_t	signatureSize,
		TPMI_ALG_HASH	hashAlgorithm,
		TPMT_SIGNATURE *	tpmSignature
	)

Convert signature from DER to TPM format.

The signature in DER format is converted to TPM format to enable verification by the TPM.

Parameters

[in]	tpmPublic	The public information of the signature key
[in]	signature	A byte buffer holding the DER encoded signature
[in]	signatureSize	The size of signature in bytes
[in]	hashAlgorithm	The TSS identifier for the hash algorithm used to compute the digest
[out]	tpmSignature	The signature in TPM format

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_BAD_REFERENCE	if tpmPublic, signature or tpmSignature is NULL
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.

ifapi_get_hash_alg_for_size()

TSS2_RC ifapi_get_hash_alg_for_size	(	uint16_t	size,
		TPMI_ALG_HASH *	hashAlgorithm
	)

Returns a suitable hash algorithm for a given digest size.

Parameters

[in]	size	The size of the digest
[out]	hashAlgorithm	A suitable hash algorithm for the digest size

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if hashAlgorithm is NULL
TSS2_FAPI_RC_BAD_VALUE	if the digest size is invalid

ifapi_get_profile_sig_scheme()

TPM2_RC ifapi_get_profile_sig_scheme	(	const IFAPI_PROFILE *	profile,
		const TPMT_PUBLIC *	tpmPublic,
		TPMT_SIG_SCHEME *	signatureScheme
	)

Returns the signature scheme that is currently used in the FAPI context.

Parameters

[in]	profile	The FAPI profile from which the signing scheme is retrieved
[in]	tpmPublic	The public key for which the signing key is fetched from the FAPI
[out]	signatureScheme	The currently used signature scheme

Return values

TSS2_RC_SUCCESS	if the signature scheme was successfully fetched
TSS2_FAPI_RC_BAD_REFERENCE	if one of the parameters is NULL
TSS2_FAPI_RC_BAD_VALUE	if the key type is not TPM2_ALG_RSA or TPM2_ALG_ECC

ifapi_get_public_from_pem_cert()

TSS2_RC ifapi_get_public_from_pem_cert	(	const char *	pem_cert,
		TPM2B_PUBLIC *	tpm_public
	)

Get public information for key of a pem certificate.

Parameters

[in]	pem_cert	The pem certificate.
[out]	tpm_public	The public information of the key in TPM format.

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_VALUE	if the conversion fails.
TSS2_FAPI_RC_GENERAL_FAILURE	if openssl errors occur.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.

ifapi_get_signature_algorithm_from_pem()

TPM2_ALG_ID ifapi_get_signature_algorithm_from_pem

(

const char *

pemKey

)

Returns the TPM algorithm identifier that matches to the signature algorithm of a given PEM key.

Parameters

[in]

pemKey

The public key from which the signature algorithm is retrieved

Return values

TPM2_ALG_RSA	if pemKey holds an RSA key
TPM2_ALG_ECC	if pemKey holds an ECC key
TPM2_ALG_ERROR	if the signature algorithm could not be determined
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.

ifapi_get_tpm2b_public_from_pem()

TSS2_RC ifapi_get_tpm2b_public_from_pem	(	const char *	pemKey,
		TPM2B_PUBLIC *	tpmPublic
	)

Gets an object with the TPM-relevant public information of a PEM encoded public key. The information is gathered from the key itself and the currently used FAPI profile.

Parameters

[in]	pemKey	A byte buffer holding the PEM encoded public key for which the public information is retrieved
[out]	tpmPublic	The public information of pemKey

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if profile, pemKey or tpmPublic is NULL
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.

ifapi_get_tpm_key_fingerprint()

TSS2_RC ifapi_get_tpm_key_fingerprint	(	const TPM2B_PUBLIC *	tpmPublicKey,
		TPMI_ALG_HASH	hashAlg,
		TPM2B_DIGEST *	fingerprint
	)

Compute the fingerprint of a TPM public key.

Parameters

[in]	tpmPublicKey	The public key created by the TPM
[in]	hashAlg	The hash algorithm used for fingerprint computation.
[out]	fingerprint	The fingerprint digest.

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_BAD_REFERENCE	if tpmPublicKey or pemKeySize are NULL
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.

ifapi_hash_get_digest_size()

size_t ifapi_hash_get_digest_size

(

TPM2_ALG_ID

hashAlgorithm

)

Returns the digest size of a given hash algorithm.

Parameters

[in]

hashAlgorithm

The TSS identifier of the hash algorithm

Returns

The size of the digest produced by the hash algorithm if hashAlgorithm is valid

Return values

0	if hashAlgorithm is invalid

ifapi_initialize_sign_public()

TSS2_RC ifapi_initialize_sign_public	(	TPM2_ALG_ID	signatureAlgorithm,
		TPM2B_PUBLIC *	public
	)

Initializes a FAPI key template for a given signature algorithm.

Parameters

[in]	signatureAlgorithm	The signature algorithm to use. Must be TPM2_ALG_RSA or TPM2_ALG_ECC
[out]	public	The template to initialize

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if template is NULL
TSS2_FAPI_RC_BAD_VALUE	if signatureAlgorithm is not TPM2_ALG_RSA or TPM2_ALG_ECC

ifapi_pub_pem_key_from_tpm()

TSS2_RC ifapi_pub_pem_key_from_tpm	(	const TPM2B_PUBLIC *	tpmPublicKey,
		char **	pemKey,
		int *	pemKeySize
	)

Convert a TPM public key into a PEM formatted byte buffer. This can be used by TLS libraries.

Parameters

[in]	tpmPublicKey	The public key created by the TPM
[out]	pemKey	A byte buffer that will hold the PEM representation of the public key (callee allocated)
[out]	pemKeySize	The size of pemKey in bytes

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_BAD_REFERENCE	if tpmPublicKey or pemKeySize are NULL
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.

ifapi_tpm_ecc_sig_to_der()

TSS2_RC ifapi_tpm_ecc_sig_to_der	(	const TPMT_SIGNATURE *	tpmSignature,
		uint8_t **	signature,
		size_t *	signatureSize
	)

Convert a TPM ECDSA signature into a DER formatted byte buffer. This can be used by TLS libraries.

Parameters

[in]	tpmSignature	The signature created by the TPM
[out]	signature	A byte buffer that will hold the DER representation of the signature (callee allocated)
[out]	signatureSize	The size of signature in bytes. May be NULL

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if tpmSignature is NULL
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library

ifapi_verify_ek_cert()

TSS2_RC ifapi_verify_ek_cert	(	char *	root_cert_pem,
		char *	intermed_cert_pem,
		char *	ek_cert_pem
	)

Verify EK certificate read from TPM.

Parameters

[in]	root_cert_pem	The vendor root certificate.
[in]	intermed_cert_pem	The vendor intermediate certificate.
[in]	ek_cert_pem	The ek certificate from TPM.

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_VALUE	if the verification was no successful.
TSS2_FAPI_RC_NO_CERT	if an error did occur during certificate downloading.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.

ifapi_verify_signature()

TSS2_RC ifapi_verify_signature	(	const IFAPI_OBJECT *	keyObject,
		const uint8_t *	signature,
		size_t	signatureSize,
		const uint8_t *	digest,
		size_t	digestSize
	)

Verifies a signature using a given FAPI public key.

Parameters

[in]	keyObject	The FAPI public key used for verification
[in]	signature	The signature to verify
[in]	signatureSize	The size of signature in bytes
[in]	digest	The digest of the signature
[in]	digestSize	The size of digest in bytes

Return values

TSS2_RC_SUCCESS	In case of success
TSS2_FAPI_RC_BAD_REFERENCE	if keyObject, signature or digest is NULL
TSS2_FAPI_RC_BAD_VALUE	if the type of the key is wrong
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_SIGNATURE_VERIFICATION_FAILED	if the verification of the signature fails

ifapi_verify_signature_quote()

TSS2_RC ifapi_verify_signature_quote	(	const IFAPI_OBJECT *	keyObject,
		const uint8_t *	signature,
		size_t	signatureSize,
		const uint8_t *	digest,
		size_t	digestSize,
		const TPMT_SIG_SCHEME *	signatureScheme
	)

Verifies the signature created by a Quote command.

Parameters

[in]	keyObject	A FAPI key with which the signature is verified
[in]	signature	A byte buffer holding the signature
[in]	signatureSize	The size of signature in bytes
[in]	digest	The digest of the signature
[in]	digestSize	The size of digest in bytes
[in]	signatureScheme	The signature scheme

Return values

TSS2_RC_SUCCESS	on success
TSS2_FAPI_RC_BAD_REFERENCE	if keyObject, signature, digest or signatureScheme is NULL
TSS2_FAPI_RC_MEMORY	if memory could not be allocated
TSS2_FAPI_RC_BAD_VALUE	if the PEM encoded key could not be decoded
TSS2_FAPI_RC_GENERAL_FAILURE	if an error occurs in the crypto library
TSS2_FAPI_RC_SIGNATURE_VERIFICATION_FAILED	if the verification of the signature fails