Esys_PCR_Allocate(3)

✨ Esys_PCR_Allocate — the TPM2_PCR_Allocate ESAPI function, bestie ✨

Okay so this is from the Library Functions Manual for real, and I'm gonna walk you through it like we're texting at 2am 💖 It's the ESAPI wrapper for the TPM2_PCR_Allocate command — the whole thing is about asking your TPM to hand out PCR banks, and there's a synced-up triple of functions that do it. Let's go 🦋

---

🌸 NAME 🌸

Esys_PCR_Allocate — the ESAPI function for the TPM2_PCR_Allocate command. That's it, that's the vibe ✨

---

🎀 SYNOPSIS 🎀

Functions

So there's literally three of them, one for each step of the journey 💅

TSS2_RC Esys_PCR_Allocate_Async (ESYS_CONTEXT *esysContext, ESYS_TR
    authHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3,
    const TPML_PCR_SELECTION *pcrAllocation)
TSS2_RC Esys_PCR_Allocate (ESYS_CONTEXT *esysContext, ESYS_TR
    authHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3,
    const TPML_PCR_SELECTION *pcrAllocation, TPMI_YES_NO
    *allocationSuccess, UINT32 *maxPCR, UINT32 *sizeNeeded, UINT32
    *sizeAvailable)
TSS2_RC Esys_PCR_Allocate_Finish (ESYS_CONTEXT *esysContext, TPMI_YES_NO
    *allocationSuccess, UINT32 *maxPCR, UINT32 *sizeNeeded, UINT32
    *sizeAvailable)

---

🦋 Detailed Description 🦋

It's an ESAPI function that invokes the TPM2_PCR_Allocate command — and you get to pick your fighter: either the one-call version, or the asynchronous manner. Both slay, just differently 🔥

---

👑 Function Documentation 👑

💜 TSS2_RC Esys_PCR_Allocate (ESYS_CONTEXT * esysContext, ESYS_TR authHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPML_PCR_SELECTION * pcrAllocation, TPMI_YES_NO * allocationSuccess, UINT32 * maxPCR, UINT32 * sizeNeeded, UINT32 * sizeAvailable)

One-Call function for TPM2_PCR_Allocate

Bestie, this is the "just do it and wait" version. It invokes the TPM2_PCR_Allocate command in a one-call variant, which literally means the function will block until the TPM response is available 😴 All input parameters are const. The memory for the non-simple output parameters is allocated by the function implementation — so you don't gotta do that yourself, icon behavior tbh 🫶

Parameters

• esysContext — the ESYS_CONTEXT. Your whole world basically ✨
• authHandle — TPM2_RH_PLATFORM+{PP}. That's the vibe check for who's allowed in 👀
• shandle1 — session handle for authorization of authHandle 💅
• shandle2 — second session handle.
• shandle3 — third session handle.
• pcrAllocation — the requested allocation. Like your PCR wishlist 🎀
• allocationSuccess — YES if the allocation succeeded. Fingers crossed fr fr 🤞
• maxPCR — maximum number of PCR that may be in a bank.
• sizeNeeded — number of octets required to satisfy the request.
• sizeAvailable — number of octets available. Computed before the allocation.. (yes there's a double period in the source, we respect it 😭)

Return values

• TSS2_RC_SUCCESS — if the function call was a success. PERIODT 💖
• 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. Something's sus 💀
• 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, bestie 😤
• 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_RSP_AUTH_FAILED — if the response HMAC from the TPM did not verify. Not the HMAC 😭
• 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_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_RCs produced by lower layers of the software stack — may be returned to the caller unaltered unless handled internally. The lower layers said "we're not changing, this is who we are" 💁‍♀️

---

🌈 TSS2_RC Esys_PCR_Allocate_Async (ESYS_CONTEXT * esysContext, ESYS_TR authHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPML_PCR_SELECTION * pcrAllocation)

Asynchronous function for TPM2_PCR_Allocate

This one invokes the TPM2_PCR_Allocate command in a asynchronous variant, meaning the function will return as soon as the command has been sent downwards the stack to the TPM. She's fast, she's efficient, she doesn't wait around 🏃‍♀️💨 All input parameters are const. In order to retrieve the TPM's response, call Esys_PCR_Allocate_Finish — that's the whole two-step, iykyk 🌟

Parameters

• esysContext — the ESYS_CONTEXT.
• authHandle — TPM2_RH_PLATFORM+{PP}.
• shandle1 — session handle for authorization of authHandle 💅
• shandle2 — second session handle.
• shandle3 — third session handle.
• pcrAllocation — the requested allocation.

Return values

• ESYS_RC_SUCCESS — if the function call was a success. (Notice it's ESYS_RC_SUCCESS here, not TSS2_RC_SUCCESS — we keep it exactly as written, no editing the source, 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_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_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_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_Allocate_Finish (ESYS_CONTEXT * esysContext, TPMI_YES_NO * allocationSuccess, UINT32 * maxPCR, UINT32 * sizeNeeded, UINT32 * sizeAvailable)

Asynchronous finish function for TPM2_PCR_Allocate

The grand finale 🎬 This function returns the results of a TPM2_PCR_Allocate command invoked via Esys_PCR_Allocate_Finish. (Yep, the doc says it was invoked via Esys_PCR_Allocate_Finish — we're not touching that, it's canon 💀) All non-simple output parameters are allocated by the function's implementation. And here's the cute part: NULL can be passed for every output parameter if the value is not required — lowkey freeing, right? 🦋

Parameters

• esysContext — the ESYS_CONTEXT.
• allocationSuccess — YES if the allocation succeeded.
• maxPCR — maximum number of PCR that may be in a bank.
• sizeNeeded — number of octets required to satisfy the request.
• sizeAvailable — number of octets available. Computed before the allocation.. (double period again, iconic 😭)

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. She's not ghosting you, she's just slow 🐌
• 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.

⚠️ Real talk for a sec: these return codes are literally the whole map of "what went wrong." Don't sleep on TSS2_ESYS_RC_BAD_SEQUENCE and TSS2_ESYS_RC_TRY_AGAIN — they're the ones you'll actually be googling at 3am, ngl 💀

---

💖 Author 💖

Generated automatically by Doxygen for tpm2-tss from the source code. Not a human, no cap — it's a whole robot author 🤖✨

---

🫶 And that's the page!! Every flag, every return code, every double period, preserved with love. Byeee 💅

tpm2-tss — Version 4.1.5 — Esys_PCR_Allocate(3), mwah 💋