ESYS_DICTIONARYATTACKPARAMETERS(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

✨ NAME ✨

Esys_DictionaryAttackParameters — the ESAPI function for the TPM2_DictionaryAttackParameters command, bestie 💅

(yeah so this is a page from the tpm2-tss library functions manual, and it's lowkey about locking down your TPM when people keep guessing wrong 🔐)

🦋 SYNOPSIS 🦋

Functions

TSS2_RC Esys_DictionaryAttackParameters_Async (ESYS_CONTEXT
    *esysContext, ESYS_TR lockHandle, ESYS_TR shandle1, ESYS_TR
    shandle2, ESYS_TR shandle3, UINT32 newMaxTries, UINT32
    newRecoveryTime, UINT32 lockoutRecovery)
TSS2_RC Esys_DictionaryAttackParameters (ESYS_CONTEXT *esysContext,
    ESYS_TR lockHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR
    shandle3, UINT32 newMaxTries, UINT32 newRecoveryTime, UINT32
    lockoutRecovery)
TSS2_RC Esys_DictionaryAttackParameters_Finish (ESYS_CONTEXT
    *esysContext)

💖 Detailed Description 💖

It's an ESAPI function that invokes the TPM2_DictionaryAttackParameters command. You can call it two ways, queen: as a one-call, or in an asynchronous manner ✨ pick your vibe.

🎀 Function Documentation 🎀

🌸 TSS2_RC Esys_DictionaryAttackParameters (ESYS_CONTEXT * esysContext, ESYS_TR lockHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT32 newMaxTries, UINT32 newRecoveryTime, UINT32 lockoutRecovery)

One-call function for TPM2_DictionaryAttackParameters 🫶

So here's the tea: this function invokes the TPM2_DictionaryAttackParameters command in a one-call variant. That means it will block until the TPM response is available 😴 (yes, actually wait for it, no cap). All input parameters are const. The memory for non-simple output parameters is allocated by the function implementation — she handles it, don't worry 💅

Parameters

  • esysContext — The ESYS_CONTEXT.
  • lockHandle — TPM2_RH_LOCKOUT.
  • shandle1 — Session handle for authorization of lockHandle
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • newMaxTries — Count of authorization failures before the lockout is imposed.
  • newRecoveryTime — Time in seconds before the authorization failure count is automatically decremented.
  • lockoutRecovery — Time in seconds after a lockoutAuth failure before use of lockoutAuth is allowed.

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.
  • 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_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.

🦋 TSS2_RC Esys_DictionaryAttackParameters_Async (ESYS_CONTEXT * esysContext, ESYS_TR lockHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, UINT32 newMaxTries, UINT32 newRecoveryTime, UINT32 lockoutRecovery)

Asynchronous function for TPM2_DictionaryAttackParameters ⚡

This one invokes the TPM2_DictionaryAttackParameters command in a asynchronous variant — meaning the function will return as soon as the command has been sent downwards the stack to the TPM 🏃‍♀️💨 no waiting around, main character energy. All input parameters are const. In order to retrieve the TPM's response, call Esys_DictionaryAttackParameters_Finish (that's literally the whole point, iykyk).

Parameters

  • esysContext — The ESYS_CONTEXT.
  • lockHandle — TPM2_RH_LOCKOUT.
  • shandle1 — Session handle for authorization of lockHandle
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • newMaxTries — Count of authorization failures before the lockout is imposed.
  • newRecoveryTime — Time in seconds before the authorization failure count is automatically decremented.
  • lockoutRecovery — Time in seconds after a lockoutAuth failure before use of lockoutAuth is allowed.

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_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_DictionaryAttackParameters_Finish (ESYS_CONTEXT * esysContext)

Asynchronous finish function for TPM2_DictionaryAttackParameters 🏁

This function returns the results of a TPM2_DictionaryAttackParameters command invoked via Esys_DictionaryAttackParameters_Finish. All non-simple output parameters are allocated by the function's implementation. NULL can be passed for every output parameter if the value is not required — she's flexible like that 💅

Parameters

  • esysContext — The ESYS_CONTEXT.

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.

👑 Author 👑

Generated automatically by Doxygen for tpm2-tss from the source code. (not a human, just a very diligent robot 🧚)

okay that's the whole page bestie, go forth and lock out those dictionary attackers 💜

sign-off szn 🎀: this gorgeous little page comes to you from tpm2-tss, Version 4.1.5, and it's the Esys_Dicti...kParameters(3) entry in the Library Functions Manual. slay, bye! 💖✨

📦 where this page comes from