Struct tss2_fapi_rs::FapiContext

pub struct FapiContext { /* private fields */ }

Wraps the native FAPI_CONTEXT and exposes the related FAPI functions.

Each FAPI context represents a logically independent connection to the TPM. It stores meta data information about object in order to calculate session auths and similar things.

A context is allocated and initialized using the new() function, while dropping the object finalizes and de-allocates the context.

See also: FAPI_CONTEXT()

FAPI Specification

Most functions provided by FapiContext are direct equivalents of the underlying FAPI library functions.

For details, please refer to the TCG Feature API specification:
https://trustedcomputinggroup.org/wp-content/uploads/TSS_FAPI_v0p94_r09_pub.pdf

Optional Parameters

Some FAPI function have optional input parameters. These parameters are represented as Option<T> on the Rust layer and they may be set to None, if they are not needed for a certain use-case. Set to Some(value), if the parameter is actually used.

Return Values

The FAPI functions have a return type of Result<T, ErrorCode> on the Rust layer. If the underlying native FAPI invocation has succeeded, then the variant Ok(_) wrapping the actual return value(s) is returned. Otherwise, if an error has occurred, the variant Err(error) containing the relevant error code is returned. Please refer to the ErrorCode enumeration for details!

Some FAPI functions have optional return values (output parameters). On the rust layer, the call flags control whether these optional outputs shall be requested. The corresponding return values have type Option<T> and will be None if unavailable.

Thread Safety

FapiContext implements the Send trait, so it may be transferred to another thread. However, it does not implement the Sync trait! Hence, in order to share a FapiContext between multiple concurrent threads, wrapping the context in an Arc<Mutex<_>> is required. This effectively ensures that at most one thread at a time can access the “shared” FapiContext.

FAPI Library

The tss2-fapi-rs wrapper requires that the native TSS2 2.0 FAPI library, e.g. libtss2-fapi.so, is available at runtime.

Please refer to the section prerequisites in the module-level documentation for more details!

FAPI Configuration

The FAPI context implicitly uses the local FAPI configuration (e.g. fapi-config.json).

Please set the environment variable TSS2_FAPICONF before creating a new FAPI context in order to change the path of the configuration file to be used by the TSS2 2.0 FAPI library. Otherwise, FAPI will fall back to the default path!

A template for creating the FAPI configuration is provided in the tests/data directory, but a valid configuration is probably already available, if you installed the native TSS2 2.0 FAPI library via the operating system’s package manager.

FAPI Logging

FAPI logging can be controlled by the environment variable TSS2_LOG, which can be useful for debugging purposes.

Please set TSS2_LOG before creating a new FAPI context in order to change the log level of the TSS2 2.0 FAPI library. For example, set this variable to all+debug for more verbose outputs. A value of all+none will silence all debug outputs.

Implementations

impl FapiContext

pub fn new() -> Result<Self, ErrorCode>

Creates and initializes a FAPI_CONTEXT that holds all the state and metadata information during an interaction with the TPM.

See also: Fapi_Initialize()

pub fn set_auth_callback( &mut self, auth_callback: AuthCallback, ) -> Result<(), ErrorCode>

This function registers an application-defined function as a callback to allow the FAPI to request authorization values from the application. The callback is implemented via the AuthCallback struct.

See also: Fapi_SetAuthCB()

pub fn set_sign_callback( &mut self, sign_callback: SignCallback, ) -> Result<(), ErrorCode>

This function registers an application-defined function as a callback to allow the FAPI to request signatures for authorizing the use of TPM objects from the application. The callback is implemented via the SignCallback struct.

See also: Fapi_SetSignCB()

pub fn set_branch_callback( &mut self, bran_callback: BranCallback, ) -> Result<(), ErrorCode>

This function registers an application-defined function as a callback to allow the FAPI to request branch choices from the application during policy evaluation. The callback is implemented via the BranCallback struct.

See also: Fapi_SetBranchCB()

pub fn set_policy_action_callback( &mut self, actn_callback: ActnCallback, ) -> Result<(), ErrorCode>

This function registers an application-defined function as a callback to allow the FAPI to notify the application about policy actions. The callback is implemented via the ActnCallback struct.

See also: Fapi_SetPolicyActionCB()

pub fn provision( &mut self, auth_eh: Option<&str>, auth_sh: Option<&str>, auth_lo: Option<&str>, ) -> Result<(), ErrorCode>

Provisions a TSS with its TPM. This includes the setting of important passwords and policy settings as well as the readout of the EK and its certificate and the initialization of the system-wide keystore.

See also: Fapi_Provision()

pub fn get_info(&mut self) -> Result<JsonValue, ErrorCode>

Returns a JSON value that identifies the versions of FAPI, TPM, configurations and other relevant information.

See also: Fapi_GetInfo()

pub fn get_random(&mut self, length: NonZeroUsize) -> Result<Vec<u8>, ErrorCode>

Creates an array with a specified number of bytes. May execute the underlying TPM command multiple times if the requested number of bytes is too big.

See also: Fapi_GetRandom()

pub fn create_key( &mut self, key_path: &str, key_type: Option<&[KeyFlags]>, pol_path: Option<&str>, auth_val: Option<&str>, ) -> Result<(), ErrorCode>

Creates a key inside the TPM based on the Key type, using the supplied policy and authValue. The key is then stored either in the FAPI metadata store or the TPM.

See also: Fapi_CreateKey()

pub fn import(&mut self, path: &str, data: &JsonValue) -> Result<(), ErrorCode>

Imports a JSON encoded policy, policy template or key and stores it at the given path.

See also: Fapi_Import()

pub fn export_key( &mut self, key_to_duplicate: &str, new_parent_public_key: Option<&str>, ) -> Result<JsonValue, ErrorCode>

Duplicates the key pointed to by key_to_duplicate, inclduing all keys below it, and encrypts it using the public key pointed to by new_parent_public_key. The exported data will contain the re-wrapped key and then the JSON encoded policy.

If the parameter new_parent_public_key is None, then the public key pointed to by key_to_duplicate will be exported.

See also: Fapi_ExportKey()

pub fn export_policy(&mut self, path: &str) -> Result<JsonValue, ErrorCode>

Exports a policy to a JSON encoded byte buffer.

See also: Fapi_ExportPolicy()

pub fn get_tpm_blobs( &mut self, key_path: &str, get_pubkey: bool, get_privkey: bool, get_policy: bool, ) -> Result<(Option<Vec<u8>>, Option<Vec<u8>>, Option<JsonValue>), ErrorCode>

Get the public and private BLOBs of a TPM object. They can be loaded with a lower-level API such as the SAPI or the ESAPI.

The flags get_pubkey, get_privkey and get_policy control which BLOBs are requested. Even if a BLOB was requested, that BLOB may not be available, in which case a None value is returned.

See also: Fapi_GetTpmBlobs()

Return Value

(Option(public_key), Option(private_key), Option(policy))

pub fn get_esys_blob( &mut self, path: &str, ) -> Result<(BlobType, Vec<u8>), ErrorCode>

Gets blobs of FAPI objects which can be used to create ESAPI objects.

See also: Fapi_GetEsysBlob()

pub fn create_nv( &mut self, nv_path: &str, nvi_type: Option<&[NvFlags]>, nvi_size: usize, pol_path: Option<&str>, auth_val: Option<&str>, ) -> Result<(), ErrorCode>

This command creates an NV index in the TPM using a given path and type.

See also: Fapi_CreateNv()

pub fn nv_read( &mut self, nv_path: &str, request_log: bool, ) -> Result<(Vec<u8>, Option<JsonValue>), ErrorCode>

Reads data from an NV index within the TPM.

The flag request_log controls whether the log data shall be requested, if the NV index was created as “pcr” type.

See also: Fapi_NvRead()

Return Value

(nv_data, Option(log_data))

pub fn nv_read_u64(&mut self, nv_path: &str) -> Result<u64, ErrorCode>

Convenience function to nv_read() an u64 value. Assumes “big endian” byte order.

See also: Fapi_NvRead()

pub fn nv_write(&mut self, nv_path: &str, data: &[u8]) -> Result<(), ErrorCode>

Writes data to an “ordinary” (i.e not pin, extend or counter) NV index.

See also: Fapi_NvWrite()

pub fn nv_write_u64( &mut self, nv_path: &str, value: u64, ) -> Result<(), ErrorCode>

Convenience function to nv_write() an u64 value. Assumes “big endian” byte order.

See also: Fapi_NvWrite()

pub fn nv_increment(&mut self, nv_path: &str) -> Result<(), ErrorCode>

Increments an NV index that is a counter by 1.

See also: Fapi_NvIncrement()

pub fn nv_set_bits( &mut self, nv_path: &str, bitmap: u64, ) -> Result<(), ErrorCode>

Sets bits in an NV index that was created as a bit field. Any number of bits from 0 to 64 may be SET.

See also: Fapi_NvSetBits()

pub fn nv_extend( &mut self, nv_path: &str, data: &[u8], log_data: Option<&JsonValue>, ) -> Result<(), ErrorCode>

Performs an extend operation on an NV index that was created as “pcr” type.

See also: Fapi_NvExtend()

pub fn write_authorize_nv( &mut self, nv_path: &str, pol_path: &str, ) -> Result<(), ErrorCode>

Write the policyDigest of a policy to an NV index so it can be used in policies containing PolicyAuthorizeNV elements.

See also: Fapi_WriteAuthorizeNv()

pub fn pcr_extend( &mut self, pcr_no: u32, data: &[u8], log_data: Option<&str>, ) -> Result<(), ErrorCode>

Performs an extend operation on a given PCR.

See also: Fapi_PcrExtend()

pub fn pcr_read( &mut self, pcr_no: u32, request_log: bool, ) -> Result<(Vec<u8>, Option<JsonValue>), ErrorCode>

Reads from a given PCR and returns the value and the event log.

The flags request_log controls whether a PCR log shall be requested too.

See also: Fapi_PcrRead()

Return Value

(pcr_value, Option(prc_log))

pub fn quote( &mut self, pcr_no: &[u32], quote_type: Option<&[QuoteFlags]>, key_path: &str, qualifying_data: Option<&[u8]>, request_log: bool, request_cert: bool, ) -> Result<(JsonValue, Vec<u8>, Option<JsonValue>, Option<String>), ErrorCode>

Given a set of PCRs and a restricted signing key, it will sign those PCRs and return the quote.

The optional qualifying_data is a nonce provided by the caller to ensure freshness of the signature.

The flags request_log and request_cert control whether to request PCR log and/or certificate. Even if requested, a signer certificate may not be available, in which case a None value is returned.

See also: Fapi_Quote()

Return Value

(quote_info, signature, Option(prc_log), Option(certificate))

pub fn verify_quote( &mut self, key_path: &str, qualifying_data: Option<&[u8]>, quote_info: &JsonValue, signature: &[u8], prc_log: Option<&JsonValue>, ) -> Result<bool, ErrorCode>

Verifies that the data returned by a quote is valid. This includes:

• Reconstructing the quote_info’s PCR values from the prc_log (if a prc_log was provided)
• Verifying the quote_info using the signature and the public key at key_path

See also: Fapi_VerifyQuote()

pub fn encrypt( &mut self, key_path: &str, plaintext: &[u8], ) -> Result<Vec<u8>, ErrorCode>

Encrypt the provided data for the target key using the TPM encryption schemes as specified in the crypto profile. This function does not use the TPM; i.e. works in non-TPM mode.

See also: Fapi_Encrypt()

pub fn decrypt( &mut self, key_path: &str, ciphertext: &[u8], ) -> Result<Vec<u8>, ErrorCode>

Decrypts data that was previously encrypted with encrypt().

See also: Fapi_Decrypt()

pub fn sign( &mut self, key_path: &str, pad_algo: Option<&[PaddingFlags]>, digest: &[u8], get_pubkey: bool, get_cert: bool, ) -> Result<(Vec<u8>, Option<String>, Option<String>), ErrorCode>

Uses a key, identified by its path, to sign a digest and puts the result in a TPM2B bytestream.

The flags get_pubkey and get_cert control whether the signer’s public key and/or the signer certificate shall be returned. If requested, a signer certificate may not be available, in which case a None value is returned.

Note that this function can not sign the “plain” message! Use, e.g., the sha2 crate for computing the digest to be signed!

See also: Fapi_Sign()

Return Value

(signature_value, Option(public_key), Option(certificate))

pub fn verify_signature( &mut self, key_path: &str, digest: &[u8], signature: &[u8], ) -> Result<bool, ErrorCode>

Verifies a signature using a public key found in a keyPath.

Returns Ok(true) if the signature is valid, Ok(false) if the signature is invalid (or malformed), and Err(_) if an error other than the signature value being invalid (or malformed) occurred during the verification process.

See also: Fapi_VerifySignature()

pub fn create_seal( &mut self, path: &str, seal_type: Option<&[SealFlags]>, seal_size: NonZeroUsize, pol_path: Option<&str>, auth_val: Option<&str>, data: Option<&[u8]>, ) -> Result<(), ErrorCode>

Creates a sealed object and stores it in the FAPI metadata store. If no data is provided, the TPM generates random data to fill the sealed object.

See also: Fapi_CreateSeal()

pub fn unseal(&mut self, path: &str) -> Result<Vec<u8>, ErrorCode>

Unseals data from a seal in the FAPI metadata store.

See also: Fapi_Unseal()

pub fn get_certificate( &mut self, path: &str, ) -> Result<Option<String>, ErrorCode>

Gets an x.509 certificate for the key at a given path.

See also: Fapi_GetCertificate()

pub fn set_certificate( &mut self, path: &str, cert_data: Option<&str>, ) -> Result<(), ErrorCode>

Sets an x509 cert into the path of a key.

If the parameter cert_data is None, then an existing certificate will be removed from the entity.

See also: Fapi_SetCertificate()

pub fn get_platform_certificates( &mut self, ) -> Result<Option<Vec<u8>>, ErrorCode>

Returns the set of Platform certificates concatenated in a continuous buffer, if the platform provides platform certificates. Platform certificates for TPM 2.0 can consist not only of a single certificate but also a series of so-called delta certificates.

See also: Fapi_GetPlatformCertificates()

pub fn get_description( &mut self, path: &str, ) -> Result<Option<String>, ErrorCode>

Returns the description of a previously stored object.

See also: Fapi_GetDescription()

pub fn set_description( &mut self, path: &str, description: Option<&str>, ) -> Result<(), ErrorCode>

Allows an application to assign a human readable description to an object in the metadata store.

If the parameter description is None, then any stored description assigned to the referenced object is deleted.

See also: Fapi_SetDescription()

pub fn get_app_data(&mut self, path: &str) -> Result<Option<Vec<u8>>, ErrorCode>

Returns the previously stored application data for an object.

See also: Fapi_GetAppData()

pub fn set_app_data( &mut self, path: &str, app_data: Option<&[u8]>, ) -> Result<(), ErrorCode>

Associates an arbitrary data blob with a given object.

If the parameter app_data is None, then the stored data for the referenced object is erased.

See also: Fapi_SetAppData()

pub fn list(&mut self, path: &str) -> Result<Vec<String>, ErrorCode>

Enumerates all objects in the metadatastore in a given path and returns them in a list of complete paths.

See also: Fapi_List()

pub fn delete(&mut self, path: &str) -> Result<(), ErrorCode>

Deletes a given key, policy or NV index from the system.

See also: Fapi_Delete()

pub fn change_auth( &mut self, path: &str, auth: Option<&str>, ) -> Result<(), ErrorCode>

Changes the authorization data of an entity found at key path. The parameter auth is a 0-terminated UTF-8 encoded password. If it is longer than the digest size of the entity’s nameAlg, it will be hashed according the the TPM specification part 1, rev 138, section 19.6.4.3.

If authValue is NULL then thep assword is set to the empty string.

See also: Fapi_ChangeAuth()

pub fn authorize_policy( &mut self, pol_path: &str, key_path: &str, ref_data: Option<&[u8]>, ) -> Result<(), ErrorCode>

If a current policy happens to be a PolicyAuthorize, then for it to be used, the user must first satisfy a policy authorized by a having been signed (and made into a ticket) by an authorized party.

See also: Fapi_AuthorizePolicy()

pub fn get_tcti(&mut self) -> Result<*mut [u8; 0], ErrorCode>

Returns the TSS2_TCTI_CONTEXT currently used by this FAPI_CONTEXT. The purpose is to enable advanced access to the TPM that is currently being talked to.

See also: Fapi_GetTcti()

pub fn get_poll_handles(&mut self) -> Result<Vec<()>, ErrorCode>

Returns an array of handles that can be polled on to get notified when data from the TPM or from a disk operation is available.

See also: Fapi_GetPollHandles()

This functions is a stub. Currently, Fapi_GetPollHandles() is not implemented in the Rust wrapper library!

Trait Implementations

impl Debug for FapiContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FapiContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.