Esys_NV_Read(3)

💅 Esys_NV_Read(3) — like, the ESAPI glow-up for TPM2_NV_Read

okay so bestie, we're in the Library Functions Manual section, page Esys_NV_Read(3), and this is genuinely one of those pages you're gonna want bookmarked. it's giving "cryptographic non-volatile storage but make it readable." let's get into it 🎀

---

✨ NAME ✨

Esys_NV_Read — the ESAPI function for the TPM2_NV_Read command. that's it, that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

Functions

TSS2_RC Esys_NV_Read_Async (ESYS_CONTEXT *esysContext, ESYS_TR
    authHandle, ESYS_TR nvIndex, ESYS_TR shandle1, ESYS_TR shandle2,
    ESYS_TR shandle3, UINT16 size, UINT16 offset)

TSS2_RC Esys_NV_Read (ESYS_CONTEXT *esysContext, ESYS_TR authHandle,
    ESYS_TR nvIndex, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR
    shandle3, UINT16 size, UINT16 offset, TPM2B_MAX_NV_BUFFER **data)

TSS2_RC Esys_NV_Read_Finish (ESYS_CONTEXT *esysContext,
    TPM2B_MAX_NV_BUFFER **data)

Detailed Description 💖

ESAPI function to invoke the TPM2_NV_Read command either as a one-call or in an asynchronous manner. yes bestie, you get options. main character energy fr fr. ✨

---

🦋 Function Documentation 🦋

💜 TSS2_RC Esys_NV_Read (ESYS_CONTEXT * esysContext, ESYS_TR authHandle, ESYS_TR nvIndex, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT16 size, UINT16 offset, TPM2B_MAX_NV_BUFFER ** data)

One-Call function for TPM2_NV_Read

so this one invokes the TPM2_NV_Read command in a one-call variant. what does that actually mean? it means the function will block until the TPM response is available — no sneaky async business, you just sit there and wait like a loyal bestie. 🫶

all input parameters are const. the memory for non-simple output parameters is allocated by the function implementation. so like, it handles the malloc-ing, not you. iconic behavior honestly.

Parameters

• esysContext — the ESYS_CONTEXT.
• authHandle — the handle indicating the source of the authorization value.
• nvIndex — the NV Index to be read.
• shandle1 — session handle for authorization of authHandle.
• shandle2 — second session handle.
• shandle3 — third session handle.
• size — number of octets to read.
• offset — octet offset into the area.
• data — the data read. (callee-allocated)

Return values

• TSS2_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. 😬 like girl, finish the last one first.
• 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.
• 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_RCs produced by lower layers of the software stack may be returned to the caller unaltered unless handled internally.

ngl, that's a lot of return codes, but like — read them, bestie. future you will be grateful. 🍓

---

🧚 TSS2_RC Esys_NV_Read_Async (ESYS_CONTEXT * esysContext, ESYS_TR authHandle, ESYS_TR nvIndex, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT16 size, UINT16 offset)

Asynchronous function for TPM2_NV_Read

this one invokes the TPM2_NV_Read command in a asynchronous variant. meaning: the function will return as soon as the command has been sent downwards the stack to the TPM. it does not wait around. it's the "seen 3:47pm" of function calls. 😭

all input parameters are const. in order to retrieve the TPM's response, call Esys_NV_Read_Finish. that's the whole point — async sends, Finish collects. 🎀

Parameters

• esysContext — the ESYS_CONTEXT.
• authHandle — the handle indicating the source of the authorization value.
• nvIndex — the NV Index to be read.
• shandle1 — session handle for authorization of authHandle.
• shandle2 — second session handle.
• shandle3 — third session handle.
• size — number of octets to read.
• offset — octet offset into the area.

Return values

• 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_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_RC Esys_NV_Read_Finish (ESYS_CONTEXT * esysContext, TPM2B_MAX_NV_BUFFER ** data)

Asynchronous finish function for TPM2_NV_Read

this is the collector. it returns the results of a TPM2_NV_Read command invoked via Esys_NV_Read_Finish. (yes, the page literally says Esys_NV_Read_Finish there — i'm not touching it, that's canon. 🫶)

all non-simple output parameters are allocated by the function's implementation. and the cute part: NULL can be passed for every output parameter if the value is not required. lowkey freeing, honestly.

Parameters

• esysContext — the ESYS_CONTEXT.
• data — the data read. (callee-allocated)

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. ⏰ (try again bestie, the vibes weren't ready)
• 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, not a vibe-checker — a parser. we respect it. 💀✨

---

and that's the page, bestie!! 🌸 go read your NV index, hydrate, and remember: Esys_NV_Read blocks, Esys_NV_Read_Async doesn't, and Esys_NV_Read_Finish picks up the pieces. iykyk. 💅🦋

this masterclass in TPM chaos was brought to you by tpm2-tss, Version 4.1.5 — that's the source + version for the sign-off, no date on this footer so don't come for me 🙈 — mwah, go slay your ESAPI calls 🎀