TSPI_CONTEXT_REGISTERKEY(3)

💖 Tspi_Context_RegisterKey(3) 💖

Library Functions Manual ✨ TCG Software Stack Developers Reference

okay bestie, we're deep in the TCG Software Stack docs now, and this one is a whole moment. sit down, hydrate, and let's get into it 🫶

✨ NAME ✨

Tspi_Context_RegisterKey — register a key in the TSS Persistent Storage database 🎀

🌸 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_RegisterKey(TSS_HCONTEXT hContext,                    TSS_HKEY hKey,
                                    TSS_FLAG     persistentStorageType,       TSS_UUID uuidKey,
                                    TSS_FLAG     persistentStorageTypeParent, TSS_UUID uuidParentKey);

like yes, that's a lot of headers, and yes, you need all of them. we don't make the rules 💅

🦋 DESCRIPTION 🦋

So, Tspi_Context_RegisterKey is the API that registers a key with the TSS Persistent Storage database, so that it can be loaded as necessary. it's giving "save your fave so you can summon it later" ✨

and it doesn't just drop the name in there — it also includes all the info required for loading the key, plus information about its parent key. full context, no crumbs. periodt.

🎀 PARAMETERS 🎀

hContext

the hContext parameter is the handle of the context object. your whole vibe starts here.

hKey

the hKey parameter is the handle of the key object addressing the key to be registered. this is the key that's getting its moment 👑

persistentStorageType

the persistentStorageType parameter indicates the persistent storage the key is registered in. telling us where the key lives, basically.

uuidKey

the uuidKey parameter is the UUID by which the key is registered in persistent storage. its little name tag 🏷️

persistentStorageTypeParent

the persistentStorageTypeParent parameter indicates the persistent storage that the parent key is registered in. yes, the parent gets its own storage-type argument. family matters 💜

uuidParentKey

the uuidParentKey parameter is the UUID by which the parent key is registered in persistent storage. the parent's name tag, separately specified, because of course.

💀 RETURN CODES 💀

Tspi_Context_RegisterKey returns TSS_SUCCESS on success — slay — otherwise one of the following values is returned:

• TSS_E_INVALID_HANDLE — hContext is not a valid handle. the handle said "not today" 😭
• TSS_E_PS_KEY_NOTFOUND — the key cannot be found in the persistent storage database. it's not there, bestie, we looked everywhere 🙈
• TSS_E_INTERNAL_ERROR — an internal SW error has been detected. not us, it's an internal thing 💀
• TSS_E_BAD_PARAMETER — one or more parameters is bad. something in the argument list is misbehaving 🚩

🌈 EXAMPLE 🌈

here's the whole storyline, top to bottom:

#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
}

see how it flows? create the context, connect to the TCSD, make the key object, load the parent by UUID, do your policy/secret handling, create the key, register it, use it, then unregister on the way out. that's the whole arc, main character energy from start to finish 🌟

⭐ CONFORMING TO ⭐

Tspi_Context_RegisterKey conforms to the Trusted Computing Group Software Specification version 1.1 Golden. certified iconic, no notes.

👑 SEE ALSO 👑

• Tspi_Context_UnregisterKey(3)
• Tspi_Context_LoadKeyByUUID(3)
• Tspi_Context_GetRegisteredKeyByUUID(3)

and that's the page, bestie 🫶 this was TSS 1.1, dated 2004-05-25, and it lives in Tspi_Context_RegisterKey(3). go register something 💖✨🎀