Esys_GetRandom(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

✨ Esys_GetRandom(3) ✨

okay bestie so real quick — this is a page from the Library Functions Manual for tpm2-tss, and it's literally the ESAPI function for the TPM2_GetRandom command 💖 random bytes from your TPM, no cap. come sit with me, i'll walk you through it 🫶

🌸 NAME 🌸

Esys_GetRandom — The ESAPI function for the TPM2_GetRandom command.

🦋 SYNOPSIS 🦋

Functions

TSS2_RC Esys_GetRandom_Async (ESYS_CONTEXT *esysContext, ESYS_TR
    shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT16 bytesRequested)
TSS2_RC Esys_GetRandom (ESYS_CONTEXT *esysContext, ESYS_TR shandle1,
    ESYS_TR shandle2, ESYS_TR shandle3, UINT16 bytesRequested,
    TPM2B_DIGEST **randomBytes)
TSS2_RC Esys_GetRandom_Finish (ESYS_CONTEXT *esysContext, TPM2B_DIGEST
    **randomBytes)

🧚 Detailed Description 🧚

so this here is the ESAPI function to invoke the TPM2_GetRandom command — and you've got two vibes to pick from: either as a one-call (blocking, one and done, main character energy 👑) or in an asynchronous manner (send it off and come back for the results later, lowkey efficient ✨).

💅 Function Documentation 💅

TSS2_RC Esys_GetRandom (ESYS_CONTEXT * esysContext, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT16 bytesRequested, TPM2B_DIGEST ** randomBytes)

One-Call function for TPM2_GetRandom 🔥

This function invokes the TPM2_GetRandom command in a one-call variant. Translation? The function will block until the TPM response is available — it literally sits there waiting, so dramatic 😭. All input parameters are const. The memory for non-simple output parameters is allocated by the function implementation (not you, bestie — it's handled 🫶).

Parameters

  • esysContext — The ESYS_CONTEXT.
  • shandle1 — First session handle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • bytesRequested — Number of octets to return.
  • randomBytes — The random octets. (callee-allocated)

Return values

  • TSS2_RC_SUCCESS — if the function call was a success. slay 🎀
  • 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_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_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. (iykyk 🌀)

TSS2_RC Esys_GetRandom_Async (ESYS_CONTEXT * esysContext, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT16 bytesRequested)

Asynchronous function for TPM2_GetRandom 🦋

This function invokes the TPM2_GetRandom command in a asynchronous variant. It's giving "sent, not read" — the function 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_GetRandom_Finish (that's the part where you actually get your goodies back 🎁).

Parameters

  • esysContext — The ESYS_CONTEXT.
  • shandle1 — First session handle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • bytesRequested — Number of octets to return.

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_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_GetRandom_Finish (ESYS_CONTEXT * esysContext, TPM2B_DIGEST ** randomBytes)

Asynchronous finish function for TPM2_GetRandom 🌈

This function returns the results of a TPM2_GetRandom command invoked via Esys_GetRandom_Finish (yes, the page literally says that — quoting it exactly, bestie, don't @ me 🙈). All non-simple output parameters are allocated by the function's implementation. And good news: NULL can be passed for every output parameter if the value is not required — flex that freedom 💅.

Parameters

  • esysContext — The ESYS_CONTEXT.
  • randomBytes — The random octets. (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.
  • 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.
bestie note 🎀 — Esys_GetRandom lists TSS2_RC_SUCCESS for its success return, but Esys_GetRandom_Async lists ESYS_RC_SUCCESS. that's literally what the page says, so i'm not touching it. also only Esys_GetRandom and Esys_GetRandom_Finish mention TSS2_ESYS_RC_BAD_SEQUENCE, and only _Finish has TSS2_ESYS_RC_TRY_AGAIN. no cap, read the lists 💜

👑 Author 👑

Generated automatically by Doxygen for tpm2-tss from the source code. (the robots wrote it, we just gave it ✨flavor✨)

and that's the whole page, bestie 🍓 go get those random octets.

tpm2-tss — Version 4.1.5 — Esys_GetRandom(3) 💜🦋🎀 mwah, see u in the next manpage 💅

📦 where this page comes from