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.

Methods

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: &[u8],
    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 create_primary_key(
    &mut self,
    primary_handle: ESYS_TR,
    public: &TPM2B_PUBLIC,
    auth_value: &[u8],
    initial_data: &[u8],
    outside_info: &[u8],
    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: &[u8],
    initial_data: &[u8],
    outside_info: &[u8],
    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 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: &[u8],
    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: &[u8],
    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 load_external(
    &mut self,
    private: &TPM2B_SENSITIVE,
    public: &TPM2B_PUBLIC,
    hierarchy: TPMI_RH_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: TPMI_RH_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: PcrSelections
) -> Result<(u32, TPML_PCR_SELECTION, TPML_DIGEST)>

Read values from selected PCRs

pub fn quote(
    &mut self,
    signing_key_handle: ESYS_TR,
    qualifying_data: &[u8],
    signing_scheme: TPMT_SIG_SCHEME,
    pcr_selection: PcrSelections
) -> 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 get_random(&mut self, num_bytes: usize) -> Result<Vec<u8>>

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 tr_set_auth(&mut self, handle: ESYS_TR, auth_value: &[u8]) -> 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, handle: ESYS_TR) -> Result<TPM2B_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, handle: ESYS_TR) -> Result<TpmaSession>

Get session attribute flags.

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.