Esys_Sign(3)

📦
version 4.1.5 · 8 versions
, in fedora 44

💅 Esys_Sign — the ESAPI function for the TPM2_Sign command 🎀

Okay so bestie, welcome to Esys_Sign(3), straight out of the tpm2-tss library functions manual. This is the ESAPI glow-up of the TPM2_Sign command, and trust me, once you get it you're gonna be signing digests like it's nothing. ✨

🌸 NAME 🌸

Esys_Sign — literally the ESAPI function for the TPM2_Sign command. That's the whole vibe. 💖

🦋 SYNOPSIS 🦋

Functions

TSS2_RC Esys_Sign_Async (ESYS_CONTEXT *esysContext, ESYS_TR keyHandle,
    ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const
    TPM2B_DIGEST *digest, const TPMT_SIG_SCHEME *inScheme, const
    TPMT_TK_HASHCHECK *validation)

TSS2_RC Esys_Sign (ESYS_CONTEXT *esysContext, ESYS_TR keyHandle, ESYS_TR
    shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_DIGEST
    *digest, const TPMT_SIG_SCHEME *inScheme, const TPMT_TK_HASHCHECK
    *validation, TPMT_SIGNATURE **signature)

TSS2_RC Esys_Sign_Finish (ESYS_CONTEXT *esysContext, TPMT_SIGNATURE
    **signature)

Three functions, one mission: get that digest signed. 👑

🌈 Detailed Description 🌈

ESAPI function to invoke the TPM2_Sign command — either as a one-call or in an asynchronous manner. Pick your fighter, both are iconic. 💅

💜 Function Documentation 💜

⭐ TSS2_RC Esys_Sign (ESYS_CONTEXT * esysContext, ESYS_TR keyHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_DIGEST * digest, const TPMT_SIG_SCHEME * inScheme, const TPMT_TK_HASHCHECK * validation, TPMT_SIGNATURE ** signature)

One-Call function for TPM2_Sign 🫶

So this one invokes the TPM2_Sign command in a one-call variant. Which means... the function will literally block until the TPM response is available. No cap, it just sits there and waits for the TPM to text back. 😭 All input parameters are const. And the memory for non-simple output parameters is allocated by the function implementation — so she provides, you receive. 🎁

🌸 Parameters

  • esysContext — The ESYS_CONTEXT.
  • keyHandle — Handle of key that will perform signing. (The main character of this whole operation, honestly.)
  • shandle1 — Session handle for authorization of keyHandle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • digest — Digest to be signed. ✍️
  • inScheme — TPM2_Signing scheme to use if the scheme for keyHandle is TPM2_ALG_NULL.
  • validation — Proof that digest was created by the TPM.
  • signature — The signature. (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_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_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_Sign_Async (ESYS_CONTEXT * esysContext, ESYS_TR keyHandle, ESYS_TR shandle1, ESYS_TR shandle2, ESYS_TR shandle3, const TPM2B_DIGEST * digest, const TPMT_SIG_SCHEME * inScheme, const TPMT_TK_HASHCHECK * validation)

Asynchronous function for TPM2_Sign 🦋

This one invokes the TPM2_Sign command in a asynchronous variant. Translation: the function returns as soon as the command has been sent downwards the stack to the TPM — she does NOT wait around, she has places to be. 💨 All input parameters are const. In order to retrieve the TPM's response, call Esys_Sign_Finish. That's the whole two-step. iykyk. ✨

🌸 Parameters

  • esysContext — The ESYS_CONTEXT.
  • keyHandle — Handle of key that will perform signing.
  • shandle1 — Session handle for authorization of keyHandle.
  • shandle2 — Second session handle.
  • shandle3 — Third session handle.
  • digest — Digest to be signed.
  • inScheme — TPM2_Signing scheme to use if the scheme for keyHandle is TPM2_ALG_NULL.
  • validation — Proof that digest was created by the TPM.

🎀 Return values

  • ESYS_RC_SUCCESS — if the function call was a success. (Yes bestie, that's how it's written in the source — keep it exactly like that. 🙈)
  • 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_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_Sign_Finish (ESYS_CONTEXT * esysContext, TPMT_SIGNATURE ** signature)

Asynchronous finish function for TPM2_Sign 🧚

This is the part two, the ~resolution~, the third act. 💖 This function returns the results of a TPM2_Sign command invoked via Esys_Sign_Finish. 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. Low-maintenance queen. 👑

🫶 Ngl, the source really does say "invoked via Esys_Sign_Finish" right there — that's the text, we keep it, we don't touch it.

🌸 Parameters

  • esysContext — The ESYS_CONTEXT.
  • signature — The signature. (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. 😭 (be patient, she's typing…)
  • 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. So nobody hand-wrote this, it's giving machine-made icon behavior. 🤖✨

Okay bestie, that's the whole page! Go sign those digests. Mwah 💋

tpm2-tss · Version 4.1.5 · Esys_Sign(3) — that's the version and date situation, signed off with love 🎀💖

📦 where this page comes from