Struct tss_esapi::Context

pub struct Context { /* fields omitted */ }

Safe abstraction over an ESYS_CONTEXT.

Serves as a low-level abstraction interface to the TPM, providing a thin wrapper around the unsafe FFI calls. It is meant for more advanced uses of the TSS where control over all parameters is necessary or important.

The methods it exposes take the parameters advertised by the specification, with some of the parameters being passed as generated by bindgen and others in a more convenient/Rust-efficient way.

The context also keeps track of all object allocated and deallocated through it and, before being dropped, will attempt to close all outstanding handles. However, care must be taken by the client to not exceed the maximum number of slots available from the RM.

Code safety-wise, the methods should cover the two kinds of problems that might arise:

• in terms of memory safety, all parameters passed down to the TSS are verified and the library stack is then trusted to provide back valid outputs
• in terms of thread safety, all methods require a mutable reference to the context object, ensuring that no two threads can use the context at the same time for an operation (barring use of unsafe constructs on the client side) More testing and verification will be added to ensure this.

For most methods, if the wrapped TSS call fails and returns a non-zero TPM2_RC, a corresponding Tss2ResponseCode will be created and returned as an Error. Wherever this is not the case or additional error types can be returned, the method definition should mention it.

Implementations

impl Context

pub unsafe fn new(tcti: Tcti) -> Result<Self>

Create a new ESYS context based on the desired TCTI

Safety

• the client is responsible for ensuring that the context can be initialized safely, threading-wise

Errors

• if either Tss2_TctiLdr_Initiialize or Esys_Initialize fail, a corresponding Tss2ResponseCode will be returned

pub fn start_auth_session(
    &mut self,
    tpm_key: ESYS_TR,
    bind: ESYS_TR,
    nonce: Option<&Nonce>,
    session_type: TPM2_SE,
    symmetric: TPMT_SYM_DEF,
    auth_hash: TPMI_ALG_HASH
) -> Result<ESYS_TR>

Start new authentication session and return the handle.

The caller nonce is passed as a slice and converted by the method in a TSS digest structure.

Constraints

• nonce must be at most 64 elements long

Errors

• if the nonce is larger than allowed, a WrongSizeParam wrapper error is returned

pub fn set_sessions(&mut self, session_handles: (ESYS_TR, ESYS_TR, ESYS_TR))

pub fn sessions(&self) -> (ESYS_TR, ESYS_TR, ESYS_TR)

pub fn get_capabilities(
    &mut self,
    capability: TPM2_CAP,
    property: u32,
    property_count: u32
) -> Result<(TPMS_CAPABILITY_DATA, bool)>

Get current capability information about the TPM.

pub fn create_primary_key(
    &mut self,
    primary_handle: ESYS_TR,
    public: &TPM2B_PUBLIC,
    auth_value: Option<&Auth>,
    initial_data: Option<&SensitiveData>,
    outside_info: Option<&Data>,
    creation_pcrs: &[TPMS_PCR_SELECTION]
) -> Result<ESYS_TR>

Create a primary key and return the handle.

The authentication value, initial data, outside info and creation PCRs are passed as slices which are then converted by the method into TSS native structures.

Constraints

• outside_info must be at most 64 elements long
• creation_pcrs must be at most 16 elements long
• auth_value must be at most 64 elements long
• initial_data must be at most 256 elements long

Errors

• if either of the slices is larger than the maximum size of the native objects, a WrongParamSize wrapper error is returned

pub fn create_key(
    &mut self,
    parent_handle: ESYS_TR,
    public: &TPM2B_PUBLIC,
    auth_value: Option<&Auth>,
    initial_data: Option<&SensitiveData>,
    outside_info: Option<&Data>,
    creation_pcrs: &[TPMS_PCR_SELECTION]
) -> Result<(TPM2B_PRIVATE, TPM2B_PUBLIC)>

Create a key and return the handle.

The authentication value, initial data, outside info and creation PCRs are passed as slices which are then converted by the method into TSS native structures.

Constraints

• outside_info must be at most 64 elements long
• creation_pcrs must be at most 16 elements long
• auth_value must be at most 64 elements long
• initial_data must be at most 256 elements long

Errors

• if either of the slices is larger than the maximum size of the native objects, a WrongParamSize wrapper error is returned

pub fn unseal(&mut self, item_handle: ESYS_TR) -> Result<SensitiveData>

Unseal and return data from a Sealed Data Object

pub fn load(
    &mut self,
    parent_handle: ESYS_TR,
    private: TPM2B_PRIVATE,
    public: TPM2B_PUBLIC
) -> Result<ESYS_TR>

Load a previously generated key back into the TPM and return its new handle.

pub fn sign(
    &mut self,
    key_handle: ESYS_TR,
    digest: &Digest,
    scheme: TPMT_SIG_SCHEME,
    validation: &TPMT_TK_HASHCHECK
) -> Result<Signature>

Sign a digest with a key present in the TPM and return the signature.

The digest is passed as a slice, converted by the method to a TSS digest structure.

Constraints

• digest must be at most 64 elements long

Errors

• if the digest provided is too long, a WrongParamSize wrapper error will be returned

pub fn verify_signature(
    &mut self,
    key_handle: ESYS_TR,
    digest: &Digest,
    signature: &TPMT_SIGNATURE
) -> Result<TPMT_TK_VERIFIED>

Verify if a signature was generated by signing a given digest with a key in the TPM.

The digest is passed as a sliice and converted by the method to a TSS digest structure.

Constraints

• digest must be at most 64 elements long

Errors

• if the digest provided is too long, a WrongParamSize wrapper error will be returned

pub fn rsa_encrypt(
    &mut self,
    key_handle: ESYS_TR,
    message: PublicKeyRSA,
    in_scheme: &TPMT_RSA_DECRYPT,
    label: Data
) -> Result<PublicKeyRSA>

Perform an asymmetric RSA encryption.

pub fn rsa_decrypt(
    &mut self,
    key_handle: ESYS_TR,
    cipher_text: PublicKeyRSA,
    in_scheme: &TPMT_RSA_DECRYPT,
    label: Data
) -> Result<PublicKeyRSA>

Perform an asymmetric RSA decryption.

pub fn load_external(
    &mut self,
    private: &TPM2B_SENSITIVE,
    public: &TPM2B_PUBLIC,
    hierarchy: Hierarchy
) -> Result<ESYS_TR>

Load an external key into the TPM and return its new handle.

pub fn load_external_public(
    &mut self,
    public: &TPM2B_PUBLIC,
    hierarchy: Hierarchy
) -> Result<ESYS_TR>

Load the public part of an external key and return its new handle.

pub fn read_public(&mut self, key_handle: ESYS_TR) -> Result<TPM2B_PUBLIC>

Read the public part of a key currently in the TPM and return it.

pub fn flush_context(&mut self, handle: ESYS_TR) -> Result<()>

Flush the context of an object from the TPM.

pub fn context_save(&mut self, handle: ESYS_TR) -> Result<TpmsContext>

Save the context of an object from the TPM and return it.

Errors

• if conversion from TPMS_CONTEXT to TpmsContext fails, a WrongParamSize error will be returned

pub fn context_load(&mut self, context: TpmsContext) -> Result<ESYS_TR>

Load a previously saved context into the TPM and return the object handle.

Errors

• if conversion from TpmsContext to the native TPMS_CONTEXT fails, a WrongParamSize error will be returned

pub fn pcr_read(
    &mut self,
    pcr_selection_list: &PcrSelectionList
) -> Result<(u32, PcrSelectionList, PcrData)>

Reads the value of a PCR slot associated with a specific hashing algorithm

Constraints

• If the selection contains more pcr values then 16 (number of elements in TPML_DIGEST). Then not all values will be read. The Selection in the return value will indicate what values that have been read.

Errors

• Several different errors can occur if conversion of return data fails.

pub fn quote(
    &mut self,
    signing_key_handle: ESYS_TR,
    qualifying_data: &Data,
    signing_scheme: TPMT_SIG_SCHEME,
    pcr_selection_list: PcrSelectionList
) -> Result<(TPM2B_ATTEST, Signature)>

Generate a quote on the selected PCRs

Constraints

• qualifying_data must be at most 64 elements long

Errors

• if the qualifying data provided is too long, a WrongParamSize wrapper error will be returned

pub fn policy_pcr(
    &mut self,
    policy_session: ESYS_TR,
    pcr_policy_digest: &Digest,
    pcr_selection_list: PcrSelectionList
) -> Result<()>

Cause conditional gating of a policy based on PCR.

The TPM will use the hash algorithm of the policy_session to calculate a digest from the values of the pcr slots specified in the pcr_selections. This is then compared to pcr_policy_digest if they match then the policyDigest of the policy session is extended.

Constraints

• pcr_policy_digest must be at most 64 elements long

Errors

• if the pcr policy digest provided is too long, a WrongParamSize wrapper error will be returned

See: "Trusted Platform Module Library", "Part 3: Commands" "Family “2.0” Level 00 Revision 01.59 Section: 23.7 TPM2_PolicyPCR

pub fn policy_or(
    &mut self,
    policy_session: ESYS_TR,
    digest_list: DigestList
) -> Result<()>

Cause conditional gating of a policy based on an OR'd condition.

The TPM will ensure that the current policy digest equals at least one of the digests. If this is the case, the policyDigest of the policy session is replaced by the value of the different hashes.

Constraints

• hash_list must be at least 2 and at most 8 elements long

Errors

• if the hash list provided is too short or too long, a WrongParamSize wrapper error will be returned

pub fn policy_locality(
    &mut self,
    policy_session: ESYS_TR,
    locality: TPMA_LOCALITY
) -> Result<()>

Cause conditional gating of a policy based on locality.

The TPM will ensure that the current policy can only complete in the specified locality (extended) or any of the specified localities (non-extended).

pub fn policy_command_code(
    &mut self,
    policy_session: ESYS_TR,
    code: TPM2_CC
) -> Result<()>

Cause conditional gating of a policy based on command code of authorized command.

The TPM will ensure that the current policy can only be used to complete the command indicated by code.

pub fn policy_physical_presence(
    &mut self,
    policy_session: ESYS_TR
) -> Result<()>

Cause conditional gating of a policy based on physical presence.

The TPM will ensure that the current policy can only complete when physical presence is asserted. The way this is done is implementation-specific.

pub fn policy_cp_hash(
    &mut self,
    policy_session: ESYS_TR,
    cp_hash_a: &Digest
) -> Result<()>

Cause conditional gating of a policy based on command parameters.

The TPM will ensure that the current policy can only be used to authorize a command where the parameters are hashed into cp_hash_a.

pub fn policy_name_hash(
    &mut self,
    policy_session: ESYS_TR,
    name_hash: &Digest
) -> Result<()>

Cause conditional gating of a policy based on name hash.

The TPM will ensure that the current policy can only be used to authorize a command acting on an object whose name hashes to name_hash.

pub fn policy_auth_value(&mut self, policy_session: ESYS_TR) -> Result<()>

Cause conditional gating of a policy based on authValue.

The TPM will ensure that the current policy requires the user to know the authValue used when creating the object.

pub fn policy_password(&mut self, policy_session: ESYS_TR) -> Result<()>

Cause conditional gating of a policy based on password.

The TPM will ensure that the current policy requires the user to know the password used when creating the object.

pub fn policy_nv_written(
    &mut self,
    policy_session: ESYS_TR,
    written_set: bool
) -> Result<()>

Cause conditional gating of a policy based on NV written state.

The TPM will ensure that the NV index that is used has a specific written state.

pub fn policy_authorize(
    &mut self,
    policy_session: ESYS_TR,
    approved_policy: &Digest,
    policy_ref: &Nonce,
    key_sign: &Name,
    check_ticket: TPMT_TK_VERIFIED
) -> Result<()>

Cause conditional gating of a policy based on an authorized policy

The TPM will ensure that the current policy digest is correctly signed by the ticket in check_ticket and that check_ticket is signed by the key named in key_sign. If this is the case, the policyDigest of the policy session is replaced by the value of the key_sign and policy_ref values.

pub fn get_random(&mut self, num_bytes: usize) -> Result<Digest>

Get a number of random bytes from the TPM and return them.

Errors

• if converting num_bytes to u16 fails, a WrongParamSize will be returned

pub fn test_parms(&mut self, parms: PublicParmsUnion) -> Result<()>

Test if the given parameters are supported by the TPM.

Errors

• if any of the public parameters is not compatible with the TPM, an Err containing the specific unmarshalling error will be returned.

pub fn hash(
    &mut self,
    data: &MaxBuffer,
    hashing_algorithm: HashingAlgorithm,
    hierarchy: Hierarchy
) -> Result<(Digest, HashcheckTicket)>

Function for invoking TPM2_Hash command.

pub fn policy_get_digest(&mut self, policy_session: ESYS_TR) -> Result<Digest>

Function for retriving the current policy digest for the session.

pub fn tr_set_auth(
    &mut self,
    object_handle: ObjectHandle,
    auth: &Auth
) -> Result<()>

TPM Resource Section Set the authentication value for a given object handle in the ESYS context.

Constraints

• auth_value must be at most 64 elements long

Errors

• if auth_value is larger than the limit, a WrongParamSize wrapper error is returned

pub fn tr_get_name(&mut self, object_handle: ObjectHandle) -> Result<Name>

Retrieve the name of an object from the object handle

pub fn tr_sess_set_attributes(
    &mut self,
    handle: ESYS_TR,
    attributes: TpmaSession
) -> Result<()>

Set the given attributes on a given session.

pub fn tr_sess_get_attributes(
    &mut self,
    object_handle: ObjectHandle
) -> Result<TpmaSession>

Get session attribute flags.

pub fn tr_from_tpm_public(
    &mut self,
    tpm_handle: TpmHandle
) -> Result<ObjectHandle>

Used to construct an esys object from the resources inside the TPM.

pub fn tr_close(&mut self, object_handle: &mut ObjectHandle) -> Result<()>

pub fn nv_define_space(
    &mut self,
    nv_authorization: NvAuthorization,
    auth: Option<&Auth>,
    public_info: &NvPublic
) -> Result<NvIndexHandle>

TPM Non Volatile Section NV Define Space

Allocates an index in the non volatile storage.

pub fn nv_undefine_space(
    &mut self,
    nv_authorization: NvAuthorization,
    nv_index_handle: NvIndexHandle
) -> Result<()>

NV Undefine Space

Deletes an index in the non volatile storage.

pub fn nv_read_public(
    &mut self,
    nv_index_handle: NvIndexHandle
) -> Result<(NvPublic, Name)>

NV Read Public

Reads the public part of an nv index.

pub fn nv_read(
    &mut self,
    auth_handle: AuthHandle,
    nv_index_handle: NvIndexHandle,
    size: u16,
    offset: u16
) -> Result<MaxNvBuffer>

NV Read

Reads data from the nv index.

pub fn nv_write(
    &mut self,
    auth_handle: AuthHandle,
    nv_index_handle: NvIndexHandle,
    data: &MaxNvBuffer,
    offset: u16
) -> Result<()>

NV Write

Writes data to an nv index.

Trait Implementations

impl Debug for Context

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

Formats the value using the given formatter.

impl Drop for Context

fn drop(&mut self)

Executes the destructor for this type.