Esys_PCR_Event(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

✨ Esys_PCR_Event(3) — the TPM2_PCR_Event ESAPI glow-up ✨

okay bestie, so this is a manual page from the Library Functions Manual (iykyk, it's the tpm2-tss library) and it's literally all about Esys_PCR_Event — the ESAPI function that invokes the TPM2_PCR_Event command. no cap, this is the group chat where PCR handles get their event data hashed. let's get into it 💅

🌸 NAME 🌸

Esys_PCR_Event — the ESAPI function for the TPM2_PCR_Event command. that's it, that's the vibe. 🎀

🦋 SYNOPSIS 🦋

here's the function family, bestie — three functions, all iconic:

TSS2_RC Esys_PCR_Event_Async (ESYS_CONTEXT *esysContext, ESYS_TR pcrHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_EVENT *eventData)

TSS2_RC Esys_PCR_Event (ESYS_CONTEXT *esysContext, ESYS_TR pcrHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_EVENT *eventData, TPML_DIGEST_VALUES **digests)

TSS2_RC Esys_PCR_Event_Finish (ESYS_CONTEXT *esysContext, TPML_DIGEST_VALUES **digests)

🌈 Detailed Description 🌈

okay so this is the ESAPI function that invokes the TPM2_PCR_Event command either as a one-call or in an asynchronous manner. literally choose your fighter. 🥊

💖 Function Documentation 💖

🌟 TSS2_RC Esys_PCR_Event (...) 🌟

the one-call function for TPM2_PCR_Event — the main character energy version 💅

so real talk: this function invokes the TPM2_PCR_Event command in a one-call variant. that means it will block until the TPM response is available. all input parameters are const. the memory for non-simple output parameters is allocated by the function implementation. no cap, it handles the memory for you. 🫶

here's the full signature so you can copy-paste into your code:

TSS2_RC Esys_PCR_Event (ESYS_CONTEXT * esysContext, ESYS_TR pcrHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_EVENT * eventData, TPML_DIGEST_VALUES ** digests)

🎀 Parameters 🎀

  • esysContext — The ESYS_CONTEXT. your whole context bestie.
  • pcrHandle — Handle of the PCR. the actual PCR we're doing stuff to.
  • shandle1 — Session handle for authorization of pcrHandle. auth slay.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • eventData — Event data in sized buffer. the tea being hashed.
  • digests — (callee-allocated). the output, allocated for you by the callee, periodt.

👑 Return values 👑

like, here's every possible mood this function could come back in:

  • TSS2_RC_SUCCESS — if the function call was a success. we love a happy ending 💖
  • TSS2_ESYS_RC_BAD_REFERENCE — if the esysContext or required input pointers or required output handle references are NULL. bestie, no.
  • TSS2_ESYS_RC_BAD_CONTEXT — if esysContext corruption is detected. red flag 🚩
  • TSS2_ESYS_RC_MEMORY — if the ESAPI cannot allocate enough memory for internal operations or return parameters. not enough room for the drama.
  • TSS2_ESYS_RC_BAD_SEQUENCE — if the context has an asynchronous operation already pending. one thing at a time, babe.
  • TSS2_ESYS_RC_INSUFFICIENT_RESPONSE — if the TPM's response does not at least contain the tag, response length, and response code. like a text with no context.
  • TSS2_ESYS_RC_MALFORMED_RESPONSE — if the TPM's response is corrupted. 🫠
  • TSS2_ESYS_RC_RSP_AUTH_FAILED — if the response HMAC from the TPM did not verify. the vibes were off.
  • TSS2_ESYS_RC_MULTIPLE_DECRYPT_SESSIONS — if more than one session has the 'decrypt' attribute bit set. one decrypt session max, greedy.
  • TSS2_ESYS_RC_MULTIPLE_ENCRYPT_SESSIONS — if more than one session has the 'encrypt' attribute bit set. same energy.
  • TSS2_ESYS_RC_BAD_TR — if any of the ESYS_TR objects are unknown to the ESYS_CONTEXT or are of the wrong type or if required ESYS_TR objects are ESYS_TR_NONE. check your TRs bestie.
  • TSS2_ESYS_RC_NO_ENCRYPT_PARAM — if one of the sessions has the 'encrypt' attribute set and the command does not support encryption of the first response parameter. not supported, soz.
  • TSS2_RCs — produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally. the lower layers said what they said.

🌙 TSS2_RC Esys_PCR_Event_Async (...) 🌙

the asynchronous function for TPM2_PCR_Event — the "send it and dip" version 😌

this function invokes the TPM2_PCR_Event command in an asynchronous variant. meaning it will return as soon as the command has been sent downwards the stack to the TPM. all input parameters are const. in order to retrieve the TPM's response call Esys_PCR_Event_Finish. don't forget to finish, bestie, it's not a vibe to leave things hanging.

here's the signature, lowkey:

TSS2_RC Esys_PCR_Event_Async (ESYS_CONTEXT * esysContext, ESYS_TR pcrHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_EVENT * eventData)

🎀 Parameters 🎀

  • esysContext — The ESYS_CONTEXT. still the context, still iconic.
  • pcrHandle — Handle of the PCR.
  • shandle1 — Session handle for authorization of pcrHandle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • eventData — Event data in sized buffer.

👑 Return values 👑

  • ESYS_RC_SUCCESS — if the function call was a success. note: this one says ESYS_RC_SUCCESS, not TSS2_RC_SUCCESS — copy it exactly, don't @ me.
  • 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_RCs — produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally.
  • 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_BAD_TR — if any of the ESYS_TR objects are unknown to the ESYS_CONTEXT or are of the wrong type or if required ESYS_TR objects are ESYS_TR_NONE.
  • TSS2_ESYS_RC_NO_ENCRYPT_PARAM — if one of the sessions has the 'encrypt' attribute set and the command does not support encryption of the first response parameter.

🧚 TSS2_RC Esys_PCR_Event_Finish (...) 🧚

the asynchronous finish function for TPM2_PCR_Event — the and that's on periodt closure 🎬

this function returns the results of a TPM2_PCR_Event command invoked via Esys_PCR_Event_Finish. all non-simple output parameters are allocated by the function's implementation. NULL can be passed for every output parameter if the value is not required. waste not, want not, bestie. ✨

here's the signature:

TSS2_RC Esys_PCR_Event_Finish (ESYS_CONTEXT * esysContext, TPML_DIGEST_VALUES ** digests)

🎀 Parameters 🎀

  • esysContext — The ESYS_CONTEXT.
  • digests — (callee-allocated). the results, allocated for you, no stress.

👑 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. literally try again, it's giving patience.
  • 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_RSP_AUTH_FAILED — if the response HMAC from the TPM did not verify.
  • 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.

🍓 Author 🍓

Generated automatically by Doxygen for tpm2-tss from the source code. not a human author, a whole robot doing its thing. we respect it. 🤖

okay bestie, that's the whole page — tpm2-tss Version 4.1.5, the Esys_PCR_Event(3) manual, and honestly? it ate. go hash those events and slay 💅✨🎀

📦 where this page comes from