jsr 321 - trusted computing api for java

JSR321 Trusted Computing API for Java™ Java™ Community Process Specification Proposed Final Draft

Copyright 2009-11

Institute for Applied Information Processing and Communications (IAIK) Graz University Of Technology Inffeldgasse 16a A-8010 Graz Austria

All rights reserved.

This Proposed Final Draft of the JSR321 Specification (covering this document and JavaDoc) is released for review under the terms provided in the License chapter.

Table of Contents I. Preface ......................................................................................................................................................... 4

1. Revision History ........................................................................................................................................... 4

2. Who Should Use This Specification ............................................................................................................. 4

3. Outline ......................................................................................................................................................... 4

4. Introduction ................................................................................................................................................. 5

5. Contributors ................................................................................................................................................. 6

6. Contributing To This Specification ............................................................................................................... 6

7. Open Issues .................................................................................................................................................. 7

II. Technical Background and Design ............................................................................................................... 8

8. The Needs of the TPM ................................................................................................................................. 8

TCG Standard Approach for the C Programming Language ................................................................ 8

9. JSR321 API Design Considerations ............................................................................................................... 9

Design Goals ........................................................................................................................................ 9

Limitation from the TCG Architecture ................................................................................................ 9

Limited Choice of Cryptographic Algorithms .................................................................................... 10

JSR321 API Scope and Limitations .................................................................................................... 10

Expected Developer Knowledge ....................................................................................................... 10

10. Outline of the API ...................................................................................................................................... 11

11. Feature Selection ....................................................................................................................................... 13

III. Normative Part .......................................................................................................................................... 19

12. Definitions .................................................................................................................................................. 19

13. Requirements ............................................................................................................................................ 19

14. Detailed API Specifications ........................................................................................................................ 20

IV. License ....................................................................................................................................................... 85

V. References and Relevant Literature .......................................................................................................... 90

I. Preface

These specifications allow integrating Trusted Computing into JavaTM.

Java™ is a platform with integrated security features and therefore well suited for Trusted Computing (TC) software. However, the current releases of Java™ do not provide standard integration of TC functionality which is available in today's hardware platforms equipped with a Trusted Platform Module (TPM).

This document introduces the work performed within the Java™ Specification Request # 321 (JSR321) Expert Group (EG). It contains a detailed description of the technical approach and presents the proposed final specification.

The presented API is based on the Java2 Standard Edition (J2SE) Desktop-PC system architecture.

The JSR321 EG plans for the future to release all final results under free licenses. Specification documents and header, respectively Javadoc definitions will be available for evaluation and allow creating and distributing specification compliant implementations. Reference Implementation and Technology Compatibility Kit will be made available under the GNU GPLv2 with Classpath Exception.

Revision History Version Revision Date Anticipated Release Date Comment 09.04 March 27, 2009 April 10, 2009 Early Draft Review Release 10.11 November 12, 2010

Updated Nov. 19 November 26, 2010 January 3, 2011

Public Review Release

11.04 March 25, 2011 April 8, 2011 Proposed Final Draft

Who Should Use This Specification This document is written for the public community reviewing this specification, the Java™ Community Process (JCP) Expert Group defining this specification, implementers of this API, and application developers targeting the Java™ platform.

Outline The Preface describes this document and introduces the goals of JSR321, the contributors and information on how to review and participate.

The Technical Background chapter outlines the existing specifications of the Trusted Computing Group for hardware and software. It also covers the goals and design decisions for JSR321.

The Normative Part contains binding requirements for all implementations of the JSR321 API. The API is specified in detail.

This document and the accompanying JavaDoc of the API is released under the terms given in the License chapter.

References and Relevant Literature conclude this document.

Introduction

The concept of Trusted Computing (TC) promises an approach to improve the security of computer systems. The core functionality, based on a hardware component known as the Trusted Platform Module (TPM), is being integrated into commonly available hardware. Hundreds of millions of TPMs have shipped so far. Still, only limited software support exists.

Indeed, a recent study on the TCG Software Stack (TSS) [Selhorst] concluded, that, “it is apparent that, until now, no application exists that makes use of this technology. Even the simplest applications, [..] have not been applied yet.”

A reason for this might be the high complexity and slow adoption of the TSS, which is the Trusted Computing Group's industrial standard software accompanying the TPM. It solely supports the C programming language.

However, a major share of the software market is utilizing the platform-independent Java™ environment. The Java™ language provides inherent security features such as type-safety and bounds-checking. The runtime environment provides automated memory management, access control checks and bytecode verification. Performance concerns of Java™ applications can be mitigated by using just-in-time compilation of JavaTM bytecode. Furthermore, a rich set of libraries covers communication and cryptography.

This integrated security by design makes the managed Java™ environment a natural choice as basis for a Trusted Computing Platform. While the current releases of Java™ do not provide support to access the TPM by default, there are already multiple use-cases demonstrated for TC-enabled Java™ Applications.

Thus, the goal of this work is to make TPM and TSS-based features available to Java™ developers in a consistent, object oriented, and also easy-to-use, intuitive way.

JSR321 will allow developers to make use of Trusted Computing functionality based on the Trusted Platform Module (TPM) in their Java™ applications. Striving for a new simplified design, the resulting API will be easier to use than the interfaces available today for other programming languages. This and the fact that all results will be released under an open source license will hopefully foster the use of trusted technology for research, open and also commercial JavaTM applications.

Contributors

Specification Lead: Ronald Toegl, IAIK, Graz University of Technology

The members of the JSR321 Expert Group are

• Ronald Toegl and Peter Lipp, Institute for Applied Information Processing and Communications (IAIK), Graz University Of Technology

• Jeff Nisewanger, Sun Microsystems/Oracle • Deepak Dasaratha Rao, Samsung Electronics Corporation • Winkler, Thomas • Keil, Werner • Hong, Theodore • Nauman, Mohammad • Gungoren, Bora

Former members of the Expert Group are

• Kenneth M. Graf, Intel Corp.

The Expert Group would like to thank Indrawati Schnepp (Atego), Sebastian Panenka (Mixed Mode) and Marc Richard-Foy (Atego) for their extensive feedback and suggestions.

Contributing To This Specification

The Java™ Specification Request No. 321 Expert Group has chosen an open, transparent and agile working style. Thus the technical discussion is also open for non-members of the JCP, allowing for further cooperation with and integration into the Java community.

Reviewers are asked to send their comments and contributions to the specification lead.

The official JSR321 web page is located at http://www.jcp.org/en/jsr/detail?id=321, but it is not freely editable. Thus, JSR321 also makes use of the free services offered by the java.net web platform at http://jsr321.java.net/. It offers the possibility to update the community and informs any interested party on the advances of the specification process.

A Wiki collaboration platform is also available at java.net. The public part can be viewed and edited by every java.net registered user.

To increase the transparency and trustworthiness, both Reference Implementation and Technology Compatibility Kit (TCK) will to be released as open source software under the GNU license. Even more so, the open source and Java™ community are invited to partake in the design as well as in the implementations.

http://www.jcp.org/en/jsr/detail?id=321�

http://jsr321.java.net/�

Open Issues

Currently None.

II. Technical Background and Design

The Needs of the TPM

The Trusted Computing Group (TCG) has specified the Trusted Platform Module. Much like a smart card it features cryptographic primitives, but is physically bound to the platform. A tamper hardened casing contains low-level functional units for asymmetric key cryptography, key generation, cryptographic hashing and random number generation. With the help of these components it can protect against (remote) attackers.

The hardware resources of a TPM are manufacturer implementation specific and typically very limited. For instance, the TPM supplies only a few cryptographic key slots and thus must continually swap keys to and from external storage during operation. It also provides for additional high-level functionality consisting of protected non-volatile storage, integrity collection and reporting (attestation), binding of data to a device or a state (sealing), time stamping and identity management. The state of a system can be evaluated with the help of the Platform Configuration Registers (PCR), using the extend operation, which builds a chain-of-trust consisting of concatenated SHA-1 hashes. Version 1.2 TPMs only support the SHA-1 hash function and RSA asymmetric cryptography in hardware.

For later analysis of the aggregated information, a Stored Measurement Log (SML) must be kept by the system software. Thus, the current TPM design establishes the need for a singleton system software component that authoritatively manages the TPM device resources and arbitrates concurrent accesses from multiple clients. In our experience, this need is a challenge with architectures where direct access to hardware is limited.

TCG Standard Approach for the C Programming Language This section describes an architecture that implements TPM access and management, the TCG Software Stack (TSS) [TSS1.2]. It targets C-based systems and applications and does not consider the requirements of virtualized or managed environments, such as Java™. The Trusted Device Driver Library (TDDL) abstracts the low-level hardware details into a platform independent interface that takes commands and returns responses as byte streams.

Generic TPM 1.2 drivers are integrated in recent Operating System (OS) releases. Resource management is implemented in the Trusted Core Services (TCS), which run as a singleton system service. Additional functionalities provided by the TCS are persistent storage of keys, TPM command generation and communication mechanisms. The TCS event manager handles a log which records PCR extend operations. The upper layers of the software stack may access the TCS in two ways. The first way, intended for development and testing, is a interface that can be accessed directly. An alternative second option is a platform-independent Simple Object Access Protocol (SOAP) interface. It defines a network protocol that manages multiple requests, ensuring proper synchronization. Thus, if the TCS implement SOAP, TPM virtualization at the level of a system service can be provided to applications [Challener]. Furthermore, in the case of SOAP based communication, client applications do not require root privileges to access the TPM hardware. The can use the network protocol stack to communicate with the TCS and TPM.

Applications can access Trusted Computing functionality by using the Trusted Service Provider (TSP) interface. It provides a TCG standardized Context object as entry point to all other functionalities such as policies and key

handling, data hashing, encryption or PCR composition. In addition, mechanism for command authorization and validation are provided. Each application dynamically uses a shared library instance of the TSP interface.

The TSS was also designed to allow partial integration in existing high-level APIs libraries, such as PKCS#11 or as a Cryptographic Service Provider (CSP) in Microsoft CAPI. This enables the use of the cryptographic primitives provided by the TPM. A limitation of this approach is that these legacy cryptographic APIs do not account for high-level TC concepts such as Sealing.

JSR321 API Design Considerations

Design Goals The EG has decided on a number of design goals for the JSR321 API.

• Integration with Existing Trusted Computing Platforms. To the OS, the Java Virtual Machine appears just as an ordinary application. Therefore, the TPM access mechanisms need to integrate with the surrounding environment, be it virtualized or not, and management services.

• Simplified Interface. To make the new API fit into the Java ecosystem, a completely new and fully object-oriented interface is to be designed. For instance, generic objects (e.g., keys) in the TSS should be replaced with instances of specific classes that represent the different types. This allows the set of offered operations to be limited to those actually applicable for a certain object type, thus furthering usability.

• Reduced Overhead. The TSS API requires a substantial amount of boilerplate code for routine tasks, such as key creation, data encryption or password management. The proposed API should attempt to replace these lengthy code fragments with simple calls using sensible default parameters where required.

• Conceptual Consistency. Names in the API should be consistent not only within the API but also with the nomenclature used by the TCG and in Trusted Computing literature. This will allow users to easily switch from other environments to the proposed API. Still, naming conventions of Java must be adhered to.

• Testable and Implementable Specifications. The API design should target a small core set of functionality, based on the essential use cases of Trusted Computing. This restriction in size will allow for complete implementations and functional testing thereof.

• Extendability. The API should allow implementers and vendors to add functionality which is optional or dependent on the capabilities of the surrounding platform.

Limitation from the TCG Architecture Required by the very nature of Java, the JSR321 approach builds on and extends the TSS services offered by the operating system environment. However, while TSS and JSR321 are strongly related in the technical sense, there are significant differences, which stem from the requirements of the design processes and the targeted developer audience. This leads to different functional scopes.

In the process that had been employed to conceive the original TSS specification of the TCG, a working group devised a set of APIs to form an industry specification, covering no less than 757 pages. It not only covers a user-oriented API (the TSPI), but also architectural and internal details clearly intended for developers who plan to build a complete TSS. On the other hand, the actual functionalities are not elaborated in detail; especially the relationship of different commands on the different layers (TSP, TCS, TDDL, and TPM) is not specified.

Unfortunately, functional completeness is not required by implementations. Also, there is no reference implementation of a TSS. As a result, to the best knowledge of the authors, no currently available implementation covers the complete specification. Indeed, several sets of highly complex functionalities were specified, but have not successfully been implemented and tested since the TSS standards were released in 2003 (version 1.1b) and January 2006 (version 1.2).

While recently a compliance test suite for the TPM hardware has been made available to TCG members, there are no test suites or test vectors supplied for the software TSS.

Limited Choice of Cryptographic Algorithms Revison 1.2 of the TPM specifications does not require to offer symmetric cryptography. For asymmetric cryptography, only RSA is offered, but with limited choice of padding schemes. For use in signatures, only the “SHA1withRSA“ scheme is widely available in JCA/JCE implementations. Also, only one cryptographic hash function (SHA-1) is supported. Since 2005, this hash algorithm has been found to be, in theory, less robust than to be expected from a 160-bit cryptographic hash algorithm. In an assessment by IBM and the DoD [Goldman], the impact on the security of the TPM was studied in detail and should be considered before applying TPM 1.2-based TC mechanisms.

The set of algorithms hardcoded in the TPM cannot be influenced by a software architecture such as JSR321.

JSR321 API Scope and Limitations Of course, a clear, comprehensible and compact design is generally preferable. Very much in contrast to the TSS, in the JCP it is impossible to specify functionality without implementations and tests. As a Java™ integration may rely on the TSS-based services of the operating system surrounding the Java™ Virtual Machine (JVM), this imposes natural restrictions to the functional scope of the JSR321 API. We can only use those parts of the TSS spec which are available and thoroughly tested in existing TSS implementations. Also, Java™ developers create mostly application software and middleware and do not need specific support to create operating system level software.

The major design decision for JSR321 is to focus on the most important core concepts of Trusted Computing. The second main goal is to provide a high usability. At the same time, the API is designed to remain modular enough to be extendable to future developments.

Expected Developer Knowledge In general, a developer using JSR321 should be familiar with the cryptographic mechanisms provided in the Java™ Security Architecture. For instance, she should be able to encrypt and decrypt data and files, create and process message digests with hash algorithms and know how to handle key material. She should be familiar with the algorithms used in the TPM (SHA-1, RSA).

A general understanding of Trusted Computing concepts and the mechanisms of the TPM are required. In particular this includes

• TPM Lifecycle and Ownership • Roots of Trust • Chain of Trust • Integrity Measurement, PCRs, and Reporting (Attestation)

• TPM key policies, key types, creation, storage and hierarchy of keys • AIK and AIK certificates • Key Migration (i.e. understand that non-migratable keys cannot be backed up) • Sealing and Binding • Requirements for Trusted Operating Systems • Windows Vista TBS and group policy configurations (on Windows platforms) • Structure of TSS and responsibilities of individual layers, such as TSP, TCS, TDDL, Driver and TPM. • Time stamping • Key certification • Monotonic counter

For interested developers, there is a number of books or other materials available which cover these requirements, especially [Mueller], [Challener], or [Gallery].

Outline of the API

The package name assigned to the JSR321 API is javax.trustedcomputing. Within this space, a number of packages has been specified, each representing a well defined set of functionality. These packages are:

• javax.trustedcomputing.tpm This package contains all relevant functionality for connecting to a TPM. A TPM connection is represented by the central TPMContext object that acts as a factory for other objects specified by the API such as the KeyManager or the Sealer. The TPM interface is also defined in this package, which provides general TPM related information such as its version and manufacturer. Additionally, it allows PCR registers to be read and extended.

• javax.trustedcomputing.tpm.keys Contrary to the TSS specification, JSR321 introduces specific interfaces for the individual key types supported by the TPM. This includes interfaces for storage, sealing and binding keys. Compared to having one generic key object, this approach reduces ambiguities in the API and allows appropriate key usage to be enforced at the interface level.

• javax.trustedcomputing.tpm.structures This package holds data structures required for certain TPM operations. They include the PCREvent structure required for operations on the measurement log, PCRInfo used as part of platform attestation and ValidationData as returned by the TPM quote operation.

• javax.trustedcomputing.tpm.tools In this package, there are interface definitions for helpers classes to perform TPM operations such as binding, sealing, signing and remote attestation.

• javax.trustedcomputing.tpm.tools.remote offers abstract classes that allow a remote host without TPM the interaction in Trusted Computing protocols. It provides the functionality to validate and verify signatures on TC data types.

For error handling, a single TrustedComputingException covers all lower layers. It offers the original TPM/TSS error codes, but also a human readable text representation, which is a great step forward in terms of usability. Despite using only a single exception class, implementations of the API should forward as much error information as possible. For illegal inputs to the JSR321 API, default Java runtime exceptions are used. Finally, functions offering bit-wise access to status and capability flags are replaced by specific methods that allow access to application relevant flags.

In JSR321, the KeyManager interface defines methods for creating new TPMKeys. Upon creation, a secret for key usage and an optional secret for key migration have to be specified. After a key is created, the KeyManager allows the key, encrypted by its parent, to be stored in non-volatile storage. As required, the KeyManager allows keys to be reloaded into the TPM, provided that the key chain up to the storage root key has been established (i.e. each parent key is already loaded into the TPM). Every time a new key is created or loaded from permanent storage, a usage secret has to be provided. This secret is represented by an instance of a dedicated class Secret that is attached to the key object upon construction. Secret also encapsulates and handles details such as string encoding, which are often a source of incompatibility between different TPM-based applications.

Figure 1: Illustration of the relationship between the core components, including the TPMContext,KeyManager, and Key classes and the Tools.

The extendable tools package implements various core concepts of Trusted Computing. As each tool that accesses the TPM is already linked to a TPMContext at creation, there are few or no configuration settings required before using the tool. Each tool provides a small group of methods that offer closed functionality. For example, a Binder allows the caller to bind data under a BindingKey and a Secret, and returns the encrypted byte array. Usage complexity is minimal as no further parameters need to be configured and the call to unbind encrypted data is completely symmetric. In addition to the core set of tools (Signer, Binder, Sealer, Attestor), implementers of JSR321 may add further sets of functionality. An example is the tool Initializer which manages TPM ownership. It is only needed, if the Java™ library is implemented on an OS without tools for doing so.

Feature Selection

JSR321 will provide functionality focused on applications, rather than provide support for the low level BIOS or OS features of the TPM. This restriction matches the field of use of Java™ and allows reducing the complexity significantly. Also, JSR321 will not duplicate existing elements of the Java™ Cryptography Architecture, thus melting in with the existing library framework. The API will revolve around the object and key usage and handling policies implemented by the TPM. A package of tool methods will enable more of its unique features and also allow for optional and vendor specific plug-ins.

To derive the functional scope of the API, the commented complete list of TCG-specified TSP functions [Challener] was considered. As the JSR321 API will not support TPM functionalities targeted for use by the BIOS (for instance hardware implementation of hashing) or the operating system (for instance take ownership), we filtered the list of functions, so that only features designed for applications, and middleware remained.

TPM Identity Management depends on remote PrivacyCA services with no currently established, uniform protocol available. It is therefore a task for the operating system or external tools.

In addition, many of those TSS functions are simply not needed in Java™ APIs:

• Management of memory and other resources can and should be hidden from application developers.

• Object initialization and destruction are natural features of object-oriented languages.

• Cryptographic primitives like hash functions are already well-supported in the Java™ Cryptography Extension. Also, due to the restricted choice of hardware supported algorithms, it is advisable to use the more flexible JCE mechanisms and possibly other algorithms in applications. Note however, that using SHA-1 in the API cannot be avoided in all operations that directly involve the TPM (e.g., extending PCRs or digital signing of data).

For error handling, a single TrustedComputingException covers all lower layers. It offers the original TPM/TSS error codes, but also a human readable text representation, which is a great step forward in terms of usability. Despite using only a single Exception class, implementations of the API should forward as much error information as possible. For illegal inputs to the JSR321 API, default Java™ runtime exceptions are used.

Finally, functions offering bit-wise access to status and capability flags are replaced by specific methods that allow access to application relevant flags.

The following table summarizes the features selected.

TSS C-Function Name Description Reason for Removal or Implementation

Visible in API

JSR321 Object that will handle the functionality

Tspi_GetAttribUint32 Find out the value of an integer attribute of an object.

Access to basic information on TSS

No TPM

Tspi_GetAttribData Get a non-integer attribute of an object.

Access to basic information on TSS

No TPM

Tspi_GetPolicyObject Find out the current authorization policy associated with the context.

Essential for processing commands

Yes Hidden. Configured using Secret object

Tspi_Context_Close Close a context. Context Sessions are essential to TPM

Yes TPMContext

Tspi_Context_Connect Connect to a context after it is created.

Context Sessions are essential to TPM

Yes TPMContext

Tspi_Context_Create Create a context. Context Sessions are essential to TPM

Yes TPMContext

Tspi_Context_FreeMemory

Free memory allocated by a Tspi-level function.

Java hides Memory Management

- -

Tspi_Context_GetDefaultPolicy

Use the default authorization policy for the creation of an object.

Essential No Hidden. Configured using Secret object

Tspi_Context_CreateObject

Create an object, such as a key object. After creating the object, the fields in the object need to be set.

TPM object live in Contexts

Yes TPMContext

Tspi_Context_CloseObject

Destroy an object. Java manages resources

No -

Tspi_Context_GetCapability

Get the current capabilities of the context.

Configuration of Context

No TPMContext

Tspi_Context_GetTPMObject

Get the TPM object associated with a context.

Essential Yes TPMContext

Tspi_Policy_FlushSecret

Remove the authorization data from memory.

Desirable for security.

Yes Secret destruction could be difficult in actual implementations (delayed garbage collection)

Tspi_Policy_AssignToObject

How one assigns a policy to an object—for example, a key.

Essential for processing commands

No Hidden. Configured using Secret object

Tspi_TPM_GetCapability

Get the set of capabilities of the TPM.

Access to basic information on TPM

No TPM

Tspi_TPM_SetCapability

Set capabilities of the TPM. Access to basic information on TPM

No TPM

Tspi_TPM_GetRandom Return a random number of the specified size.

Useful feature Yes TPM

Tspi_TPM_StirRandom A means of adding entropy to the internal random number generator. It is a good habit to call it with the current time. (Because it only adds entropy, it can never hurt.)

Useful feature Yes TPM

Tspi_Key_GetPubKey Get the public key of a key pair.

Vital Feature Yes TPMKey

Tspi_Hash_Sign Hashes and signs data with a given key.

Useful feature No Signer

Tspi_Hash_VerifySignature

Verifies the signature of given data.

Useful feature No RemoteSigner

Tspi_Hash_SetHashValue

Set a particular hash value if you don't happen to want to use SHA-1.

Standard feature in JCE

- -

Tspi_Hash_GetHashValue

Determine the current value of a hash object.


- -

Tspi_Hash_UpdateHashValue

Add new data into a hash object, which continues the hash in the way defined by the hash algorithm. Currently only SHA-1 is supported.


- -

Tspi_Data_Unbind Unbind data by decrypting with a private storage key. This takes place inside the TPM.

Useful feature Yes Binder

Tspi_Data_Unseal Decrypt data sealed to a TPM when PCRs are in a determined state (and optional authorization data is present).

Useful feature Yes Sealer

Tspi_PcrComposite_ SelectPcrIndex

Select a particular set of PCRs in a PcrComposite object.

Vital Feature Yes PCRInfo

Tspi_PcrComposite_ SetPcrValue

Set what values the PCRs in a PcrComposite object should have. This is preparation for doing a seal.


Tspi_PcrComposite_ GetPcrValue

Returns the current value of a PCR in a PcrComposite object.


Tspip_CallbackHMACAuth

Used by an application if it doesn't want to use the default mechanism for creating an HMAC for proving knowledge of authorization data.

C-style callback functions are not needed in Java

- -

Tspip_CallbackXorEnc Used to provide a means of inserting a secret to a TPM object (such as when doing a change auth) without allowing sniffing software to see what the new authorization is as it goes by.


- -

Tspip_CallbackTakeOwnership

Take ownership of a TPM using a callback mechanism.


- -

Tspip_CallbackChange AuthAsym

Use a callback mechanism to change authorization.


- -

Tspi_Data_SealX Just like Seal, except that it can also use locality and record historical PCR values for PCRs other than the ones it is locking to.

Nice to have No -

Tspi_TPM_Quote2 Provide more information (including locality stuff) than Tspi_TPM_Quote does.

Vital Feature Yes Attestor

Tspi_PcrComposite_ SetPcrLocality

Set the locality settings for a PcrComposite structure.

Nice to have No PCRInfo

Tspi_PcrComposite_ GetPcrLocality

Return the locality settings of a PcrComposite structure.

Nice to have No PCRInfo

Tspi_PcrComposite_ GetCompositeHash

Return the Composite hash of the PcrComposite structure.

Vital Feature No PCRInfo

Tspi_PcrComposite_ SelectPcrIndexEx

Because the new Pcr_long structure independently sets which PCRs to record historically and which to use for release, this command was needed to set them individually.

Hidden implementation detail

No PCRInfo

Tspi_TPM_ReadCurrentCounter

Read the value of the current counter.

Nice to have, monotonic counters are not supported in current OSes

No -

Tspi_TPM_ReadCurrentTicks

Read the current tick value (which corresponds loosely to time) of the TPM.

Useful, but TCG specifications are ambiguous

No -

Tspi_Hash_TickStampBlob

Sign data together with the current tick value and tick nonce. Uses an AIK.

Useful, but TCG specifications are ambiguous

No -

Tspi_NV_DefineSpace Create a section of NVRAM and associates it with specific authorization (such as authorization data, PCR values, locality, or once per power on).

NV RAM Access is not needed for applications

- -

Tspi_NV_ReleaseSpace Put NVRAM space previously allocated back into the pool.


- -

Tspi_NV_WriteValue Write a value to the NVRAM space previously allocated.


- -

Tspi_NV_ReadValue Read a value from NVRAM space previously allocated.


- -

Tspi_TPM_DAA_Sign Use a DAA credential to verify either a message or an AIK.


- -

Tspi_TPM_GetAuditDigest

Get the current audit digest of the TPM.

TPM Implementations do not support Audits

- -

Tspi_TPM_SetOrdinal AuditStatus

Set an ordinal to be audited. TPM Implementations do not support Audits

- -

Tspicb_CallbackSealxMask

Used when masking or unmasking data sent or returned with Data_SealX or Tspi_Data_Unseal operations.


No Sealer

Tspicb_CollateIdentity

Because it isn't clear what encryption algorithms will be required by a certificate authority, this command can be used to encrypt the

Optional functionality for AIK Cycle

No -

collated information with any encryption algorithm.

Tspicb_ActivateIdentity

Similarly, when a certificate is encrypted by the certificate authority, the decryption will be done entirely in software, so this command allows any decryption algorithm trusted by the certificate authority to be used.


No -

Tspicb_DAA_Sign Extend properties of the DAA protocol.

No DAA reference implementations available

- -

Tspicb_DAA_VerifySignature

Extend the usefulness of the DAA protocol.

No DAA reference implementations available

- -

Tspi_Key_LoadKey Load a particular key into the TPM.

Vital Feature No TPMKey

Tspi_ChangeAuth Create a new object with a different authorization.

Vital Feature Yes TPMKey

Tspi_ChangeAuthAsym Create a new object with a different authorization (but the same other internal parameters) without revealing knowledge of the new authorization to the parent key.

Implementation Detail

No -

Tspi_Context_LoadKeyBlob

Load an encrypted key blob into the TPM, used when you have the key blob file.


No KeyManager

Tspi_Context_LoadKeyByUUID

Load a key into the TPM when you know its UUID.

Vital Key Management Feature

Yes KeyManager

Tspi_Context_UnregisterKey

Remove a key from a user or system key store.


Yes KeyManager

Tspi_Context_DeleteKey ByUUID

Remove a key from the TPM referenced by UUID.


Yes KeyManager

Tspi_Context_GetKeyByUUID

Search for a key by its UUID, and returns a handle to it.


Yes KeyManager

Tspi_Context_GetKey ByPublicInfo

Search for a key by its public data and returns a handle to it.


Yes KeyManager

Tspi_Context_Get Registered Keys ByUUID

Return a list of all the registered keys in a registry, along with their UUIDs.


Yes KeyManager

Tspi_TPM_GetStatus Find out how bits in the TPM are set.

Basic TPM feature Yes TPM

Tspi_TPM_Quote Uses an ID to sign the PCRs currently in the TPM. A nonce is used to guarantee freshness.

Vital Feature Yes Attestor

Tspi_Key_ConvertMigrationBlob

Import a migration blob from a migratable key.

Migration is optional No -

Tspi_TPM_CertifySelfTest

Tells the TPM to use an AIK to certify the self-test results.

Not useful for applications

No -

Tspi_TPM_GetTestResult

Get the self test result, unsigned.


No -

Tspi_SetAttribUint32 Set an integer attribute of an object.


No -

Tspi_SetAttribData Set a non-integer attribute of an object.


No -

Tspi_Policy_SetSecret

How one associates authorization data with a policy, to be used, for example, in creating or using a key.

Key Feature No Hidden using Secret

Tspi_TPM_PcrExtend Extend a particular PCR. Vital Feature Yes TPM

Tspi_Data_Bind Bind data to a TPM by encrypting it with a public storage key. This takes place outside the TPM.

Vital feature Yes RemoteBinder

Tspi_Data_Seal Encrypt data to a TPM key and PCR values. It can be done only inside the TPM because it also registers historical data as to the PCR values in the TPM when the command is done.

Useful feature Yes Sealer

Tspi_Context_RegisterKey

Register a key into either a user's key store or a system's key store and returns the UUID.


Yes KeyManager

Tspi_TPM_GetPub EndorsementKey

Return the public portion of the endorsement key.


No -

Tspi_TPM_Collate IdentityRequest

Gather all the information a certificate authority will need in order to provide a certificate for an AIK.


No -

Tspi_TPM_ActivateIdentity

Take the encrypted returned data from the certificate authority, and use it to determine the decryption key used to return the certificate for an AIK to the owner.


No -

Tspi_TPM_SetStatus Set bits in the TPM. Not useful for applications

- -

Tspi_TPM_SelfTestFull

Tells the TPM to execute a full self test.


- -

Tspi_TPM_PcrRead Read a particular PCR. Useful Feature Yes TPM

Tspi_Key_CertifyKey Create a certificate of a non-migratable key by signing it and its characteristics with an AIK (ID).

Useful Feature Yes TPMKey

Tspi_Key_CreateKey Create a new RSA key. Vital Key Management Feature

Yes KeyManager

Tspi_Key_WrapKey Wrap an already extant RSA private key.


Yes KeyManger

Tspi_Key_CreateMigrationBlob

Create a migration blob from a migratable key.

Migration is optional Yes -

Tspi_Key_UnloadKey Remove a key in the TPM. Vital Key Management Feature

Yes TPMKey

III. Normative Part

Definitions This document uses definitions based upon those specified in RFC 2119.

Term Definition MUST The associated definition is an absolute requirement of this specification. MUST NOT The definition is an absolute prohibition of this specification. SHOULD Indicates a recommended practice. There may exist valid reasons in particular circumstances to

ignore this recommendation, but the full implications must be understood and carefully weighed before choosing a different course.

SHOULD NOT

Indicates a non-recommended practice. There may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

MAY Indicates that an item is truly optional.

Requirements

• Implementations aiming to be JSR321 compliant MUST be designed to use a TPM that conforms to Trusted Computing Group’s TPM specification version 1.2 or higher. Final implementations of the JSR321 API MUST NOT emulate TPM functionality in software but use TPM functionality made available by the underlying operating system. While by default this functionality is provided by a hardware TPM, in the context of e.g. virtualized environments that MAY be a virtualized, TCG-specification compliant TPM providing equivalent security characteristics as a hardware TPM.

• JSR321 implementations SHOULD integrate with TPM management software of the Operating System. An implementation MAY also choose to directly access the TPM.

• Implementations of this technology MAY support J2SE 1.2 or later but MUST at a minimum support version 1.5 or later of J2SE.

• Any JSR321 implementation SHOULD allow safe multiple concurrent accesses to the TPM by different Java™ and non-Java™ applications.

• Java™ applications using JSR321 MUST NOT require “root” or “Administrator” privileges to access the TPM.

• JSR321 is NOT a specification for a TCG Software Stack (TSS). It does not specify aspects like managing the hardware resources of the TPM. As a high-level interface, implementations of JSR321 MAY be based on a TSS.

• JSR321 does NOT cover operating system related functionalities of the TPM. However, implementations can OPTIONALLY provide those.

• JSR321 implementations MUST consider and document thread-safety. • Implementations MAY add optional functionality as new classes or methods to the API, especially the

tools package. This additional functionality SHOULD NOT duplicate existing API functionality.

Detailed API Specifications

JSR321API 23.03.11 11:12

Package Summary Page

javax.trustedcomputing This package and its subpackages provide for integration of Trusted Computing in Java.

20

javax.trustedcomputing.tpm This package allows to connect to a Trusted Platform Module (TPM). 23

javax.trustedcomputing.tpm.keys This package allows the creation, storage, loading and unloading of hierarchies of TPM keys.

38

javax.trustedcomputing.tpm.structures This package contains helper classes for interaction with various other classes from the javax.trustedcomputing.tpm package.

55

javax.trustedcomputing.tpm.tools This package allows using various core concepts of Trusted Computing. 64

javax.trustedcomputing.tpm.tools.remote This package allows using various core concepts of Trusted Computing from a remote host.

75

Package javax.trustedcomputing

This package and its subpackages provide for integration of Trusted Computing in Java.

See:

Description

Exception Summary Page

TrustedComputingException The default Exception used in the javax.trustedcomputing package. 21

Package javax.trustedcomputing Description

This package and its subpackages provide for integration of Trusted Computing in Java. This is an proposed final draft of the JSR321 API.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:

• JSR 321 Web

Copyright

https://jsr321.java.net/�

Package javax.trustedcomputing

Copyright (c) IAIK, Graz University of Technology, 2011. All rights reserved. This JavaDoc is provided for review under the terms given in the License chapter of the accompanying documentation. Reviewers should send their comments and contributions to the specification lead.

Class TrustedComputingException javax.trustedcomputing

java.lang.Object

java.lang.Throwable

java.lang.Exception

javax.trustedcomputing.TrustedComputingException

All Implemented Interfaces: Serializable

abstract public class TrustedComputingException

extends Exception

The default Exception used in the javax.trustedcomputing package. It covers all unexpected behaviors on all levels of the trusted platform. This includes also the errors raised in lower layers of the TCG architecture such as error codes returned from the TPM, and the TSS and its sub-layers.

Field Summary Page

static long

HIGH_LEVEL_API_LAYER_ERROR

Numeric Error code returned when the TrustedComputingException was raised at JSR 321 level.

22

Constructor Summary Page

TrustedComputingException() 22

Method Summary Page

abstract Throwable

getCause()

Returns the originally thrown Exception. 22

abstract long

getLowLevelErrorCode()

Returns the detailed C-styled error code that is generated by lower-level software components that connect to the TPM.

22

abstract String

getMessage()

Returns a detailed text description of the error cause. 22

Class TrustedComputingException

abstract String

getShortMessage()

Returns a short, one-line text description of the error cause. 23

Field Detail

HIGH_LEVEL_API_LAYER_ERROR

public static final long HIGH_LEVEL_API_LAYER_ERROR

Numeric Error code returned when the TrustedComputingException was raised at JSR 321 level. The value is 0x00004000.

Constructor Detail

TrustedComputingException

public TrustedComputingException()

Method Detail

getCause

public abstract Throwable getCause()

Returns the originally thrown Exception. The returned type is implementation specific and may be null.

Overrides:

getCause in class Throwable

getLowLevelErrorCode

public abstract long getLowLevelErrorCode()

Returns the detailed C-styled error code that is generated by lower-level software components that connect to the TPM. The error may have been caused by the OS, the TPM, and the TSS, on TDDL, TCS, TSP layers. If the error results from the high-level API, no specific error code is returned, but a general HIGH_LEVEL_API_LAYER_ERROR. Then a more detailed error description is to be communicated Java Style via the String or specialized derived exceptions.

Returns:

detailed error code

getMessage

public abstract String getMessage()

Returns a detailed text description of the error cause. If available, this includes indication of TCG error codes and layer information.

Class TrustedComputingException

Overrides:

getMessage in class Throwable

getShortMessage

public abstract String getShortMessage()

Returns a short, one-line text description of the error cause.

Package javax.trustedcomputing.tpm

This package allows to connect to a Trusted Platform Module (TPM).

See:

Description

Interface Summary Page

TPM This represents the hardware TPM and the basic functionalities it offers. 24

Class Summary Page

TPMContext The Context class is the centerpiece of the JSR321 API. 31


PCRsNotAccessibleException This Exception is thrown if an operation that access the PCRs is blocked by the operating system.

24

Package javax.trustedcomputing.tpm Description

This package allows to connect to a Trusted Platform Module (TPM). The TPMContext class serves as object factory for the TPM and KeyManager classes. This package and its subpackages allow to

• Access and configure the TPM. • Manage TPM-protected cryptographic keys. • Utilize core Trusted Computing concepts.

Note that the hardware TPM offers only a restricted set of cryptographic algorithms that might not match your requirements. It is advisable to use the more flexible mechanisms and different algorithms offered in the Java Cryptography Extension for any task that is not directly dependent on the hardware Trusted Computing mechanisms of the TPM.

Class PCRsNotAccessibleException

Class PCRsNotAccessibleException javax.trustedcomputing.tpm

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

javax.trustedcomputing.tpm.PCRsNotAccessibleException


public class PCRsNotAccessibleException

extends RuntimeException

This Exception is thrown if an operation that access the PCRs is blocked by the operating system. On Windows, the TPM Base Services (TBS) block any operation accessing the PCR registers. This is set in the default group policies and may be changed by the administrator.


PCRsNotAccessibleException(String string) 24

Constructor Detail

PCRsNotAccessibleException

public PCRsNotAccessibleException(String string)

Interface TPM javax.trustedcomputing.tpm

public interface TPM

This represents the hardware TPM and the basic functionalities it offers. It allows to query the status and capabilities of the hardware TPM and provides access to the random number generator. It also provides access to the Platform Configuration Registers (PCRs). Instances are created by TPMContext.

Interface TPM

Field Summary Page

String PROPERTY_JSR_REVISION

Property key to query the JSR321 specification revision. 26

String PROPERTY_JSR_VERSION

Property key to query the JSR321 implementation version. 27

String PROPERTY_NUMBER_PCRS

Property key to query the amount of available PCRs on the TPM. 27

String PROPERTY_TPM_FIRMWARE_VERSION

Property key to query the TPM firmware version. 26

String PROPERTY_TPM_MANUFACTURER

Property key to query the TPM manufacturer. 26

String PROPERTY_TPM_VERSION

Property key to query the TPM specification version. 26

String PROPERTY_TSS_VENDOR

Property key to query the vendor of the underlying TSS. 26

String PROPERTY_TSS_VERSION

Property key to query the version of the underlying TSS. 26

Method Summary Page

void extendPCR(int PCRindex, Digest data)

Performs the Extend operation with the given data on the selected PCR. 29

void extendPCR(int PCRindex, PCREvent event)

Performs the Extend operation with the given event on the selected PCR. 29

int getNumberPCR()

Provides the number of PCR registers provided by this TPM. 28

Object getProperty(String property)

Allows to query properties and information on the Trusted Computing mechanisms of this platform. 30

byte[] getRandom(int length)

Returns an array of random numbers, generated by the cryptographic true random number generator of the TPM.

27

boolean isActivated()

Determines the status of the TPM operation mode (Activated/Deactivate). 27

boolean isEnabled()

Determines the status of the TPM operation mode (Enables/Disabled). 28

Interface TPM

boolean isOwned()

Determines the status of the TPM operation mode (Owned or no ownership taken). 28

PCRInfo readPCR(int[] PCRindices)

Reads the current values of a set of PCR registers from the TPM. 29

void stirRandom(byte[] entropy)

Allows to add entropy to the hardware Random Number Generator of the TPM. 30

Field Detail

PROPERTY_TPM_MANUFACTURER

public static final String PROPERTY_TPM_MANUFACTURER

Property key to query the TPM manufacturer. Returned type is String. The TPM vendor ID string will have a maximum string length of four characters and it will not have a terminating zero.

PROPERTY_TPM_VERSION

public static final String PROPERTY_TPM_VERSION

Property key to query the TPM specification version. Returned type is String. For example, a version 1.2 TPM this will return "1.2".

PROPERTY_TPM_FIRMWARE_VERSION

public static final String PROPERTY_TPM_FIRMWARE_VERSION

Property key to query the TPM firmware version. Returned type is String.

PROPERTY_TSS_VENDOR

public static final String PROPERTY_TSS_VENDOR

Property key to query the vendor of the underlying TSS. Returned type is String.

PROPERTY_TSS_VERSION

public static final String PROPERTY_TSS_VERSION

Property key to query the version of the underlying TSS. Returned type is String.

PROPERTY_JSR_REVISION

public static final String PROPERTY_JSR_REVISION

Interface TPM

Property key to query the JSR321 specification revision. Returned type is String.

PROPERTY_JSR_VERSION

public static final String PROPERTY_JSR_VERSION

Property key to query the JSR321 implementation version. Returned type is String.

PROPERTY_NUMBER_PCRS

public static final String PROPERTY_NUMBER_PCRS

Property key to query the amount of available PCRs on the TPM. Returned type is Integer.

Method Detail

getRandom

byte[] getRandom(int length) throws TrustedComputingException

Returns an array of random numbers, generated by the cryptographic true random number generator of the TPM. It is advisable to use the result as seed for a cryptographic software RNG.

Parameters:

length - The number of bytes. The length must not exceed 4096 bytes.

Returns:

the entropy provided from the TPM. Its length may be less than requested.

Throws:


isActivated

boolean isActivated() throws TrustedComputingException

Determines the status of the TPM operation mode (Activated/Deactivate). If it is deactivated, TPM functionalities are not available. A common cause for a de-activated TPM is an application that switched off the TPM temporarily until the next system restart.

Returns:

true if the TPM is activated.

Throws:


Interface TPM

isEnabled

boolean isEnabled() throws TrustedComputingException

Determines the status of the TPM operation mode (Enables/Disabled). If it is disabled, TPM functionalities are not available. This is the default shipping configuration for most devices. Typically, the TPM must be enabled in the BIOS.

Returns:

true if the TPM is enabled.

Throws:


isOwned

boolean isOwned() throws TrustedComputingException

Determines the status of the TPM operation mode (Owned or no ownership taken). If it is un-owned, certain TPM functionalities are not available. If so, the owner of the platform has not yet defined an owner authentication secret and a SRK secret. Typically, the operating system provides a tool to take ownership.

Returns:

true if the TPM is enabled.

Throws:


getNumberPCR

int getNumberPCR() throws TrustedComputingException

Provides the number of PCR registers provided by this TPM. For TPM 1.2 this number is at least 24.

Returns:

the number of PCR registers.

Throws:


Interface TPM

extendPCR

void extendPCR(int PCRindex, Digest data) throws TrustedComputingException, PCRsNotAccessibleException

Performs the Extend operation with the given data on the selected PCR. On Windows systems, any PCR access is by default blocked.

Parameters:

PCRindex - The PCR to be changed

data - This will be passed to the TPM unchanged.

Throws:


PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System

extendPCR

void extendPCR(int PCRindex, PCREvent event) throws TrustedComputingException

Performs the Extend operation with the given event on the selected PCR. It also logs the event accordingly in the Storage Measurement Log. On Windows OS, any PCR access is by default blocked.

Parameters:

PCRindex - The PCR to be changed

event - Contains the event description and the value passed on to the TPM.

Throws:



readPCR

PCRInfo readPCR(int[] PCRindices) throws TrustedComputingException

Reads the current values of a set of PCR registers from the TPM. On Windows OS, any PCR access is by default blocked.

Parameters:

PCRindices - The index values of the PCRs to be included in the result. 1.2 TPMs offer at least 24 PCRs.

Interface TPM

Returns:

the set of PCR values.

Throws:



stirRandom

void stirRandom(byte[] entropy) throws TrustedComputingException

Allows to add entropy to the hardware Random Number Generator of the TPM.

Parameters:

entropy - Data to add entropy to the TPM's hardware true RNG state. Length must not exceed 256.

Throws:


getProperty

Object getProperty(String property)

Allows to query properties and information on the Trusted Computing mechanisms of this platform. Valid keys are:

• PROPERTY_TPM_MANUFACTURER • PROPERTY_TPM_VERSION • PROPERTY_TPM_FIRMWARE_VERSION • PROPERTY_TSS_VENDOR • PROPERTY_TSS_VERSION • PROPERTY_JSR_REVISION • PROPERTY_JSR_VERSION • PROPERTY_NUMBER_PCRS

Parameters:

property - The key of the property to be queried.

Returns:

The property value.

Class TPMContext

Class TPMContext javax.trustedcomputing.tpm

java.lang.Object

javax.trustedcomputing.tpm.TPMContext

abstract public class TPMContext

extends Object

The Context class is the centerpiece of the JSR321 API. It serves as central object factory. All TPM-depending objects are created here. While there may exist several TPMContext at the same time, all derived Objects (such as keys) are only valid within one TPMContext session instance.

Method Summary Page

abstract void

close()

Closes the connection to the TPMContext session. 32

abstract void

connect(URL remoteAdress)

Connects this TPMContext to a TPM context session. 32

abstract Attestor

getAttestor()

Creates an instance of Attestor that provides all services for remote attestation. 38

abstract Binder

getBinder()

Creates a Binder object that provides functionality for TPM-based binding. 35

abstract Certifier

getCertifier()

Creates an instance of the optional Certifier tool that provides all services for key certification. 38

abstract Digest

getDigest(byte[] digest)

Creates a Digest, which holds a given SHA-1 hash. 36

abstract Initializer

getInitializer()

Returns an Initializer that allows the initial configuration of the TPM, for instance taking ownership.

37

static TPMContext

getInstance()

returns an instance of a TPMContext implementation. 33

static TPMContext

getInstance(String className)

returns an Instance of a TPMContext implementation. 33

abstract KeyManager

getKeyManager()

Creates an instance of KeyManager which handles all operations to create, store and load keys. 34

abstract PCREvent

getPCREvent(long eventType, Digest data, String eventDescription)

Returns an initialized PCREvent object. 37

Class TPMContext

abstract PCRInfo

getPCRInfo()

Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24). 36

abstract PCRInfo

getPCRInfo(int numberOfPCRs)

Creates a PCRInfo object with a given number of PCR registers, which cannot be changed once set.

36

abstract Sealer

getSealer()

Creates a Sealer object that provides functionality for TPM-based data sealing. 35

abstract Secret

getSecret(char[] password)

A Secret is a convenient representation of hashed passwords used to authenticate operations with the TPM.

37

abstract Secret

getSecret(char[] password, boolean addNullTermination, Charset encoding)

Creates a Secret object that contains a password which will be converted according to the Charset encoding and optional null-termination settings which are applied before performing the SHA-1 hash operation.

37

abstract Secret

getSecret(Digest hashedSecret)

Creates a Secret object directly from a SHA-1 hash. 36

abstract Signer

getSigner()

Creates a Signer object that provides functionality for signing data with TPM-protected keys. 35

abstract TPM

getTPMInstance()

Creates an implementation-specific instance of TPM. 34

abstract boolean

isConnected()

Determines if a TPMContext is connected to the session context of a hardware TPM. 34

Method Detail

close

public abstract void close() throws TrustedComputingException

Closes the connection to the TPMContext session. Invalidates all objects that depend on it. It is not possible to revert to a previous session once it is closed.

Throws:


connect

public abstract void connect(URL remoteAdress) throws TrustedComputingException

Class TPMContext

Connects this TPMContext to a TPM context session. Typically this is provided by a service of the TCG's TSS at TCS layer. Not only the local TPM can be accessed, but also a remote machine could offer the service interface.

Parameters:

remoteAdress - The URL to connect to. If null, the local TPM is accessed.

Throws:


getInstance

public static TPMContext getInstance() throws ClassCastException, ClassNotFoundException, InstantiationException, IllegalAccessException

returns an instance of a TPMContext implementation. The returned context is not connected yet.

As part of its initialization, the TPMContext class will attempt to load a class that extends and implements TPMContext and is referenced in the "jsr321.tpmcontextimpl" system property. This allows a user to customize the JSR 321 implementation used on their system. For example in your ~/.hotjava/properties file you might specify:

jsr321.tpmcontextimpl=foo.bah.TPMContextImpl

Returns:

an implementation specific instance of TPMContext.

Throws:

ClassCastException

ClassNotFoundException

InstantiationException

IllegalAccessException

getInstance

public static TPMContext getInstance(String className) throws ClassCastException, ClassNotFoundException, InstantiationException, IllegalAccessException

returns an Instance of a TPMContext implementation. The returned Context is not connected yet. This method allows to load a specific implementation of JSR 321.

Class TPMContext

Parameters:

className - The name of the class that extends and implements TPMContext.

Returns:

an implementation specific instance of TPMContext.

Throws:

ClassCastException

ClassNotFoundException

InstantiationException

IllegalAccessException

getTPMInstance

public abstract TPM getTPMInstance() throws TrustedComputingException

Creates an implementation-specific instance of TPM. It is bound to this TPMContext and to the hardware TPM.

Returns:

an initialized TPM object for this TPMContext

Throws:


isConnected

public abstract boolean isConnected() throws TrustedComputingException

Determines if a TPMContext is connected to the session context of a hardware TPM. All functionality of TPMContext and derived objects can only be accessed if connected.

Returns:

true if this TPMContext is currently connected to a hardware TPM

Throws:


getKeyManager

public abstract KeyManager getKeyManager() throws TrustedComputingException

Class TPMContext

Creates an instance of KeyManager which handles all operations to create, store and load keys.

Returns:

a KeyManager which is linked to this TPMContext and its hardware TPM.

Throws:


getSealer

public abstract Sealer getSealer() throws TrustedComputingException

Creates a Sealer object that provides functionality for TPM-based data sealing. Sealing is the encryption of data to a TPM-protected key and PCR configuration.

Returns:

a Sealer which is linked to this TPMContext

Throws:


getBinder

public abstract Binder getBinder() throws TrustedComputingException

Creates a Binder object that provides functionality for TPM-based binding. Binding is the encryption of data to a TPM-protected key.

Returns:

a Binder which is linked to this TPMContext

Throws:


getSigner

public abstract Signer getSigner() throws TrustedComputingException

Creates a Signer object that provides functionality for signing data with TPM-protected keys.

Returns:

a Signer which is linked to this TPMContext

Class TPMContext

Throws:


getDigest

public abstract Digest getDigest(byte[] digest)

Creates a Digest, which holds a given SHA-1 hash. This class allows for more convenient use of the API, but does not perform hashing operations.

Parameters:

digest - An array of bytes, with an exact length of 20 bytes.

Throws:

IllegalArgumentException - if the size of digest is not exactly 20.

getPCRInfo

public abstract PCRInfo getPCRInfo()

Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24). Platform Configuration Registers hold disgests that describe a system's configuration.

getPCRInfo

public abstract PCRInfo getPCRInfo(int numberOfPCRs)


Parameters:

numberOfPCRs - The number of PCRs to consider. Must be greater than zero. TPM 1.2 typically provide 24 PCRs or more.

getSecret

public abstract Secret getSecret(Digest hashedSecret)

Creates a Secret object directly from a SHA-1 hash. Secrets are convenient representations of hashed passwords used to authenticate operations with the TPM.

Parameters:

hashedSecret - The already hashed secret.

Class TPMContext

getSecret

public abstract Secret getSecret(char[] password)

A Secret is a convenient representation of hashed passwords used to authenticate operations with the TPM. The input will be encoded to "UTFl16LE" and hashed using the SHA-1 algorithm.

Parameters:

password - The plaintext password as character array.

getSecret

public abstract Secret getSecret(char[] password, boolean addNullTermination, Charset encoding)

Creates a Secret object that contains a password which will be converted according to the Charset encoding and optional null-termination settings which are applied before performing the SHA-1 hash operation. Use this only for inter-operability with passwords encoded by legacy applications. Secrets are convenient representations of hashed passwords used to authenticate operations with the TPM.

Parameters:

password - The plaintext password as character array.

addNullTermination - indicates if a trailing zero is appended before hashing.

encoding - indicated the Charset that is used to generate the byte-stream to be hashed. For example Charset.forName("ASCII"). Relevent charsets may be "UTF-16LE" or "ASCII".

getPCREvent

public abstract PCREvent getPCREvent(long eventType, Digest data, String eventDescription)

Returns an initialized PCREvent object.

Parameters:

eventType - A numerical representation of the event type.

data - The hash digest of the data to be extended.

eventDescription - A description that is added to the system's Stored Measurement Log.

getInitializer

public abstract Initializer getInitializer() throws TrustedComputingException, UnsupportedOperationException

Class TPMContext

Returns an Initializer that allows the initial configuration of the TPM, for instance taking ownership. It will throw an UnsupportedOperationException if this optional tool is not implemented.

Throws:


UnsupportedOperationException

getAttestor

public abstract Attestor getAttestor() throws TrustedComputingException

Creates an instance of Attestor that provides all services for remote attestation.

Returns:

a Attestor which is linked to this TPMContext and its hardware TPM.

Throws:


getCertifier

public abstract Certifier getCertifier() throws TrustedComputingException, UnsupportedOperationException

Creates an instance of the optional Certifier tool that provides all services for key certification. It will throw an UnsupportedOperationException if this optional tool is not implemented.

Returns:

a Certifier which is linked to this TPMContext and its hardware TPM.

Throws:


UnsupportedOperationException

Package javax.trustedcomputing.tpm.keys

This package allows the creation, storage, loading and unloading of hierarchies of TPM keys.

See:

Description

Package javax.trustedcomputing.tpm.keys

Interface Summary Page

BindingKey Binding keys protect data which is bound to a specific platform. 39

IdentityKey IdentityKeys perform signatures on data that originates within the TPM. 40

LegacyKey LegacyKeys are the only TPM based keys that are allowed to perform both signing and encryption operations.

49

SigningKey Signing keys sign arbitrary data. 50

StorageKey Storage keys wrap other keys or sealed data. 50

StorageRootKey The Storage Root Key (SRK) is the highest key in the TPM key hierarchy. 50

TPMKey Provides common functionality for all types of TPM-based keys, as created by the KeyManager. 51

TPMRSAKey Provides access to the public parts of the RSA keys used by version 1.2 TPMs. 54

Class Summary Page

KeyManager Provides management functionality for TPM-based cryptographic keys. 40


KeyNotMigratableException This Exception is thrown if an operation that can only be performed on migratable TPM keys is called on a non-migratable TPM key.

49

Package javax.trustedcomputing.tpm.keys Description

This package allows the creation, storage, loading and unloading of hierarchies of TPM keys. The central KeyManager class must be created by TPMContext. The TPM enforces different usage policies for different types of keys, this is reflected in the set of key types in this package.

Interface BindingKey javax.trustedcomputing.tpm.keys

All Superinterfaces: RSAKey, TPMKey, TPMRSAKey

public interface BindingKey

extends TPMKey, TPMRSAKey

Binding keys protect data which is bound to a specific platform.

Interface IdentityKey

Interface IdentityKey javax.trustedcomputing.tpm.keys


public interface IdentityKey


IdentityKeys perform signatures on data that originates within the TPM. They represent a unique digital identity. Identity keys are always wrapped by the Storage Root Key.

Class KeyManager javax.trustedcomputing.tpm.keys

java.lang.Object

javax.trustedcomputing.tpm.keys.KeyManager

abstract public class KeyManager

extends Object

Provides management functionality for TPM-based cryptographic keys. It allows to create, store and delete keys for different operations. A KeyManager object may only exist within a TPMContext. While the KeyManager provides a number of methods to persistently store keys and to retrieve them, it does not automatically store them at creation or loading. Note there are separate storages for keys belonging to the current user and the system.

Method Summary Page

abstract BindingKey

createBindingKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo)

Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.

41

abstract SigningKey

createSigningKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo)

Creates a cryptographic RSA key pair for signing operations in the TPM and loads it into a TPM key slot.

42

abstract StorageKey

createStorageKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, PCRInfo pcrInfo)


43

Class KeyManager

abstract void deleteTPMKey(UUID identifier)

Removes a key from the user persistent key storage permanently. 44

abstract void deleteTPMSystemKey(UUID identifier)

Removes a key from the system persistent key storage permanently. 44

abstract UUID[]

getStoredTPMKeys()

Retrieves a list of the identifiers of all keys stored in the persistent user key store. 48

abstract UUID[]

getStoredTPMSystemKeys()

Retrieves a list of the identifiers of all keys stored in the persistent system key store. 48

abstract LegacyKey

importLegacyKey(StorageKey parent, KeyPair keyPair, Secret keySecret)

Imports a given RSA public key and derives a TPM legacy key from it. 44

abstract StorageRootKey

loadStorageRootKey(Secret srkSecret)

Loads the Storage Root Key (SRK) from the TPM. 45

abstract TPMKey

loadTPMKey(StorageKey parent, RSAPublicKey pubKey, Secret usageSecret)

Retrieves a cryptographic RSA key object from user persistent storage and loads it into a TPM key slot.

46

abstract TPMKey

loadTPMKey(StorageKey parent, UUID identifier, Secret usageSecret)


46

abstract TPMKey

loadTPMSystemKey(StorageKey parent, RSAPublicKey pubKey, Secret usageSecret)

Retrieves a cryptographic RSA key object from system persistent storage and loads it into a TPM key slot.

45

abstract TPMKey

loadTPMSystemKey(StorageKey parent, UUID identifier, Secret usageSecret)


47

abstract void storeTPMKey(StorageKey parent, TPMKey key, UUID identifier)

Stores a key in the user persistent key storage for later use. 47

abstract void storeTPMSystemKey(StorageKey parent, TPMKey key, UUID identifier)

Stores a key in the system persistent key storage for later use. 47

Method Detail

createBindingKey

public abstract BindingKey createBindingKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo) throws TrustedComputingException

Class KeyManager


Parameters:

parent - The immediate parent in the TPM key hierarchy.

usageSecret - The authentication secret that is required when using the key.

migrationSecret - The authentication secret that is required at key migration.

isMigratable - If the key is created as migratable, migration to another TPM or backups are allowed. Otherwise the private part will never leave the TPM.

isVolatile - Volatile keys will be destroyed at reboot time.

needsAuthorization - Indicates if the key requires a secret. If not, usageSecret and migrationSecret are ignored.

RSAKeyLength - The length of the RSA key (valid are 512, 1024, and 2048 (bit)).

pcrInfo - Restricts usage of the key to the PCR value specified. Ignored if null.

Returns:

Returns a freshly created key, ready for use.

Throws:


createSigningKey

public abstract SigningKey createSigningKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo) throws TrustedComputingException

Creates a cryptographic RSA key pair for signing operations in the TPM and loads it into a TPM key slot.

Parameters:






Class KeyManager


RSAKeyLength - The length of the RSA key (valid are 512, 1024, and 2048 (bit)).


Returns:

Returns a freshly created key, ready for use.

Throws:


createStorageKey

public abstract StorageKey createStorageKey(StorageKey parent, Secret usageSecret, Secret migrationSecret, boolean isMigratable, boolean isVolatile, boolean needsAuthorization, PCRInfo pcrInfo) throws TrustedComputingException

Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot. A storage key is always 2048 bits long.

Parameters:








Returns:

Returns a freshly created key, ready for use

Throws:


Class KeyManager

deleteTPMKey

public abstract void deleteTPMKey(UUID identifier) throws TrustedComputingException

Removes a key from the user persistent key storage permanently. This does not change the key's loaded-into-TPM-status.

Parameters:

identifier - identifies the key to be deleted.

Throws:


deleteTPMSystemKey

public abstract void deleteTPMSystemKey(UUID identifier) throws TrustedComputingException

Removes a key from the system persistent key storage permanently. This does not change the key's loaded-into-TPM-status.

Parameters:

identifier - identifies the key to be deleted.

Throws:


importLegacyKey

public abstract LegacyKey importLegacyKey(StorageKey parent, KeyPair keyPair, Secret keySecret) throws TrustedComputingException

Imports a given RSA public key and derives a TPM legacy key from it.

Parameters:

parent - The TPMKey which is this key's parent in the hierarchy.

keyPair - The RSA key pair.

keySecret - The Secret that controls use of this key by the TPM.

Returns:

a legacy-type TPM key, that can be used for operations involving the TPM.

Class KeyManager

Throws:


loadStorageRootKey

public abstract StorageRootKey loadStorageRootKey(Secret srkSecret) throws TrustedComputingException

Loads the Storage Root Key (SRK) from the TPM. This is the root of the TPM's key hierarchy.

Parameters:

srkSecret - The SRK usage secret set during Take Ownership. In most cases this is Secret.WELL_KNOWN_SECRET.

Returns:

the SRK loaded into the TPM and ready to use

Throws:


loadTPMSystemKey

public abstract TPMKey loadTPMSystemKey(StorageKey parent, RSAPublicKey pubKey, Secret usageSecret) throws TrustedComputingException


Parameters:


pubKey - The public key that identifies the TPM key.

usageSecret - The usage secret assigned to the loaded key. Note that parent hold the secret for unwrapping the returned key.

Returns:

the loaded key, ready to use.

Throws:


Class KeyManager

loadTPMKey

public abstract TPMKey loadTPMKey(StorageKey parent, RSAPublicKey pubKey, Secret usageSecret) throws TrustedComputingException


Parameters:


pubKey - The public key that identifies the TPM key.


Returns:


Throws:


loadTPMKey

public abstract TPMKey loadTPMKey(StorageKey parent, UUID identifier, Secret usageSecret) throws TrustedComputingException


Parameters:


identifier - The unique ID that identifies the TPM key.


Returns:


Throws:


Class KeyManager

loadTPMSystemKey

public abstract TPMKey loadTPMSystemKey(StorageKey parent, UUID identifier, Secret usageSecret) throws TrustedComputingException


Parameters:


identifier - The unique ID that identifies the TPM key.


Returns:


Throws:


storeTPMKey

public abstract void storeTPMKey(StorageKey parent, TPMKey key, UUID identifier) throws TrustedComputingException

Stores a key in the user persistent key storage for later use.

Parameters:


key - The key to store

identifier - A new identifier to retrieve the key later. Will fail with an IllegalArgumentException if UUID already exists within this storage.

Throws:


storeTPMSystemKey

public abstract void storeTPMSystemKey(StorageKey parent, TPMKey key, UUID identifier) throws TrustedComputingException

Class KeyManager

Stores a key in the system persistent key storage for later use.

Parameters:


key - The key to store

identifier - A new identifier to retrieve the key later. Will fail with an IllegalArgumentException if UUID already exists within this storage.

Throws:


getStoredTPMKeys

public abstract UUID[] getStoredTPMKeys() throws TrustedComputingException

Retrieves a list of the identifiers of all keys stored in the persistent user key store.

Returns:

A list of UUID key identifiers.

Throws:


getStoredTPMSystemKeys

public abstract UUID[] getStoredTPMSystemKeys() throws TrustedComputingException

Retrieves a list of the identifiers of all keys stored in the persistent system key store.

Returns:

A list of UUID key identifiers.

Throws:


Class KeyNotMigratableException

Class KeyNotMigratableException javax.trustedcomputing.tpm.keys

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

javax.trustedcomputing.tpm.keys.KeyNotMigratableException


public class KeyNotMigratableException

extends RuntimeException

This Exception is thrown if an operation that can only be performed on migratable TPM keys is called on a non-migratable TPM key. All TPM keys are either migratable or non-migratable. This property is set at key creation and cannot be changed. In general the behavior of both types is identical, however, only migratable keys are able to migrate to another TPM. This is the only way to back-up TPM keys.


KeyNotMigratableException(String string) 49

Constructor Detail

KeyNotMigratableException

public KeyNotMigratableException(String string)

Interface LegacyKey javax.trustedcomputing.tpm.keys


public interface LegacyKey


LegacyKeys are the only TPM based keys that are allowed to perform both signing and encryption operations. They should only be used to integrate legacy applications.

Interface LegacyKey

Interface SigningKey javax.trustedcomputing.tpm.keys


public interface SigningKey


Signing keys sign arbitrary data. The TPM uses the RSAASSA-PKCS1-v1_5 scheme.

Interface StorageKey javax.trustedcomputing.tpm.keys


All Known Subinterfaces: StorageRootKey

public interface StorageKey


Storage keys wrap other keys or sealed data. The TPM uses the RSAES-OAEP encryption scheme. This allows building hierarchies of keys. Storage keys are always 2048 bits long.

Interface StorageRootKey javax.trustedcomputing.tpm.keys

All Superinterfaces: RSAKey, StorageKey, TPMKey, TPMRSAKey

public interface StorageRootKey

extends StorageKey

The Storage Root Key (SRK) is the highest key in the TPM key hierarchy. The unique SRK is created when the TPM_TakeOwnership hardware command is performed. The storage root key can not be migrated.

Interface StorageRootKey

Field Summary Page

UUID SRK_UUID

The unique identifier of the SRK for use with the persistent key storage. 51

Method Summary Page

void changeUsageSecret(Secret ownerSecret, Secret newSecret)

Changes the usage policy secret from the old secret to the new secret. 51

Field Detail

SRK_UUID

public static final UUID SRK_UUID

The unique identifier of the SRK for use with the persistent key storage. In accordance with the TSS, it is 00000000-0000-0000-0000-000000000001

Method Detail

changeUsageSecret

void changeUsageSecret(Secret ownerSecret, Secret newSecret) throws TrustedComputingException

Changes the usage policy secret from the old secret to the new secret.

Parameters:

ownerSecret - The TPM owner authorization.

newSecret - The new value of the usage secret. The change will take immediate effect.

Throws:


Interface TPMKey javax.trustedcomputing.tpm.keys

All Known Subinterfaces: BindingKey, IdentityKey, LegacyKey, SigningKey, StorageKey, StorageRootKey

public interface TPMKey

Provides common functionality for all types of TPM-based keys, as created by the KeyManager. Note that the TPM discerns different types of keys, which can be used for different applications.

Interface TPMKey

Method Summary Page

void changeMigrationSecret(StorageKey parent, Secret oldSecret, Secret newSecret)

Changes the migration policy secret from the old secret to the new secret. 52

void changeUsageSecret(StorageKey parent, Secret oldSecret, Secret newSecret)

Changes the usage policy secret from the old secret to the new secret. 52

UUID getUUID()

Gets the Universally Unique IDentifier of this key. 53

void setUUID(UUID keyIdentifier)

Set the Universally Unique IDentifier of this key. 53

void unload()

Unload this key from the TPM. 53

Method Detail

changeMigrationSecret

void changeMigrationSecret(StorageKey parent, Secret oldSecret, Secret newSecret) throws TrustedComputingException, KeyNotMigratableException

Changes the migration policy secret from the old secret to the new secret.

Parameters:

parent - The StorageKey which wraps this key.

oldSecret - The currently valid migration secret of the key.

newSecret - The new value of the migration secret. The change will take immediate effect.

Throws:


KeyNotMigratableException - if the key is not a migratable key.

changeUsageSecret

void changeUsageSecret(StorageKey parent, Secret oldSecret, Secret newSecret) throws TrustedComputingException

Changes the usage policy secret from the old secret to the new secret. Note that the user is responsible for updating the key in the persistent storage after changing the usage secret.

Interface TPMKey

Parameters:

parent - The StorageKey which wraps this key.

oldSecret - The currently valid usage secret of the key.

newSecret - The new value of the usage secret. The change will take immediate effect.

Throws:


unload

void unload() throws TrustedComputingException

Unload this key from the TPM. This key instance cannot be used afterwards.

Throws:


setUUID

void setUUID(UUID keyIdentifier)

Set the Universally Unique IDentifier of this key. The UUID needs to be set for storing and retrieving keys from the persistent storage key database.

Parameters:

keyIdentifier - the UUID assigned to this key.

getUUID

UUID getUUID()

Gets the Universally Unique IDentifier of this key. It is used to identify a TPM key in the persistent storage key database.

Returns:

the UUID of this key. NULL if no UUID has been set.

Interface TPMRSAKey

Interface TPMRSAKey javax.trustedcomputing.tpm.keys

All Superinterfaces: RSAKey

All Known Subinterfaces: BindingKey, IdentityKey, LegacyKey, SigningKey, StorageKey, StorageRootKey

public interface TPMRSAKey

extends RSAKey

Provides access to the public parts of the RSA keys used by version 1.2 TPMs.

Method Summary Page

BigInteger getModulus()

Returns the modulus of the RSA key pair. 54

RSAPublicKey getPublicKey()

Provides the public part of a TPM protected key. 54

Method Detail

getModulus

BigInteger getModulus()

Returns the modulus of the RSA key pair.

Specified by:

getModulus in interface RSAKey

getPublicKey

RSAPublicKey getPublicKey() throws TrustedComputingException

Provides the public part of a TPM protected key.

Returns:

public part of the RSA key pair.

Throws:


Interface TPMRSAKey

Package javax.trustedcomputing.tpm.structures

This package contains helper classes for interaction with various other classes from the javax.trustedcomputing.tpm package.

See:

Description

Class Summary Page

Digest Provides a container for a SHA-1 hash. 55

PCREvent Holds the data to be extended into PCRs, together with event information that will be stored in the systems Stored Measurement Log (SML).

56

PCRInfo The contents of the Platform Configuration Registers (PCR) of a TPM can be used to report the configuration of a system.

58

Secret Provides conversion of password strings into the hashed binary format expected by the TPM. 60

ValidationData Holds all information necessary to validate that an operation that returns it was properly performed by an authentic TPM.

62

Package javax.trustedcomputing.tpm.structures Description

This package contains helper classes for interaction with various other classes from the javax.trustedcomputing.tpm package. The classes in this package are passive, i.e. do not communicate with the hardware TPM directly.

Class Digest javax.trustedcomputing.tpm.structures

java.lang.Object

javax.trustedcomputing.tpm.structures.Digest

abstract public class Digest

extends Object

Provides a container for a SHA-1 hash. This kind of input data is often used by the TPM, so this class provides stronger typing than just byte[]. SHA-1 hashes are always 20 bytes long.


Digest(byte[] digest)

Creates a Digest, which holds a given SHA-1 hash. 56

Class Digest

Method Summary Page

abstract byte[]

getBytes()

Provides the 20 bytes hash passed at construction. 56

Constructor Detail

Digest

public Digest(byte[] digest)

Creates a Digest, which holds a given SHA-1 hash. Does not perform hashing operations.

Parameters:

digest - An array of bytes, with an exact length of 20 bytes.

Throws:

IllegalArgumentException - if the size of digest is not exactly 20.

Method Detail

getBytes

public abstract byte[] getBytes()

Provides the 20 bytes hash passed at construction.

Returns:

the 20 byte long hash, this Digest was created from.

Class PCREvent javax.trustedcomputing.tpm.structures

java.lang.Object

javax.trustedcomputing.tpm.structures.PCREvent

public class PCREvent

extends Object

Holds the data to be extended into PCRs, together with event information that will be stored in the systems Stored Measurement Log (SML).

Class PCREvent


PCREvent(long eventType, Digest data, String eventDescription)

Returns an initialized PCREvent object. 57

Method Summary Page

Digest getDataDigest() 57

String getEventDescription() 57

long getEventType() 58

Constructor Detail

PCREvent

public PCREvent(long eventType, Digest data, String eventDescription)

Returns an initialized PCREvent object.

Parameters:

eventType - A numerical representation of the event type.

data - The hash digest of the data to be extended.

eventDescription - A description that is added to the system's Stored Measurement Log.

Method Detail

getDataDigest

public Digest getDataDigest()

Returns:

the Digest of the data

getEventDescription

public String getEventDescription()

Returns:

the description of the event

Class PCREvent

getEventType

public long getEventType()

Returns:

the type of the event

Class PCRInfo javax.trustedcomputing.tpm.structures

java.lang.Object

javax.trustedcomputing.tpm.structures.PCRInfo

abstract public class PCRInfo

extends Object

The contents of the Platform Configuration Registers (PCR) of a TPM can be used to report the configuration of a system. A trust decision may be based on this. This class is used to provide a high-level representation of PCR information. An instance of such a class is used from all functions that need PCR information. PCR values are always 20-byte SHA-1 hashes, and the number of PCRs is TPM implementation dependent.


PCRInfo()

Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24). 59

PCRInfo(int numberOfPCRs)

Creates a PCRInfo object with a given number of PCR registers, which cannot be changed once set. 59

Method Summary Page

abstract int

getNumberOfPCRs()

Gets the number of PCRs specified in this PCRInfo 60

abstract Digest

getPCRValue(int index)

Returns the requested PCR value of the PCRInfo. 59

abstract int[]

getValueIndices()

Returns an array of the PCR values that are different from null in this object. 59

abstract void

setPCRValue(int index, Digest value)

Sets the assigned PCR entry in PCRInfo to the given value. 60

Class PCRInfo

Constructor Detail

PCRInfo

public PCRInfo()

Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24).

PCRInfo

public PCRInfo(int numberOfPCRs) throws IllegalArgumentException


Parameters:

numberOfPCRs - The number of PCRs to consider. Must be greater than zero. TPM 1.2 typically provide 24 PCRs or more. Will throw IllegalArgumentException if out of the valid range, but will not compare with the hardware TPM's capabilities.

Method Detail

getPCRValue

public abstract Digest getPCRValue(int index)

Returns the requested PCR value of the PCRInfo.

Parameters:

index - The index of the PCR value to be returned.

Returns:

the 20-byte hash value stored in the PCRInfo at the given index.

getValueIndices

public abstract int[] getValueIndices()

Returns an array of the PCR values that are different from null in this object.

Returns:

an array of indexes where the PCR value has been set.

Class PCRInfo

setPCRValue

public abstract void setPCRValue(int index, Digest value)

Sets the assigned PCR entry in PCRInfo to the given value.

Parameters:

index - The index of the PCR value to set. Must be a value from 0 to number of PCRs -1.

value - The desired SHA-1 value of the PCR representation. Must be 20 bytes in length.

getNumberOfPCRs

public abstract int getNumberOfPCRs()

Gets the number of PCRs specified in this PCRInfo

Returns:

The number of PCRs in this object

Class Secret javax.trustedcomputing.tpm.structures

java.lang.Object

javax.trustedcomputing.tpm.structures.Secret

abstract public class Secret

extends Object

Provides conversion of password strings into the hashed binary format expected by the TPM. It helps handling byte-oder and null-termination.

Field Summary Page

static Secret

WELL_KNOWN_SECRET

Provides the TSS_WELL_KNOWN_SECRET which consists of 20 bytes of zero. 61


Secret(char[] password)

Creates a Secret object that holds a converted password. 61

Class Secret

Secret(char[] password, boolean addNullTermination, Charset encoding)

Creates a Secret object that contains a converted password and allows to determine the encoding and null-termination settings which are applied before performing the SHA-1 hash operation.

62

Secret(Digest hashedSecret)

Creates a Secret object directly from a SHA-1 hash. 61

Method Summary Page

abstract void

flushSecret()

Deletes the secret data from memory. 62

abstract byte[]

getBytes()

Provides the password secret encoded as a 20 bytes long SHA-1 hash. 62

Field Detail

WELL_KNOWN_SECRET

public static Secret WELL_KNOWN_SECRET

Provides the TSS_WELL_KNOWN_SECRET which consists of 20 bytes of zero.

Constructor Detail

Secret

public Secret(Digest hashedSecret)

Creates a Secret object directly from a SHA-1 hash.

Parameters:

hashedSecret - The already hashed secret.

Secret

public Secret(char[] password)

Creates a Secret object that holds a converted password. Maps the char array to the canonical UTF-16LE without null-termination format. This should be used by default.

Parameters:

password - The plaintext password.

Class Secret

Secret

public Secret(char[] password, boolean addNullTermination, Charset encoding)

Creates a Secret object that contains a converted password and allows to determine the encoding and null-termination settings which are applied before performing the SHA-1 hash operation. Use this only for inter-operability with passwords encoded by legacy applications.

Parameters:

password - The plaintext password.

addNullTermination - indicates if a trailing zero is appended before hashing.

encoding - indicated the Charset that is used to generate the byte-stream to be hashed. For example Charset.forName("ASCII"). Relevent charsets may be "UTF-16LE" or "ASCII".

Method Detail

flushSecret

public abstract void flushSecret()

Deletes the secret data from memory.

getBytes

public abstract byte[] getBytes()

Provides the password secret encoded as a 20 bytes long SHA-1 hash.

Returns:

the secret hash

Class ValidationData javax.trustedcomputing.tpm.structures

java.lang.Object

javax.trustedcomputing.tpm.structures.ValidationData


Class ValidationData

public class ValidationData

extends Object

implements Serializable

Holds all information necessary to validate that an operation that returns it was properly performed by an authentic TPM.


ValidationData(byte[] nonce, byte[] data, byte[] validationData)

Creates a ValidationData object that contains the results of a signature operation in the TPM. 63

Method Summary Page

byte[] getData()

Data which was used to calculate the validation. 63

byte[] getNonce()

Random external data (i.e a nonce) supplied to the TPM used to avoid replay attacks. 64

byte[] getValidationData()

The validation data, which is the signature preformed by the TPM. 64

Constructor Detail

ValidationData

public ValidationData(byte[] nonce, byte[] data, byte[] validationData)

Creates a ValidationData object that contains the results of a signature operation in the TPM. This object is independent of the TPMContext as it is needed for verification at remote parties.

Parameters:

nonce - A unique random number to provide freshness.

data - Data which was used to calculate the validation.

validationData - The validation data, which is the signature of the TPM.

Method Detail

getData

public byte[] getData()

Data which was used to calculate the validation. This contains the structures the TPM operates on.

Class ValidationData

Returns:

the data that was processed

getNonce

public byte[] getNonce()

Random external data (i.e a nonce) supplied to the TPM used to avoid replay attacks.

Returns:

the nonce

getValidationData

public byte[] getValidationData()

The validation data, which is the signature preformed by the TPM.

Returns:

the validation data

Package javax.trustedcomputing.tpm.tools

This package allows using various core concepts of Trusted Computing.

See:

Description

Class Summary Page

Attestor Provides all services for performing services for remote attestation 65

Binder Provides all services for performing the TPM-bind operation on user data. 67

Certifier Provides services for certifying a TPMKey and for validating the key's policy. 68

Initializer This class allows perform basic initialization operations for the TPM, such as taking ownership. 70

Sealer Provides all services for performing TPM_SEAL on user data. 72

Signer This class allows to sign user data or files using a SigningKey or a LegacyKey. 74

Package javax.trustedcomputing.tpm.tools Description

This package allows using various core concepts of Trusted Computing. Each tool that accesses the TPM needs to be linked to a TPMContext in the constructor.

Package javax.trustedcomputing.tpm.tools

Class Attestor javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteAttestor

javax.trustedcomputing.tpm.tools.Attestor

abstract public class Attestor

extends RemoteAttestor

Provides all services for performing services for remote attestation


Attestor(TPMContext context)

Initializes and returns this instance of Attestor within the context of a TPM. 65

Method Summary Page

abstract ValidationData

quote(int[] PCRindices, IdentityKey key, Digest nonce)

Performs the Quote operation. 66


quote(int[] PCRindices, SigningKey key, Digest nonce)

Performs the Quote operation. 66

Constructor Detail

Attestor

public Attestor(TPMContext context)

Initializes and returns this instance of Attestor within the context of a TPM.

Parameters:

context - The context of the TPM session.

Class Attestor

Method Detail

quote

public abstract ValidationData quote(int[] PCRindices, IdentityKey key, Digest nonce) throws TrustedComputingException, PCRsNotAccessibleException

Performs the Quote operation. The TPM will sign the current PCR configuration using an Identity key. On Windows systems, any PCR access is by default blocked.

Parameters:


key - The Identity Key to be used in this operation

nonce - A nonce to guarantee freshness.

Returns:

The signed TPM Quote.

Throws:



quote

public abstract ValidationData quote(int[] PCRindices, SigningKey key, Digest nonce) throws TrustedComputingException, PCRsNotAccessibleException

Performs the Quote operation. The TPM will sign the current PCR configuration using an Identity key. On Windows systems, any PCR access is by default blocked.

Parameters:


key - The Signing Key to be used in this operation


Returns:

The signed TPM Quote.

Throws:


Class Attestor


Class Binder javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteBinder

javax.trustedcomputing.tpm.tools.Binder

abstract public class Binder

extends RemoteBinder

Provides all services for performing the TPM-bind operation on user data. It allows to bind and unbind byte arrays using a BindingKey.


Binder(TPMContext context)

Initializes and returns this instance of Binder within the context of a TPM. 67

Method Summary Page

abstract byte[]

unbind(byte[] encrytedData, BindingKey key)

Unbinds and decrypts a bound byte array. 67

Constructor Detail

Binder

public Binder(TPMContext context)

Initializes and returns this instance of Binder within the context of a TPM.

Parameters:


Method Detail

unbind

public abstract byte[] unbind(byte[] encrytedData, BindingKey key) throws TrustedComputingException

Class Binder

Unbinds and decrypts a bound byte array.

Parameters:

encrytedData - The data to be decrypted.

key - A BindingKey

Throws:


Class Certifier javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteCertifier

javax.trustedcomputing.tpm.tools.Certifier

abstract public class Certifier

extends RemoteCertifier

Provides services for certifying a TPMKey and for validating the key's policy.


Certifier(TPMContext context)

Initializes and returns this instance of Certifier within the context of a TPM. 68

Method Summary Page


certifyKey(TPMKey toBeCertified, IdentityKey certifyingKey, Digest nonce)

Performs the certify operation using an IdentityKey. 69


certifyKey(TPMKey toBeCertified, LegacyKey certifyingKey, Digest nonce)

Performs the certify operation using a LegacyKey. 70


certifyKey(TPMKey toBeCertified, SigningKey certifyingKey, Digest nonce)

Performs the certify operation using a SigningKey. 69

Constructor Detail

Certifier

public Certifier(TPMContext context)

Class Certifier

Initializes and returns this instance of Certifier within the context of a TPM.

Parameters:


Method Detail

certifyKey

public abstract ValidationData certifyKey(TPMKey toBeCertified, IdentityKey certifyingKey, Digest nonce) throws TrustedComputingException, IllegalArgumentException

Performs the certify operation using an IdentityKey. Note that an IdentityKey can only certify non-migratable keys. If a migratable toBeCertified key is passed to this method, it will throw an IllegalArgumentException.

Parameters:

toBeCertified - The non-migratable TPMKey to be certified.

certifyingKey - The certifying IdentityKey.


Returns:

The data necessary to validate that a key is certified.

Throws:


IllegalArgumentException

certifyKey

public abstract ValidationData certifyKey(TPMKey toBeCertified, SigningKey certifyingKey, Digest nonce) throws TrustedComputingException

Performs the certify operation using a SigningKey.

Parameters:

toBeCertified - The TPMKey to be certified.

certifyingKey - The certifying SigningKey .


Class Certifier

Returns:


Throws:


certifyKey

public abstract ValidationData certifyKey(TPMKey toBeCertified, LegacyKey certifyingKey, Digest nonce) throws TrustedComputingException

Performs the certify operation using a LegacyKey.

Parameters:

toBeCertified - The TPMKey to be certified.

certifyingKey - The certifying LegacyKey.


Returns:


Throws:


Class Initializer javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.Initializer

abstract public class Initializer

extends Object

This class allows perform basic initialization operations for the TPM, such as taking ownership. Some operating systems will provide this functionality independent of JSR 321. Therefore this is an optional class.

Class Initializer


Initializer(TPMContext context)

Initializes and returns this instance of Initializer within the context of a TPM. 71

Method Summary Page

abstract void

clearOwnership(Secret ownerSecret)

Removes all owner-related information from the TPM and deletes the Storage Root Key. 71

abstract void

takeOwnership(Secret ownerSecret, Secret srkSecret)

Takes ownership of an active and enabled, but currently unowned TPM. 71

Constructor Detail

Initializer

public Initializer(TPMContext context)

Initializes and returns this instance of Initializer within the context of a TPM.

Parameters:


Method Detail

takeOwnership

public abstract void takeOwnership(Secret ownerSecret, Secret srkSecret) throws TrustedComputingException

Takes ownership of an active and enabled, but currently unowned TPM. A new Storage Root Key is generated by this process and usage authorizations set.

Parameters:

ownerSecret - New owner authentication secret.

srkSecret - New authentication secret for the SRK. By convention, Secret.WELL_KNOWN_SECRET should be used.

Throws:


clearOwnership

public abstract void clearOwnership(Secret ownerSecret) throws TrustedComputingException

Class Initializer

Removes all owner-related information from the TPM and deletes the Storage Root Key. All other user keys will be inaccessible.

Parameters:

ownerSecret - the current owner authentication secret

Throws:


Class Sealer javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.Sealer

abstract public class Sealer

extends Object

Provides all services for performing TPM_SEAL on user data. It allows to seal and unseal byte arrays using a SealingKey.


Sealer(TPMContext context)

Initializes and returns this instance of Sealer within the context of a TPM. 72

Method Summary Page

abstract byte[]

seal(byte[] plainData, PCRInfo targetState, StorageKey storageKey, Secret dataSecret)

Encrypts a byte array and seals it to a target state using a SealingKey.

73

abstract byte[]

unseal(byte[] encrytedData, StorageKey key, Secret dataSecret)

Unseals and decrypts a sealed byte array. 73

Constructor Detail

Sealer

public Sealer(TPMContext context)

Initializes and returns this instance of Sealer within the context of a TPM.

Class Sealer

Parameters:


Method Detail

seal

public abstract byte[] seal(byte[] plainData, PCRInfo targetState, StorageKey storageKey, Secret dataSecret) throws TrustedComputingException, PCRsNotAccessibleException

Encrypts a byte array and seals it to a target state using a SealingKey.

Parameters:

plainData - The data to be encrypted and sealed.

targetState - The PCR-configuration that must be present in the TPM at unsealing.

storageKey - A SealingKey

dataSecret - The authorization secret for using the data.

Returns:

a sealed byte array.

Throws:



unseal

public abstract byte[] unseal(byte[] encrytedData, StorageKey key, Secret dataSecret) throws TrustedComputingException, PCRsNotAccessibleException

Unseals and decrypts a sealed byte array. Will only succeed, if the TPM PCR configuration is the exact same state the data was sealed to.

Parameters:

encrytedData - The data to be unsealed and decrypted.

key - A SealingKey

dataSecret - The authorization secret for using the data.

Class Sealer

Throws:



Class Signer javax.trustedcomputing.tpm.tools

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteSigner

javax.trustedcomputing.tpm.tools.Signer

abstract public class Signer

extends RemoteSigner

This class allows to sign user data or files using a SigningKey or a LegacyKey. It also provides methods for signature verification.


Signer(TPMContext context)

Initializes and returns this instance of Signer within the context of a TPM. 74

Method Summary Page

abstract byte[]

sign(byte[] plainData, LegacyKey key)

Signs data using a TPM-protected key. 75

abstract byte[]

sign(byte[] plainData, SigningKey key)

Signs data using a TPM-protected key. 75

Constructor Detail

Signer

public Signer(TPMContext context)

Initializes and returns this instance of Signer within the context of a TPM.

Parameters:


Class Signer

Method Detail

sign

public abstract byte[] sign(byte[] plainData, LegacyKey key) throws TrustedComputingException

Signs data using a TPM-protected key.

Parameters:

plainData - The user provided data that will be hashed and signed.

key - The key to sign the data with.

Returns:

the signature on the hash of the data as returned by the TPM.

Throws:


sign

public abstract byte[] sign(byte[] plainData, SigningKey key) throws TrustedComputingException

Signs data using a TPM-protected key.

Parameters:

plainData - The user provided data that will be hashed and signed.

key - The key to sign the data with.

Returns:

The signature on the hash of the data as returned by the TPM.

Throws:


Package javax.trustedcomputing.tpm.tools.remote

This package allows using various core concepts of Trusted Computing from a remote host.

See:

Description

Package javax.trustedcomputing.tpm.tools.remote

Class Summary Page

RemoteAttestor Allows verification of Quote result using a public key. 76

RemoteBinder Allows binding data to a public key. 77

RemoteCertifier Allows validation of a certified key. 78

RemoteSigner Allows validation of signed data. 83

Package javax.trustedcomputing.tpm.tools.remote Description

This package allows using various core concepts of Trusted Computing from a remote host. Remote tool do not need direct access to the TPM. Instead they can be used as building blocks in application layer protocols.

Class RemoteAttestor javax.trustedcomputing.tpm.tools.remote

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteAttestor

Direct Known Subclasses: Attestor

abstract public class RemoteAttestor

extends Object

Allows verification of Quote result using a public key. This can be performed without TPM access or by remote parties.


RemoteAttestor()

Creates a RemoteAttestor instance. 76

Method Summary Page

abstract boolean

validateQuote(ValidationData dataToValidate, RSAPublicKey identityKey, Digest nonce, PCRInfo expectedValues)

Calculates the expected PCR configuration and compares it and the nonce to the one provided in the ValidationData and also verifies the signature.

77

Constructor Detail

RemoteAttestor

public RemoteAttestor()

Class RemoteAttestor

Creates a RemoteAttestor instance. It does not require a TPMContext.

Method Detail

validateQuote

public abstract boolean validateQuote(ValidationData dataToValidate, RSAPublicKey identityKey, Digest nonce, PCRInfo expectedValues)

Calculates the expected PCR configuration and compares it and the nonce to the one provided in the ValidationData and also verifies the signature.

Parameters:

dataToValidate - Holds all verification data that is to be validated. Typically received from a remote system.

identityKey - The public part of the IdentityKey or SigningKey used to sign the TPM's PCRs.

nonce - The challenge that was sent to the remote system and integrated in the ValidationData.

expectedValues - The PCRInfo configuration expected in this quote.

Returns:

true if signature is valid and configuration is as expected. false else.

Class RemoteBinder javax.trustedcomputing.tpm.tools.remote

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteBinder

Direct Known Subclasses: Binder

abstract public class RemoteBinder

extends Object

Allows binding data to a public key. This can be performed without TPM access or by remote parties.


RemoteBinder()

Creates a RemoteBinder instance. 78

Class RemoteBinder

Method Summary Page

abstract byte[]

bind(byte[] plainData, RSAPublicKey bindingKey)

Encrypts a byte array and binds it using a BindingKey. 78

Constructor Detail

RemoteBinder

public RemoteBinder()

Creates a RemoteBinder instance. It does not require a TPMContext.

Method Detail

bind

public abstract byte[] bind(byte[] plainData, RSAPublicKey bindingKey) throws TrustedComputingException

Encrypts a byte array and binds it using a BindingKey. Only a small amount of data can be protected by the TPM key.

Parameters:

plainData - The data to be encrypted. The maximum payload length is 17, 81, 209 bytes for 512, 1024, 2048 bit RSA keys, respectively.

bindingKey - A BindingKey

Returns:

a byte array bound to the HW protected key.

Throws:


Class RemoteCertifier javax.trustedcomputing.tpm.tools.remote

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteCertifier

Direct Known Subclasses: Certifier

abstract public class RemoteCertifier

extends Object

Class RemoteCertifier

Allows validation of a certified key. This can be performed without TPM access or by remote parties.


RemoteCertifier()

Creates a RemoteCertifier instance. 79

Method Summary Page

abstract boolean

containsPCRInfo(ValidationData certifiedKeyInfo, PCRInfo desiredPCRInfo)

Checks if the key described in the given ValidationData requires the desired PCR values when being used.

80

abstract boolean

isBindingKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a BindingKey. 80

abstract boolean

isKeyOfLength(ValidationData certifiedKeyInfo, int desiredKeyLength)

Checks if the key described in the given ValidationData has the desired key length. 81

abstract boolean

isLegacyKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a LegacyKey. 81

abstract boolean

isMigratable(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is migratable. 81

abstract boolean

isSigningKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a SigningKey. 82

abstract boolean

isStorageKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a StorageKey. 82

abstract boolean

isVolatile(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is volatile. 82

abstract boolean

needsAuthorization(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData needs authorization. 82

abstract boolean

validate(ValidationData dataToValidate, RSAPublicKey certifiedKey, RSAPublicKey certifyingKey, Digest nonce)

Performs the operation to validate a previously certified key.

80

Constructor Detail

RemoteCertifier

public RemoteCertifier()

Creates a RemoteCertifier instance. It does not require a TPMContext.


Method Detail

validate

public abstract boolean validate(ValidationData dataToValidate, RSAPublicKey certifiedKey, RSAPublicKey certifyingKey, Digest nonce)

Performs the operation to validate a previously certified key. This method will perform a check on the parameters passed, using the given ValidationData. It will validate the signature using the certifying RSAPublicKey and compare the certifiedKey and the nonce with the data provided in dataToValidate.

Parameters:

dataToValidate - The validation data that was generated by calling one of the following methods:

• Certifier.certifyKey(TPMKey, IdentityKey, Digest) • Certifier.certifyKey(TPMKey, LegacyKey, Digest) • Certifier.certifyKey(TPMKey, SigningKey, Digest).

certifiedKey - The public key of the TPMKey to be validated.

certifyingKey - The public key of the key that certified the certifiedKey.

nonce - The nonce that was used to certify the certifiedKey.

Returns:

true if the signature was valid and the given certifiedKey is the key that was certified, false otherwise.

containsPCRInfo

public abstract boolean containsPCRInfo(ValidationData certifiedKeyInfo, PCRInfo desiredPCRInfo)

Checks if the key described in the given ValidationData requires the desired PCR values when being used.

Parameters:

certifiedKeyInfo - The validation data that was returned from the certifying operation.

desiredPCRInfo - The PCRInfo to check against.

Returns:

true if the key depends on the desired PCRs, false otherwise.

isBindingKey

public abstract boolean isBindingKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a BindingKey.


Parameters:


Returns:

true if the certified key is a BindingKey, false otherwise.

isKeyOfLength

public abstract boolean isKeyOfLength(ValidationData certifiedKeyInfo, int desiredKeyLength)

Checks if the key described in the given ValidationData has the desired key length.

Parameters:


desiredKeyLength - The key length to check against.

Returns:

true if the key has the desired length, false otherwise.

isLegacyKey

public abstract boolean isLegacyKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a LegacyKey.

Parameters:


Returns:

true if the certified key is a LegacyKey, false otherwise.

isMigratable

public abstract boolean isMigratable(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is migratable.

Parameters:


Returns:

true if the certified key is migratable, false otherwise.


isSigningKey

public abstract boolean isSigningKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a SigningKey.

Parameters:


Returns:

true if the certified key is a SigningKey, false otherwise.

isStorageKey

public abstract boolean isStorageKey(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is a StorageKey.

Parameters:


Returns:

true if the certified key is a StorageKey, false otherwise.

isVolatile

public abstract boolean isVolatile(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData is volatile.

Parameters:


Returns:

true if the certified key is volatile, false otherwise.

needsAuthorization

public abstract boolean needsAuthorization(ValidationData certifiedKeyInfo)

Checks if the key described in the given ValidationData needs authorization.

Parameters:



Returns:

true if the certified key needs authorization, false otherwise.

Class RemoteSigner javax.trustedcomputing.tpm.tools.remote

java.lang.Object

javax.trustedcomputing.tpm.tools.remote.RemoteSigner

Direct Known Subclasses: Signer

abstract public class RemoteSigner

extends Object

Allows validation of signed data. This can be performed without TPM access or by remote parties.


RemoteSigner()

Creates a RemoteSigner instance. 83

Method Summary Page

abstract boolean

validate(byte[] signature, byte[] data, RSAPublicKey key)

Verifies that a provided signature is valid using the claimed key. 83

Constructor Detail

RemoteSigner

public RemoteSigner()

Creates a RemoteSigner instance. It does not require a TPMContext.

Method Detail

validate

public abstract boolean validate(byte[] signature, byte[] data, RSAPublicKey key) throws TrustedComputingException

Class RemoteSigner

Verifies that a provided signature is valid using the claimed key.

Parameters:

signature - The signature performed on the SHA-1 hash of the provided file.

data - The original data that was signed.

key - The public part of the key-pair that signed the hash.

Returns:

true if signature is valid.

Throws:


IV. License

INSTITUTE FOR APPLIED INFORMATION PROCESSING AND COMMUNICATIONS (IAIK) IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE AGREEMENT ("AGREEMENT"). PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY.

Specification: JSR-000321 Trusted Computing API for Java(tm) ("Specification")

Version: 11.04

Status: Proposed Final Draft

Release: 25 March 2011

Copyright 2010 Institute for Applied Information Processing and Communications (IAIK)

Graz University of Technology

Inffeldgasse 16a

A-8010 Graz

Austria

All rights reserved.

NOTICE

The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of IAIK and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement.

Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, IAIK hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under IAIK's intellectual property rights to:

1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Specification.

2.Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation:

(i) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented;

(ii) is clearly and prominently marked with the word "UNTESTED" or "EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee's control; and

(iii) includes the following notice:

"This is an implementation of an early-draft specification developed under the Java Community Process (JCP). The code is not compatible with any specification of the JCP."

The grant set forth above concerning your distribution of implementations of the Specification is contingent upon your agreement to terminate development and distribution of your implementation of early draft upon final completion of the Specification. If you fail to do so, the foregoing grant shall be considered null and void.

No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification.

Other than this limited license, you acquire no right, title or interest in or to the Specification or any other IAIK intellectual property, and the Specification may only be used in accordance with

the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from IAIK if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification.

"Licensor Name Space" means the public class or interface declarations whose names begin with "java", "javax", "com.iaik" or their equivalents in any subsequent naming convention adopted through the Java Community Process, or any recognized successors or replacements thereof

TRADEMARKS

No right, title, or interest in or to any trademarks, service marks, or trade names of IAIK or IAIK's licensors is granted hereunder. Java and Java-related logos, marks and names are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DISCLAIMER OF WARRANTIES

THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY IAIK. IAIK MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. IAIK MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

LIMITATION OF LIABILITY

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL IAIK OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF IAIK AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will hold IAIK (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.

RESTRICTED RIGHTS LEGEND

If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in

accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

REPORT

You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide IAIK with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant IAIK a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.

GENERAL TERMS

Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.

The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.

This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party.

Rev. January 2006

V. References and Relevant Literature [Berger] S. Berger, R. Cáceres, K. Goldman, R. Perez, R. Sailer, L. van Doorn. vTPM: Virtualizing the

Trusted Platform Module. IBM Research Report, RC23879 (W0602-126), 2006.

[Challener] D. Challener, K. Yoder, R. Catherman, D. Safford, L. van Doorn, A Practical Guide to Trusted Computing, ISBN-13: 978-0-13-239842-8, IBM Press, 2008

[Kinney] S. Kinney. Trusted Platform Module Basics: Using TPM in Embedded Systems. Elsevier, Burlington, MA, USA, ISBN 13: 978-0-7506-7960-2, 2006.

[Mueller] T. Müller, Trusted Computing Systeme: Konzepte und Anforderungen, Springer, 2008 (in German).

[Gallery] Eimear Gallery, Chris Mitchell. Trusted Computing Teaching Material, Royal Holloway University of London, http://www.isg.rhul.ac.uk/msc/teaching/iy5608, 2009.

[Goldman] Ken Goldman, Stan Potter, SHA-1 Uses in TPM v1.2, White Paper, TCG April 2, 2010, https://www.trustedcomputinggroup.org/

[Sarmenta] L. Sarmenta, J. Rhodes, and T. Müller. TPM/J Java-based API for the Trusted Platform Module , http://projects.csail.mit.edu/tc/tpmj/ , 2007.

[Selhorst] M. Selhorst, C. Stueble & F. Teerkorn TSS Study, Sirrix AG security technologies, http://www.sirrix.com/content/pages/50590.htm, 2008

[STC] R. Toegl, T. Winkler, M. Nauman, T. Hong - Towards Platform-Independent Trusted Computing – ACM Workshop on Scalable Trusted Computing (STC) 2009 Proceedings; in CCS 2009 Co-Located Workshops' Compilation Proceedings, ACM, 2009

[TBS] Microsoft Developer Network. TPM Base Services, http://msdn2.microsoft.com/en-us/library/aa446796.aspx, 2007.

[TCGA] Trusted Computing Group. TCG Specification Architecture Overview, Revision 1.4, 2007. https://www.trustedcomputinggroup.org/

[Toegl] R.Toegl, M. Pirker. An ongoing Game of Tetris: Integrating Trusted Computing in Java, block-by-block. In: Proceedings of Future of Trust in Computing Conference, Berlin, Vieweg+Teubner, 2008.

[TrouSerS] TrouSerS - An Open-Source TCG Software Stack Implementation. http://trousers.sourceforge.net/, 2007.

[trustedJava] M. Pirker, R. Toegl T. Winkler. Trusted Computing for the Java Platform, http://trustedjava.sourceforge.net/, 2007-11.

[TPM1.2] Trusted Computing Group. TCG Trusted Platform Module (TPM) Specifications, Version 1.2 Rev. 116, March 1, 2011. https://www.trustedcomputinggroup.org/

[TSS1.2] Trusted Computing Group. TCG Software Stack (TSS) Specification, Version 1.2, Errata A, March 7, 2007. https://www.trustedcomputinggroup.org/

http://www.isg.rhul.ac.uk/msc/teaching/iy5608�

https://www.trustedcomputinggroup.org/�

http://projects.csail.mit.edu/tc/tpmj/�

http://www.sirrix.com/content/pages/50590.htm�

http://msdn2.microsoft.com/en-us/library/aa446796.aspx�


http://trousers.sourceforge.net/�

http://trustedjava.sourceforge.net/�



jsr 321 - trusted computing api for java

Documents