[−][src]Struct tss_esapi::Context
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
[src]
pub unsafe fn new(tcti: Tcti) -> Result<Self>
[src]
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
orEsys_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>
[src]
&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, aWrongSizeParam
wrapper error is returned
pub fn set_sessions(&mut self, session_handles: (ESYS_TR, ESYS_TR, ESYS_TR))
[src]
pub fn sessions(&self) -> (ESYS_TR, ESYS_TR, ESYS_TR)
[src]
pub fn get_capabilities(
&mut self,
capability: TPM2_CAP,
property: u32,
property_count: u32
) -> Result<(TPMS_CAPABILITY_DATA, bool)>
[src]
&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>
[src]
&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 longcreation_pcrs
must be at most 16 elements longauth_value
must be at most 64 elements longinitial_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)>
[src]
&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 longcreation_pcrs
must be at most 16 elements longauth_value
must be at most 64 elements longinitial_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>
[src]
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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
Read the public part of a key currently in the TPM and return it.
pub fn flush_context(&mut self, handle: ESYS_TR) -> Result<()>
[src]
Flush the context of an object from the TPM.
pub fn context_save(&mut self, handle: ESYS_TR) -> Result<TpmsContext>
[src]
Save the context of an object from the TPM and return it.
Errors
- if conversion from
TPMS_CONTEXT
toTpmsContext
fails, aWrongParamSize
error will be returned
pub fn context_load(&mut self, context: TpmsContext) -> Result<ESYS_TR>
[src]
Load a previously saved context into the TPM and return the object handle.
Errors
- if conversion from
TpmsContext
to the nativeTPMS_CONTEXT
fails, aWrongParamSize
error will be returned
pub fn pcr_read(
&mut self,
pcr_selection_list: &PcrSelectionList
) -> Result<(u32, PcrSelectionList, PcrData)>
[src]
&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)>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
&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<()>
[src]
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<()>
[src]
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<()>
[src]
&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<()>
[src]
&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>
[src]
Get a number of random bytes from the TPM and return them.
Errors
- if converting
num_bytes
tou16
fails, aWrongParamSize
will be returned
pub fn test_parms(&mut self, parms: PublicParmsUnion) -> Result<()>
[src]
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)>
[src]
&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>
[src]
Function for retriving the current policy digest for the session.
pub fn tr_set_auth(&mut self, handle: ESYS_TR, auth: &Auth) -> Result<()>
[src]
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, aWrongParamSize
wrapper error is returned
pub fn tr_get_name(&mut self, handle: ESYS_TR) -> Result<Name>
[src]
Retrieve the name of an object from the object handle
pub fn tr_sess_set_attributes(
&mut self,
handle: ESYS_TR,
attributes: TpmaSession
) -> Result<()>
[src]
&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>
[src]
Get session attribute flags.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Context
impl Send for Context
impl Sync for Context
impl Unpin for Context
impl UnwindSafe for Context
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Free for T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,