Tspi_C...terKey(3)

✨ NAME ✨

Tspi_Context_UnregisterKey — bestie, this is the one that unregisters a key from the persistent storage device. Yes, we're deleting. We're cleaning up. We're letting go 💅

🌸 SYNOPSIS 🌸

#include <tss/platform.h>
#include <tss/tcpa_defines.h>
#include <tss/tcpa_typedef.h>
#include <tss/tcpa_struct.h>
#include <tss/tss_typedef.h>
#include <tss/tss_structs.h>
#include <tss/tspi.h>

TSS_RESULT Tspi_Context_UnregisterKey(TSS_HCONTEXT hContext, TSS_FLAG  persistentStorageType,
                                      TSS_UUID     uuidKey,  TSS_HKEY* phKey);

okay so like all seven of those includes? yeah you need every single one of them, no skipping 🎀 that's the whole TCG Software Stack Developer's Reference vibe, and this page lives in it.

🦋 DESCRIPTION 🦋

TSS_Context_UnregisterKey provides the capabilities of the TSS Core Service or TSS Service Provider. that's it, that's the whole description, it's giving minimal but iconic 👑

💖 PARAMETERS 💖

• hContext — the handle of the context object. your little context bestie 🫶
• persistentStorageType — a flag indicating the persistent storage.
• uuidKey — the UUID of the key to be removed from the persistent storage. this is the one getting evicted, no hard feelings ✨
• phKey — recieves the handle of a key object containing the information from the archive. (yes, "recieves". we keep the typo, we respect the typo 💀)
• pulRespDataLength — recieves the length (in bytes) of the prgbRespData parameter.
• prgbRespData — on successful completion of the command, this parameter points to the buffer containing the actual data of the specified capability. The handle of the object to be destroyed.

⭐ RETURN CODES ⭐

Tspi_Context_UnregisterKey returns TSS_SUCCESS on success 🎉 otherwise, one of these lil guys comes back instead:

• TSS_E_INVALID_HANDLE — the parameter hContext is an invalid parameter. not it 😭
• TSS_E_PS_KEY_NOTFOUND — the parameter uuidKey is an invalid UUID.
• TSS_E_INTERNAL_ERROR — An error occurred internal to the TSS.

🔥 EXAMPLE 🔥

here's the whole thing, verbatim, no cap:

#include <trousers/tss.h>

int
main(void)
{
     TSS_FLAGS initFlags = ...;
     TSS_HKEY  hKey, hSRK;
     TSS_UUID  keyUUID = {...};

     // Create a TSP handle
     result = Tspi_Context_Create(&hContext);
     if (result != TSS_SUCCESS)
          Error_Path();

     // Connect to the TCSD
     result = Tspi_Context_Connect(hContext, GLOBALSERVER);
     if (result != TSS_SUCCESS)
          Error_Path();

     // Create the Key Object
     result = Tspi_Context_CreateObject(hContext,
               TSS_OBJECT_TYPE_RSAKEY,
               initFlags, &hKey);
     if (result != TSS_SUCCESS)
          Error_Path();

     // Load parent Key by UUID
     result = Tspi_Context_LoadKeyByUUID(hContext, TSS_PS_TYPE_SYSTEM,
               SRK_UUID, &hSRK);
     if (result != TSS_SUCCESS)
          Error_Path();

     // Do policy/secret handling here

     result = Tspi_Key_CreateKey(hKey, hSRK, 0);
     if (result != TSS_SUCCESS)
          Error_Path();

     // Register the Key in System PS (on the TCSD's platform)
     result = Tspi_Context_RegisterKey(hContext, hKey, TSS_PS_TYPE_SYSTEM,
               keyUUID, TSS_PS_TYPE_SYSTEM,
               SRK_UUID);
     if (result != TSS_SUCCESS)
          Error_Path();

     /* ...
      *
      * Use the key as needed, exiting the program if necessary, reloading
      * the key using Tspi_Context_LoadKeyByUUID() after each restart. Once
      * the key is no longer useful, unregister it from system PS as part
      * of clean up.
      */

     // Unregister the Key
     result = Tspi_Context_UnregisterKey(hContext, TSS_PS_TYPE_SYSTEM,
               migratableSignUUID, &hKey);
     if (result != TSS_SUCCESS)
          Error_Path();

     // exit, discarding hKey
}

🌈 CONFORMING TO 🌈

Tspi_Context_UnregisterKey conforms to the Trusted Computing Group Software Specification version 1.1 Golden ✨ (yes, Golden, it's giving main character energy fr fr)

👑 SEE ALSO 👑

• Tspi_Key_CreateKey(3)
• Tspi_Context_RegisterKey(3)

and that's the page bestie!! this gem is from the TCG Software Stack Developer's Reference, TSS 1.1, dated 2004-05-26 — old but iconic, we stan a vintage manpage 🎀💜 mwah, go unregister something responsibly ✨