Esys_PolicyGetDigest(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

NAME 🎀

Esys_PolicyGetDigest — the ESAPI function for the TPM2_PolicyGetDigest command. That's it, that's the vibe. 💅

SYNOPSIS ✨

Okay so the whole squad of functions you get is exactly these three, written out character-for-character so you can't mess 'em up:

TSS2_RC Esys_PolicyGetDigest_Async (ESYS_CONTEXT *esysContext, ESYS_TR
    policySession, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3)

TSS2_RC Esys_PolicyGetDigest (ESYS_CONTEXT *esysContext, ESYS_TR
    policySession, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3,
    TPM2B_DIGEST **policyDigest)

TSS2_RC Esys_PolicyGetDigest_Finish (ESYS_CONTEXT *esysContext,
    TPM2B_DIGEST **policyDigest)

DETAILED DESCRIPTION 🌈

So basically Esys_PolicyGetDigest is your ESAPI function that lets you invoke the TPM2_PolicyGetDigest command. And you've got two whole modes, bestie: either as a one-call (blocking, simple, iconic) or in an asynchronous manner (send it and dip, main character energy). Pick your fighter. 🥊✨

FUNCTION DOCUMENTATION 🦋

TSS2_RC Esys_PolicyGetDigest (ESYS_CONTEXT * esysContext, ESYS_TR policySession, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, TPM2B_DIGEST ** policyDigest) 💖

One-Call function for TPM2_PolicyGetDigest

This one invokes the TPM2_PolicyGetDigest command in its one-call variant. Translation: the function will block until the TPM response is ready — no ghosting, it waits for the reply. 💌

Also, all input parameters are const (so nobody's out here mutating your stuff), and the memory for non-simple output parameters is allocated by the function implementation. Not your problem, bestie, they handle it. 🫶

Parameters 🎀

  • esysContext — The ESYS_CONTEXT. The holder of the whole ESAPI vibe.
  • policySession — Handle for the policy session.
  • shandle1 — First session handle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • policyDigest — The current value of the policySession->policyDigest. (callee-allocated — meaning the function's side does the allocating, slay.)

Return values ⭐

  • TSS2_RC_SUCCESS — if the function call was a success. We love a win. 🎉
  • 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. Ruh-roh. 💀
  • 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. 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.
  • TSS2_ESYS_RC_MALFORMED_RESPONSE — if the TPM's response is corrupted. Not the serve we wanted. 😭
  • TSS2_ESYS_RC_RSP_AUTH_FAILED — if the response HMAC from the TPM did not verify. Auth said no. 🙈
  • TSS2_ESYS_RC_MULTIPLE_DECRYPT_SESSIONS — if more than one session has the 'decrypt' attribute bit set. Two is too many, pick one. ✋
  • 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. Identity crisis, lowkey.
  • 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. The stack does not filter, periodt. 💅

TSS2_RC Esys_PolicyGetDigest_Async (ESYS_CONTEXT * esysContext, ESYS_TR policySession, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3) 💜

Asynchronous function for TPM2_PolicyGetDigest

This one invokes the TPM2_PolicyGetDigest command in its asynchronous variant. Meaning: it returns as soon as the command has been sent downwards the stack to the TPM — it does not wait around. It dips. 👋

All input parameters are const, as always. And when you actually want the TPM's response, you gotta call Esys_PolicyGetDigest_Finish. That's the whole tradeoff. 🎯

Parameters 🌸

  • esysContext — The ESYS_CONTEXT.
  • policySession — Handle for the policy session.
  • shandle1 — First session handle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.

Return values 🔥

  • ESYS_RC_SUCCESS — if the function call was a success. (Yes bestie, the original literally says ESYS_RC_SUCCESS here — I'm not fixing it, that's what it says.)
  • 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. (This one appears loud and early in the list, no cap.)
  • 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_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_RC Esys_PolicyGetDigest_Finish (ESYS_CONTEXT * esysContext, TPM2B_DIGEST ** policyDigest) 🧚

Asynchronous finish function for TPM2_PolicyGetDigest

This function returns the results of a TPM2_PolicyGetDigest command invoked via... okay so the original text literally says "invoked via Esys_PolicyGetDigest_Finish" right here — I'm keeping it exactly, even though the vibe is that you'd pair it with the Async one. Manpage says what manpage says. 🤷‍♀️

All non-simple output parameters are allocated by the function's implementation. And here's a cute one: NULL can be passed for every output parameter if the value is not required. Not needed? Just pass NULL and move on, queen. 👑

Parameters 🌺

  • esysContext — The ESYS_CONTEXT.
  • policyDigest — The current value of the policySession->policyDigest. (callee-allocated)

Return values 🌟

  • TSS2_RC_SUCCESS — on success.
  • ESYS_RC_SUCCESS — if the function call was a success. (Yup, both success lines are here in the original — all the details, bestie. 💖)
  • 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. Not a fail, just a "maybe later". ⏳
  • 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 🍓

So like, this entire page was generated automatically by Doxygen for tpm2-tss from the source code. No human wrote it, it just spawned like that. Iconic, honestly. ✨

Okay bestie, that's the whole page! Brought to you by tpm2-tss, Version 4.1.5 — slay forever, and remember: always check your return codes. 🫶💖✨

📦 where this page comes from