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:


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.
 TcIMigData createMigDataObject(long initFlags)
          This method returns a new migdata 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.
 TcIMonotonicCtr getMonotonicCounters(long nvIndex)
          This method is used to obtain a Monotonic Counter object that allows interaction with the TPM's counters.
 TcINvRam getNvRamObject(long nvIndex)
          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)
          Deprecated. Use the getRegisteredKeysByUuid method with TSS_PS_TYPE_SYSTEM as parameter instead.
 TcIRsaKey loadKeyByUuidFromUser(TcTssUuid uuid)
          Deprecated. Use the getRegisteredKeysByUuid method with TSS_PS_TYPE_USER as parameter instead.
 void registerKey(TcIRsaKey key, long stypeKey, TcTssUuid uuidKey, long stypeParentKey, TcTssUuid uuidParent)
          This method registers a key in the TSS Persistent Storage database.
 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. For example "http://127.0.0.1:30004/axis/services/TSSCoreServiceBindingImpl"
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

getMonotonicCounters

TcIMonotonicCtr getMonotonicCounters(long nvIndex)
                                     throws TcTssException
This method is used to obtain a Monotonic Counter object that allows interaction with the TPM's counters.

Returns:
Ctr object representing the system's montonic counters
Throws:
TcTssException
TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:
87

getNvRamObject

TcINvRam getNvRamObject(long nvIndex)
                        throws TcTssException
This method is used to obtain a NV RAM object that allows interaction with the TPM's NV RAM.

Returns:
an object representing the system's NV-RAM
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:
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:
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:
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:
Returns:
the new hash object.
Throws:
TcTssException
TSS Spec. 1.10 Golden, Aug. 20, 2003, page number:
83

createMigDataObject

TcIMigData createMigDataObject(long initFlags)
                               throws TcTssException
This method returns a new migdata object. It is based on the createObject method of the TSS with TSS_OBJECT_TYPE_MIGDATA 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.2 there is no migdata related init flag defined. Consequently, 0 should be used as initFlags parameter.
Returns:
the new migdata object.
Throws:
TcTssException
TSS Spec. 1.2 Errata A, page number:
194

loadKeyByUuidFromSystem

TcIRsaKey loadKeyByUuidFromSystem(TcTssUuid uuid)
                                  throws TcTssException
Deprecated. Use the getRegisteredKeysByUuid method with TSS_PS_TYPE_SYSTEM as parameter instead.

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.

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
Deprecated. Use the getRegisteredKeysByUuid method with TSS_PS_TYPE_USER as parameter instead.

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.

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:
subCap - Data indicating the attribute to query.
Valid subCaps are:
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:
subCap - Data indicating the attribute to query.
Valid subCaps are:
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:
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 stypeParentKey,
                 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
stypeParentKey - 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