Fapi_GetRandom(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

💅 Fapi_GetRandom(3) ✨

okay so this is a page from the Library Functions Manual, bestie — yes, a real manpage, and yes it's about grabbing random bytes from your TPM. it's giving "crypto snack time". let's go 🎀

🌸 NAME 🌸

Fapi_GetRandom — literally just Fapi_GetRandom. that's the whole name. iconic minimalism, no notes 💅

✨ SYNOPSIS ✨

🦋 Functions

TSS2_RC Fapi_GetRandom (FAPI_CONTEXT *context, size_t numBytes, uint8_t
    **data)
TSS2_RC Fapi_GetRandom_Async (FAPI_CONTEXT *context, size_t numBytes)
TSS2_RC Fapi_GetRandom_Finish (FAPI_CONTEXT *context, uint8_t **data)

🌈 Detailed Description 🌈

so these are the FAPI functions that invoke GetRandom — and you can do it either as a one-call (easy mode, one and done, slay) or in an asynchronous manner (the "start it, come back later" main-character route). pick your vibe 🫶

👑 Function Documentation 👑

💖 TSS2_RC Fapi_GetRandom (FAPI_CONTEXT * context, size_t numBytes, uint8_t ** data)

the one-call function for Fapi_GetRandom — bestie, this is the whole thing in one go ✨

it creates an array with a specified number of bytes. and here's the tea: it may execute the underlying TPM command multiple times if the requested number of bytes is too big. like, the TPM's not gonna do it all in one breath, so it just... keeps asking. no cap 🔥

🍓 Parameters

  • context — the FAPI_CONTEXT
  • numBytes — the number of bytes requested from the TPM
  • data — the array of random bytes returned from the TPM

💀 Return values

  • TSS2_RC_SUCCESS if the function call was a success.
  • TSS2_FAPI_RC_BAD_REFERENCE if context or data is NULL.
  • TSS2_FAPI_RC_BAD_CONTEXT if context corruption is detected.
  • TSS2_FAPI_RC_BAD_VALUE if numBytes is 0.
  • TSS2_FAPI_RC_BAD_SEQUENCE if the context has an asynchronous operation already pending.
  • TSS2_FAPI_RC_IO_ERROR if the data cannot be saved.
  • TSS2_FAPI_RC_MEMORY if the FAPI cannot allocate enough memory for internal operations or return parameters.
  • TSS2_FAPI_RC_NO_TPM if FAPI was initialized in no-TPM-mode via its config file.
  • TSS2_FAPI_RC_PATH_NOT_FOUND if a FAPI object path was not found during authorization.
  • TSS2_FAPI_RC_KEY_NOT_FOUND if a key was not found.
  • TSS2_FAPI_RC_TRY_AGAIN if an I/O operation is not finished yet and this function needs to be called again.
  • TSS2_FAPI_RC_GENERAL_FAILURE if an internal error occurred.
  • TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN if a required authorization callback is not set.
  • TSS2_FAPI_RC_AUTHORIZATION_FAILED if the authorization attempt fails.
  • TSS2_FAPI_RC_POLICY_UNKNOWN if policy search for a certain policy digest was not successful.
  • TSS2_ESYS_RC_* possible error codes of ESAPI.
  • TSS2_FAPI_RC_NOT_PROVISIONED FAPI was not provisioned.
  • TSS2_FAPI_RC_BAD_PATH if the path is used in inappropriate context or contains illegal characters.

🧚 TSS2_RC Fapi_GetRandom_Async (FAPI_CONTEXT * context, size_t numBytes)

the asynchronous function for Fapi_GetRandom. same energy, but you're not waiting around for it 🌸

it creates an array with a specified number of bytes, and yeah — it may execute the underlying TPM command multiple times if the requested number of bytes is too big. same deal as before, fr fr.

💡 call Fapi_GetRandom_Finish to finish the execution of this command. don't leave it hanging, bestie 😭

🍓 Parameters

  • context — the FAPI_CONTEXT
  • numBytes — the number of bytes requested from the TPM

💀 Return values

  • TSS2_RC_SUCCESS if the function call was a success.
  • TSS2_FAPI_RC_BAD_REFERENCE if context is NULL.
  • TSS2_FAPI_RC_BAD_CONTEXT if context corruption is detected.
  • TSS2_FAPI_RC_BAD_VALUE if numBytes is 0.
  • TSS2_FAPI_RC_BAD_SEQUENCE if the context has an asynchronous operation already pending.
  • TSS2_FAPI_RC_IO_ERROR if the data cannot be saved.
  • TSS2_FAPI_RC_MEMORY if the FAPI cannot allocate enough memory for internal operations or return parameters.
  • TSS2_FAPI_RC_NO_TPM if FAPI was initialized in no-TPM-mode via its config file.
  • TSS2_FAPI_RC_PATH_NOT_FOUND if a FAPI object path was not found during authorization.
  • TSS2_FAPI_RC_KEY_NOT_FOUND if a key was not found.
  • TSS2_FAPI_RC_NOT_PROVISIONED FAPI was not provisioned.
  • TSS2_FAPI_RC_BAD_PATH if the path is used in inappropriate context or contains illegal characters.

🎀 TSS2_RC Fapi_GetRandom_Finish (FAPI_CONTEXT * context, uint8_t ** data)

the asynchronous finish function for Fapi_GetRandom — the part where you come back and collect your little gift 🎁

🫶 this function should be called after a previous Fapi_GetRandom_Async. like, that's the whole point, okay?

🍓 Parameters

  • context — the FAPI_CONTEXT
  • data — the array of random bytes returned from the TPM

💀 Return values

  • TSS2_RC_SUCCESS if the function call was a success.
  • TSS2_FAPI_RC_BAD_REFERENCE if context or data is NULL.
  • TSS2_FAPI_RC_BAD_CONTEXT if context corruption is detected.
  • TSS2_FAPI_RC_BAD_SEQUENCE if the context has an asynchronous operation already pending.
  • TSS2_FAPI_RC_IO_ERROR if the data cannot be saved.
  • TSS2_FAPI_RC_MEMORY if the FAPI cannot allocate enough memory for internal operations or return parameters.
  • TSS2_FAPI_RC_TRY_AGAIN if the asynchronous operation is not yet complete. Call this function again later.
  • TSS2_FAPI_RC_GENERAL_FAILURE if an internal error occurred.
  • TSS2_FAPI_RC_BAD_VALUE if an invalid value was passed into the function.
  • TSS2_FAPI_RC_PATH_NOT_FOUND if a FAPI object path was not found during authorization.
  • TSS2_FAPI_RC_KEY_NOT_FOUND if a key was not found.
  • TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN if a required authorization callback is not set.
  • TSS2_FAPI_RC_AUTHORIZATION_FAILED if the authorization attempt fails.
  • TSS2_FAPI_RC_POLICY_UNKNOWN if policy search for a certain policy digest was not successful.
  • TSS2_ESYS_RC_* possible error codes of ESAPI.
  • TSS2_FAPI_RC_NOT_PROVISIONED FAPI was not provisioned.
  • TSS2_FAPI_RC_BAD_PATH if the path is used in inappropriate context or contains illegal characters.

🦋 Author 🦋

Generated automatically by Doxygen for tpm2-tss from the source code. not me being auto-generated by Doxygen 😭 she's literally built different 💅

and that's the page, bestie 🫶 mwah 💖

this masterpiece of automated documentation is served up courtesy of tpm2-tss — Version 4.1.5 — dated on the Fapi_GetRandom(3) page, periodt ✨💜

📦 where this page comes from