iaik.tc.tss.api.tspi
Interface TcITpm

All Superinterfaces:

TcIAttributes, TcIAuthObject, TcIWorkingObject

public interface TcITpm
extends TcIWorkingObject, TcIAttributes, TcIAuthObject

One purpose of the TPM class is to represent the owner for a TCG subsystem (TPM). The owner of a TPM is comparable with an administrator in the PC environment. For that reason there exists only one instance of the TPM class per context. This object is automatically associated with one policy object, which must be used to handle the owner authentication data. On the other hand it provides some basic control and reporting functionality.

Method Summary

TcBlobData	activateIdentity(TcIRsaKey identityKey, TcBlobData asymCaContentsBlob, TcBlobData symCaAttestationBlob) This method proofs the credential to be the credential of the identity key and returns the decrypted credential created by the Privacy CA for that identity.
TcTpmMigrationkeyAuth	authorizeMigrationTicket(TcIRsaKey migrationKey, long migrationScheme) This method provides the migration ticket required for the migration process.
TcTssValidation	certifySelfTest(TcIRsaKey key, TcTssValidation validation) This method performs a self-test of each internal TPM function and returns an authenticated value (signature) if the test has passed.
TcTssValidation	checkMaintenancePubKey(TcIRsaKey key, TcTssValidation validationData) This method proofs the maintenance public key.
void	clearOwner(boolean forcedClear) This method clears the TPM ownership.
void	CMKApproveMA(TcIMigData maAuthData) This method creates an authorization ticket, to allow the TPM owner to specify which Migration Authorities they approve and allow users to create certified-migration-keys without further involvement with the TPM owner.
void	CMKCreateTicket(TcIRsaKey verifyKey, TcIMigData sigData) This method uses a public key to verify the signature over a digest.
void	CMKSetRestrictions(long cmkDelegate) This method is used by the owner to globally dictate the usage of a certified migration key with delegated authorization.
TcBlobData	collateIdentityRequest(TcIRsaKey srk, TcIRsaKey caPubKey, TcBlobData identityLabel, TcIRsaKey identityKey, long algId) This method creates an identity key, binds it to the label and returns a certificate request package.
TcTssValidation	createEndorsementKey(TcIRsaKey key, TcTssValidation validationData) This method creates the endorsement key.
Object[]	createRevocableEndorsementKey(TcIRsaKey key, TcTssValidation validationData, TcTpmNonce ekResetData) This method creates the revocable endorsement key.
TcBlobData	dirRead(long dirIndex) This method reads a Data Integrity Register.
void	dirWrite(long dirIndex, TcBlobData dirData) This method writes a Data Integrity Register.
TcBlobData	getCapability(long capArea, TcBlobData subCap) This method provides the capabilities of the TPM.
boolean	getCapabilityBoolean(long capArea, TcBlobData subCap) This method is an alternative to getCapability(long, TcBlobData).
void	getCapabilitySigned() The TPM function TPM_GetCapabilitySigned that actually performs this functions was found to contain a vulnerability that makes its security questionable therefore its use unadvised.
long	getCapabilityUINT32(long capArea, TcBlobData subCap) This method is an alternative to getCapability(long, TcBlobData).
TcTssVersion	getCapabilityVersion(long capArea, TcBlobData subCap) This method is an alternative to getCapability(long, TcBlobData).
TcTssPcrEvent	getEvent(long pcrIndex, long eventNumber) This method provides a PCR event for a given PCR index and event number.
int	getEventCount(long pcrIndex) This method is similar to the getEvents method.
TcTssPcrEvent[]	getEventLog() This method provides the whole event log.
TcTssPcrEvent[]	getEvents(long pcrIndex, long startNumber, long eventNumber) This method provides a specific number of PCR events for a given index.
Object[]	getPubEndorsementKey(boolean ownerAuthorized, TcTssValidation validataionData) This method returns the public endorsement key.
TcIRsaKey	getPubEndorsementKeyOwner() This method returns the public endorsement key.
TcBlobData	getRandom(long length) This method returns random data obtained from the TPM via the TSS.
boolean	getStatus(long statusFlag) This method returns the TPM status.
TcBlobData	getTestResult() This method provides manufacturer specific information regarding the results of the self test.
void	killMaintenanceFeature() This method disables the functionality of creating a maintenance archive.
TcTssValidation	loadMaintenancePubKey(TcIRsaKey key, TcTssValidation validationData) This method loads the public maintenance key into the TPM.
TcIRsaKey	OwnerGetSRKPubKey() This method returns the public part of the SRK.
TcBlobData	pcrExtend(long pcrIndex, TcBlobData data, TcTssPcrEvent pcrEvent) This method extends a PCR register and writes the PCR event log.
TcBlobData	pcrRead(long pcrIndex) This methods reads a PCR register.
void	pcrReset(TcIPcrComposite pcrComposite) This methods resets a PCR register.
TcTssValidation	quote(TcIRsaKey identKey, TcIPcrComposite pcrComposite, TcTssValidation validation) This method quotes a TCG system.
Object[]	quote2(TcIRsaKey identKey, boolean addVersion, TcIPcrComposite pcrComposite, TcTssValidation validation) This method quotes a TCG system using TPM_Quote2 which provides the requestor a more complete view of the current platform configuration than TPM_Quote.
TcTpmCounterValue	readCurrentCounter() This method reads the current value of the current active counter register.
TcTpmCurrentTicks	readCurrentTicks() This method reads the current tick out of the TPM.
void	revokeEndorsementKey(TcTpmNonce ekResetData) This method clears the TPM revocable endorsement key pair.
void	selfTestFull() This method performs a self-test of each internal TPM function.
void	setOperatorAuth(TcIPolicy operatorPolicy) This function sets the operator authorization value in the TPM.
void	setStatus(long statusFlag, boolean tpmState) This method modifies the TPM status.
void	stirRandom(TcBlobData entropyData) This method adds entropy to the TPM Random Number Generator.
void	takeOwnership(TcIRsaKey srk, TcIRsaKey pubEk) This method takes ownership of the TPM.

Methods inherited from interface TcIAttributes

getAttribData, getAttribUint32, setAttribData, setAttribUint32

Methods inherited from interface TcIAuthObject

changeAuth, changeAuthAsym, getPolicyObject, getUsagePolicyObject

Method Detail

takeOwnership

void takeOwnership(TcIRsaKey srk,
                   TcIRsaKey pubEk)
                   throws TcTssException

This method takes ownership of the TPM. The process of taking ownership is the procedure whereby the owner inserts a shared secret into the TPM. The owner of the TPM has the right to perform special operations. As part of this command, the owner password is set and a new SRK key pair is created.

Parameters:

srk - The storage root key object.

pubEk - The public endorsement key object. The public endorsement key is required for encryption of the SRK and EK secret sent to the TPM. The pubEk parameter can be set to null. In this case, the takeOwnership method will query the TPM for the public endorsement key.s

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

252

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

110

getPubEndorsementKey

Object[] getPubEndorsementKey(boolean ownerAuthorized,
                              TcTssValidation validataionData)
                              throws TcTssException

This method returns the public endorsement key. The public key information of the endorsement key can be retrieved via TcIAttributes.getAttribData(long, long).

Parameters:

ownerAuthorized - Flag determining if owner authorization is required. Note that owner authorization is not required if the ownership of the TPM has not yet been taken. After TPM ownership has been taken, owner authorization is required to obtain the public EK.

validataionData - External data that is used by the TPM to compute the checksum. If this parameter is omitted (i.e. it is set to null), the validation is done by the TSP:

Returns:

The returned Object[] contains the following elements:

• 0 ... endorsement key object TcIRsaKey
• 1 ... outgoing validation (TcTssValidation

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

243

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

109

getPubEndorsementKeyOwner

TcIRsaKey getPubEndorsementKeyOwner()
                                    throws TcTssException

This method returns the public endorsement key. The public key information of the endorsement key can be retrieved via TcIAttributes.getAttribData(long, long). This method always tries to read the public EK using owner authorization. If effectively is a shortcut for getPubEndorsementKey(boolean, TcTssValidation) with (true, null) as parameters.

Returns:

TcIRsaKey

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

243

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

109

getStatus

boolean getStatus(long statusFlag)
                  throws TcTssException

This method returns the TPM status.
Valid statusFlags are:

• TcTssConstants.TSS_TPMSTATUS_DISABLEOWNERCLEAR
• TcTssConstants.TSS_TPMSTATUS_DISABLEFORCECLEAR
• TcTssConstants.TSS_TPMSTATUS_DISABLED
• TcTssConstants.TSS_TPMSTATUS_PHYSICALSETDEACTIVATED
• TcTssConstants.TSS_TPMSTATUS_SETTEMPDEACTIVATED
• TcTssConstants.TSS_TPMSTATUS_SETOWNERINSTALL
• TcTssConstants.TSS_TPMSTATUS_DISABLEPUBEKREAD
• TcTssConstants.TSS_TPMSTATUS_ALLOWMAINTENANCE
• TcTssConstants.TSS_TPMSTATUS_PHYSPRES_LIFETIMELOCK
• TcTssConstants.TSS_TPMSTATUS_PHYSPRES_HWENABLE
• TcTssConstants.TSS_TPMSTATUS_PHYSPRES_CMDENABLE
• TcTssConstants.TSS_TPMSTATUS_CEKP_USED
• TcTssConstants.TSS_TPMSTATUS_PHYSPRESENCE
• TcTssConstants.TSS_TPMSTATUS_PHYSPRES_LOCK

Parameters:

statusFlag - status flag to be read

Returns:

value of status flag

Throws:

TcTssException

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

118

setStatus

void setStatus(long statusFlag,
               boolean tpmState)
               throws TcTssException

This method modifies the TPM status.

Parameters:

statusFlag - determines the flag to be set.
Valid statusFlags are:

• TcTssConstants.TSS_TPMSTATUS_DISABLEOWNERCLEAR, tpmState is ignored
• TcTssConstants.TSS_TPMSTATUS_DISABLEFORCECLEAR, tpmState is ignored
• TcTssConstants.TSS_TPMSTATUS_OWNERSETDISABLE
• TcTssConstants.TSS_TPMSTATUS_PHYSICALDISABLE
• TcTssConstants.TSS_TPMSTATUS_PHYSICALSETDEACTIVATED
• TcTssConstants.TSS_TPMSTATUS_SETTEMPDEACTIVATED, tpmState is ignored
• TcTssConstants.TSS_TPMSTATUS_SETOWNERINSTALL
• TcTssConstants.TSS_TPMSTATUS_DISABLEPUBEKREAD, tpmState is ignored

tpmState - the new value of the flag

Throws:

TcTssException

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

116

getRandom

TcBlobData getRandom(long length)
                     throws TcTssException

This method returns random data obtained from the TPM via the TSS.

Parameters:

length - The length of the data to be requested. The maximum length of the random data is 4096.

Returns:

Random data received from the TPM.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

281

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

131

pcrRead

TcBlobData pcrRead(long pcrIndex)
                   throws TcTssException

This methods reads a PCR register.

Parameters:

pcrIndex - Index of the PCR to read.

Returns:

The PCR data read from the TPM.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

291

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

139

pcrReset

void pcrReset(TcIPcrComposite pcrComposite)
              throws TcTssException

This methods resets a PCR register. Whether or not is succeeds may depend on the locality executing the command. PCRs can be defined in a platform specific specification to allow reset of certain PCRs only for certain localities. The one exception is PCR 16 which can always be reset in a 1.2 implementation. This is to allow for software testing.

Parameters:

pcrComposite - Indices of the PCR to read.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

299

pcrExtend

TcBlobData pcrExtend(long pcrIndex,
                     TcBlobData data,
                     TcTssPcrEvent pcrEvent)
                     throws TcTssException

This method extends a PCR register and writes the PCR event log. If no pcrEvent parameter is supplied, the pcrEventData parameter is expected to be a SHA-1 hash that is directly extended into the specified PCR register. In this case, the provided pcrEventData value is not touched by the TSP. If however a pcrEvent is provided, then the value that is extended into the specified PCR is computed as follows: SHA-1(pcrIndex || pcrEventData || pcrEvent.eventType || pcrEvent).

Parameters:

pcrIndex - Index of the PCR to extend.

data - Data blob for the PCR extend operation.

pcrEvent - Contains the info for an event entry. If this object is null no event entry is created and the method only executes an TPM extend operation

Returns:

Memory block containing the PCR data after the extend operation.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

289

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

138

getEvent

TcTssPcrEvent getEvent(long pcrIndex,
                       long eventNumber)
                       throws TcTssException

This method provides a PCR event for a given PCR index and event number.

Parameters:

pcrIndex - Index of the PCR to request.

eventNumber - Index of the event to request.

Returns:

PCR event data.

Throws:

TcTssException

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

134

getEvents

TcTssPcrEvent[] getEvents(long pcrIndex,
                          long startNumber,
                          long eventNumber)
                          throws TcTssException

This method provides a specific number of PCR events for a given index.

Parameters:

pcrIndex - Index of the PCR to request.

startNumber - Index of the first event to request.

eventNumber - Number of elements to request.

Returns:

array of PCR event data.

Throws:

TcTssException

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

135

getEventCount

int getEventCount(long pcrIndex)
                  throws TcTssException

This method is similar to the getEvents method. The only difference is the return value: This method returns the number of entries that would be retrieved when calling the getEvents method. This method is based on the getEvents method of the TSS where the prgPcrEvents parameter is set to 0.

Parameters:

pcrIndex - Index of the PCR to request.

Returns:

number of events reported

Throws:

TcTssException

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

135

getEventLog

TcTssPcrEvent[] getEventLog()
                            throws TcTssException

This method provides the whole event log.

Returns:

The event log.

Throws:

TcTssException

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

136

quote

TcTssValidation quote(TcIRsaKey identKey,
                      TcIPcrComposite pcrComposite,
                      TcTssValidation validation)
                      throws TcTssException

This method quotes a TCG system. Which PCRs should be quoted must be set in the PcrComposite object before calling this method.
If structure type other than TcTssConstants.TSS_PCRS_STRUCT_INFO is used in the PcrComposite a TcTssException with error code TcTssErrors.TSS_E_INVALID_OBJ_ACCESS is thrown. The returned signature is computed over the TcTpmQuoteInfo structure.

Parameters:

identKey - Signature key.

pcrComposite - PCR composite object. Will be used as input only.

validation - Provides externalData information required to compute the signature. If this parameter is omitted (set to null), the TSP will generate external data and do the validation.
An important use of TPM_Quote is to provide a digital signature on arbitrary data, where the signature includes the PCR values of the platform at the time of signing. Hence, the externalData is not just for anti-replay purposes although it is used for that purpose in an integrity challenge. If the validation parameter is omitted (set to null), the TSP will generate anti-replay data that is validated upon receiving the response from the TPM.

Returns:

The validation data and the data the validation data was computed from.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

287

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

137

quote2

Object[] quote2(TcIRsaKey identKey,
                boolean addVersion,
                TcIPcrComposite pcrComposite,
                TcTssValidation validation)
                throws TcTssException

This method quotes a TCG system using TPM_Quote2 which provides the requestor a more complete view of the current platform configuration than TPM_Quote. The required information about which PCRs should be quoted must be set in the PcrComposite object before calling this method.
If structure type other than TcTssConstants.TSS_PCRS_STRUCT_INFO_SHORT is used in the PcrComposite a TcTssException with error code TcTssErrors.TSS_E_INVALID_OBJ_ACCESS is thrown. The returned signature is computed over the TcTpmQuoteInfo structure.

Parameters:

identKey - Signature key.

addVersion - If true, the TPM version is added to the output otherwise it is omitted.

pcrComposite - PCR composite object. Will be used as input only.

validation - Provides externalData information required to compute the signature. If this parameter is omitted (set to null), the TSP will generate external data and do the validation.
An important use of TPM_Quote is to provide a digital signature on arbitrary data, where the signature includes the PCR values of the platform at the time of signing. Hence, the externalData is not just for anti-replay purposes although it is used for that purpose in an integrity challenge. If the validation parameter is omitted (set to null), the TSP will generate anti-replay data that is validated upon receiving the response from the TPM.

Returns:

The returned Object[] contains the following elements:

• 0 ... outgoing validation (TcTssValidation
• 1 ... TPM version as reported by TcTpmConstants.TPM_CAP_VERSION_VAL. If addVersion is false, this element is null (TcTpmCapVersionInfo.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

303

stirRandom

void stirRandom(TcBlobData entropyData)
                throws TcTssException

This method adds entropy to the TPM Random Number Generator.

Parameters:

entropyData - The entropy data.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

282

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

132

createEndorsementKey

TcTssValidation createEndorsementKey(TcIRsaKey key,
                                     TcTssValidation validationData)
                                     throws TcTssException

This method creates the endorsement key. The key information required for creating the endorsement key must be set in the key object using TcIAttributes.setAttribUint32(long, long, long) and TcIAttributes.setAttribData(long, long, TcBlobData)

Parameters:

key - Key object specifying the attributes of the endorsement key to create.

validationData - Provides externalData information required to compute the checksum. If the TSP should compute compute the checksum set this parameter to null.

Returns:

The validation checksum and the data the validation checksum was computed from.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

242

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

108

createRevocableEndorsementKey

Object[] createRevocableEndorsementKey(TcIRsaKey key,
                                       TcTssValidation validationData,
                                       TcTpmNonce ekResetData)
                                       throws TcTssException

This method creates the revocable endorsement key. The key information required for creating the endorsement key must be set in the key object using TcIAttributes.setAttribUint32(long, long, long) and TcIAttributes.setAttribData(long, long, TcBlobData)

Parameters:

key - Key object specifying the attributes of the endorsement key to create.

validationData - Provides externalData information required to compute the checksum. If the TSP should compute compute the checksum set this parameter to null.

ekResetData - The authorization value to be used with RevokeEndorsementKeyPair. Generated by the TPM if null.

Returns:

The returned Object[] contains the following elements:

• 0 ... validation data plus checksum TcTssValidation
• 1 ... authorisation value for resetting the endorsement key (TcTpmNonce

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

242

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

108

revokeEndorsementKey

void revokeEndorsementKey(TcTpmNonce ekResetData)
                          throws TcTssException

This method clears the TPM revocable endorsement key pair.

Parameters:

ekResetData - The authorization value which was set with createRevocableEndorsementKey

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

242

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

108

clearOwner

void clearOwner(boolean forcedClear)
                throws TcTssException

This method clears the TPM ownership. Note on using physical presence for proofing TPM ownership: As the mechanism to determine physical presence is platform dependent you have to consult the manual of your system for further information. On typical PC type platforms, a forced clear can only be done from the systems BIOS.

Parameters:

forcedClear - If FALSE, a clear ownership with proof of the TPM owner secret is done. If TRUE, a forced clear ownership with proof of physical access is done.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

253

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

115

dirRead

TcBlobData dirRead(long dirIndex)
                   throws TcTssException

This method reads a Data Integrity Register.

Parameters:

dirIndex - Index of the DIR to read.

Returns:

memory block containing the the DIR data.

Throws:

TcTssException

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

141

dirWrite

void dirWrite(long dirIndex,
              TcBlobData dirData)
              throws TcTssException

This method writes a Data Integrity Register.

Parameters:

dirIndex - Index of the DIR to write.

dirData - data to be written to the DIR.

Throws:

TcTssException

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

140

getCapability

TcBlobData getCapability(long capArea,
                         TcBlobData subCap)
                         throws TcTssException

This method provides the capabilities of the TPM.

Parameters:

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

• TcTssConstants.TSS_TPMCAP_ORD
• TcTssConstants.TSS_TPMCAP_FLAG
• TcTssConstants.TSS_TPMCAP_ALG
• TcTssConstants.TSS_TPMCAP_PROPERTY
• TcTssConstants.TSS_TPMCAP_VERSION
• TcTssConstants.TSS_TPMCAP_VERSION_VAL
• TcTssConstants.TSS_TPMCAP_NV_LIST
• TcTssConstants.TSS_TPMCAP_NV_INDEX
• TcTssConstants.TSS_TPMCAP_MFR
• TcTssConstants.TSS_TPMCAP_SYM_MODE
• TcTssConstants.TSS_TPMCAP_HANDLE
• TcTssConstants.TSS_TPMCAP_TRANS_ES
• TcTssConstants.TSS_TPMCAP_AUTH_ENCRYPT

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

• TcTpmOrdinals.TPM_ORD_*
• TcTssConstants.TSS_ALG_*
• TcTpmConstants.TPM_SYM_MODE_*
• TcTssConstants.TSS_RT_*
• TcTssConstants.TSS_ES_*

Returns:

data of the specified attribute

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

268

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

123

getCapabilityBoolean

boolean getCapabilityBoolean(long capArea,
                             TcBlobData subCap)
                             throws TcTssException

This method is an alternative to getCapability(long, TcBlobData). The only difference is that the returned data is interpreted as TSS_BOOL (boolean).

Throws:

TcTssException

getCapabilityUINT32

long getCapabilityUINT32(long capArea,
                         TcBlobData subCap)
                         throws TcTssException

This method is an alternative to getCapability(long, TcBlobData). The only difference is that the returned data is interpreted as UINT32 (long).

Throws:

TcTssException

getCapabilityVersion

TcTssVersion getCapabilityVersion(long capArea,
                                  TcBlobData subCap)
                                  throws TcTssException

This method is an alternative to getCapability(long, TcBlobData). The only difference is that the returned data is interpreted as TSS_VERSION. Note that on 1.2 TPMs, TSS_TPMCAP_VERSION is fixed to always return 1.1.0.0. To obtain the real TPM version on a 1.2 TPM, TSS_TPMCAP_VERSION_VAL has to be used. TSS_TPMCAP_VERSION_VAL not only retrieves the version but a TcTpmCapVersionInfo structure. This method returns the version field of this structure. To obtain the full TcTpmCapVersionInfo structure, use getCapability(long, TcBlobData).

Parameters:

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

• TcTssConstants.TSS_TPMCAP_VERSION
• TcTssConstants.TSS_TPMCAP_VERSION_VAL (on 1.2 TPMs)

subCap - Ignored (set to null);

Returns:

The TPM version.

Throws:

TcTssException

getCapabilitySigned

void getCapabilitySigned()
                         throws TcTssException

The TPM function TPM_GetCapabilitySigned that actually performs this functions was found to contain a vulnerability that makes its security questionable therefore its use unadvised.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

276

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

125

selfTestFull

void selfTestFull()
                  throws TcTssException

This method performs a self-test of each internal TPM function.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

278

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

120

getTestResult

TcBlobData getTestResult()
                         throws TcTssException

This method provides manufacturer specific information regarding the results of the self test.

Returns:

Memory block containing the TPM manufacturer specific information.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

280

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

122

certifySelfTest

TcTssValidation certifySelfTest(TcIRsaKey key,
                                TcTssValidation validation)
                                throws TcTssException

This method performs a self-test of each internal TPM function and returns an authenticated value (signature) if the test has passed. If the signature scheme of the provided key is not TcTssConstants.TSS_SS_RSASSAPKCS1V15_SHA1, the return value can either be a BAD_PARAMETER error or success with a vendor specific signature.

Parameters:

key - Signature key.

validation - ExternalData information required to compute the signature. If not validation data is provided (i.e. this parameter is set to null), validation is done by the TSP.

Returns:

Validation data and the data the validation data was computed from. Calculation of hash value for the validation data: SHA1 hash of the following three concatenated data blobs: ("Test Passed\0" || externalData || ordinal).

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

279

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

121

killMaintenanceFeature

void killMaintenanceFeature()
                            throws TcTssException

This method disables the functionality of creating a maintenance archive. After disabling the functionality of creating a maintenance archive, this functionality can only be enabled again by releasing the TPM ownership.

Throws:

TcTssException

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

128

loadMaintenancePubKey

TcTssValidation loadMaintenancePubKey(TcIRsaKey key,
                                      TcTssValidation validationData)
                                      throws TcTssException

This method loads the public maintenance key into the TPM. The maintenance public key can only be loaded once. Subsequent calls to Tspi_TPM_LoadMaintenancePubKey will fail.

Parameters:

key - maintenance key object

validationData - externalData information required to compute the signature. If validationData != NULL: The caller has to proof the digest by its own. If validationData == NULL: The TSS Service Provider proofs the digest got from the TPM internally.

Returns:

validation data and the data the validation data was computed from. Calculation of hash value for the validation data: SHA1 hash of the concatenated data of ||

Throws:

TcTssException

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

129

checkMaintenancePubKey

TcTssValidation checkMaintenancePubKey(TcIRsaKey key,
                                       TcTssValidation validationData)
                                       throws TcTssException

This method proofs the maintenance public key.

Parameters:

key - maintenance key object

validationData - externalData information required to compute the signature.

Returns:

validation data and the data the validation data was computed from. Note: If validation is not null, the state of the provided validation object is modified by this method.

Throws:

TcTssException

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

129

collateIdentityRequest

TcBlobData collateIdentityRequest(TcIRsaKey srk,
                                  TcIRsaKey caPubKey,
                                  TcBlobData identityLabel,
                                  TcIRsaKey identityKey,
                                  long algId)
                                  throws TcTssException

This method creates an identity key, binds it to the label and returns a certificate request package. The privacy CA requires this certificate request to attest the identity key. Only the owner of the TPM has the privilege of creating a TPM identity key. Executing this method the TSS Service Provider performs two encryptions. The first is to symmetrically encrypt the information and the second is to encrypt the symmetric encryption key with an asymmetric algorithm. The symmetric key is a random nonce and the asymmetric key is the public key of the CA that will provide the identity credential.

Parameters:

srk - object (Storage Root Key).

caPubKey - Key object holding the public key of the CA which signs the certificate of the created identity key.

algId - Symmetric algorithm to use as required by the Privacy CA.

identityLabel - The identity label which should be a UNICODE string.

identityKey - Identity key object. The template for the identity key to be created. The key parameters must be set up correctly when creating the key object before this method is called..

Returns:

A blob containing the certificate request structure of type TPM_IDENTITY_REQ. This structure holds two blob: The symBlob is encrypted with a symmetric session key. The asymBlob holds this symmetric session key encrypted using the public key of the chosen Privacy CA. By that it is ensured that only this Privacy CA can decrypt the request blob.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

244

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

111

activateIdentity

TcBlobData activateIdentity(TcIRsaKey identityKey,
                            TcBlobData asymCaContentsBlob,
                            TcBlobData symCaAttestationBlob)
                            throws TcTssException

This method proofs the credential to be the credential of the identity key and returns the decrypted credential created by the Privacy CA for that identity.

Parameters:

identityKey - The identity key object.

asymCaContentsBlob - The blob containing the encrypted ASYM_CA_CONTENTS data structure received from the Privacy CA.

symCaAttestationBlob - The blob containing the encrypted SYM_CA_ATTESTATION data structure received from the Privacy CA.

Returns:

The blob containing the decrypted credential.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

247

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

113

authorizeMigrationTicket

TcTpmMigrationkeyAuth authorizeMigrationTicket(TcIRsaKey migrationKey,
                                               long migrationScheme)
                                               throws TcTssException

This method provides the migration ticket required for the migration process.

Parameters:

migrationKey - key object representing the migration key.

migrationScheme - Flag indicating the migration scheme to be used.
Valid migrationSchemes are:

• TcTssConstants.TSS_MS_MAINT
• TcTssConstants.TSS_MS_MIGRATE
• TcTssConstants.TSS_MS_REWRAP

Returns:

memory block containing the migration ticket blob.

Throws:

TcTssException

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

133

readCurrentTicks

TcTpmCurrentTicks readCurrentTicks()
                                   throws TcTssException

This method reads the current tick out of the TPM.

Returns:

Current value of tick counter in the TPM

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

373

readCurrentCounter

TcTpmCounterValue readCurrentCounter()
                                     throws TcTssException

This method reads the current value of the current active counter register.

Returns:

Current value of the counter

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

372

OwnerGetSRKPubKey

TcIRsaKey OwnerGetSRKPubKey()
                            throws TcTssException

This method returns the public part of the SRK. Can be used to initialize the system persistent storage with the SRK without the need to take ownership again.

Returns:

A key object containing only the public part of the storage root key (SRK).

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

274

CMKSetRestrictions

void CMKSetRestrictions(long cmkDelegate)
                        throws TcTssException

This method is used by the owner to globally dictate the usage of a certified migration key with delegated authorization. This command can't be owner delegated.

Parameters:

cmkDelegate - Bit mask to determine the restrictions on certified-migration-keys Valid Flags are:

• TcTssConstants.TSS_CMK_DELEGATE_BIND
• TcTssConstants.TSS_CMK_DELEGATE_LEGACY
• TcTssConstants.TSS_CMK_DELEGATE_MIGRATE
• TcTssConstants.TSS_CMK_DELEGATE_SIGNING
• TcTssConstants.TSS_CMK_DELEGATE_STORAGE

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

336

CMKApproveMA

void CMKApproveMA(TcIMigData maAuthData)
                  throws TcTssException

This method creates an authorization ticket, to allow the TPM owner to specify which Migration Authorities they approve and allow users to create certified-migration-keys without further involvement with the TPM owner.

Parameters:

maAuthData - Migration data properties object to transfer the input and output data blob during the migration process. For this command the object calculates the digest of the selected MSA (Migration Selection Authority) which are imported into this object.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

337

CMKCreateTicket

void CMKCreateTicket(TcIRsaKey verifyKey,
                     TcIMigData sigData)
                     throws TcTssException

This method uses a public key to verify the signature over a digest. The output ticket data can be used to prove the same TPM for signature verification. This operation requires owner authorization which can be delegated.

Parameters:

verifyKey - The Key object containing the public key used to check the signature value.

sigData - Migration data properties object to transfer the input and output data blob during the migration process. For this command the object includes the data proper to be signed and the signature value to be verified. The caller can access the ticket/signature data via GetAttribData().

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

338

setOperatorAuth

void setOperatorAuth(TcIPolicy operatorPolicy)
                     throws TcTssException

This function sets the operator authorization value in the TPM.

Parameters:

operatorPolicy - the policy object holding the new operator authorization value.

Throws:

TcTssException

TSS Spec. 1.2 Errata A, page number:

259