Internal Cryptographic Backend
Feature API » Internals of Feature API

## Functions

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_curl_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

## 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_curl_verify_ek_cert()

TSS2_RC ifapi_curl_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_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_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