iaik.tc.tss.api.tspi
Interface TcIContext

All Superinterfaces:

TcIAttributes, TcIWorkingObject

public interface TcIContext
extends TcIWorkingObject, TcIAttributes

The Context class represents a context of a connection to the TSS Core Service running on the local or a remote TCG system.
The focus of the Context object is:

• to provide a connection to a TSS Core Service. There might be multiple connections to the same or different core services.
• to provide functions for resource management and freeing of memory
• to create working objects.
• to establish a default policy for working objects as well as a policy object for the TPM object representing the TPM owner.
• to provide functionality to access the persistent storage database.

Method Summary

void	closeContext() This method destroys the object associated with the object handle.
void	closeObject(TcIWorkingObject obj) This method is used to close a given object.
void	connect() This method tries to connect the context to the default host (localhost).
void	connect(String hostname) This method tries to connect the context to a host running a TCS service.
TcIEncData	createEncDataObject(long initFlags) This method returns a new encdata object.
TcIHash	createHashObject(long initFlags) This method returns a new hash object.
TcIPcrComposite	createPcrCompositeObject(long initFlags) This method returns a new PCR object.
TcIPolicy	createPolicyObject(long initFlags) This method returns a new policy object.
TcIRsaKey	createRsaKeyObject(long initFlags) This method returns a new key object.
void	freeMemory(long cPtr) This method frees memory allocated by TSS Service Provider on a context base.
TcBlobData	getCapability(long capArea, TcBlobData subCap) This method provides the capabilities of the TSS Core Service or TSS Service Provider.
boolean	getCapabilityBoolean(long capArea, TcBlobData subCap) This method provides the capabilities of the TSS Core Service or TSS Service Provider.
TcTssVersion	getCapabilityVersion(long capArea, TcBlobData subCap) This method provides the capabilities of the TSS Core Service or TSS Service Provider.
TcIPolicy	getDefaultPolicy() This method provides the default policy object of the context.
TcIRsaKey	getKeyByPublicInfo(long stypeKey, long algId, TcBlobData publicInfo) This method searches the persistent storage for a registered key using the provided public key information and creates a key object initialized according to the found data.
TcIRsaKey	getKeyByUuid(long stypeKey, TcTssUuid uuidKey) This method searches the persistent storage for a registered key using the provided UUID and creates a key object initialized according to the found data.
TcINvRam	getNvRamObject(long initFlags) This method is used to obtain a NV RAM object that allows interaction with the TPM's NV RAM.
TcTssKmKeyinfo[]	getRegisteredKeysByUuid(TcTssUuid uuid, long storage) This method gets an array of key info objects.
TcTssKmKeyinfo[]	getRegisteredKeysByUuidSystem(TcTssUuid uuid) This method is a wrapper for the getRegisteredKeysByUuid method.
TcTssKmKeyinfo[]	getRegisteredKeysByUuidUser(TcTssUuid uuid) This method is a wrapper for the getRegisteredKeysByUuid method.
TcITpm	getTpmObject() This method is used to obtain a TPM object that allows interaction with the system's TPM.
boolean	isConnected() This method returns the status of the context: True is returned if the context is connected, otherwise false.
TcIRsaKey	loadKeyByBlob(TcIRsaKey unwrappingKey, TcBlobData blob) This method creates a key object based on the information got by the key blob and loads the key into the TPM which unwraps the key blob utilizing the key addressed by unwrappingKey.
TcIRsaKey	loadKeyByUuidFromSystem(TcTssUuid uuid) This method creates a key object based on the information contained in the key manager using the UUID and loads the key into the TPM.
TcIRsaKey	loadKeyByUuidFromUser(TcTssUuid uuid) This method creates a key object based on the information contained in the key manager using the UUID and loads the key into the TPM.
void	registerKey(TcIRsaKey key, long stypeKey, TcTssUuid uuidKey, long stypePartenKey, TcTssUuid uuidParent) This method registers a key in the TSS Persistent Storage database.
Object[]	tickStampBlog(TcTpmDigest digestToStamp, TcIRsaKey key, TcTssValidation validationData) This method is similar to a time stamp: it associates a tick value with a blob, indicating that the blob existed at some point earlier than the time corresponding to the tick value.
TcIRsaKey	unregisterKey(long stypeKey, TcTssUuid uuidKey) This method unregisters a key from the persistent storage database.

Methods inherited from interface TcIAttributes

getAttribData, getAttribUint32, setAttribData, setAttribUint32

Method Detail

connect

void connect(String hostname)
             throws TcTssException

This method tries to connect the context to a host running a TCS service.

Parameters:

hostname - The name of the cost to connect to.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

192

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

80

connect

void connect()
             throws TcTssException

This method tries to connect the context to the default host (localhost).

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

192

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

80

isConnected

boolean isConnected()

This method returns the status of the context: True is returned if the context is connected, otherwise false.

Returns:

boolean indication connections status

getTpmObject

TcITpm getTpmObject()
                    throws TcTssException

This method is used to obtain a TPM object that allows interaction with the system's TPM.

Returns:

TPM object representing the system's TPM

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

87

getNvRamObject

TcINvRam getNvRamObject(long initFlags)
                        throws TcTssException

This method is used to obtain a NV RAM object that allows interaction with the TPM's NV RAM.

Returns:

TPM object representing the system's TPM

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

87

createRsaKeyObject

TcIRsaKey createRsaKeyObject(long initFlags)
                             throws TcTssException

This method returns a new key object. It is based on the createObject method of the TSS specification with the objectType set to TcTssConstants.TSS_OBJECT_TYPE_RSAKEY.

Parameters:

initFlags - is used to specify further options for the new object as defined by the TSS specification. Key related initialization values are prefixed with TSS_KEY_ and are defined in TcTssConstants.
Valid initFlags are:

• TcTssConstants.TSS_KEY_SIZE_DEFAULT
• TcTssConstants.TSS_KEY_SIZE_512
• TcTssConstants.TSS_KEY_SIZE_1024
• TcTssConstants.TSS_KEY_SIZE_2048
• TcTssConstants.TSS_KEY_SIZE_4096
• TcTssConstants.TSS_KEY_SIZE_8192
• TcTssConstants.TSS_KEY_SIZE_16384
• TcTssConstants.TSS_KEY_TYPE_AUTHCHANGE
• TcTssConstants.TSS_KEY_TYPE_BIND
• TcTssConstants.TSS_KEY_TYPE_DEFAULT
• TcTssConstants.TSS_KEY_TYPE_IDENTITY
• TcTssConstants.TSS_KEY_TYPE_LEGACY (signing and binding)
• TcTssConstants.TSS_KEY_TYPE_SIGNING
• TcTssConstants.TSS_KEY_TYPE_STORAGE
• TcTssConstants.TSS_KEY_NON_VOLATILE
• TcTssConstants.TSS_KEY_VOLATILE
• TcTssConstants.TSS_KEY_NOT_MIGRATABLE (default)
• TcTssConstants.TSS_KEY_MIGRATABLE
• TcTssConstants.TSS_KEY_CERTIFIED_MIGRATABLE
• TcTssConstants.TSS_KEY_NOT_CERTIFIED_MIGRATABLE
• TcTssConstants.TSS_KEY_NO_AUTHORIZATION (default)
• TcTssConstants.TSS_KEY_AUTHORIZATION
• TcTssConstants.TSS_KEY_AUTHORIZATION_PRIV_USE_ONLY
• TcTssConstants.TSS_KEY_STRUCT_DEFAULT (default)
• TcTssConstants.TSS_KEY_STRUCT_KEY
• TcTssConstants.TSS_KEY_STRUCT_KEY12
• TcTssConstants.TSS_KEY_TSP_SRK

Returns:

The new key object.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

195

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

83

createPolicyObject

TcIPolicy createPolicyObject(long initFlags)
                             throws TcTssException

This method returns a new policy object. It is based on the createObject method of the TSS with TSS_OBJECT_TYPE_POLICY as parameter.

Parameters:

initFlags - is used to specify further options for the new object as defined by the TSS specification. Policy related initialization values are prefixed with TSS_POLICY_ and are defined in TcTssConstants.
Valid initFlags are:

• TcTssConstants.TSS_POLICY_MIGRATION
• TcTssConstants.TSS_POLICY_USAGE

Returns:

the new policy object.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

83

createEncDataObject

TcIEncData createEncDataObject(long initFlags)
                               throws TcTssException

This method returns a new encdata object. It is based on the createObject method of the TSS with TSS_OBJECT_TYPE_ENCDATA as parameter.

Parameters:

initFlags - is used to specify further options for the new object as defined by the TSS specification. EncData related initialization values are prefixed with TSS_ENCDATA_ and are defined in TcTssConstants.
Valid initFlags are:

• TcTssConstants.TSS_ENCDATA_BIND
• TcTssConstants.TSS_ENCDATA_SEAL
• TcTssConstants.TSS_ENCDATA_LEGACY

Returns:

the new encdata object.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

83

createPcrCompositeObject

TcIPcrComposite createPcrCompositeObject(long initFlags)
                                         throws TcTssException

This method returns a new PCR object. It is based on the createObject method of the TSS with TSS_OBJECT_TYPE_PCRS as parameter.

Parameters:

initFlags - is used to specify further options for the new object as defined by the TSS specification. Note: For TSS version 1.1 there is no PCR related init flag defined. Consequently, 0 should be used as initFlags parameter.

Returns:

the new pcr object

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

83

createHashObject

TcIHash createHashObject(long initFlags)
                         throws TcTssException

This method returns a new hash object. It is based on the createObject method of the TSS with TSS_OBJECT_TYPE_HASH as parameter.

Parameters:

initFlags - is used to specify further options for the new object as defined by the TSS specification. Hash related initialization values are prefixed with TSS_HASH_ and are defined in TcTssConstants.
Valid initFlags are:

• TcTssConstants.TSS_HASH_DEFAULT
• TcTssConstants.TSS_HASH_OTHER
• TcTssConstants.TSS_HASH_SHA1

Returns:

the new hash object.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

83

loadKeyByUuidFromSystem

TcIRsaKey loadKeyByUuidFromSystem(TcTssUuid uuid)
                                  throws TcTssException

This method creates a key object based on the information contained in the key manager using the UUID and loads the key into the TPM. The persistent storage provides all information to load the parent keys required to load the key associated with the given UUID. This method tries to load the requested key from the system storage. It is based on the loadKeyByUUID method of the TSS with TSS_PS_TYPE_SYSTEM as parameter.

Parameters:

uuid - UUID of the key to be loaded.

Returns:

key object representing the loaded key

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

89

loadKeyByUuidFromUser

TcIRsaKey loadKeyByUuidFromUser(TcTssUuid uuid)
                                throws TcTssException

This method creates a key object based on the information contained in the key manager using the UUID and loads the key into the TPM. The persistent storage provides all information to load the parent keys required to load the key associated with the given UUID. This method tries to load the requested key from the user storage. It is based on the loadKeyByUUID method of the TSS with TSS_PS_TYPE_USER as parameter.

Parameters:

uuid - UUID of the key to be loaded.

Returns:

key object representing the loaded key

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

89

loadKeyByBlob

TcIRsaKey loadKeyByBlob(TcIRsaKey unwrappingKey,
                        TcBlobData blob)
                        throws TcTssException

This method creates a key object based on the information got by the key blob and loads the key into the TPM which unwraps the key blob utilizing the key addressed by unwrappingKey. The key addressed by unwrappingKey must have been loaded previously into the TPM.

Parameters:

unwrappingKey - Key to unwrap the blob.

blob - Wrapped key blob to load.

Returns:

The created key object.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

207

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

88

closeContext

void closeContext()
                  throws TcTssException

This method destroys the object associated with the object handle. All allocated resources (e.g. objects) associated within the object are also released.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

75

getRegisteredKeysByUuid

TcTssKmKeyinfo[] getRegisteredKeysByUuid(TcTssUuid uuid,
                                         long storage)
                                         throws TcTssException

This method gets an array of key info objects. This information reflects the registered key hierarchy. The keys stored in the persistent storage are totally independent from either the context of the function call or the context, which was provided while processing the key registration.

Parameters:

uuid - The UUID the key was registered in the persistent storage. If no key UUID is provided (null), the returned key info array contains data reflecting the whole key hierarchy starting with the root key. If a certain key UUID is provided, the returned array only contains data reflecting the path of the key hierarchy regarding that key. The first array entry is the key addressed by the given UUID followed by its parent key up to the root key.

storage - Flag indicating the persistent storage the key is registered in (TcTssConstatnts.TSS_PS_TYPE_*).

Returns:

Array containing the actual key hierarchy data

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

94

getRegisteredKeysByUuidSystem

TcTssKmKeyinfo[] getRegisteredKeysByUuidSystem(TcTssUuid uuid)
                                               throws TcTssException

This method is a wrapper for the getRegisteredKeysByUuid method. The storage type is set to TSS_PS_TYPE_SYSTEM.

Parameters:

uuid - (see getRegisteredKeysByUuid)

Returns:

(see getRegisteredKeysByUuid)

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

94

getRegisteredKeysByUuidUser

TcTssKmKeyinfo[] getRegisteredKeysByUuidUser(TcTssUuid uuid)
                                             throws TcTssException

This method is a wrapper for the getRegisteredKeysByUuid method. The storage type is set to TSS_PS_TYPE_USER.

Parameters:

uuid - (see getRegisteredKeysByUuid)

Returns:

(see getRegisteredKeysByUuid)

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

94

getDefaultPolicy

TcIPolicy getDefaultPolicy()
                           throws TcTssException

This method provides the default policy object of the context.

Returns:

The default policy object bound to the context.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

194

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

82

freeMemory

void freeMemory(long cPtr)
                throws TcTssException

This method frees memory allocated by TSS Service Provider on a context base.

Parameters:

cPtr - The memory block to be freed.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

193

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

81

closeObject

void closeObject(TcIWorkingObject obj)
                 throws TcTssException

This method is used to close a given object.

Parameters:

obj - The object to be closed.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

84

getCapability

TcBlobData getCapability(long capArea,
                         TcBlobData subCap)
                         throws TcTssException

This method provides the capabilities of the TSS Core Service or TSS Service Provider. This method returns the capability data as a binary blob.

Parameters:

capArea - Flag indicating the attribute to query.
Valid capAreas are:

• TcTssConstants.TSS_TCSCAP_ALG
• TcTssConstants.TSS_TCSCAP_VERSION
• TcTssConstants.TSS_TCSCAP_CACHING
• TcTssConstants.TSS_TCSCAP_PERSSTORAGE
• TcTssConstants.TSS_TCSCAP_MANUFACTURER
• TcTssConstants.TSS_TSPCAP_ALG
• TcTssConstants.TSS_TSPCAP_VERSION
• TcTssConstants.TSS_TSPCAP_PERSSTORAGE
• TcTssConstants.TSS_TSPCAP_RANDOMLIMIT

subCap - Data indicating the attribute to query.
Valid subCaps are:

• TcTssConstants.TSS_ALG_XXX
• TcTssConstants.TSS_TCSCAP_PROP_KEYCACHE
• TcTssConstants.TSS_TCSCAP_PROP_AUTHCACHE
• TcTssConstants.TSS_TCSCAP_PROP_MANUFACTURER_ID
• TcTssConstants.TSS_TCSCAP_PROP_MANUFACTURER_STR

Returns:

capability blob

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

85

getCapabilityBoolean

boolean getCapabilityBoolean(long capArea,
                             TcBlobData subCap)
                             throws TcTssException

This method provides the capabilities of the TSS Core Service or TSS Service Provider. This method is to be used to read boolean flags.

Parameters:

capArea - Flag indicating the attribute to query.
Valid capAreas are:

• TcTssConstants.TSS_TCSCAP_ALG
• TcTssConstants.TSS_TCSCAP_CACHING
• TcTssConstants.TSS_TSPCAP_ALG
• TcTssConstants.TSS_TSPCAP_PERSSTORAGE

subCap - Data indicating the attribute to query.
Valid subCaps are:

• TcTssConstants.TSS_ALG_XXX
• TcTssConstants.TSS_TCSCAP_PROP_KEYCACHE
• TcTssConstants.TSS_TCSCAP_PROP_AUTHCACHE

Returns:

boolean value

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

85

getCapabilityVersion

TcTssVersion getCapabilityVersion(long capArea,
                                  TcBlobData subCap)
                                  throws TcTssException

This method provides the capabilities of the TSS Core Service or TSS Service Provider. This method is to be used to read version flags.

Parameters:

capArea - Flag indicating the attribute to query.
Valid capAreas are:

• TcTssConstants.TSS_TCSCAP_VERSION
• TcTssConstants.TSS_TSPCAP_VERSION

subCap - Data indicating the attribute to query

Returns:

version object

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

85

registerKey

void registerKey(TcIRsaKey key,
                 long stypeKey,
                 TcTssUuid uuidKey,
                 long stypePartenKey,
                 TcTssUuid uuidParent)
                 throws TcTssException

This method registers a key in the TSS Persistent Storage database.

Parameters:

key - Handle of the key object addressing the key to be registered.

stypeKey - Flag indicating the persistent storage

uuidKey - UUID by which the key is registered in the persistent storage

stypePartenKey - Flag indicating the persistent storage

uuidParent - UUID by which the parent key was registered in the persistent storage

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

90

unregisterKey

TcIRsaKey unregisterKey(long stypeKey,
                        TcTssUuid uuidKey)
                        throws TcTssException

This method unregisters a key from the persistent storage database.

Parameters:

stypeKey - Flag indicating the persistent storage

uuidKey - UUID of the key to be removed from the persistent storage

Returns:

key object containing the info from the archive

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

91

getKeyByUuid

TcIRsaKey getKeyByUuid(long stypeKey,
                       TcTssUuid uuidKey)
                       throws TcTssException

This method searches the persistent storage for a registered key using the provided UUID and creates a key object initialized according to the found data. On successful completion of the method a handle to the created new key object is returned.

Parameters:

stypeKey - Flag indicating the persistent storage

uuidKey - UUID of the key by which the key was registered in the persistent storage

Returns:

key object representing the key

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

92

getKeyByPublicInfo

TcIRsaKey getKeyByPublicInfo(long stypeKey,
                             long algId,
                             TcBlobData publicInfo)
                             throws TcTssException

This method searches the persistent storage for a registered key using the provided public key information and creates a key object initialized according to the found data. On successful completion of the method a handle to the created new key object is returned. NOTE: The returned key structure does not carry a UUID.

Parameters:

stypeKey - Flag indicating the persistent storage.

algId - Parameter indicates the algorithm of the requested key.

publicInfo - Public key info provided to identify the key to be looked for.

Returns:

Object representing the key.

Throws:

TcTssException

TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:

93

tickStampBlog

Object[] tickStampBlog(TcTpmDigest digestToStamp,
                       TcIRsaKey key,
                       TcTssValidation validationData)
                       throws TcTssException

This method is similar to a time stamp: it associates a tick value with a blob, indicating that the blob existed at some point earlier than the time corresponding to the tick value.

Parameters:

digestToStamp - The 20 byte hash to be time stamped

key - Key to sign the time stamp

validationData - holds a nonce incorporated in stamping in the externalData_ field

Returns:

Object array of [0] validationData additionally externalData_ it now holds the signature in the field validationData_ [1] currentTicks at the time of stamping

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

374