JSR321
Trusted Computing API for Java™
Java™ Community Process Specification
Final Release
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 JSR321 Specification (covering this document and JavaDoc) is released under the terms provided in the
License chapter.
2
Table of Contents
I.
Preface ......................................................................................................................................................... 4
1. Revision History ........................................................................................................................................... 4
2. Who Should Use This Specification ............................................................................................................. 4
3. Outline ......................................................................................................................................................... 4
4. Introduction ................................................................................................................................................. 6
5. Contributors................................................................................................................................................. 7
6. Contributing To This Specification ............................................................................................................... 7
7. Open Issues.................................................................................................................................................. 8
8. Changes since Proposed Final Draft, version 11.04..................................................................................... 9
II.
Technical Background and Design ............................................................................................................. 10
9. The Needs of the TPM ............................................................................................................................... 10
TCG Standard Approach for the C Programming Language.............................................................. 10
10. JSR321 API Design Considerations............................................................................................................. 11
Design Goals...................................................................................................................................... 11
Limitation from the TCG Architecture .............................................................................................. 11
Limited Choice of Cryptographic Algorithms .................................................................................... 12
JSR321 API Scope and Limitations .................................................................................................... 12
Expected Developer Knowledge ....................................................................................................... 12
11. Outline of the API ...................................................................................................................................... 13
12. Feature Selection ....................................................................................................................................... 15
III.
Normative Part .......................................................................................................................................... 23
13. Definitions.................................................................................................................................................. 23
14. Requirements ............................................................................................................................................ 23
15. Detailed API Specifications ........................................................................................................................ 25
IV.
License ....................................................................................................................................................... 91
16. License for Evaluation Purposes ................................................................................................................ 91
17. License for Implementations ..................................................................................................................... 94
V.
References and Relevant Literature .......................................................................................................... 98
3
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 final release of the
specification.
The presented API is based on the Java2 Standard Edition (J2SE) Desktop-PC system architecture.
The JSR321 EG, represented by IAIK, Graz University of Technology, releases all results under free licenses.
Specification documents and Javadoc definitions are openly available for evaluation and allow creating and
distributing specification compliant implementations. Reference Implementation and Technology Compatibility
Kit are 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,
Updated Nov. 19
2010 November 26, 2010
11.04
March 25, 2011
April 8, 2011
11.10
October
11,
2011
upd. October 31, 2011
Public Review Release
January 3, 2011
Proposed Final Draft
Submission
to
Approval Ballot
Final
Who Should Use This Specification
This document is written for the public community evaluating 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.
4
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.
5
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 based on C libraries.
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.
In addition to this specification document, an extended discussion about JSR321, its history, design and
technical background is provided in a separate full length journal publication [Toegl11].
JSR321 allows 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 is easier to use than other
available interfaces for other programming languages. This and the fact that all results are released under an
open source license will hopefully foster the use of trusted technology for research, open and also commercial
JavaTM applications.
6
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, 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.
Comments and contributions should be sent 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) are released as open source software under the GNU license v2 with Classpath Exception. Even more so,
the open source and Java™ community have been invited to partake in the design as well as in the
implementations.
7
Open Issues
Currently None.
8
Changes since Proposed Final Draft, version 11.04.
The following method definition changes have been added (bold) or removed (strike) since version 11.04.
TPM
abstract public Object getProperty(String property)
throws TrustedComputingException, IllegalArgumentException;
Attestor and Remote Attestor
public abstract boolean validateQuote(ValidationData dataToValidate,
RSAPublicKey identityKey, Digest nonce, PCRInfo expectedValues)
throws GeneralSecurityException, TrustedComputingException;
Signer and RemoteSigner
public abstract boolean validate(byte[] signature, byte[] data, RSAPublicKey
key)
throws TrustedComputingException;
throws GeneralSecurityException;
Certifier and RemoteCertifier
public abstract boolean validate(ValidationData dataToValidate,
RSAPublicKey certifiedKey, RSAPublicKey certifyingKey, Digest nonce)
throws GeneralSecurityException;
TPMContext
public abstract Secret getSecret(char[] password, boolean addNullTermination,
Charset encoding)
throws CharacterCodingException;
public abstract RemoteAttestor getRemoteAttestor();
public abstract RemoteBinder getRemoteBinder();
public abstract RemoteCertifier getRemoteCertifier();
public abstract RemoteSigner getRemoteSigner();
9
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
10
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 highlevel 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 objectoriented 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 useroriented 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.
11
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 offering 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. 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)
12
•
•
•
•
•
•
•
•
•
•
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 TBS and group policy configurations (on Windows Vista and later 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 major 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.
13
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.
14
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.
15
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_FreeMem
ory
Free memory allocated by a
Tspi-level function.
Java hides Memory
Management
-
-
Tspi_Context_GetDefa
ultPolicy
Use the default
authorization policy for the
creation of an object.
Essential
No
Hidden. Configured
using Secret object
Tspi_Context_CreateO
bject
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_CloseOb
ject
Destroy an object.
Java manages
resources
No
-
Tspi_Context_GetCapa
bility
Get the current capabilities
of the context.
Configuration of
Context
No
TPMContext
Tspi_Context_GetTPMO
bject
Get the TPM object
associated with a context.
Essential
Yes
TPMContext
Tspi_Policy_FlushSec
ret
Remove the authorization
data from memory.
Desirable for
security.
Yes
Tspi_Policy_AssignTo
Object
How one assigns a policy to
an object—for example, a
key.
Essential for
processing
commands
No
Secret destruction could
be difficult in actual
implementations
(delayed garbage
collection)
16
Hidden. Configured
using Secret object
Tspi_TPM_GetCapabili
ty
Get the set of capabilities of
the TPM.
Access to basic
information on TPM
No
TPM
Tspi_TPM_SetCapabili
ty
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_VerifySign
ature
Verifies the signature of
given data.
Useful feature
No
RemoteSigner
Tspi_Hash_SetHashVal
ue
Set a particular hash value if
you don't happen to want to
use SHA-1.
Standard feature in
JCE
-
-
Tspi_Hash_GetHashVal
ue
Determine the current value
of a hash object.
Standard feature in
JCE
-
-
Tspi_Hash_UpdateHash
Value
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.
Standard feature in
JCE
-
-
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
17
Tspi_PcrComposite_
SetPcrValue
Set what values the PCRs in
a PcrComposite object
should have. This is
preparation for doing a seal.
Vital Feature
Yes
PCRInfo
Tspi_PcrComposite_
GetPcrValue
Returns the current value of
a PCR in a PcrComposite
object.
Vital Feature
Yes
PCRInfo
Tspip_CallbackHMACAu
th
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.
C-style callback
functions are not
needed in Java
-
-
Tspip_CallbackTakeOw
nership
Take ownership of a TPM
using a callback mechanism.
C-style callback
functions are not
needed in Java
-
-
Tspip_CallbackChange
AuthAsym
Use a callback mechanism
to change authorization.
C-style callback
functions are not
needed in Java
-
-
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
18
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_ReadCurrent
Counter
Read the value of the
current counter.
Nice to have,
monotonic counters
are not supported in
current OSes
No
-
Tspi_TPM_ReadCurrent
Ticks
Read the current tick value
(which corresponds loosely
to time) of the TPM.
Useful, but TCG
specifications are
ambiguous
No
-
Tspi_Hash_TickStampB
lob
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.
NV RAM Access is not
needed for
applications
-
-
Tspi_NV_WriteValue
Write a value to the NVRAM
space previously allocated.
NV RAM Access is not
needed for
applications
-
-
Tspi_NV_ReadValue
Read a value from NVRAM
space previously allocated.
NV RAM Access is not
needed for
applications
-
-
Tspi_TPM_DAA_Sign
Use a DAA credential to
verify either a message or
an AIK.
NV RAM Access is not
needed for
applications
-
-
Tspi_TPM_GetAuditDig
est
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
-
-
19
Tspicb_CallbackSealx
Mask
Used when masking or
unmasking data sent or
returned with Data_SealX or
Tspi_Data_Unseal
operations.
C-style callback
functions are not
needed in Java
No
Sealer
Tspicb_CollateIdenti
ty
Because it isn't clear what
encryption algorithms will
be required by a certificate
authority, this command
can be used to encrypt the
collated information with
any encryption algorithm.
Optional
functionality for AIK
Cycle
No
-
Tspicb_ActivateIdent
ity
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.
Optional
functionality for AIK
Cycle
No
-
Tspicb_DAA_Sign
Extend properties of the
DAA protocol.
No DAA reference
implementations
available
-
-
Tspicb_DAA_VerifySig
nature
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_LoadKey
Blob
Load an encrypted key blob
into the TPM, used when
you have the key blob file.
Implementation
Detail
No
KeyManager
Tspi_Context_LoadKey
ByUUID
Load a key into the TPM
when you know its UUID.
Vital Key
Management Feature
Yes
KeyManager
20
Tspi_Context_Unregis
terKey
Remove a key from a user or
system key store.
Vital Key
Management Feature
Yes
KeyManager
Tspi_Context_DeleteK
ey ByUUID
Remove a key from the TPM
referenced by UUID.
Vital Key
Management Feature
Yes
KeyManager
Tspi_Context_GetKeyB
yUUID
Search for a key by its UUID,
and returns a handle to it.
Vital Key
Management Feature
Yes
KeyManager
Tspi_Context_GetKey
ByPublicInfo
Search for a key by its public
data and returns a handle to
it.
Vital Key
Management Feature
Yes
KeyManager
Tspi_Context_Get
Registered Keys
ByUUID
Return a list of all the
registered keys in a registry,
along with their UUIDs.
Vital Key
Management Feature
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_ConvertMigr
ationBlob
Import a migration blob
from a migratable key.
Migration is optional
No
-
Tspi_TPM_CertifySelf
Test
Tells the TPM to use an AIK
to certify the self-test
results.
Not useful for
applications
No
-
Tspi_TPM_GetTestResu
lt
Get the self test result,
unsigned.
Not useful for
applications
No
-
Tspi_SetAttribUint32
Set an integer attribute of
an object.
Implementation
Detail
No
-
Tspi_SetAttribData
Set a non-integer attribute
of an object.
Implementation
Detail
No
-
Tspi_Policy_SetSecre
t
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
21
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_Registe
rKey
Register a key into either a
user's key store or a
system's key store and
returns the UUID.
Vital Key
Management Feature
Yes
KeyManager
Tspi_TPM_GetPub
EndorsementKey
Return the public portion of
the endorsement key.
Optional
functionality for AIK
Cycle
No
-
Tspi_TPM_Collate
IdentityRequest
Gather all the information a
certificate authority will
need in order to provide a
certificate for an AIK.
Optional
functionality for AIK
Cycle
No
-
Tspi_TPM_ActivateIde
ntity
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.
Optional
functionality for AIK
Cycle
No
-
Tspi_TPM_SetStatus
Set bits in the TPM.
Not useful for
applications
-
-
Tspi_TPM_SelfTestFul
l
Tells the TPM to execute a
full self test.
Not useful for
applications
-
-
Tspi_TPM_PcrRead
Read a particular PCR.
Useful Feature
Yes
TPM
Tspi_Key_CertifyKey
Create a certificate of a nonmigratable 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.
Vital Key
Management Feature
Yes
KeyManger
Tspi_Key_CreateMigra
tionBlob
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
22
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.
23
•
•
•
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.
24
Detailed API Specifications
JSR321API
10/11/11 12:15 PM
Package Summary
Page
javax.trustedcomputing
This package and its subpackages provide for integration of Trusted
Computing in Java.
25
javax.trustedcomputing.tpm
This package allows to connect to a Trusted Platform Module (TPM).
28
javax.trustedcomputing.tpm.keys
This package allows the creation, storage, loading and unloading of
hierarchies of TPM keys.
45
javax.trustedcomputing.tpm.structures
This package contains helper classes for interaction with various other
classes from the javax.trustedcomputing.tpm package.
61
javax.trustedcomputing.tpm.tools
This package allows using various core concepts of Trusted Computing.
70
javax.trustedcomputing.tpm.tools.remote
This package allows using various core concepts of Trusted Computing
from a remote host.
82
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.
26
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
Copyright (c) IAIK, Graz University of Technology, 2011. All rights reserved.
25
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
static
long
Page
HIGH_LEVEL_API_LAYER_ERROR
Numeric Error code returned when the TrustedComputingException was raised at JSR 321
27
level.
Constructor Summary
Page
27
TrustedComputingException()
Method Summary
abstract
Throwable
Page
getCause()
27
Returns the originally thrown Exception.
abstract
long
getLowLevelErrorCode()
Returns the detailed C-styled error code that is generated by lower-level software components that
connect to the TPM.
abstract
String
getMessage()
Returns a detailed text description of the error cause.
abstract
String
27
27
getShortMessage()
Returns a short, one-line text description of the error cause.
26
28
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.
Overrides:
getMessage in class Throwable
27
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.
Class Summary
Page
TPMContext The Context class is the centerpiece of the JSR321 API.
Exception Summary
PCRsNotAccessibleException
29
35
Page
This Exception is thrown if an operation that access the PCRs is blocked by the
operating system.
29
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.
28
Class PCRsNotAccessibleException
javax.trustedcomputing.tpm
java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
javax.trustedcomputing.tpm.PCRsNotAccessibleException
All Implemented Interfaces:
Serializable
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.
Constructor Summary
Page
29
PCRsNotAccessibleException(String string)
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.
Field Summary
String
Page
PROPERTY_JSR_REVISION
Property key to query the JSR321 specification revision.
29
31
String
PROPERTY_JSR_VERSION
Property key to query the JSR321 implementation version.
String
PROPERTY_TPM_FIRMWARE_VERSION
Property key to query the TPM firmware version.
String
Method Summary
extendPCR(int PCRindex, Digest data)
33
readPCR(int[] PCRindices)
Reads the current values of a set of PCR registers from the TPM.
void
32
isOwned()
Determines the status of the TPM operation mode (Owned or no ownership taken).
PCRInfo
32
isEnabled()
Determines the status of the TPM operation mode (Enables/Disabled).
boolean
32
isActivated()
Determines the status of the TPM operation mode (Activated/Deactivate).
boolean
35
getRandom(int length)
Returns an array of random numbers, generated by the cryptographic true random number
generator of the TPM.
boolean
33
getProperty(String property)
Allows to query properties and information on the Trusted Computing mechanisms of this platform.
byte[]
34
getNumberPCR()
Provides the number of PCR registers provided by this TPM.
Object
33
extendPCR(int PCRindex, PCREvent event)
Performs the Extend operation with the given event on the selected PCR.
int
31
Page
Performs the Extend operation with the given data on the selected PCR.
void
31
PROPERTY_TSS_VERSION
Property key to query the version of the underlying TSS.
void
31
PROPERTY_TSS_VENDOR
Property key to query the vendor of the underlying TSS.
String
31
PROPERTY_TPM_VERSION
Property key to query the TPM specification version.
String
31
PROPERTY_TPM_MANUFACTURER
Property key to query the TPM manufacturer.
String
31
34
stirRandom(byte[] entropy)
Allows to add entropy to the hardware Random Number Generator of the TPM.
30
34
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
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.
31
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:
TrustedComputingException
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:
TrustedComputingException
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:
TrustedComputingException
32
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:
TrustedComputingException
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:
TrustedComputingException
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:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
33
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:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
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.
Returns:
the set of PCR values.
Throws:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
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.
34
Throws:
TrustedComputingException
getProperty
Object getProperty(String property)
throws TrustedComputingException,
IllegalArgumentException
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
Parameters:
property - The key of the property to be queried.
Returns:
The property value.
Throws:
TrustedComputingException
IllegalArgumentException
{@link - IllegalArgumentException} if wrong or illegal property is queried
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. An exception are the Remote Tools, which do not require a connection to a
hardware TPM and can be used on a remote host.
35
Method Summary
abstract void
Page
close()
Closes the connection to the TPMContext session.
abstract void
connect(URL remoteAdress)
Connects this TPMContext to a TPM context session.
abstract
Attestor
38
getInstance(String className)
returns an Instance of a TPMContext implementation.
abstract
KeyManager
43
getInstance()
returns an instance of a TPMContext implementation.
static
TPMContext
41
getInitializer()
Returns an Initializer that allows the initial configuration of the TPM, for instance taking
ownership.
static
TPMContext
43
getDigest(byte[] digest)
Creates a Digest, which holds a given SHA-1 hash.
abstract
Initializer
40
getCertifier()
Creates an instance of the optional Certifier tool that provides all services for key
certification.
abstract Digest
43
getBinder()
Creates a Binder object that provides functionality for TPM-based binding.
abstract
Certifier
38
getAttestor()
Creates an instance of Attestor that provides all services for remote attestation.
abstract Binder
37
38
getKeyManager()
Creates an instance of KeyManager which handles all operations to create, store and load
40
keys.
abstract
PCREvent
getPCREvent(long eventType, Digest data, String eventDescription)
Returns an initialized PCREvent object.
abstract
PCRInfo
getPCRInfo()
Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24).
abstract
PCRInfo
41
getPCRInfo(int numberOfPCRs)
Creates a PCRInfo object with a given number of PCR registers, which cannot be changed
once set.
abstract
RemoteAttestor
42
41
getRemoteAttestor()
Creates an instance of the RemoteAttestor tool which can be used to validate TPM Quote
data on a remote host without a TPM.
36
44
abstract
RemoteBinder
getRemoteBinder()
Creates an instance of the RemoteBinder tool which can be used to bind data on a remote
host to a TPM-protected BindingKey.
abstract
RemoteCertifier
getRemoteCertifier()
Creates an instance of the RemoteCertifier tool which can be used to validate the policies
of TPM-protected keys a remote host without a TPM.
abstract
RemoteSigner
40
getTPMInstance()
Creates an implementation-specific instance of TPM.
abstract
boolean
41
getSigner()
Creates a Signer object that provides functionality for signing data with TPM-protected keys.
abstract TPM
42
getSecret(Digest hashedSecret)
Creates a Secret object directly from a SHA-1 hash.
abstract Signer
42
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.
abstract Secret
40
getSecret(char[] password)
A Secret is a convenient representation of hashed passwords used to authenticate
operations with the TPM.
abstract Secret
44
getSealer()
Creates a Sealer object that provides functionality for TPM-based data sealing.
abstract Secret
44
getRemoteSigner()
Creates an instance of the RemoteSigner tool which helps verifying cryptographic signatures
performed by the TPM.
abstract Sealer
44
39
isConnected()
Determines if a TPMContext is connected to the session context of a hardware TPM.
39
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:
TrustedComputingException
37
connect
public abstract void connect(URL remoteAdress)
throws TrustedComputingException
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:
TrustedComputingException
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
38
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.
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:
TrustedComputingException
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:
TrustedComputingException
39
getKeyManager
public abstract KeyManager getKeyManager()
throws TrustedComputingException
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:
TrustedComputingException
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:
TrustedComputingException
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:
TrustedComputingException
getSigner
public abstract Signer getSigner()
throws TrustedComputingException
Creates a Signer object that provides functionality for signing data with TPM-protected keys.
40
Returns:
a Signer which is linked to this TPMContext
Throws:
TrustedComputingException
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)
Creates a PCRInfo object with a given number of PCR registers, which cannot be changed once set.
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.
41
Parameters:
hashedSecret - The already hashed secret.
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)
throws CharacterCodingException
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".
Returns:
The created Secret.
Throws:
CharacterCodingException - when a character decoding or encoding error occurs.
getPCREvent
public abstract PCREvent getPCREvent(long eventType,
Digest data,
String eventDescription)
Returns an initialized PCREvent object.
42
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
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:
TrustedComputingException
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:
TrustedComputingException
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.
43
Throws:
TrustedComputingException
UnsupportedOperationException
getRemoteAttestor
public abstract RemoteAttestor getRemoteAttestor()
Creates an instance of the RemoteAttestor tool which can be used to validate TPM Quote data on a remote host
without a TPM. It can be used even if the TPMContext is not connected.
Returns:
a RemoteAttestor, which can act without a local hardware TPM.
getRemoteBinder
public abstract RemoteBinder getRemoteBinder()
Creates an instance of the RemoteBinder tool which can be used to bind data on a remote host to a TPM-protected
BindingKey. It can be used even if the TPMContext is not connected.
Returns:
a RemoteBinder, which can act without a local hardware TPM.
getRemoteCertifier
public abstract RemoteCertifier getRemoteCertifier()
Creates an instance of the RemoteCertifier tool which can be used to validate the policies of TPM-protected keys
a remote host without a TPM. It can be used even if the TPMContext is not connected.
Returns:
a RemoteCertifier, which can act without a local hardware TPM.
getRemoteSigner
public abstract RemoteSigner getRemoteSigner()
Creates an instance of the RemoteSigner tool which helps verifying cryptographic signatures performed by the
TPM. It can be used even if the TPMContext is not connected.
Returns:
a RemoteSigner, which can act without a local hardware TPM.
44
Package javax.trustedcomputing.tpm.keys
This package allows the creation, storage, loading and unloading of hierarchies of TPM keys.
See:
Description
Interface Summary
Page
BindingKey
Binding keys protect data which is bound to a specific platform.
45
IdentityKey
IdentityKeys perform signatures on data that originates within the TPM.
46
LegacyKey
LegacyKeys are the only TPM based keys that are allowed to perform both signing and encryption
operations.
55
SigningKey
Signing keys sign arbitrary data.
56
StorageKey
Storage keys wrap other keys or sealed data.
56
StorageRootKey The Storage Root Key (SRK) is the highest key in the TPM key hierarchy.
56
TPMKey
Provides common functionality for all types of TPM-based keys, as created by the KeyManager.
57
TPMRSAKey
Provides access to the public parts of the RSA keys used by version 1.2 TPMs.
60
Class Summary
Page
KeyManager Provides management functionality for TPM-based cryptographic keys.
Exception Summary
KeyNotMigratableException
46
Page
This Exception is thrown if an operation that can only be performed on migratable TPM
keys is called on a non-migratable TPM key.
55
Package javax.trustedcomputing.tpm.keys Description
This package allows the creation, storage, loading and unloading of hierarchies of TPM keys. The central KeyManager class
TPMContext.
must
be
created
by
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
45
Interface BindingKey
public interface BindingKey
extends TPMKey, TPMRSAKey
Binding keys protect data which is bound to a specific platform.
Interface IdentityKey
javax.trustedcomputing.tpm.keys
All Superinterfaces:
RSAKey, TPMKey, TPMRSAKey
public interface IdentityKey
extends TPMKey, TPMRSAKey
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
abstract
BindingKey
Page
createBindingKey(StorageKey
parent,
Secret
usageSecret,
migrationSecret,
boolean
isMigratable,
boolean
isVolatile,
needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo)
Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.
46
Secret
boolean
48
abstract
SigningKey
createSigningKey(StorageKey
parent,
Secret
usageSecret,
migrationSecret,
boolean
isMigratable,
boolean
isVolatile,
needsAuthorization, int RSAKeyLength, PCRInfo pcrInfo)
Secret
boolean
48
Creates a cryptographic RSA key pair for signing operations in the TPM and loads it into a TPM
key slot.
abstract
StorageKey
createStorageKey(StorageKey
parent,
Secret
migrationSecret,
boolean
isMigratable,
boolean
needsAuthorization, PCRInfo pcrInfo)
usageSecret,
isVolatile,
Secret
boolean
49
Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.
abstract void
deleteTPMKey(UUID identifier)
Removes a key from the user persistent key storage permanently.
abstract void
deleteTPMSystemKey(UUID identifier)
Removes a key from the system persistent key storage permanently.
abstract
UUID[]
53
storeTPMKey(StorageKey parent, TPMKey key, UUID identifier)
Stores a key in the user persistent key storage for later use.
abstract void
51
loadTPMSystemKey(StorageKey parent, UUID identifier, Secret usageSecret)
Retrieves a cryptographic RSA key object from system persistent storage and loads it into a
TPM key slot.
abstract void
52
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.
abstract
TPMKey
52
loadTPMKey(StorageKey parent, UUID identifier, Secret usageSecret)
Retrieves a cryptographic RSA key object from user persistent storage and loads it into a TPM
key slot.
abstract
TPMKey
51
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.
abstract
TPMKey
50
loadStorageRootKey(Secret srkSecret)
Loads the Storage Root Key (SRK) from the TPM.
abstract
TPMKey
54
importLegacyKey(StorageKey parent, KeyPair keyPair, Secret keySecret)
Imports a given RSA public key and derives a TPM legacy key from it.
abstract
StorageRootKey
54
getStoredTPMSystemKeys()
Retrieves a list of the identifiers of all keys stored in the persistent system key store.
abstract
LegacyKey
50
getStoredTPMKeys()
Retrieves a list of the identifiers of all keys stored in the persistent user key store.
abstract
UUID[]
50
53
storeTPMSystemKey(StorageKey parent, TPMKey key, UUID identifier)
Stores a key in the system persistent key storage for later use.
47
54
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
Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.
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:
TrustedComputingException
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.
48
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:
TrustedComputingException
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:
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.
49
pcrInfo - Restricts usage of the key to the PCR value specified. Ignored if null.
Returns:
Returns a freshly created key, ready for use
Throws:
TrustedComputingException
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-TPMstatus.
Parameters:
identifier - identifies the key to be deleted.
Throws:
TrustedComputingException
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-intoTPM-status.
Parameters:
identifier - identifies the key to be deleted.
Throws:
TrustedComputingException
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.
50
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.
Throws:
TrustedComputingException
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:
- The SRK usage secret set during Take Ownership. In most cases this is
Secret.WELL_KNOWN_SECRET.
srkSecret
Returns:
the SRK loaded into the TPM and ready to use
Throws:
TrustedComputingException
loadTPMSystemKey
public abstract TPMKey loadTPMSystemKey(StorageKey parent,
RSAPublicKey pubKey,
Secret usageSecret)
throws TrustedComputingException
Retrieves a cryptographic RSA key object from system persistent storage and loads it into a TPM key slot.
Parameters:
parent - The TPMKey which is this key's parent in the hierarchy.
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.
51
Returns:
the loaded key, ready to use.
Throws:
TrustedComputingException
loadTPMKey
public abstract TPMKey loadTPMKey(StorageKey parent,
RSAPublicKey pubKey,
Secret usageSecret)
throws TrustedComputingException
Retrieves a cryptographic RSA key object from user persistent storage and loads it into a TPM key slot.
Parameters:
parent - The TPMKey which is this key's parent in the hierarchy.
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:
TrustedComputingException
loadTPMKey
public abstract TPMKey loadTPMKey(StorageKey parent,
UUID identifier,
Secret usageSecret)
throws TrustedComputingException
Retrieves a cryptographic RSA key object from user persistent storage and loads it into a TPM key slot.
Parameters:
parent - The TPMKey which is this key's parent in the hierarchy.
identifier - The unique ID 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.
52
Throws:
TrustedComputingException
loadTPMSystemKey
public abstract TPMKey loadTPMSystemKey(StorageKey parent,
UUID identifier,
Secret usageSecret)
throws TrustedComputingException
Retrieves a cryptographic RSA key object from system persistent storage and loads it into a TPM key slot.
Parameters:
parent - The TPMKey which is this key's parent in the hierarchy.
identifier - The unique ID 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:
TrustedComputingException
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:
parent - The TPMKey which is this key's parent in the hierarchy.
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:
TrustedComputingException
53
storeTPMSystemKey
public abstract void storeTPMSystemKey(StorageKey parent,
TPMKey key,
UUID identifier)
throws TrustedComputingException
Stores a key in the system persistent key storage for later use.
Parameters:
parent - The TPMKey which is this key's parent in the hierarchy.
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:
TrustedComputingException
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:
TrustedComputingException
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:
TrustedComputingException
54
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
All Implemented Interfaces:
Serializable
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.
Constructor Summary
Page
55
KeyNotMigratableException(String string)
Constructor Detail
KeyNotMigratableException
public KeyNotMigratableException(String string)
Interface LegacyKey
javax.trustedcomputing.tpm.keys
All Superinterfaces:
RSAKey, TPMKey, TPMRSAKey
public interface LegacyKey
extends TPMKey, TPMRSAKey
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.
55
Interface LegacyKey
Interface SigningKey
javax.trustedcomputing.tpm.keys
All Superinterfaces:
RSAKey, TPMKey, TPMRSAKey
public interface SigningKey
extends TPMKey, TPMRSAKey
Signing keys sign arbitrary data. The TPM uses the RSAASSA-PKCS1-v1_5 scheme.
Interface StorageKey
javax.trustedcomputing.tpm.keys
All Superinterfaces:
RSAKey, TPMKey, TPMRSAKey
All Known Subinterfaces:
StorageRootKey
public interface StorageKey
extends TPMKey, TPMRSAKey
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.
56
Field Summary
UUID
Page
SRK_UUID
The unique identifier of the SRK for use with the persistent key storage.
Method Summary
void
57
Page
changeUsageSecret(Secret ownerSecret, Secret newSecret)
Changes the usage policy secret from the old secret to the new secret.
57
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 000000000000-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:
TrustedComputingException
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.
57
Interface TPMKey
Method Summary
void
Page
changeMigrationSecret(StorageKey parent, Secret oldSecret, Secret newSecret)
Changes the migration policy secret from the old secret to the new secret.
void
changeUsageSecret(StorageKey parent, Secret oldSecret, Secret newSecret)
Changes the usage policy secret from the old secret to the new secret.
UUID
59
setUUID(UUID keyIdentifier)
Set the Universally Unique IDentifier of this key.
void
58
getUUID()
Gets the Universally Unique IDentifier of this key.
void
58
59
unload()
59
Unload this key from the TPM.
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:
TrustedComputingException
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.
58
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:
TrustedComputingException
unload
void unload()
throws TrustedComputingException
Unload this key from the TPM. This key instance cannot be used afterwards.
Throws:
TrustedComputingException
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.
59
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
BigInteger
Page
getModulus()
Returns the modulus of the RSA key pair.
RSAPublicKey
60
getPublicKey()
Provides the public part of a TPM protected key.
Method Detail
getModulus
BigInteger getModulus()
Returns the modulus of the RSA key pair. Will return NULL if operation fails.
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:
TrustedComputingException
60
60
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.
61
PCREvent
Holds the data to be extended into PCRs, together with event information that will be stored in the
systems Stored Measurement Log (SML).
63
PCRInfo
The contents of the Platform Configuration Registers (PCR) of a TPM can be used to report the
configuration of a system.
64
Secret
Provides conversion of password strings into the hashed binary format expected by the TPM.
66
ValidationData
Holds all information necessary to validate that an operation that returns it was properly performed
by an authentic TPM.
69
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.
Constructor Summary
Page
Digest(byte[] digest)
62
Creates a Digest, which holds a given SHA-1 hash.
61
Method Summary
abstract
boolean
Page
equals(Object other)
Indicates whether some other object is "equal to" this one.
abstract
byte[]
getBytes()
Provides the 20 bytes hash passed at construction.
abstract
int
62
62
hashCode()
63
Returns a hash code value for the object.
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.
equals
public abstract boolean equals(Object other)
Indicates whether some other object is "equal to" this one.
Overrides:
equals in class Object
62
hashCode
public abstract int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those
provided by Hashtable.
Overrides:
hashCode in class Object
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).
Constructor Summary
Page
PCREvent(long eventType, Digest data, String eventDescription)
63
Returns an initialized PCREvent object.
Method Summary
Page
Digest
getDataDigest()
64
String
getEventDescription()
64
getEventType()
64
long
Constructor Detail
PCREvent
public PCREvent(long eventType,
Digest data,
String eventDescription)
Returns an initialized PCREvent object.
63
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
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.
64
Constructor Summary
Page
PCRInfo()
Creates a PCRInfo object with default number of PCRs 1.2 in TPMs (24).
65
PCRInfo(int numberOfPCRs)
Creates a PCRInfo object with a given number of PCR registers, which cannot be changed once set.
Method Summary
abstract
int
Page
getNumberOfPCRs()
Gets the number of PCRs specified in this PCRInfo
abstract
Digest
65
getValueIndices()
Returns an array of the PCR values that are different from null in this object.
abstract
void
66
getPCRValue(int index)
Returns the requested PCR value of the PCRInfo.
abstract
int[]
65
66
setPCRValue(int index, Digest value)
Sets the assigned PCR entry in PCRInfo to the given value.
66
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
Creates a PCRInfo object with a given number of PCR registers, which cannot be changed once set.
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)
65
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.
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
66
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
static
Secret
Page
WELL_KNOWN_SECRET
Provides the TSS_WELL_KNOWN_SECRET which consists of 20 bytes of zero.
Constructor Summary
67
Page
Secret(char[] password)
Creates a Secret object that holds a converted password.
68
Secret(char[] password, boolean addNullTermination, Charset encoding)
Creates a Secret object that contains a converted password and allows to determine the encoding and nulltermination settings which are applied before performing the SHA-1 hash operation.
68
Secret(Digest hashedSecret)
67
Creates a Secret object directly from a SHA-1 hash.
Method Summary
abstract
void
Page
flushSecret()
68
Deletes the secret data from memory.
abstract
byte[]
getBytes()
Provides the password secret encoded as a 20 bytes long SHA-1 hash.
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.
67
68
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.
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 nulltermination settings which are applied before performing the SHA-1 hash operation. Use this only for interoperability 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
68
Class ValidationData
javax.trustedcomputing.tpm.structures
java.lang.Object
javax.trustedcomputing.tpm.structures.ValidationData
All Implemented Interfaces:
Serializable
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.
Constructor Summary
Page
ValidationData(byte[] nonce, byte[] data, byte[] validationData)
Creates a ValidationData object that contains the results of a signature operation in the TPM.
Method Summary
byte[]
Page
getData()
Data which was used to calculate the validation.
byte[]
70
getNonce()
Random external data (i.e a nonce) supplied to the TPM used to avoid replay attacks.
byte[]
69
70
getValidationData()
The validation data, which is the signature preformed by the TPM.
70
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.
69
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.
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
70
Package javax.trustedcomputing.tpm.tools
Class Summary
Page
Attestor Provides all services for performing services for remote attestation
71
Binder
Provides all services for performing the TPM-bind operation on user data.
73
Certifier
Provides services for certifying a TPMKey and for validating the key's policy.
74
Initializer This class allows perform basic initialization operations for the TPM, such as taking ownership.
77
Sealer
Provides all services for performing TPM_SEAL on user data.
78
Signer
This class allows to sign user data or files using a SigningKey or a LegacyKey.
80
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.
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
Constructor Summary
Page
Attestor(TPMContext context)
Initializes and returns this instance of Attestor within the context of a TPM.
Method Summary
abstract
ValidationData
Page
quote(int[] PCRindices, IdentityKey key, Digest nonce)
72
Performs the Quote operation.
abstract
ValidationData
72
quote(int[] PCRindices, SigningKey key, Digest nonce)
72
Performs the Quote operation.
71
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.
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:
PCRindices - The index values of the PCRs to be included in the result. 1.2 TPMs offer at least 24 PCRs.
key - The Identity Key to be used in this operation
nonce - A nonce to guarantee freshness.
Returns:
The signed TPM Quote.
Throws:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
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.
72
Parameters:
PCRindices - The index values of the PCRs to be included in the result. 1.2 TPMs offer at least 24 PCRs.
key - The Signing Key to be used in this operation
nonce - A nonce to guarantee freshness.
Returns:
The signed TPM Quote.
Throws:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
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.
Constructor Summary
Page
Binder(TPMContext context)
Initializes and returns this instance of Binder within the context of a TPM.
Method Summary
abstract
byte[]
73
Page
unbind(byte[] encryptedData, BindingKey key)
74
Unbinds and decrypts a bound byte array.
Constructor Detail
Binder
public Binder(TPMContext context)
73
Initializes and returns this instance of Binder within the context of a TPM.
Parameters:
context - The context of the TPM session.
Method Detail
unbind
public abstract byte[] unbind(byte[] encrytedData,
BindingKey key)
throws TrustedComputingException
Unbinds and decrypts a bound byte array.
Parameters:
encrytedData - The data to be decrypted.
key - A BindingKey
Throws:
TrustedComputingException
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.
Constructor Summary
Page
Certifier(TPMContext context)
Initializes and returns this instance of Certifier within the context of a TPM.
74
75
Method Summary
abstract
ValidationData
Page
certifyKey(TPMKey toBeCertified, IdentityKey certifyingKey, Digest nonce)
Performs the certify operation using an IdentityKey.
abstract
ValidationData
certifyKey(TPMKey toBeCertified, LegacyKey certifyingKey, Digest nonce)
Performs the certify operation using a LegacyKey.
abstract
ValidationData
75
76
certifyKey(TPMKey toBeCertified, SigningKey certifyingKey, Digest nonce)
Performs the certify operation using a SigningKey.
76
Constructor Detail
Certifier
public Certifier(TPMContext context)
Initializes and returns this instance of Certifier within the context of a TPM.
Parameters:
context - The context of the TPM session.
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.
nonce - A nonce to guarantee freshness.
Returns:
The data necessary to validate that a key is certified.
Throws:
TrustedComputingException
IllegalArgumentException
75
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 .
nonce - A nonce to guarantee freshness.
Returns:
The data necessary to validate that a key is certified.
Throws:
TrustedComputingException
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.
nonce - A nonce to guarantee freshness.
Returns:
The data necessary to validate that a key is certified.
Throws:
TrustedComputingException
76
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.
Constructor Summary
Page
Initializer(TPMContext context)
Initializes and returns this instance of Initializer within the context of a TPM.
Method Summary
abstract
void
Page
clearOwnership(Secret ownerSecret)
Removes all owner-related information from the TPM and deletes the Storage Root Key.
abstract
void
77
78
takeOwnership(Secret ownerSecret, Secret srkSecret)
Takes ownership of an active and enabled, but currently unowned TPM.
77
Constructor Detail
Initializer
public Initializer(TPMContext context)
Initializes and returns this instance of Initializer within the context of a TPM.
Parameters:
context - The context of the TPM session.
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.
77
Parameters:
ownerSecret - New owner authentication secret.
srkSecret - New authentication secret for the SRK. By convention, Secret.WELL_KNOWN_SECRET should
be used.
Throws:
TrustedComputingException
clearOwnership
public abstract void clearOwnership(Secret ownerSecret)
throws TrustedComputingException
Removes all owner-related information from the TPM and deletes the Storage Root Key. All other user keys will be
inaccessible. Note that on taking ownership some platforms may configure the hardware TPM to require proof of
physical presence for this operation. Note that on typical PC platforms a forced clear without owner password can
only be done from the systems BIOS.
Parameters:
ownerSecret - the current owner authentication secret
Throws:
TrustedComputingException
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.
Constructor Summary
Page
Sealer(TPMContext context)
Initializes and returns this instance of Sealer within the context of a TPM.
78
79
Method Summary
abstract
byte[]
seal(byte[]
dataSecret)
Page
plainData,
PCRInfo
targetState,
StorageKey
storageKey,
Secret
79
Encrypts a byte array and seals it to a target state using a SealingKey.
abstract
byte[]
unseal(byte[] encrytedData, StorageKey key, Secret dataSecret)
80
Unseals and decrypts a sealed byte array.
Constructor Detail
Sealer
public Sealer(TPMContext context)
Initializes and returns this instance of Sealer within the context of a TPM.
Parameters:
context - The context of the TPM session.
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:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
79
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.
Throws:
TrustedComputingException
PCRsNotAccessibleException - If access to PCRs is blocked by the Operating System
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.
Constructor Summary
Page
Signer(TPMContext context)
Initializes and returns this instance of Signer within the context of a TPM.
Method Summary
abstract
byte[]
81
Page
sign(byte[] plainData, LegacyKey key)
81
Signs data using a TPM-protected key.
80
abstract
byte[]
sign(byte[] plainData, SigningKey key)
81
Signs data using a TPM-protected key.
Constructor Detail
Signer
public Signer(TPMContext context)
Initializes and returns this instance of Signer within the context of a TPM.
Parameters:
context - The context of the TPM session.
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:
TrustedComputingException
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.
81
Returns:
The signature on the hash of the data as returned by the TPM.
Throws:
TrustedComputingException
Package javax.trustedcomputing.tpm.tools.remote
This package allows using various core concepts of Trusted Computing from a remote host.
See:
Description
Class Summary
Page
RemoteAttestor Allows verification of Quote result using a public key.
82
RemoteBinder
Allows binding data to a public key.
84
RemoteCertifier Allows validation of a certified key.
85
RemoteSigner
89
Allows validation of signed data.
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.
82
Constructor Summary
Page
RemoteAttestor()
83
Creates a RemoteAttestor instance.
Method Summary
abstract
boolean
Page
validateQuote(ValidationData dataToValidate,
nonce, PCRInfo expectedValues)
RSAPublicKey
identityKey,
Digest
Calculates the expected PCR configuration and compares it and the nonce to the one provided in the
ValidationData and also verifies the signature.
83
Constructor Detail
RemoteAttestor
public 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)
throws GeneralSecurityException,
TrustedComputingException
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.
Throws:
GeneralSecurityException - If cryptographic validation fails.
83
TrustedComputingException - if an error in the construction of quote data structures.
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.
Constructor Summary
Page
RemoteBinder()
84
Creates a RemoteBinder instance.
Method Summary
abstract
byte[]
Page
bind(byte[] plainData, RSAPublicKey bindingKey)
Encrypts a byte array and binds it using a BindingKey.
84
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.
84
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:
TrustedComputingException
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
Allows validation of a certified key. This can be performed without TPM access or by remote parties.
Constructor Summary
Page
RemoteCertifier()
86
Creates a RemoteCertifier instance.
Method Summary
abstract
boolean
Page
containsPCRInfo(ValidationData certifiedKeyInfo, PCRInfo desiredPCRInfo)
Checks if the key described in the given ValidationData requires the desired PCR values when
being used.
abstract
boolean
isBindingKey(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is a BindingKey.
abstract
boolean
87
87
isKeyOfLength(ValidationData certifiedKeyInfo, int desiredKeyLength)
Checks if the key described in the given ValidationData has the desired key length.
85
87
abstract
boolean
isLegacyKey(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is a LegacyKey.
abstract
boolean
isMigratable(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is migratable.
abstract
boolean
89
needsAuthorization(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData needs authorization.
abstract
boolean
89
isVolatile(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is volatile.
abstract
boolean
88
isStorageKey(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is a StorageKey.
abstract
boolean
88
isSigningKey(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is a SigningKey.
abstract
boolean
88
validate(ValidationData dataToValidate, RSAPublicKey certifiedKey, RSAPublicKey
certifyingKey, Digest nonce)
89
86
Performs the operation to validate a previously certified key.
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)
throws GeneralSecurityException
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).
86
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.
Throws:
GeneralSecurityException - if signature validation fails.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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.
87
Parameters:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
Returns:
true if the certified key is a SigningKey, false otherwise.
88
isStorageKey
public abstract boolean isStorageKey(ValidationData certifiedKeyInfo)
Checks if the key described in the given ValidationData is a StorageKey.
Parameters:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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:
certifiedKeyInfo - The validation data that was returned from the certifying operation.
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
89
abstract public class RemoteSigner
extends Object
Allows validation of signed data. This can be performed without TPM access or by remote parties.
Constructor Summary
Page
RemoteSigner()
90
Creates a RemoteSigner instance.
Method Summary
abstract
boolean
Page
validate(byte[] signature, byte[] data, RSAPublicKey key)
Verifies that a provided signature is valid using the claimed key.
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 GeneralSecurityException
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:
GeneralSecurityException
90
90
IV. License
License for Evaluation Purposes
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
("Specification")
Trusted
Computing
API
for
Java(tm)
Version: 11.10
Status: Final Release
Release: 11 October 2011
Copyright 2011 Institute
Communications (IAIK)
for
Applied
Information
Processing
and
Graz University of Technology
Inffeldgasse 16a
A-8010 Graz
Austria
All rights reserved.
LIMITED EVALUATION LICENSE
Institute for Applied Information Processing and Communications (IAIK)
hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide,
limited license (without the right to sublicense), under Institute for
Applied Information Processing and Communications (IAIK)'s applicable
intellectual property rights to view, download, use and reproduce the
Specification only for the purpose of internal evaluation. This includes
(i) developing applications intended to run on an implementation of the
Specification, provided that such applications do not themselves implement
any portion(s) of the Specification, and (ii) 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 Technology. No license of any kind
is granted hereunder for any other purpose including, for example, creating
and distributing implementations of the Specification, modifying the
Specification (other than to the extent of your fair use rights), or
distributing the Specification to third parties. Also, no right, title, or
interest in or to any trademarks, service marks, or trade names of Oracle
or Oracle's licensors, Institute for Applied Information Processing and
Communications (IAIK) or the Institute for Applied Information Processing
and Communications (IAIK)'s licensors is granted hereunder. If you wish to
create and distribute an implementation of the Specification, a license for
that purpose is available at http://www.jcp.org. The foregoing license is
expressly conditioned on your acting within its scope, and will terminate
immediately without notice from Oracle if you breach the Agreement or act
outside the scope of the licenses granted above. Java, and Java-related
logos, marks and names are trademarks or registered trademarks of Oracle
America, Inc. in the U.S. and other countries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS". INSTITUTE FOR APPLIED INFORMATION
PROCESSING AND COMMUNICATIONS (IAIK) MAKES NO REPRESENTATIONS OR
WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR IMPLEMENTATION
OF THE SPECIFICATION), OR THAT THE CONTENTS OF THE SPECIFICATION ARE
SUITABLE FOR ANY PURPOSE. This document does not represent any commitment
to release or implement any portion of the Specification in any product. In
addition, the Specification could include technical inaccuracies or
typographical errors.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SPECFICATION LEAD 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, RELATED IN ANY WAY TO YOUR HAVING OR USING THE SPECIFICATION,
EVEN IF INSTITUTE FOR APPLIED INFORMATION PROCESSING AND COMMUNICATIONS
(IAIK) AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
RESTRICTED RIGHTS LEGEND
U.S. Government: If this Specification 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
If you provide Institute for Applied Information Processing and
Communications (IAIK) with any comments or suggestions concerning the
Specification ("Feedback"), you hereby: (i) agree that such Feedback is
provided on a non-proprietary and non-confidential basis, and (ii) grant
Institute for Applied Information Processing and Communications (IAIK) a
92
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.
GOVERNING LAW
Any action relating to or arising out of 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.
Rev. January 2006
93
License for Implementations
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
("Specification")
Trusted
Computing
API
for
Java(tm)
Version: 11.10
Status: Final Release
Release: 11 October 2011
Copyright 2011 Institute
Communications (IAIK)
for
Applied
Information
Processing
and
Graz University of Technology
Inffeldgasse 16a
A-8010 Graz
Austria
All rights reserved.
LIMITED LICENSE GRANTS
1. License for Evaluation Purposes. Institute for Applied Information
Processing and Communications (IAIK) hereby grants you a fully-paid, nonexclusive, non-transferable, worldwide, limited license (without the right
to sublicense), under Institute for Applied Information Processing and
Communications (IAIK)'s applicable intellectual property rights to view,
download, use and reproduce the Specification only for the purpose of
internal evaluation. This includes (i) developing applications intended to
run on an implementation of the Specification, provided that such
applications do not themselves implement any portion(s) of the
Specification, and (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
94
do not in the aggregate constitute a significant portion of the
Specification.
2. License for the Distribution of Compliant Implementations. Institute for
Applied Information Processing and Communications (IAIK) also grants you a
perpetual, non-exclusive, non-transferable, worldwide, fully paid-up,
royalty free, limited license (without the right to sublicense) under any
applicable copyrights or, subject to the provisions of subsection 4 below,
patent rights it may have covering the Specification to create and/or
distribute an Independent Implementation of the Specification that: (a)
fully implements the Specification including all its required interfaces
and functionality; (b) 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; and (c) passes the Technology
Compatibility Kit (including satisfying the requirements of the applicable
TCK Users Guide) for such Specification ("Compliant Implementation"). In
addition, the foregoing license is expressly conditioned on your not acting
outside its scope. No license is granted hereunder for any other purpose
(including, for example, modifying the Specification, other than to the
extent of your fair use rights, or distributing the Specification to third
parties). Also, no right, title, or interest in or to any trademarks,
service marks, or trade names of Institute for Applied Information
Processing and Communications (IAIK) or Institute for Applied Information
Processing and Communications (IAIK)'s licensors is granted hereunder.
Java, and Java-related logos, marks and names are trademarks or registered
trademarks of Oracle America, Inc. in the U.S. and other countries.
3. Pass-through Conditions. You need not include limitations (a)-(c) from
the previous paragraph or any other particular "pass through" requirements
in any license You grant concerning the use of your Independent
Implementation or products derived from it. However, except with respect
to Independent Implementations (and products derived from them) that
satisfy limitations (a)-(c) from the previous paragraph, You may neither:
(a) grant or otherwise pass through to your licensees any licenses under
Institute for Applied Information Processing and Communications (IAIK)'s
applicable intellectual property rights; nor (b) authorize your licensees
to make any claims concerning their implementation's compliance with the
Specification in question.
4. Reciprocity Concerning Patent Licenses.
a. With respect to any patent claims covered by the license
granted under subparagraph 2 above that would be infringed by all
technically feasible implementations of the Specification, such license is
conditioned upon your offering on fair, reasonable and non-discriminatory
terms, to any party seeking it from You, a perpetual, non-exclusive, nontransferable, worldwide license under Your patent rights which are or would
be infringed by all technically feasible implementations of the
Specification to develop, distribute and use a Compliant Implementation.
b With respect to any patent claims owned by Institute for Applied
Information Processing and Communications (IAIK) and covered by the license
granted under subparagraph 2, whether or not their infringement can be
avoided in a technically feasible manner when implementing the
Specification, such license shall terminate with respect to such claims if
You initiate a claim against Institute for Applied Information Processing
and Communications (IAIK) that it has, in the course of performing its
responsibilities as the Institute for Applied Information Processing and
Communications (IAIK), induced any other entity to infringe Your patent
rights.
95
c Also with respect to any patent claims owned by Institute for
Applied Information Processing and Communications (IAIK) and covered by the
license granted under subparagraph 2 above, where the infringement of such
claims can be avoided in a technically feasible manner when implementing
the Specification such license, with respect to such claims, shall
terminate if You initiate a claim against Institute for Applied Information
Processing and Communications (IAIK) that its making, having made, using,
offering to sell, selling or importing a Compliant Implementation infringes
Your patent rights.
5. Definitions. For the purposes of this Agreement: "Independent
Implementation" shall mean an implementation of the Specification that
neither derives from any of Institute for Applied Information Processing
and Communications (IAIK)'s source code or binary code materials nor,
except with an appropriate and separate license from Institute for Applied
Information Processing and Communications (IAIK), includes any of Institute
for Applied Information Processing and Communications (IAIK)'s source code
or binary code materials; "Licensor Name Space" shall mean the public class
or interface declarations whose names begin with "java", "javax", "iaik."
or their equivalents in any subsequent naming convention adopted by Oracle
through the Java Community Process, or any recognized successors or
replacements thereof; and "Technology Compatibility Kit" or "TCK" shall
mean the test suite and accompanying TCK User's Guide provided by Institute
for Applied Information Processing and Communications (IAIK) which
corresponds to the Specification and that was available either (i) from
Institute for Applied Information Processing and Communications (IAIK)'s
120 days before the first release of Your Independent Implementation that
allows its use for commercial purposes, or (ii) more recently than 120 days
from such release but against which You elect to test Your implementation
of the Specification.
This Agreement will terminate immediately without notice from Institute for
Applied Information Processing and Communications (IAIK) if you breach the
Agreement or act outside the scope of the licenses granted above.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS". INSTITUTE FOR APPLIED INFORMATION
PROCESSING AND COMMUNICATIONS (IAIK) MAKES NO REPRESENTATIONS OR
WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR IMPLEMENTATION
OF THE SPECIFICATION), OR THAT THE CONTENTS OF THE SPECIFICATION ARE
SUITABLE FOR ANY PURPOSE. This document does not represent any commitment
to release or implement any portion of the Specification in any product. In
addition, the Specification could include technical inaccuracies or
typographical errors.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL INSTITUTE FOR APPLIED
INFORMATION PROCESSING AND COMMUNICATIONS (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 IN ANY WAY TO YOUR HAVING, IMPELEMENTING OR OTHERWISE
USING USING THE SPECIFICATION, EVEN IF INSTITUTE FOR APPLIED INFORMATION
PROCESSING AND COMMUNICATIONS (IAIK) AND/OR ITS LICENSORS HAVE BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
You will indemnify, hold harmless, and defend Institute for Applied
Information Processing and Communications (IAIK) and its licensors from any
96
claims arising or resulting from: (i) your use of the Specification; (ii)
the use or distribution of your Java application, applet and/or
implementation; and/or (iii) 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
U.S. Government: If this Specification 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
If you provide Institute for Applied Information Processing and
Communications (IAIK) with any comments or suggestions concerning the
Specification ("Feedback"), you hereby: (i) agree that such Feedback is
provided on a non-proprietary and non-confidential basis, and (ii) grant
Institute for Applied Information Processing and Communications (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.
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
to export or import regulations in other countries. Licensee agrees
comply strictly with all such laws and regulations and acknowledges
has the responsibility to obtain such licenses to export, re-export
import as may be required after delivery to Licensee.
subject
to
that it
or
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. April, 2006
97
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, blockby-block. In: Proceedings of Future of Trust in Computing Conference, Berlin,
Vieweg+Teubner, 2008.
[Toegl11]
Toegl, R., Winkler, T., Nauman, M. and Hong, T. W. (2011), Specification and Standardization
of a Java Trusted Computing API. Software: Practice and Experience. doi: 10.1002/spe.1095
http://onlinelibrary.wiley.com/doi/10.1002/spe.1095/abstract
[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/
98
[TSS1.2]
Trusted Computing Group. TCG Software Stack (TSS) Specification, Version 1.2, Errata A,
March 7, 2007. https://www.trustedcomputinggroup.org/
99