ESYS_TR(3)

📦
version 4.1.5 · 9 versions
, in fedora 44

ESYS_TR(3) 🎀 — Esys Tpm Resource ESYS_TR

okay bestie, welcome to the Library Functions Manual page for ESYS_TR — yes the header line said ESYS_TR(3) and the manual is Library Functions Manual, iykyk. This is the resource-handle lore you didn't know you needed. 💅

✨ NAME ✨

ESYS_TR — Esys Tpm Resource ESYS_TR. That's the whole name, no cap. It's the little handle that points at all the TPM resource metadata, and we're about to get deep into it. 🦋

✨ 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)

like, that's the whole roster. some of them get their full moment below, some are saving their energy for part 2 👀

✨ 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. 🎀

so like — ESYS_TR_NON, PCRs, hierarchies? global. everything from ESYS_TR_MIN_OBJECT upward? not global, that's where the real ones start. 👑

🌈 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. ✨

it's giving pointer-to-a-vibe, but make it uint32_t. iconic. 💅

🔥 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. 🚨

important bestie: this is not a delete-from-TPM button. it's a delete-from-your-context button. transient stuff goes through Esys_FlushContext, periodt.

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. ✨

(yes the summary says "synchronous" and the body says "asynchronous" — that's what the page says, I'm just the messenger bestie 💀)

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()).
don't forget the free() bestie, that's your memory now 🙈

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 💖

Okay so for the function we were just talking about, here’s the return-value menu, no cap:

  • 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.

Esys_TR_SetAuth — the auth-value glow-up 💅

TSS2_RC Esys_TR_SetAuth (ESYS_CONTEXT * esys_context, ESYS_TR esys_handle, TPM2B_AUTH const * authValue)

Sets the authorization value of an ESYS_TR — literally giving it the auth it needs to be its main character. ✨

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.

Esys_TRSess_GetAttributes — session attributes peek 👀

TSS2_RC Esys_TRSess_GetAttributes (ESYS_CONTEXT * esys_context, ESYS_TR esys_handle, TPMA_SESSION * flags)

Retrieves the session attributes of the ESYS_TR session. 🎀

Sessions possess attributes, such as whether they shall continue or 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.

Bestie, this is session-only business — no cap. If the ESYS_TR isn’t a session object, it’s giving “wrong room, wrong vibe.” 💀

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.

Esys_TRSess_SetAttributes — session attributes remix 🎛️

TSS2_RC Esys_TRSess_SetAttributes (ESYS_CONTEXT * esys_context, ESYS_TR esys_handle, TPMA_SESSION flags, TPMA_SESSION mask)

Sets session attributes. Set or unset a session’s attributes according to the provided flags and mask. It’s basically a little bit-math makeover for your session — iconic. 💖

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. Auto-generated lore, fr fr. 🫶

That’s the whole page, bestie — source tpm2-tss, version 4.1.5, and the footer’s date/page moment is the usual ESYS_TR(3) situation. Catch you in the next manpage! 💖✨🦋

📦 where this page comes from