.TH "ESYS_TR" 3 "Sun May 7 2023" "Version 4.0.1" "tpm2-tss" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ESYS_TR \- Esys Tpm Resource ESYS_TR
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBGlobal ESYS_TR objects\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef uint32_t \fBESYS_TR\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "TSS2_RC \fBEsys_TR_SetAuth\fP (\fBESYS_CONTEXT\fP *esysContext, \fBESYS_TR\fP handle, TPM2B_AUTH const *authValue)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_GetName\fP (\fBESYS_CONTEXT\fP *esysContext, \fBESYS_TR\fP handle, TPM2B_NAME **name)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_FromTPMPublic_Async\fP (\fBESYS_CONTEXT\fP *esysContext, TPM2_HANDLE tpm_handle, \fBESYS_TR\fP optionalSession1, \fBESYS_TR\fP optionalSession2, \fBESYS_TR\fP optionalSession3)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_FromTPMPublic_Finish\fP (\fBESYS_CONTEXT\fP *esysContext, \fBESYS_TR\fP *object)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_FromTPMPublic\fP (\fBESYS_CONTEXT\fP *esysContext, TPM2_HANDLE tpm_handle, \fBESYS_TR\fP optionalSession1, \fBESYS_TR\fP optionalSession2, \fBESYS_TR\fP optionalSession3, \fBESYS_TR\fP *object)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_Serialize\fP (\fBESYS_CONTEXT\fP *esys_context, \fBESYS_TR\fP object, uint8_t **buffer, size_t *buffer_size)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_Deserialize\fP (\fBESYS_CONTEXT\fP *esys_context, uint8_t const *buffer, size_t buffer_size, \fBESYS_TR\fP *esys_handle)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TR_Close\fP (\fBESYS_CONTEXT\fP *esys_context, \fBESYS_TR\fP *rsrc_handle)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TRSess_GetAttributes\fP (\fBESYS_CONTEXT\fP *esysContext, \fBESYS_TR\fP session, TPMA_SESSION *flags)"
.br
.ti -1c
.RI "TSS2_RC \fBEsys_TRSess_SetAttributes\fP (\fBESYS_CONTEXT\fP *esysContext, \fBESYS_TR\fP session, TPMA_SESSION flags, TPMA_SESSION mask)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Virtual objects with meta data for Tpm Resources\&. The Esys TPM Resources are the virtual objects inside the ESYSCONTEXT that hold the metadata for corresponding TPM Resources\&.
.PP
There are a set of global ESYS_TR objects such as ESYS_TR_NON or for the various PCRs and hierarchies\&. ESYS_TR_MIN_OBJECT denotes the first non-global ESYS_TR object\&. 
.SH "Typedef Documentation"
.PP 
.SS "\fBESYS_TR\fP"
Reference to the virtual object inside the \fBESYS_CONTEXT\fP that holds the metadata for the corresponding TPM Resource\&. Such can be Transient key, Persistent objects, NV spaces, Sessions or PCRs\&. 
.SH "Function Documentation"
.PP 
.SS "TSS2_RC Esys_TR_Close (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP * object)"
Close an ESYS_TR without removing it from the TPM\&.
.PP
This function deletes an ESYS_TR object from an \fBESYS_CONTEXT\fP without deleting it from the TPM\&. This is useful for NV-Indices or persistent keys, after Esys_TR_Serialize has been called\&. Transient objects should be deleted using Esys_FlushContext\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP 
.br
\fIobject\fP [out] ESYS_TR metadata object to be deleted from \fBESYS_CONTEXT\fP\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the ESYS_TR object is unknown to the \fBESYS_CONTEXT\fP\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_Deserialize (\fBESYS_CONTEXT\fP * esys_context, uint8_t const * buffer, size_t buffer_size, \fBESYS_TR\fP * esys_handle)"
Deserialization of an ESYS_TR from a byte buffer\&.
.PP
Deserialize the metadata of an ESYS_TR object from a byte buffer that was stored on disk for later use by a different program or context\&. An object can be deserialized using Esys_TR_Deserialize\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [out] The ESYS_TR object to deserialize\&. 
.br
\fIbuffer\fP [in] The buffer containing the metadata of the ESYS_TR object\&. 
.br
\fIbuffer_size\fP [in] The size of the buffer parameter\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if the object can not be allocated\&. 
.br
\fITSS2_ESYS_RC_INSUFFICIENT_BUFFER\fP if the buffer for unmarshalling\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_RCs\fP produced by lower layers of the software stack\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_FromTPMPublic (\fBESYS_CONTEXT\fP * esys_context, TPM2_HANDLE tpm_handle, \fBESYS_TR\fP shandle1, \fBESYS_TR\fP shandle2, \fBESYS_TR\fP shandle3, \fBESYS_TR\fP * object)"
Creation of an ESYS_TR object from TPM metadata\&.
.PP
This function can be used to create ESYS_TR object for Tpm Resources that are not created or loaded (e\&.g\&. using ESys_CreatePrimary or ESys_Load) but pre-exist inside the TPM\&. Examples are NV-Indices or persistent object\&.
.PP
Note: For PCRs and hierarchies, please use the global ESYS_TR identifiers\&. Note: If a session is provided the TPM is queried for the metadata twice\&. First without a session to retrieve some metadata then with the session where this metadata is used in the session HMAC calculation and thereby verified\&.
.PP
Since man in the middle attacks should be prevented as much as possible it is recommended to pass a session\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP 
.br
\fItpm_handle\fP [in] The handle of the TPM object to represent as ESYS_TR\&. 
.br
\fIshandle1\fP [in,out] A session for securing the TPM command (optional)\&. 
.br
\fIshandle2\fP [in,out] A session for securing the TPM command (optional)\&. 
.br
\fIshandle3\fP [in,out] A session for securing the TPM command (optional)\&. 
.br
\fIobject\fP [out] The newly created ESYS_TR metadata object\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on success 
.br
\fIESYS_RC_SUCCESS\fP if the function call was a success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext or required input pointers or required output handle references are NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_CONTEXT\fP if esysContext corruption is detected\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if the ESAPI cannot allocate enough memory for internal operations or return parameters\&. 
.br
\fITSS2_ESYS_RC_BAD_SEQUENCE\fP if the context has an asynchronous operation already pending\&. 
.br
\fITSS2_ESYS_RC_INSUFFICIENT_RESPONSE\fP if the TPM's response does not at least contain the tag, response length, and response code\&. 
.br
\fITSS2_ESYS_RC_MALFORMED_RESPONSE\fP if the TPM's response is corrupted\&. 
.br
\fITSS2_ESYS_RC_MULTIPLE_DECRYPT_SESSIONS\fP if more than one session has the 'decrypt' attribute bit set\&. 
.br
\fITSS2_ESYS_RC_MULTIPLE_ENCRYPT_SESSIONS\fP if more than one session has the 'encrypt' attribute bit set\&. 
.br
\fITSS2_ESYS_RC_NO_DECRYPT_PARAM\fP if one of the sessions has the 'decrypt' attribute set and the command does not support encryption of the first command parameter\&. 
.br
\fITSS2_RCs\fP produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_FromTPMPublic_Async (\fBESYS_CONTEXT\fP * esys_context, TPM2_HANDLE tpm_handle, \fBESYS_TR\fP shandle1, \fBESYS_TR\fP shandle2, \fBESYS_TR\fP shandle3)"
Start synchronous creation of an ESYS_TR object from TPM metadata\&.
.PP
This function starts the asynchronous retrieval of metadata from the TPM in order to create a new ESYS_TR object\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP 
.br
\fItpm_handle\fP [in] The handle of the TPM object to represent as ESYS_TR\&. 
.br
\fIshandle1\fP [in,out] A session for securing the TPM command (optional)\&. 
.br
\fIshandle2\fP [in,out] A session for securing the TPM command (optional)\&. 
.br
\fIshandle3\fP [in,out] A session for securing the TPM command (optional)\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on success 
.br
\fIESYS_RC_SUCCESS\fP if the function call was a success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_CONTEXT\fP if esysContext corruption is detected\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if the ESAPI cannot allocate enough memory for internal operations or return parameters\&. 
.br
\fITSS2_ESYS_RC_MULTIPLE_DECRYPT_SESSIONS\fP if more than one session has the 'decrypt' attribute bit set\&. 
.br
\fITSS2_ESYS_RC_MULTIPLE_ENCRYPT_SESSIONS\fP if more than one session has the 'encrypt' attribute bit set\&. 
.br
\fITSS2_ESYS_RC_NO_DECRYPT_PARAM\fP if one of the sessions has the 'decrypt' attribute set and the command does not support encryption of the first command parameter\&. 
.br
\fITSS2_RCs\fP produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_FromTPMPublic_Finish (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP * object)"
Finish asynchronous creation of an ESYS_TR object from TPM metadata\&.
.PP
This function finishes the asynchronous retrieval of metadata from the TPM in order to create a new ESYS_TR object\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP 
.br
\fIobject\fP [out] The newly created ESYS_TR metadata object\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on success 
.br
\fIESYS_RC_SUCCESS\fP if the function call was a success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext or required input pointers or required output handle references are NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_CONTEXT\fP if esysContext corruption is detected\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if the ESAPI cannot allocate enough memory for internal operations or return parameters\&. 
.br
\fITSS2_ESYS_RC_BAD_SEQUENCE\fP if the context has an asynchronous operation already pending\&. 
.br
\fITSS2_ESYS_RC_TRY_AGAIN\fP if the timeout counter expires before the TPM response is received\&. 
.br
\fITSS2_ESYS_RC_INSUFFICIENT_RESPONSE\fP if the TPM's response does not at least contain the tag, response length, and response code\&. 
.br
\fITSS2_ESYS_RC_MALFORMED_RESPONSE\fP if the TPM's response is corrupted\&. 
.br
\fITSS2_RCs\fP produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_GetName (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP esys_handle, TPM2B_NAME ** name)"
Retrieve the TPM public name of an Esys_TR object\&.
.PP
Some operations (i\&.e\&. Esys_PolicyNameHash) require the name of a TPM object to be passed\&. Esys_TR_GetName provides this name to the caller\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [in,out] The ESYS_TR for which to retrieve the name\&. 
.br
\fIname\fP [out] The name of the object (caller-allocated; use free())\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if needed memory can't be allocated\&. 
.br
\fITSS2_ESYS_RC_GENERAL_FAILURE\fP for errors of the crypto library\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the handle is invalid\&. 
.br
\fITSS2_SYS_RC_*\fP for SAPI errors\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_Serialize (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP esys_handle, uint8_t ** buffer, size_t * buffer_size)"
Serialization of an ESYS_TR into a byte buffer\&.
.PP
Serialize the metadata of an ESYS_TR object into a byte buffer such that it can be stored on disk for later use by a different program or context\&. The serialized object can be deserialized using Esys_TR_Deserialize\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [in] The ESYS_TR object to serialize\&. 
.br
\fIbuffer\fP [out] The buffer containing the serialized metadata\&. (caller-callocated) Shall be freed using free()\&. 
.br
\fIbuffer_size\fP [out] The size of the buffer parameter\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the ESYS_TR object is unknown to the \fBESYS_CONTEXT\fP\&. 
.br
\fITSS2_ESYS_RC_MEMORY\fP if the buffer for marshaling the object can't be allocated\&. 
.br
\fITSS2_ESYS_RC_BAD_VALUE\fP For invalid ESYS data to be marshaled\&. 
.br
\fITSS2_RCs\fP produced by lower layers of the software stack\&. 
.RE
.PP

.SS "TSS2_RC Esys_TR_SetAuth (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP esys_handle, TPM2B_AUTH const * authValue)"
Set the authorization value of an ESYS_TR\&.
.PP
Authorization values are associated with ESYS_TR Tpm Resource object\&. They are then picked up whenever an authorization is needed\&.
.PP
Note: The authorization value is not stored in the metadata during Esys_TR_Serialize\&. Therefor Esys_TR_SetAuth needs to be called again after every Esys_TR_Deserialize\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [in,out] The ESYS_TR for which to set the auth value\&. 
.br
\fIauthValue\fP [in] The auth value to set for the ESYS_TR or NULL to zero the auth\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the ESYS_TR object is unknown to the \fBESYS_CONTEXT\fP or it equals ESYS_TR_NONE\&. 
.RE
.PP

.SS "TSS2_RC Esys_TRSess_GetAttributes (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP esys_handle, TPMA_SESSION * flags)"
Retrieve the Session Attributes of the ESYS_TR session\&.
.PP
Sessions possess attributes, such as whether they shall continue of be flushed after the next command, or whether they are used to encrypt parameters\&. Note: this function only applies to ESYS_TR objects that represent sessions\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [in,out] The ESYS_TR of the session\&. 
.br
\fIflags\fP [out] The attributes of the session\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the ESYS_TR object is unknown to the \fBESYS_CONTEXT\fP or ESYS_TR object is not a session object\&. 
.RE
.PP

.SS "TSS2_RC Esys_TRSess_SetAttributes (\fBESYS_CONTEXT\fP * esys_context, \fBESYS_TR\fP esys_handle, TPMA_SESSION flags, TPMA_SESSION mask)"
Set session attributes
.PP
Set or unset a session's attributes according to the provided flags and mask\&. 
.PP
.nf
new_attributes = old_attributes & ~mask | flags & mask 
.fi
.PP
 Note: this function only applies to ESYS_TR objects that represent sessions\&. 
.PP
\fBParameters\fP
.RS 4
\fIesys_context\fP [in,out] The \fBESYS_CONTEXT\fP\&. 
.br
\fIesys_handle\fP [in,out] The ESYS_TR of the session\&. 
.br
\fIflags\fP [in] The flags to be set or unset for the session\&. 
.br
\fImask\fP [in] The mask for the flags to be set or unset\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fITSS2_RC_SUCCESS\fP on Success\&. 
.br
\fITSS2_ESYS_RC_BAD_REFERENCE\fP if the esysContext is NULL\&. 
.br
\fITSS2_ESYS_RC_BAD_TR\fP if the ESYS_TR object is unknown to the \fBESYS_CONTEXT\fP or ESYS_TR object is not a session object\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for tpm2-tss from the source code\&.