.\" Copyright (C) 2004 International Business Machines Corporation
.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden
.\"
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "Tspi_Context_RegisterKey" 3 "2004-05-25" "TSS 1.1"
.ce 1
TCG Software Stack Developers Reference
.SH NAME
Tspi_Context_RegisterKey \- register a key in the TSS Persistent Storage database
.SH "SYNOPSIS"
.ad l
.hy 0
.nf
.B #include <tss/platform.h>
.B #include <tss/tcpa_defines.h>
.B #include <tss/tcpa_typedef.h>
.B #include <tss/tcpa_struct.h>
.B #include <tss/tss_typedef.h>
.B #include <tss/tss_structs.h>
.B #include <tss/tspi.h>
.sp
.BI "TSS_RESULT Tspi_Context_RegisterKey(TSS_HCONTEXT " hContext ",                    TSS_HKEY " hKey ","
.BI "                                    TSS_FLAG     " persistentStorageType ",       TSS_UUID " uuidKey ","
.BI "                                    TSS_FLAG     " persistentStorageTypeParent ", TSS_UUID " uuidParentKey "); "
.fi
.sp
.ad
.hy

.SH "DESCRIPTION"
.PP
\fBTspi_Context_RegisterKey\fR is the API that
registers a key with the TSS Persistent Storage database so that it
can be loaded as necessary. It also includes all information required
for loading the key, as well as information about its parent key.

.SH "PARAMETERS"
.PP
.SS hContext
The \fIhContext\fR parameter is the handle of the context object.
.SS hKey
The \fIhKey\fR parameter is the handle of the key object addressing the key
to be registered.
.SS persistentStorageType
The \fIpersistentStorageType\fR parameter indicates the persistent
storage the key is registered in.
.SS uuidKey
The \fIuuidKey\fR parameter is the UUID by which the key is registered in
persistent storage.
.SS persistentStorageTypeParent
The \fIpersistentStorageTypeParent\fR parameter indicates the persistent storage
that the parent key is registered in.
.SS uuidParentKey
The \fIuuidParentKey\fR parameter is the UUID by which the parent key is
registered in persistent storage.

.SH "RETURN CODES"
.PP
\fBTspi_Context_RegisterKey\fR returns TSS_SUCCESS on success, otherwise
one of the following values is returned:
.TP
.SM TSS_E_INVALID_HANDLE
\fIhContext\fR is not a valid handle.

.TP
.SM TSS_E_PS_KEY_NOTFOUND
The key cannot be found in the persistent storage database.

.TP
.SM TSS_E_INTERNAL_ERROR
An internal SW error has been detected.

.TP
.SM TSS_E_BAD_PARAMETER
One or more parameters is bad.

.SH "EXAMPLE"
.nf
#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
}
.fi

.SH "CONFORMING TO"

.PP
\fBTspi_Context_RegisterKey\fR conforms to the Trusted Computing Group
Software Specification version 1.1 Golden

.SH "SEE ALSO"

.PP
\fBTspi_Context_UnregisterKey\fR(3), \fBTspi_Context_LoadKeyByUUID\fR(3),
\fBTspi_Context_GetRegisteredKeyByUUID\fR(3).