.\" Copyright (C) 2004 International Business Machines Corporation
.\" Written by Kathy Robertson 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_CreateObject" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference"
.SH NAME
Tspi_Context_CreateObject \- create an empty object and return a handle to that object.
.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_CreateObject(TSS_HCONTEXT " hContext ",  TSS_FLAG     " objectType ","
.BI "                                     TSS_FLAG     " initFlags ", TSS_HOBJECT* " phObject ");"
.fi
.sp
.ad
.hy
.SH "DESCRIPTION"
.PP
\fBTSS_Context_CreateObject\fR creates and initializes an empty object of the specified type and returns a handle addressing that object. The object is bound to an already opened context \fIhContext\fR.
.SH "PARAMETERS"
.PP
.SS hContext
The handle of the context object.
.PP
.SS objectType
Flag indicating the object type to create. Possible types are:
.TP
.SM TSS_OBJECT_TYPE_POLICY - a policy object.
.TP
.SM TSS_OBJECT_TYPE_ENCDATA - an encrypted data object (either sealed or bound data).
.TP
.SM TSS_OBJECT_TYPE_RSAKEY - an RSA key.
.TP
.SM TSS_OBJECT_TYPE_PCRS - a PCR composite object.
.TP
.SM TSS_OBJECT_TYPE_HASH - a hash object.
.PP
.SS initFlags
Flag indicating the default attributes of the object. Attributes for each type of object are:
.TP
.SM Policy:
 \fBTSS_POLICY_USAGE\fR - a usage policy (for authorization to use an object).
 \fBTSS_POLICY_MIGRATION\fR - a migration policy.
.TP
.SM Encrypted data objects:
 \fBTSS_ENCDATA_SEAL\fR - A data object used for a Seal operation.
 \fBTSS_ENCDATA_BIND\fR - A data object used for a Bind operation.
 \fBTSS_ENCDATA_LEGACY\fR - A data object for a bind operation using a legacy key.
.TP
.SM RSA Keys:
 \fBTSS_KEY_SIZE_DEFAULT\fR - Use the default key size of the TCS you're connected to.
 \fBTSS_KEY_SIZE_512\fR - Create a 512 bit key.
 \fBTSS_KEY_SIZE_1024\fR - Create a 1024 bit key.
 \fBTSS_KEY_SIZE_2048\fR - Create a 2048 bit key.
 \fBTSS_KEY_SIZE_4096\fR - Create a 4096 bit key.
 \fBTSS_KEY_SIZE_8192\fR - Create a 8192 bit key.
 \fBTSS_KEY_SIZE_16384\fR - Create a 16384 bit key.
 \fBTSS_KEY_TYPE_STORAGE\fR - Create a storage key. (Used to wrap other keys).
 \fBTSS_KEY_TYPE_SIGNING\fR - Create a signing key.
 \fBTSS_KEY_TYPE_BIND\fR - Create a binding key. (Used to encrypt data).
 \fBTSS_KEY_TYPE_IDENTITY\fR - Create an identity key. (Used for an identity).
 \fBTSS_KEY_TYPE_LEGACY\fR - Create a legacy key. (Can be used for signing and binding, created from data external to a TSS).
 \fBTSS_KEY_TYPE_AUTHCHANGE\fR - Create an ephemeral key used to change authorization values.
 \fBTSS_KEY_VOLATILE\fR - Create a volatile key. (Must be unloaded at startup).
 \fBTSS_KEY_NON_VOLATILE\fR - Create a non-volatile key. (May be unloaded at startup).
 \fBTSS_KEY_MIGRATABLE\fR - Create a migratable key.
 \fBTSS_KEY_NOT_MIGRATABLE\fR - Create a non-migratable key. [DEFAULT]
 \fBTSS_KEY_AUTHORIZATION\fR - Key will require authorization.
 \fBTSS_KEY_NO_AUTHORIZATION\fR - Key will not require authorization. [DEFAULT]
 \fBTSS_KEY_EMPTY_KEY\fR - Key template which will be returned as an object with very few attributes.

.TP
.SM PCR composite objects:
 None.
.TP
.SM Hash objects:
 \fBTSS_HASH_SHA1\fR - a hash object of type SHA-1.
 \fBTSS_HASH_OTHER\fR - a hash object of type other than SHA-1.
.PP
.PP
.SS phObject
The handle of the object to be created.

.SH "RETURN CODES"
.PP
\fBTspi_Context_CreateObject\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned:
.TP
.SM TSS_E_INVALID_HANDLE - Either \fIhContext\fR or \fIphObject\fR is an invalid handle. 
.TP
.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS.

.SH "CONFORMING TO"

.PP
\fBTspi_Context_CreateObject\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden
.SH "SEE ALSO"

.PP
\fBTspi_Context_CloseObject\fR(3).