---
name: "ESYS_TR"
section: "3"
platform: "linux"
package: "tpm2-tss"
version: "4.2.0-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ESYS_TR"
---

# ESYS\_TR(3)

Esys Tpm Resource ESYS\_TR

## NAME

ESYS\_TR - Esys Tpm Resource ESYS\_TR

## SYNOPSIS

### Topics

**Global ESYS\_TR objects**\

### Typedefs

typedef uint32\_t **ESYS\_TR**\

### Functions

TSS2\_RC **Esys\_TR\_SetAuth** (**ESYS\_CONTEXT** \*esysContext, **ESYS\_TR** handle, TPM2B\_AUTH const \*authValue)\
 TSS2\_RC **Esys\_TR\_GetName** (**ESYS\_CONTEXT** \*esysContext, **ESYS\_TR** handle, TPM2B\_NAME \*\*name)\
 TSS2\_RC **Esys\_TR\_FromTPMPublic\_Async** (**ESYS\_CONTEXT** \*esysContext, TPM2\_HANDLE tpm\_handle, **ESYS\_TR** optionalSession1, **ESYS\_TR** optionalSession2, **ESYS\_TR** optionalSession3)\
 TSS2\_RC **Esys\_TR\_FromTPMPublic\_Finish** (**ESYS\_CONTEXT** \*esysContext, **ESYS\_TR** \*object)\
 TSS2\_RC **Esys\_TR\_FromTPMPublic** (**ESYS\_CONTEXT** \*esysContext, TPM2\_HANDLE tpm\_handle, **ESYS\_TR** optionalSession1, **ESYS\_TR** optionalSession2, **ESYS\_TR** optionalSession3, **ESYS\_TR** \*object)\
 TSS2\_RC **Esys\_TR\_Serialize** (**ESYS\_CONTEXT** \*esys\_context, **ESYS\_TR** object, uint8\_t \*\*buffer, size\_t \*buffer\_size)\
 TSS2\_RC **Esys\_TR\_Deserialize** (**ESYS\_CONTEXT** \*esys\_context, uint8\_t const \*buffer, size\_t buffer\_size, **ESYS\_TR** \*esys\_handle)\
 TSS2\_RC **Esys\_TR\_Close** (**ESYS\_CONTEXT** \*esys\_context, **ESYS\_TR** \*rsrc\_handle)\
 TSS2\_RC **Esys\_TRSess\_GetAttributes** (**ESYS\_CONTEXT** \*esysContext, **ESYS\_TR** session, TPMA\_SESSION \*flags)\
 TSS2\_RC **Esys\_TRSess\_SetAttributes** (**ESYS\_CONTEXT** \*esysContext, **ESYS\_TR** session, TPMA\_SESSION flags, TPMA\_SESSION mask)\

## Detailed Description

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.

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.

## Typedef Documentation

### typedef uint32\_t ESYS\_TR

Reference to the virtual object inside the **ESYS\_CONTEXT** that holds the metadata for the corresponding TPM Resource. Such can be Transient key, Persistent objects, NV spaces, Sessions or PCRs.

## Function Documentation

### TSS2\_RC Esys\_TR\_Close (ESYS\_CONTEXT \* esys\_context, ESYS\_TR \* object)

Close an **ESYS\_TR** without removing it from the TPM.

This function deletes an **ESYS\_TR** object from an **ESYS\_CONTEXT** 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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT** \
 *object* \[out\] **ESYS\_TR** metadata object to be deleted from **ESYS\_CONTEXT**.

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the **ESYS\_TR** object is unknown to the **ESYS\_CONTEXT**.

### TSS2\_RC Esys\_TR\_Deserialize (ESYS\_CONTEXT \* esys\_context, uint8\_t const \* buffer, size\_t buffer\_size, ESYS\_TR \* esys\_handle)

Deserialization of an **ESYS\_TR** from a byte buffer.

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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *buffer* \[in\] The buffer containing the metadata of the **ESYS\_TR** object. \
 *buffer\_size* \[in\] The size of the buffer parameter. \
 *esys\_handle* \[out\] The **ESYS\_TR** object to deserialize.

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_MEMORY* if the object can not be allocated. \
 *TSS2\_ESYS\_RC\_INSUFFICIENT\_BUFFER* if the buffer for unmarshalling. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_RCs* produced by lower layers of the software stack.

### TSS2\_RC Esys\_TR\_FromTPMPublic (ESYS\_CONTEXT \* esys\_context, TPM2\_HANDLE tpm\_handle, ESYS\_TR shandle1, ESYS\_TR shandle2, ESYS\_TR shandle3, ESYS\_TR \* object)

Creation of an **ESYS\_TR** object from TPM metadata.

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.

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.

Since man in the middle attacks should be prevented as much as possible it is recommended to pass a session.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT** \
 *tpm\_handle* \[in\] The handle of the TPM object to represent as **ESYS\_TR**. \
 *shandle1* \[in,out\] A session for securing the TPM command (optional). \
 *shandle2* \[in,out\] A session for securing the TPM command (optional). \
 *shandle3* \[in,out\] A session for securing the TPM command (optional). \
 *object* \[out\] The newly created **ESYS\_TR** metadata object.

**Return values**

*TSS2\_RC\_SUCCESS* on success \
 *ESYS\_RC\_SUCCESS* if the function call was a success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext or required input pointers or required output handle references are NULL. \
 *TSS2\_ESYS\_RC\_BAD\_CONTEXT* if esysContext corruption is detected. \
 *TSS2\_ESYS\_RC\_MEMORY* if the ESAPI cannot allocate enough memory for internal operations or return parameters. \
 *TSS2\_ESYS\_RC\_BAD\_SEQUENCE* if the context has an asynchronous operation already pending. \
 *TSS2\_ESYS\_RC\_INSUFFICIENT\_RESPONSE* if the TPM's response does not at least contain the tag, response length, and response code. \
 *TSS2\_ESYS\_RC\_MALFORMED\_RESPONSE* if the TPM's response is corrupted. \
 *TSS2\_ESYS\_RC\_MULTIPLE\_DECRYPT\_SESSIONS* if more than one session has the 'decrypt' attribute bit set. \
 *TSS2\_ESYS\_RC\_MULTIPLE\_ENCRYPT\_SESSIONS* if more than one session has the 'encrypt' attribute bit set. \
 *TSS2\_ESYS\_RC\_NO\_DECRYPT\_PARAM* if one of the sessions has the 'decrypt' attribute set and the command does not support encryption of the first command parameter. \
 *TSS2\_RCs* produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally.

### TSS2\_RC Esys\_TR\_FromTPMPublic\_Async (ESYS\_CONTEXT \* esys\_context, TPM2\_HANDLE tpm\_handle, ESYS\_TR shandle1, ESYS\_TR shandle2, ESYS\_TR shandle3)

Start synchronous creation of an **ESYS\_TR** object from TPM metadata.

This function starts the asynchronous retrieval of metadata from the TPM in order to create a new **ESYS\_TR** object.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT** \
 *tpm\_handle* \[in\] The handle of the TPM object to represent as **ESYS\_TR**. \
 *shandle1* \[in,out\] A session for securing the TPM command (optional). \
 *shandle2* \[in,out\] A session for securing the TPM command (optional). \
 *shandle3* \[in,out\] A session for securing the TPM command (optional).

**Return values**

*TSS2\_RC\_SUCCESS* on success \
 *ESYS\_RC\_SUCCESS* if the function call was a success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_CONTEXT* if esysContext corruption is detected. \
 *TSS2\_ESYS\_RC\_MEMORY* if the ESAPI cannot allocate enough memory for internal operations or return parameters. \
 *TSS2\_ESYS\_RC\_MULTIPLE\_DECRYPT\_SESSIONS* if more than one session has the 'decrypt' attribute bit set. \
 *TSS2\_ESYS\_RC\_MULTIPLE\_ENCRYPT\_SESSIONS* if more than one session has the 'encrypt' attribute bit set. \
 *TSS2\_ESYS\_RC\_NO\_DECRYPT\_PARAM* if one of the sessions has the 'decrypt' attribute set and the command does not support encryption of the first command parameter. \
 *TSS2\_RCs* produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally.

### TSS2\_RC Esys\_TR\_FromTPMPublic\_Finish (ESYS\_CONTEXT \* esys\_context, ESYS\_TR \* object)

Finish asynchronous creation of an **ESYS\_TR** object from TPM metadata.

This function finishes the asynchronous retrieval of metadata from the TPM in order to create a new **ESYS\_TR** object.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT** \
 *object* \[out\] The newly created **ESYS\_TR** metadata object.

**Return values**

*TSS2\_RC\_SUCCESS* on success \
 *ESYS\_RC\_SUCCESS* if the function call was a success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext or required input pointers or required output handle references are NULL. \
 *TSS2\_ESYS\_RC\_BAD\_CONTEXT* if esysContext corruption is detected. \
 *TSS2\_ESYS\_RC\_MEMORY* if the ESAPI cannot allocate enough memory for internal operations or return parameters. \
 *TSS2\_ESYS\_RC\_BAD\_SEQUENCE* if the context has an asynchronous operation already pending. \
 *TSS2\_ESYS\_RC\_TRY\_AGAIN* if the timeout counter expires before the TPM response is received. \
 *TSS2\_ESYS\_RC\_INSUFFICIENT\_RESPONSE* if the TPM's response does not at least contain the tag, response length, and response code. \
 *TSS2\_ESYS\_RC\_MALFORMED\_RESPONSE* if the TPM's response is corrupted. \
 *TSS2\_RCs* produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally.

### TSS2\_RC Esys\_TR\_GetName (ESYS\_CONTEXT \* esys\_context, ESYS\_TR esys\_handle, TPM2B\_NAME \*\* name)

Retrieve the TPM public name of an Esys\_TR object.

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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *esys\_handle* \[in,out\] The **ESYS\_TR** for which to retrieve the name. \
 *name* \[out\] The name of the object (caller-allocated; use free()).

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_MEMORY* if needed memory can't be allocated. \
 *TSS2\_ESYS\_RC\_GENERAL\_FAILURE* for errors of the crypto library. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the handle is invalid. \
 *TSS2\_SYS\_RC\_\** for SAPI errors.

### TSS2\_RC Esys\_TR\_Serialize (ESYS\_CONTEXT \* esys\_context, ESYS\_TR esys\_handle, uint8\_t \*\* buffer, size\_t \* buffer\_size)

Serialization of an **ESYS\_TR** into a byte buffer.

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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *esys\_handle* \[in\] The **ESYS\_TR** object to serialize. \
 *buffer* \[out\] The buffer containing the serialized metadata. (caller-callocated) Shall be freed using free(). \
 *buffer\_size* \[out\] The size of the buffer parameter.

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the **ESYS\_TR** object is unknown to the **ESYS\_CONTEXT**. \
 *TSS2\_ESYS\_RC\_MEMORY* if the buffer for marshaling the object can't be allocated. \
 *TSS2\_ESYS\_RC\_BAD\_VALUE* For invalid ESYS data to be marshaled. \
 *TSS2\_RCs* produced by lower layers of the software stack.

### TSS2\_RC Esys\_TR\_SetAuth (ESYS\_CONTEXT \* esys\_context, ESYS\_TR esys\_handle, TPM2B\_AUTH const \* authValue)

Set the authorization value of an **ESYS\_TR**.

Authorization values are associated with **ESYS\_TR** Tpm Resource object. They are then picked up whenever an authorization is needed.

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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *esys\_handle* \[in,out\] The **ESYS\_TR** for which to set the auth value. \
 *authValue* \[in\] The auth value to set for the **ESYS\_TR** or NULL to zero the auth.

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the **ESYS\_TR** object is unknown to the **ESYS\_CONTEXT** or it equals ESYS\_TR\_NONE.

### TSS2\_RC Esys\_TRSess\_GetAttributes (ESYS\_CONTEXT \* esys\_context, ESYS\_TR esys\_handle, TPMA\_SESSION \* flags)

Retrieve the Session Attributes of the **ESYS\_TR** session.

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.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *esys\_handle* \[in,out\] The **ESYS\_TR** of the session. \
 *flags* \[out\] The attributes of the session.

**Return values**

*TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the **ESYS\_TR** object is unknown to the **ESYS\_CONTEXT** or **ESYS\_TR** object is not a session object.

### TSS2\_RC Esys\_TRSess\_SetAttributes (ESYS\_CONTEXT \* esys\_context, ESYS\_TR esys\_handle, TPMA\_SESSION flags, TPMA\_SESSION mask)

Set session attributes

Set or unset a session's attributes according to the provided flags and mask.

```
new_attributes = old_attributes & ~mask | flags & mask
```

 Note: this function only applies to **ESYS\_TR** objects that represent sessions.

**Parameters**

*esys\_context* \[in,out\] The **ESYS\_CONTEXT**. \
 *esys\_handle* \[in,out\] The **ESYS\_TR** of the session. \
 *flags* \[in\] The flags to be set or unset for the session. \
 *mask* \[in\] The mask for the flags to be set or unset.

**Return values**

*TSS2\_RC\_SUCCESS* on Success. \
 *TSS2\_ESYS\_RC\_BAD\_REFERENCE* if the esysContext is NULL. \
 *TSS2\_ESYS\_RC\_BAD\_TR* if the **ESYS\_TR** object is unknown to the **ESYS\_CONTEXT** or **ESYS\_TR** object is not a session object.

## Author

Generated automatically by Doxygen for tpm2-tss from the source code.