FAPI

class tpm2_pytss.FAPI(uri=None)[source]

The TPM2 Feature API. This class can be used as a python context or be closed manually via close().

authorize_policy(policy_path, key_path, policy_ref=None)[source]

Specify the underlying policy/policies for a policy Authorize.

Parameters:

  • policy_path (bytes or str) – Path to the underlying policy.

  • key_path (bytes or str) – Path to the key associated with the policy Authorize.

  • policy_ref (bytes or str) – Additional application data (e.g. a reference to another policy). Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

change_auth(path, auth_value=None)[source]

Change the password to a Fapi object.

Parameters:

  • path (bytes or str) – Path to the Fapi object.

  • auth_value (bytes or str) – New password. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

close()[source]

Finalize the Feature API. This frees allocated memory and invalidates the FAPI object.

property config
create_key(path, type_=None, policy_path=None, auth_value=None, exists_ok=False)[source]

Create a cryptographic key inside the TPM.

Parameters:

  • path (bytes or str) – Path to the new key object, e.g. /HS/SRK/new_signing_key.

  • type (bytes or str) – Comma separated list. Possible values: system, sign, decrypt, restricted, exportable, noda, 0x81000000. Defaults to None.

  • auth_value (bytes or str) – Password to key. Defaults to None.

  • exists_ok (bool) – Do not throw a TSS2_Exception if an object with the given path already exists. Defaults to False.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

True if the key was created. False otherwise.

Return type:

bool

create_nv(path, size, type_=None, policy_path=None, auth_value=None)[source]

Create non-volatile (NV) storage on the TPM.

Parameters:

  • path (bytes or str) – Path to the NV storage area.

  • size (int) – Size of the storage area in bytes.

  • type (bytes or str) – Type of the storage area. A combination of bitfield, counter, pcr, system, noda. Defaults to None.

  • policy_path (bytes or str) – The path to the policy which will be associated with the storage area. Defaults to None.

  • auth_value (bytes or str) – Password to protect the new storage area. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

create_seal(path, data=None, type_=None, policy_path=None, auth_value=None, size=None, exists_ok=False)[source]

Create a Fapi sealed (= encrypted) object, that is data sealed a Fapi parent key. Oftentimes, the data is a digest.

Parameters:

  • path (bytes or str) – The path of the new sealed object.

  • data (bytes or str) – Data to be sealed (often a digest). If None, random data will be generated. Defaults to None.

  • type (bytes or str) – Comma separated list. Possible values: system, sign, decrypt, restricted, exportable, noda, 0x81000000. Defaults to None.

  • policy_path (bytes or str) – The path to the policy which will be associated with the sealed object. Defaults to None.

  • auth_value (bytes or str) – Password to protect the new sealed object. Defaults to None.

  • size (int) – If data is None, random bytes of length size are generated. Parameters data and size cannot be given at the same time. Defaults to None.

  • exists_ok (bool) – Do not throw a TSS2_Exception if an object with the given path already exists. Defaults to False.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

True if the sealed object was created. False otherwise.

Return type:

bool

decrypt(path, ciphertext)[source]

Decrypt the ciphertext and return the plaintext.

Parameters:

  • path (bytes or str) – The decrypt key used for decryption.

  • ciphertext (bytes or str) – The data to be decrypted.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The plaintext.

Return type:

bytes

delete(path)[source]

Delete Fapi object.

Parameters:

path (bytes or str) – Path to the Fapi object to delete.

Raises:

TSS2_Exception – If Fapi returned an error code.

encrypt(path, plaintext)[source]

Encrypt the plaintext and return the ciphertext.

Parameters:

  • path (bytes or str) – The decrypt key used for encryption.

  • plaintext (bytes or str) – The data to be encrypted.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The ciphertext.

Return type:

bytes

export_key(path, new_path=None)[source]

Export a Fapi object as a JSON-encoded string.

Parameters:

  • path (bytes or str) – Path to the existing Fapi object.

  • new_path (bytes or str) – New path to the Fapi object. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The exported data.

Return type:

str

export_policy(path)[source]

Export a policy from the key store as a JSON-encoded string.

Parameters:

path (bytes or str) – Path to the FAPI policy.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

JSON-encoded policy.

Return type:

str

get_app_data(path)[source]

Get the custom application data of a Fapi object.

Parameters:

path (bytes or str) – Path to the Fapi object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The application data or None.

Return type:

Optional[bytes]

get_certificate(path)[source]

Get the custom application data of a Fapi object.

Parameters:

path (bytes or str) – Path to the Fapi object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The application data.

Return type:

bytes

get_description(path=None)[source]

Get the description of a Fapi object.

Parameters:

path (bytes or str) – Path to the Fapi object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The description of the Fapi object.

Return type:

str

get_esys_blob(path)[source]

Return the ESAPI binary blob associated with a Fapi object.

This blob can be easily loaded with load_blob().

Parameters:

path (bytes or str) – Path to the Fapi object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

A tuple of the binary blob and its type (constants.FAPI_ESYSBLOB.CONTEXTLOAD or constants.FAPI_ESYSBLOB.DESERIALIZE)

Return type:

Tuple[bytes, Any]

get_info()[source]

Get Fapi information, containing library info, TPM capabilities and more.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

JSON-encoded info string.

Return type:

str

get_platform_certificates(no_cert_ok=False)[source]

Get the platform certificate and the so-called delta certificates.

Parameters:

no_cert_ok (bool) – If True, an empty byte string is returned if no certificate is found. If False, in this case a TSS2_Exception is raised. Defaults to False.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The platform certificates

Return type:

bytes

get_random(num_bytes)[source]

Get true random bytes, generated by the TPM.

Parameters:

num_bytes (int) – Number of bytes to generate.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The random bytes.

Return type:

bytes

get_tpm_blobs(path)[source]

Get the TPM data blobs and the policy associates with a Fapi object.

Parameters:

path (bytes or str) – Path to the Fapi object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

(tpm_2b_public, tpm_2b_private, policy)

Return type:

Tuple[TPM2B_PUBLIC, TPM2B_PRIVATE, str]

import_object(path, import_data, exists_ok=False)[source]

Import policy, policy template or key into the keystore.

Parameters:

  • path (bytes or str) – Path of the future Fapi object.

  • import_data (bytes or str) – JSON-encoded data to import.

  • exists_ok (bool) – Do not throw a TSS2_Exception if an object with the given path already exists. Defaults to False.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

True if the object was imported. False otherwise.

Return type:

bool

list(search_path=None)[source]

Get a list of all Fapi current object paths.

Parameters:

search_path (bytes or str) – If given, only list children of search_path. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

List of all current Fapi object paths.

Return type:

List[str]

nv_extend(path, data, log=None)[source]

Perform an extend operation on a non-volatile TPM storage area. Requires an NV object of type pcr. For more information on the extend operation, see pcr_extend().

Parameters:

  • path (bytes or str) – Path to the NV storage area.

  • data (bytes or str) – Input data to the extend operation.

  • log (bytes or str) – JSON-encoded event to be associated with this change. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

nv_increment(path)[source]

Increment the counter value stored in non-volatile (NV) TPM storage.

Parameters:

path (bytes or str) – Path to the NV storage area.

Raises:

TSS2_Exception – If Fapi returned an error code.

nv_read(path)[source]

Read from non-volatile (NV) TPM storage.

Parameters:

path (bytes or str) – Path to the NV storage area.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

Data stored in the NV storage area and its associated event log.

Return type:

Tuple[bytes, str]

nv_set_bits(path, bitmap)[source]

Set bits of bitfielad, stored in non-volatile (NV) TPM storage.

Parameters:

  • path (bytes or str) – Path to the NV storage area.

  • bitmap (int) – Bits to set in the NV storage area.

Raises:

TSS2_Exception – If Fapi returned an error code.

nv_write(path, data)[source]

Write data to a non-volatile (NV) TPM storage and the associated event log.

Parameters:

  • path (bytes or str) – Path to the NV storage area.

  • data (bytes or str) – Data to write to the NV storage area.

Raises:

TSS2_Exception – If Fapi returned an error code.

pcr_extend(index, data, log=None)[source]

Extend the value of a TPM Platform Configuration Register (PCR). The data given by the user and the previous PCR value are hashed together. The resulting digest is stored as the new PCR value. As a result, a PCR value depends on every piece of data given via the extend command (until the PCR is reset).

Parameters:

  • index (int) – Index of the PCR (in the range of 0-23 in most cases).

  • data (bytes or str) – Input data to the extend operation.

  • log (bytes or str) – JSON-encoded event log data. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

PCR value and its associated event log.

Return type:

Tuple[bytes, str]

pcr_read(index)[source]

Read the value of a TPM Platform Configuration Register (PCR) and its associated event log.

Parameters:

index (int) – Index of the PCR (in the range of 0-23 in most cases).

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

(pcr_value, event_log)

Return type:

Tuple[bytes, str]

provision(auth_value_eh=None, auth_value_sh=None, auth_value_lockout=None, is_provisioned_ok=True)[source]

Provision the Feature API. Creates the keystore and creates some TPM objects. See also config file /etc/tpm2-tss/fapi-config.json.

Parameters:

  • auth_value_eh (bytes or str) – Endorsement Hierarchy password. Defaults to None.

  • auth_value_sh (bytes or str) – Storage/Owner Hierarchy password. Defaults to None.

  • auth_value_lockout (bytes or str) – Lockout Hierarchy password. Defaults to None.

  • is_provisioned_ok (bool) – Do not throw a TSS2_Exception if Fapi is already provisioned. Defaults to True.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

True if Fapi was provisioned, False otherwise.

Return type:

bool

quote(path, pcrs, quote_type=None, qualifying_data=None)[source]

Create a TPM quote, that is a signed data structure of the TPM Platform Configuration Registers (PCRs), reset count, firmware version and more.

Parameters:

  • path (bytes or str) – Path to the key used for signing.

  • pcrs (List[int]) – List of PCR indices to be included in the quote.

  • quote_type (bytes or str) – Type of quote to create. The default “TPM-Quote” is used if None is given. Defaults to None.

  • qualifying_data (bytes or str) – Additional application-defined data. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

info, signature, pcr_log, certificate

Return type:

Tuple[str, bytes, str, str]

set_app_data(path, app_data=None)[source]

Add custom application data to a Fapi object. This data is saved alongside the object and can be used by the application.

Parameters:

  • path (bytes or str) – Path to the Fapi object.

  • app_data (bytes or str) – Custom application data to be associated with the Fapi object. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

set_auth_callback(callback=None, user_data=None)[source]

Register a callback that provides the password for Fapi objects when needed. Typically, this callback implements a password prompt. If callback is None, the callback function is reset.

Parameters:

  • callback (Optional[Callable[[str, str, Optional[Any]], Union[bytes, str]]]) – A callback function callback(path, description, user_data=None) which returns the password (str). Defaults to None.

  • user_data (Any) – Bytes that will be handed to the callback. Defaults to None.

Raises:
set_branch_callback(callback=None, user_data=None)[source]

Set the Fapi policy branch callback, called to decide which policy path to take in a policy Or. If callback is None, the callback function is reset.

Parameters:

  • callback (Callable[[str, str, List[str], Optional[bytes]], int]) – A callback function callback(path, description, branch_names, user_data=None) which returns the index (int) of the selected branch in branch_names. Defaults to None.

  • user_data (bytes or str) – Custom data passed to the callback function. Defaults to None.

Raises:
set_certificate(path, certificate=None)[source]

Add x509 certificate to a Fapi object. This data is saved alongside the object and can be used by the application.

Parameters:

  • path (bytes or str) – Path to the Fapi object.

  • certificate (bytes or str) – x509 certificate to be associated with the Fapi object. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

set_description(path, description=None)[source]

Set the description of a Fapi object.

Parameters:

  • path (bytes or str) – Path to the Fapi object.

  • description (bytes or str) – New description of the Fapi object. Defaults to None.

Raises:

TSS2_Exception – If Fapi returned an error code.

set_policy_action_callback(callback=None, user_data=None)[source]

Set the policy Action callback which is called to satisfy the policy Action. If callback is None, the callback function is reset.

Parameters:

  • callback (Callable[[str, str, Optional[bytes]], None]) – A callback function callback(path, action, user_data=None). Defaults to None.

  • user_data (Any) – Custom data passed to the callback function. Defaults to None.

Raises:
set_sign_callback(callback=None, user_data=None)[source]

Set the Fapi signing callback which is called to satisfy the policy Signed. If callback is None, the callback function is reset.

Parameters:

  • callback (Callable[[str, str, str, str, int, bytes, Optional[bytes]], bytes]) – A callback function callback(path, description, public_key, public_key_hint, hash_alg, data_to_sign, user_data=None) which returns a signature (bytes) of data_to_sign. Defaults to None.

  • user_data (Any) – Custom data passed to the callback function. Defaults to None.

Raises:
sign(path, digest, padding=None)[source]

Create a signature over a given digest.

Parameters:

  • path (bytes or str) – Path to the signing key.

  • digest (bytes) – Digest to sign.

  • padding (bytes or str) – “rsa_ssa” or “rsa_pss”. Defaults to None (using the scheme specified in the crypto profile).

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

(signature (DER), public key (PEM), certificate (PEM))

Return type:

Tuple[bytes, str, str]

property tcti
unseal(path)[source]

Unseal a sealed (= encrypted) Fapi object and return the data in plaintext.

Parameters:

path (Union[bytes, str]) – The path to the sealed object.

Raises:

TSS2_Exception – If Fapi returned an error code.

Returns:

The unsealed data in plaintext.

Return type:

bytes

verify_quote(path, signature, quote_info, qualifying_data=None, pcr_log=None)[source]

Verify the signature to a TPM quote.

Parameters:

  • path (bytes or str) – Path to the key used for verifying the signature.

  • signature (bytes) – Signature to the quote.

  • quote_info (bytes or str) – Quote info structure.

  • qualifying_data (bytes or str) – Additional application-defined data. Defaults to None.

  • pcr_log (bytes or str) – JSON-encoded PCR log entry.

Raises:

TSS2_Exception – If Fapi returned an error code.

verify_signature(path, digest, signature)[source]

Verify a signature on a given digest.

Parameters:

  • path (bytes or str) – Path to the signing key.

  • digest (bytes) – Digest which was signed.

  • signature (bytes) – Signature to be verified.

Raises:

TSS2_Exception – If Fapi returned an error code, e.g. if the signature cannot be verified successfully.

property version

Get the tpm2-tss library version.

Returns:

The Feature API C context.

Return type:

str

write_authorize_nv(nv_path, policy_path)[source]

Write a policy to non-volatile (NV) TPM storage.

Parameters:

  • nv_path (bytes or str) – Path to the NV storage area.

  • policy_path (bytes or str) – Path to the policy to be written.

Raises:

TSS2_Exception – If Fapi returned an error code.