Download Contributing To This Specification

JSR321
Trusted Computing API for Java ™
Java™ Community Process Specification
Proposed Final Draft
Copyright 2009-11
Institute for Applied Information Processing and Communications (IAIK)
Graz University Of Technology
Inffeldgasse 16a
A-8010 Graz
Austria
All rights reserved.
This Proposed Final Draft of the JSR321 Specification (covering this document and JavaDoc) is released for review
under the terms provided in the License chapter.
Table of Contents
I.
Preface ......................................................................................................................................................... 4
1. Revision History ........................................................................................................................................... 4
2. Who Should Use This Specification ............................................................................................................. 4
3. Outline ......................................................................................................................................................... 4
4. Introduction ................................................................................................................................................. 5
5. Contributors................................................................................................................................................. 6
6. Contributing To This Specification ............................................................................................................... 6
7. Open Issues.................................................................................................................................................. 7
II.
Technical Background and Design ............................................................................................................... 8
8. The Needs of the TPM ................................................................................................................................. 8
TCG Standard Approach for the C Programming Language................................................................ 8
9. JSR321 API Design Considerations............................................................................................................... 9
Design Goals........................................................................................................................................ 9
Limitation from the TCG Architecture ................................................................................................ 9
JSR321 API Scope and Limitations .................................................................................................... 10
Expected Developer Knowledge ....................................................................................................... 10
10. Outline of the API ...................................................................................................................................... 11
11. Feature Selection ....................................................................................................................................... 13
III.
Normative Part .......................................................................................................................................... 19
12. Definitions.................................................................................................................................................. 19
13. Requirements ............................................................................................................................................ 19
14. Detailed API Specifications ........................................................................................................................ 20
IV.
License ....................................................................................................................................................... 21
V.
References and Relevant Literature .......................................................................................................... 26
I. Preface
These specifications allow integrating Trusted Computing into JavaTM.
Java™ is a platform with integrated security features and therefore well suited for Trusted Computing (TC)
software. However, the current releases of Java™ do not provide standard integration of TC functionality which is
available in today's hardware platforms equipped with a Trusted Platform Module (TPM).
This document introduces the work performed within the Java™ Specification Request # 321 (JSR321) Expert
Group (EG). It contains a detailed description of the technical approach and presents the proposed final
specification.
The presented API is based on the Java2 Standard Edition (J2SE) Desktop-PC system architecture.
The JSR321 EG plans for the future to release all final results under free licenses. Specification documents and
header, respectively Javadoc definitions will be available for evaluation and allow creating and distributing
specification compliant implementations. Reference Implementation and Technology Compatibility Kit will be
made available under the GNU GPLv2 with Classpath Exception.
Revision History
Version
09.04
10.11
11.04
Revision Date
March 27, 2009
November 12,
Updated Nov. 19
March 25, 2011
Anticipated Release Date
April 10, 2009
2010 November 26, 2010
January 3, 2011
April 8, 2011
Comment
Early Draft Review Release
Public Review Release
Proposed Final Draft
Who Should Use This Specification
This document is written for the public community reviewing this specification, the Java™ Community Process
(JCP) Expert Group defining this specification, implementers of this API, and application developers targeting the
Java™ platform.
Outline
The Preface describes this document and introduces the goals of JSR321, the contributors and information on
how to review and participate.
The Technical Background chapter outlines the existing specifications of the Trusted Computing Group for
hardware and software. It also covers the goals and design decisions for JSR321.
The Normative Part contains binding requirements for all implementations of the JSR321 API. The API is specified
in detail.
This document and the accompanying JavaDoc of the API is released under the terms given in the License chapter.
References and Relevant Literature conclude this document.
Introduction
The concept of Trusted Computing (TC) promises an approach to improve the security of computer systems. The
core functionality, based on a hardware component known as the Trusted Platform Module (TPM), is being
integrated into commonly available hardware. Hundreds of millions of TPMs have shipped so far. Still, only limited
software support exists.
Indeed, a recent study on the TCG Software Stack (TSS) [Selhorst] concluded, that, “it is apparent that, until now,
no application exists that makes use of this technology. Even the simplest applications, [..] have not been applied
yet.”
A reason for this might be the high complexity and slow adoption of the TSS, which is the Trusted Computing
Group's industrial standard software accompanying the TPM. It solely supports the C programming language.
However, a major share of the software market is utilizing the platform-independent Java™ environment. The
Java™ language provides inherent security features such as type-safety and bounds-checking. The runtime
environment provides automated memory management, access control checks and bytecode verification.
Performance concerns of Java™ applications can be mitigated by using just-in-time compilation of JavaTM
bytecode. Furthermore, a rich set of libraries covers communication and cryptography.
This integrated security by design makes the managed Java™ environment a natural choice as basis for a Trusted
Computing Platform. While the current releases of Java™ do not provide support to access the TPM by default,
there are already multiple use-cases demonstrated for TC-enabled Java™ Applications.
Thus, the goal of this work is to make TPM and TSS-based features available to Java™ developers in a consistent,
object oriented, and also easy-to-use, intuitive way.
JSR321 will allow developers to make use of Trusted Computing functionality based on the Trusted Platform
Module (TPM) in their Java™ applications. Striving for a new simplified design, the resulting API will be easier to
use than the interfaces available today for other programming languages. This and the fact that all results will be
released under an open source license will hopefully foster the use of trusted technology for research, open and
also commercial JavaTM applications.
Contributors
Specification Lead:
Ronald Toegl, IAIK, Graz University of Technology
The members of the JSR321 Expert Group are








Ronald Toegl and Peter Lipp, Institute for Applied Information Processing and Communications (IAIK),
Graz University Of Technology
Jeff Nisewanger, Sun Microsystems/Oracle
Deepak Dasaratha Rao, Samsung Electronics Corporation
Winkler, Thomas
Keil, Werner
Hong, Theodore
Nauman, Mohammad
Gungoren, Bora
Former members of the Expert Group are

Kenneth M. Graf, Intel Corp.
The Expert Group would like to thank Indrawati Schnepp (Atego), Sebastian Panenka (Mixed Mode) and Marc
Richard-Foy (Atego) for their extensive feedback and suggestions.
Contributing To This Specification
The Java™ Specification Request No. 321 Expert Group has chosen an open, transparent and agile working style.
Thus the technical discussion is also open for non-members of the JCP, allowing for further cooperation with and
integration into the Java community.
Reviewers are asked to send their comments and contributions to the specification lead.
The official JSR321 web page is located at http://www.jcp.org/en/jsr/detail?id=321, but it is not freely editable.
Thus, JSR321 also makes use of the free services offered by the java.net web platform at http://jsr321.java.net/. It
offers the possibility to update the community and informs any interested party on the advances of the
specification process.
A Wiki collaboration platform is also available at java.net. The public part can be viewed and edited by every
java.net registered user.
To increase the transparency and trustworthiness, both Reference Implementation and Technology Compatibility
Kit (TCK) will to be released as open source software under the GNU license. Even more so, the open source and
Java™ community are invited to partake in the design as well as in the implementations.
Open Issues
Currently None.
II. Technical Background and Design
The Needs of the TPM
The Trusted Computing Group (TCG) has specified the Trusted Platform Module. Much like a smart card it
features cryptographic primitives, but is physically bound to the platform. A tamper hardened casing contains
low-level functional units for asymmetric key cryptography, key generation, cryptographic hashing and random
number generation. With the help of these components it can protect against (remote) attackers.
The hardware resources of a TPM are manufacturer implementation specific and typically very limited. For
instance, the TPM supplies only a few cryptographic key slots and thus must continually swap keys to and from
external storage during operation. It also provides for additional high-level functionality consisting of protected
non-volatile storage, integrity collection and reporting (attestation), binding of data to a device or a state
(sealing), time stamping and identity management. The state of a system can be evaluated with the help of the
Platform Configuration Registers (PCR), using the extend operation, which builds a chain-of-trust consisting of
concatenated SHA-1 hashes. Version 1.2 TPMs only support the SHA-1 hash function and RSA asymmetric
cryptography in hardware.
For later analysis of the aggregated information, a Stored Measurement Log (SML) must be kept by the system
software. Thus, the current TPM design establishes the need for a singleton system software component that
authoritatively manages the TPM device resources and arbitrates concurrent accesses from multiple clients. In
our experience, this need is a challenge with architectures where direct access to hardware is limited.
TCG Standard Approach for the C Programming Language
This section describes an architecture that implements TPM access and management, the TCG Software Stack
(TSS) [TSS1.2]. It targets C-based systems and applications and does not consider the requirements of virtualized
or managed environments, such as Java™. The Trusted Device Driver Library (TDDL) abstracts the low-level
hardware details into a platform independent interface that takes commands and returns responses as byte
streams.
Generic TPM 1.2 drivers are integrated in recent Operating System (OS) releases. Resource management is
implemented in the Trusted Core Services (TCS), which run as a singleton system service. Additional functionalities
provided by the TCS are persistent storage of keys, TPM command generation and communication mechanisms.
The TCS event manager handles a log which records PCR extend operations. The upper layers of the software
stack may access the TCS in two ways. The first way, intended for development and testing, is a interface that can
be accessed directly. An alternative second option is a platform-independent Simple Object Access Protocol
(SOAP) interface. It defines a network protocol that manages multiple requests, ensuring proper synchronization.
Thus, if the TCS implement SOAP, TPM virtualization at the level of a system service can be provided to
applications [Challener]. Furthermore, in the case of SOAP based communication, client applications do not
require root privileges to access the TPM hardware. The can use the network protocol stack to communicate with
the TCS and TPM.
Applications can access Trusted Computing functionality by using the Trusted Service Provider (TSP) interface. It
provides a TCG standardized Context object as entry point to all other functionalities such as policies and key
handling, data hashing, encryption or PCR composition. In addition, mechanism for command authorization and
validation are provided. Each application dynamically uses a shared library instance of the TSP interface.
The TSS was also designed to allow partial integration in existing high-level APIs libraries, such as PKCS#11 or as
a Cryptographic Service Provider (CSP) in Microsoft CAPI. This enables the use of the cryptographic primitives
provided by the TPM. A limitation of this approach is that these legacy cryptographic APIs do not account for 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.
Unfortunately, functional completeness is not required by implementations. Also, there is no reference
implementation of a TSS. As a result, to the best knowledge of the authors, no currently available
implementation covers the complete specification. Indeed, several sets of highly complex functionalities were
specified, but have not successfully been implemented and tested since the TSS standards were released in 2003
(version 1.1b) and January 2006 (version 1.2).
While recently a compliance test suite for the TPM hardware has been made available to TCG members, there are
no test suites or test vectors supplied for the software TSS.
Limited Choice of Cryptographic Algorithms
Revison 1.2 of the TPM specifications does not require to offer symmetric cryptography. For asymmetric
cryptography, only RSA is offered, but with limited choice of padding schemes. For use in signatures, only the
“SHA1withRSA“ scheme is widely available in JCA/JCE implementations. Also, only one cryptographic hash
function (SHA-1) is supported. Since 2005, this hash algorithm has been found to be, in theory, less robust than to
be expected from a 160-bit cryptographic hash algorithm. In an assessment by IBM and the DoD [Goldman], the
impact on the security of the TPM was studied in detail and should be considered before applying TPM 1.2-based
TC mechanisms.
The set of algorithms hardcoded in the TPM cannot be influenced by a software architecture such as JSR321.
JSR321 API Scope and Limitations
Of course, a clear, comprehensible and compact design is generally preferable. Very much in contrast to the TSS,
in the JCP it is impossible to specify functionality without implementations and tests. As a Java™ integration may
rely on the TSS-based services of the operating system surrounding the Java™ Virtual Machine (JVM), this imposes
natural restrictions to the functional scope of the JSR321 API. We can only use those parts of the TSS spec which
are available and thoroughly tested in existing TSS implementations. Also, Java™ developers create mostly
application software and middleware and do not need specific support to create operating system level software.
The major design decision for JSR321 is to focus on the most important core concepts of Trusted Computing. The
second main goal is to provide a high usability. At the same time, the API is designed to remain modular enough
to be extendable to future developments.
Expected Developer Knowledge
In general, a developer using JSR321 should be familiar with the cryptographic mechanisms provided in the Java™
Security Architecture. For instance, she should be able to encrypt and decrypt data and files, create and process
message digests with hash algorithms and know how to handle key material. She should be familiar with the
algorithms used in the TPM (SHA-1, RSA).
A general understanding of Trusted Computing concepts and the mechanisms of the TPM are required. In
particular this includes




TPM Lifecycle and Ownership
Roots of Trust
Chain of Trust
Integrity Measurement, PCRs, and Reporting (Attestation)










TPM key policies, key types, creation, storage and hierarchy of keys
AIK and AIK certificates
Key Migration (i.e. understand that non-migratable keys cannot be backed up)
Sealing and Binding
Requirements for Trusted Operating Systems
Windows Vista TBS and group policy configurations (on Windows platforms)
Structure of TSS and responsibilities of individual layers, such as TSP, TCS, TDDL, Driver and TPM.
Time stamping
Key certification
Monotonic counter
For interested developers, there is a number of books or other materials available which cover these
requirements, especially [Mueller], [Challener], or [Gallery].
Outline of the API
The package name assigned to the JSR321 API is javax.trustedcomputing. Within this space, a number of
packages has been specified, each representing a well defined set of functionality. These packages are:





javax.trustedcomputing.tpm This package contains all relevant functionality for connecting to a
TPM. A TPM connection is represented by the central TPMContext object that acts as a factory for
other objects specified by the API such as the KeyManager or the Sealer. The TPM interface is also
defined in this package, which provides general TPM related information such as its version and
manufacturer. Additionally, it allows PCR registers to be read and extended.
javax.trustedcomputing.tpm.keys Contrary to the TSS specification, JSR321 introduces
specific interfaces for the individual key types supported by the TPM. This includes interfaces for storage,
sealing and binding keys. Compared to having one generic key object, this approach reduces ambiguities
in the API and allows appropriate key usage to be enforced at the interface level.
javax.trustedcomputing.tpm.structures This package holds data structures required for
certain TPM operations. They include the PCREvent structure required for operations on the
measurement log, PCRInfo used as part of platform attestation and ValidationData as returned by
the TPM quote operation.
javax.trustedcomputing.tpm.tools In this package, there are interface definitions for helpers
classes to perform TPM operations such as binding, sealing, signing and remote attestation.
javax.trustedcomputing.tpm.tools.remote offers abstract classes that allow a remote
host without TPM the interaction in Trusted Computing protocols. It provides the functionality to validate
and verify signatures on TC data types.
For error handling, a single TrustedComputingException covers all lower layers. It offers the original
TPM/TSS error codes, but also a human readable text representation, which is a great step forward in terms of
usability. Despite using only a single exception class, implementations of the API should forward as much error
information as possible. For illegal inputs to the JSR321 API, default Java runtime exceptions are used. Finally,
functions offering bit-wise access to status and capability flags are replaced by specific methods that allow access
to application relevant flags.
In JSR321, the KeyManager interface defines methods for creating new TPMKeys. Upon creation, a secret for
key usage and an optional secret for key migration have to be specified. After a key is created, the KeyManager
allows the key, encrypted by its parent, to be stored in non-volatile storage. As required, the KeyManager
allows keys to be reloaded into the TPM, provided that the key chain up to the storage root key has been
established (i.e. each parent key is already loaded into the TPM). Every time a new key is created or loaded from
permanent storage, a usage secret has to be provided. This secret is represented by an instance of a dedicated
class Secret that is attached to the key object upon construction. Secret also encapsulates and handles details
such as string encoding, which are often a source of incompatibility between different TPM-based applications.
Figure 1: Illustration of the relationship between the core components, including
the TPMContext,KeyManager, and Key classes and the Tools.
The extendable tools package implements various core concepts of Trusted Computing. As each tool that accesses
the TPM is already linked to a TPMContext at creation, there are few or no configuration settings required
before using the tool. Each tool provides a small group of methods that offer closed functionality. For example, a
Binder allows the caller to bind data under a BindingKey and a Secret, and returns the encrypted byte
array. Usage complexity is minimal as no further parameters need to be configured and the call to unbind
encrypted data is completely symmetric. In addition to the core set of tools (Signer, Binder, Sealer,
Attestor), implementers of JSR321 may add further sets of functionality. An example is the tool
Initializer which manages TPM ownership. It is only needed, if the Java™ library is implemented on an OS
without tools for doing so.
Feature Selection
JSR321 will provide functionality focused on applications, rather than provide support for the low level BIOS or OS
features of the TPM. This restriction matches the field of use of Java™ and allows reducing the complexity
significantly. Also, JSR321 will not duplicate existing elements of the Java™ Cryptography Architecture, thus
melting in with the existing library framework. The API will revolve around the object and key usage and handling
policies implemented by the TPM. A package of tool methods will enable more of its unique features and also
allow for optional and vendor specific plug-ins.
To derive the functional scope of the API, the commented complete list of TCG-specified TSP functions [Challener]
was considered. As the JSR321 API will not support TPM functionalities targeted for use by the BIOS (for instance
hardware implementation of hashing) or the operating system (for instance take ownership), we filtered the list
of functions, so that only features designed for applications, and middleware remained.
TPM Identity Management depends on remote PrivacyCA services with no currently established, uniform protocol
available. It is therefore a task for the operating system or external tools.
In addition, many of those TSS functions are simply not needed in Java™ APIs:

Management of memory and other resources can and should be hidden from application developers.

Object initialization and destruction are natural features of object-oriented languages.

Cryptographic primitives like hash functions are already well-supported in the Java™ Cryptography
Extension. Also, due to the restricted choice of hardware supported algorithms, it is advisable to use the
more
flexible
JCE
mechanisms
and
possibly
other
algorithms
in
applications.
Note however, that using SHA-1 in the API cannot be avoided in all operations that directly involve the
TPM (e.g., extending PCRs or digital signing of data).
For error handling, a single TrustedComputingException covers all lower layers. It offers the original
TPM/TSS error codes, but also a human readable text representation, which is a great step forward in terms of
usability. Despite using only a single Exception class, implementations of the API should forward as much error
information as possible. For illegal inputs to the JSR321 API, default Java™ runtime exceptions are used.
Finally, functions offering bit-wise access to status and capability flags are replaced by specific methods that allow
access to application relevant flags.
The following table summarizes the features selected.
TSS C-Function Name
Description
Reason for Removal
or Implementation
Visible
in API
Tspi_GetAttribUint32
Find out the value of an
integer attribute of an
object.
Get a non-integer attribute
of an object.
Find out the current
authorization policy
associated with the context.
Close a context.
Access to basic
information on TSS
No
JSR321 Object that will
handle the functionality
TPM
Access to basic
information on TSS
Essential for
processing
commands
Context Sessions are
essential to TPM
Context Sessions are
essential to TPM
Context Sessions are
essential to TPM
Java hides Memory
Management
Essential
No
TPM
Yes
Hidden. Configured using
Secret object
Yes
TPMContext
Yes
TPMContext
Yes
TPMContext
-
-
No
Hidden. Configured using
Secret object
TPM object live in
Contexts
Yes
TPMContext
Java manages
resources
Configuration of
Context
Essential
No
-
No
TPMContext
Yes
TPMContext
Desirable for
security.
Yes
Essential for
processing
commands
Access to basic
information on TPM
Access to basic
information on TPM
Useful feature
No
Secret destruction could
be difficult in actual
implementations (delayed
garbage collection)
Hidden. Configured using
Secret object
Tspi_GetAttribData
Tspi_GetPolicyObject
Tspi_Context_Close
Tspi_Context_Connect
Tspi_Context_Create
Tspi_Context_FreeMem
ory
Tspi_Context_GetDefa
ultPolicy
Tspi_Context_CreateO
bject
Tspi_Context_CloseOb
ject
Tspi_Context_GetCapa
bility
Tspi_Context_GetTPMO
bject
Tspi_Policy_FlushSec
ret
Tspi_Policy_AssignTo
Object
Tspi_TPM_GetCapabili
ty
Tspi_TPM_SetCapabili
ty
Tspi_TPM_GetRandom
Tspi_TPM_StirRandom
Tspi_Key_GetPubKey
Tspi_Hash_Sign
Tspi_Hash_VerifySign
ature
Connect to a context after it
is created.
Create a context.
Free memory allocated by a
Tspi-level function.
Use the default
authorization policy for the
creation of an object.
Create an object, such as a
key object. After creating
the object, the fields in the
object need to be set.
Destroy an object.
Get the current capabilities
of the context.
Get the TPM object
associated with a context.
Remove the authorization
data from memory.
How one assigns a policy to
an object—for example, a
key.
Get the set of capabilities of
the TPM.
Set capabilities of the TPM.
Return a random number of
the specified size.
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.)
Get the public key of a key
pair.
Hashes and signs data with
a given key.
Verifies the signature of
given data.
No
TPM
No
TPM
Yes
TPM
Useful feature
Yes
TPM
Vital Feature
Yes
TPMKey
Useful feature
No
Signer
Useful feature
No
RemoteSigner
Tspi_Hash_SetHashVal
ue
Tspip_CallbackTakeOw
nership
Set a particular hash value if
you don't happen to want to
use SHA-1.
Determine the current value
of a hash object.
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.
Unbind data by decrypting
with a private storage key.
This takes place inside the
TPM.
Decrypt data sealed to a
TPM when PCRs are in a
determined state (and
optional authorization data
is present).
Select a particular set of
PCRs in a PcrComposite
object.
Set what values the PCRs in
a PcrComposite object
should have. This is
preparation for doing a seal.
Returns the current value of
a PCR in a PcrComposite
object.
Used by an application if it
doesn't want to use the
default mechanism for
creating an HMAC for
proving knowledge of
authorization data.
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.
Take ownership of a TPM
using a callback mechanism.
Tspip_CallbackChange
AuthAsym
Use a callback mechanism
to change authorization.
Tspi_Data_SealX
Just like Seal, except that it
can also use locality and
record historical PCR values
for PCRs other than the
ones it is locking to.
Provide more information
(including locality stuff) than
Tspi_TPM_Quote does.
Tspi_Hash_GetHashVal
ue
Tspi_Hash_UpdateHash
Value
Tspi_Data_Unbind
Tspi_Data_Unseal
Tspi_PcrComposite_
SelectPcrIndex
Tspi_PcrComposite_
SetPcrValue
Tspi_PcrComposite_
GetPcrValue
Tspip_CallbackHMACAu
th
Tspip_CallbackXorEnc
Tspi_TPM_Quote2
Standard feature in
JCE
-
-
Standard feature in
JCE
Standard feature in
JCE
-
-
-
-
Useful feature
Yes
Binder
Useful feature
Yes
Sealer
Vital Feature
Yes
PCRInfo
Vital Feature
Yes
PCRInfo
Vital Feature
Yes
PCRInfo
C-style callback
functions are not
needed in Java
-
-
C-style callback
functions are not
needed in Java
-
-
C-style callback
functions are not
needed in Java
C-style callback
functions are not
needed in Java
Nice to have
-
-
-
-
No
-
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.
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.
Read the value of the
current counter.
Vital Feature
No
PCRInfo
Hidden
implementation
detail
No
PCRInfo
Nice to have,
monotonic counters
are not supported in
current OSes
Useful, but TCG
specifications are
ambiguous
Useful, but TCG
specifications are
ambiguous
NV RAM Access is not
needed for
applications
No
-
No
-
No
-
-
-
NV RAM Access is not
needed for
applications
NV RAM Access is not
needed for
applications
NV RAM Access is not
needed for
applications
NV RAM Access is not
needed for
applications
TPM
Implementations do
not support Audits
TPM
Implementations do
not support Audits
C-style callback
functions are not
needed in Java
-
-
-
-
-
-
-
-
-
-
-
-
No
Sealer
Optional
functionality for AIK
Cycle
No
-
Tspi_PcrComposite_
SelectPcrIndexEx
Tspi_TPM_ReadCurrent
Counter
Tspi_TPM_ReadCurrent
Ticks
Tspi_Hash_TickStampB
lob
Tspi_NV_DefineSpace
Tspi_NV_ReleaseSpace
Tspi_NV_WriteValue
Read the current tick value
(which corresponds loosely
to time) of the TPM.
Sign data together with the
current tick value and tick
nonce. Uses an AIK.
Create a section of NVRAM
and associates it with
specific authorization (such
as authorization data, PCR
values, locality, or once per
power on).
Put NVRAM space
previously allocated back
into the pool.
Write a value to the NVRAM
space previously allocated.
Tspi_NV_ReadValue
Read a value from NVRAM
space previously allocated.
Tspi_TPM_DAA_Sign
Use a DAA credential to
verify either a message or
an AIK.
Get the current audit digest
of the TPM.
Tspi_TPM_GetAuditDig
est
Tspi_TPM_SetOrdinal
AuditStatus
Set an ordinal to be audited.
Tspicb_CallbackSealx
Mask
Used when masking or
unmasking data sent or
returned with Data_SealX or
Tspi_Data_Unseal
operations.
Because it isn't clear what
encryption algorithms will
be required by a certificate
authority, this command
can be used to encrypt the
Tspicb_CollateIdenti
ty
collated information with
any encryption algorithm.
Tspicb_ActivateIdent
ity
Tspicb_DAA_Sign
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.
Extend properties of the
DAA protocol.
Tspicb_DAA_VerifySig
nature
Extend the usefulness of the
DAA protocol.
Tspi_Key_LoadKey
Load a particular key into
the TPM.
Create a new object with a
different authorization.
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.
Load an encrypted key blob
into the TPM, used when
you have the key blob file.
Load a key into the TPM
when you know its UUID.
Remove a key from a user or
system key store.
Remove a key from the TPM
referenced by UUID.
Search for a key by its UUID,
and returns a handle to it.
Tspi_ChangeAuth
Tspi_ChangeAuthAsym
Tspi_Context_LoadKey
Blob
Tspi_Context_LoadKey
ByUUID
Tspi_Context_Unregis
terKey
Tspi_Context_DeleteK
ey ByUUID
Tspi_Context_GetKeyB
yUUID
Tspi_Context_GetKey
ByPublicInfo
Tspi_Context_Get
Registered Keys
ByUUID
Tspi_TPM_GetStatus
Tspi_TPM_Quote
Tspi_Key_ConvertMigr
ationBlob
Tspi_TPM_CertifySelf
Test
Search for a key by its public
data and returns a handle to
it.
Return a list of all the
registered keys in a registry,
along with their UUIDs.
Find out how bits in the
TPM are set.
Uses an ID to sign the PCRs
currently in the TPM. A
nonce is used to guarantee
freshness.
Import a migration blob
from a migratable key.
Tells the TPM to use an AIK
to certify the self-test
results.
Optional
functionality for AIK
Cycle
No
-
No DAA reference
implementations
available
No DAA reference
implementations
available
Vital Feature
-
-
-
-
No
TPMKey
Vital Feature
Yes
TPMKey
Implementation
Detail
No
-
Implementation
Detail
No
KeyManager
Vital Key
Management Feature
Vital Key
Management Feature
Vital Key
Management Feature
Vital Key
Management Feature
Yes
KeyManager
Yes
KeyManager
Yes
KeyManager
Yes
KeyManager
Vital Key
Management Feature
Yes
KeyManager
Vital Key
Management Feature
Yes
KeyManager
Basic TPM feature
Yes
TPM
Vital Feature
Yes
Attestor
Migration is optional
No
-
Not useful for
applications
No
-
Tspi_TPM_GetTestResu
lt
Tspi_SetAttribUint32
Tspi_SetAttribData
Tspi_Policy_SetSecre
t
Tspi_TPM_PcrExtend
Tspi_Data_Bind
Tspi_Data_Seal
Tspi_Context_Registe
rKey
Tspi_TPM_GetPub
EndorsementKey
Tspi_TPM_Collate
IdentityRequest
Get the self test result,
unsigned.
Set an integer attribute of
an object.
Set a non-integer attribute
of an object.
How one associates
authorization data with a
policy, to be used, for
example, in creating or
using a key.
Extend a particular PCR.
Not useful for
applications
Implementation
Detail
Implementation
Detail
Key Feature
No
-
No
-
No
-
No
Hidden using Secret
Vital Feature
Yes
TPM
Bind data to a TPM by
encrypting it with a public
storage key. This takes place
outside the TPM.
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.
Register a key into either a
user's key store or a
system's key store and
returns the UUID.
Return the public portion of
the endorsement key.
Vital feature
Yes
RemoteBinder
Useful feature
Yes
Sealer
Vital Key
Management Feature
Yes
KeyManager
Optional
functionality for AIK
Cycle
Optional
functionality for AIK
Cycle
No
-
No
-
Optional
functionality for AIK
Cycle
No
-
Not useful for
applications
Not useful for
applications
Useful Feature
-
-
-
-
Yes
TPM
Useful Feature
Yes
TPMKey
Vital Key
Management Feature
Vital Key
Management Feature
Migration is optional
Yes
KeyManager
Yes
KeyManger
Yes
-
Vital Key
Management Feature
Yes
TPMKey
Tspi_TPM_SetStatus
Gather all the information a
certificate authority will
need in order to provide a
certificate for an AIK.
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.
Set bits in the TPM.
Tspi_TPM_SelfTestFul
l
Tspi_TPM_PcrRead
Tells the TPM to execute a
full self test.
Read a particular PCR.
Tspi_Key_CertifyKey
Create a certificate of a nonmigratable key by signing it
and its characteristics with
an AIK (ID).
Create a new RSA key.
Tspi_TPM_ActivateIde
ntity
Tspi_Key_CreateKey
Tspi_Key_WrapKey
Tspi_Key_CreateMigra
tionBlob
Tspi_Key_UnloadKey
Wrap an already extant RSA
private key.
Create a migration blob
from a migratable key.
Remove a key in the TPM.
III. Normative Part
Definitions
This document uses definitions based upon those specified in RFC 2119.
Term
MUST
MUST NOT
SHOULD
SHOULD
NOT
MAY
Definition
The associated definition is an absolute requirement of this specification.
The definition is an absolute prohibition of this specification.
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.
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.
Indicates that an item is truly optional.
Requirements









Implementations aiming to be JSR321 compliant MUST be designed to use a TPM that conforms to
Trusted Computing Group’s TPM specification version 1.2 or higher. Final implementations of the JSR321
API MUST NOT emulate TPM functionality in software but use TPM functionality made available by the
underlying operating system. While by default this functionality is provided by a hardware TPM, in the
context of e.g. virtualized environments that MAY be a virtualized, TCG-specification compliant TPM
providing equivalent security characteristics as a hardware TPM.
JSR321 implementations SHOULD integrate with TPM management software of the Operating System. An
implementation MAY also choose to directly access the TPM.
Implementations of this technology MAY support J2SE 1.2 or later but MUST at a minimum support
version 1.5 or later of J2SE.
Any JSR321 implementation SHOULD allow safe multiple concurrent accesses to the TPM by different
Java™ and non-Java™ applications.
Java™ applications using JSR321 MUST NOT require “root” or “Administrator” privileges to access the
TPM.
JSR321 is NOT a specification for a TCG Software Stack (TSS). It does not specify aspects like managing the
hardware resources of the TPM. As a high-level interface, implementations of JSR321 MAY be based on a
TSS.
JSR321 does NOT cover operating system related functionalities of the TPM. However, implementations
can OPTIONALLY provide those.
JSR321 implementations MUST consider and document thread-safety.
Implementations MAY add optional functionality as new classes or methods to the API, especially the
tools package. This additional functionality SHOULD NOT duplicate existing API functionality.
Detailed API Specifications
IV. License
INSTITUTE FOR APPLIED INFORMATION PROCESSING AND COMMUNICATIONS
(IAIK) IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE
AGREEMENT ("AGREEMENT").
PLEASE READ THE TERMS AND CONDITIONS OF
THIS AGREEMENT CAREFULLY.
Specification: JSR-000321
("Specification")
Trusted
Computing
API
for
Java(tm)
Version: 11.04
Status: Proposed Final Draft
Release: 25 March 2011
Copyright 2010 Institute
Communications (IAIK)
for
Applied
Information
Processing
and
Graz University of Technology
Inffeldgasse 16a
A-8010 Graz
Austria
All rights reserved.
NOTICE
The Specification is protected by copyright and the information
described therein may be protected by one or more U.S. patents,
foreign patents, or pending applications. Except as provided under
the following license, no part of the Specification may be
reproduced in any form by any means without the prior written
authorization of IAIK and its licensors, if any.
Any use of the
Specification and the information described therein will be governed
by the terms and conditions of this Agreement.
Subject to the terms and conditions of this license, including your
compliance with Paragraphs 1 and 2 below, IAIK hereby grants you a
fully-paid,
non-exclusive,
non-transferable,
limited
license
(without the right to sublicense) under IAIK's intellectual property
rights to:
1.Review the Specification for the purposes of evaluation.
This
includes:
(i) developing implementations of the Specification for
your internal, non-commercial use; (ii) discussing the Specification
with any third party; and (iii) excerpting brief portions of the
Specification in oral or written communications which discuss the
Specification provided that such excerpts do not in the aggregate
constitute a significant portion of the Specification.
2.Distribute implementations of the Specification to third parties
for their testing and evaluation use, provided that any such
implementation:
(i) does not modify, subset, superset or otherwise extend the
Licensor Name Space, or include any public or protected packages,
classes, Java interfaces, fields or methods within the Licensor Name
Space other than those required/authorized by the Specification or
Specifications being implemented;
(ii) is clearly and prominently marked with the word "UNTESTED" or
"EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list
of available builds and in proximity to every link initiating its
download, where the list or link is under Licensee's control; and
(iii) includes the following notice:
"This is an implementation of an early-draft specification developed
under the Java Community Process (JCP). The code is not compatible
with any specification of the JCP."
The grant set forth above concerning your distribution of
implementations of the Specification is contingent upon your
agreement to terminate development and distribution of your
implementation of early draft upon final completion of the
Specification. If you fail to do so, the foregoing grant shall be
considered null and void.
No provision of this Agreement shall be understood to restrict your
ability to make and distribute to third parties applications written
to the Specification.
Other than this limited license, you acquire no right, title or
interest in or to the Specification or any other IAIK intellectual
property, and the Specification may only be used in accordance with
the license terms set forth herein. This license will expire on the
earlier of:
(a) two (2) years from the date of Release listed
above; (b) the date on which the final version of the Specification
is publicly released; or (c) the date on which the Java
Specification Request (JSR) to which the Specification corresponds
is withdrawn. In addition, this license will terminate immediately
without notice from IAIK if you fail to comply with any provision of
this license.
Upon termination, you must cease use of or destroy
the Specification.
"Licensor Name Space" means the public class or interface
declarations whose names begin with "java", "javax", "com.iaik" or
their equivalents in any subsequent naming convention adopted
through the Java Community Process, or any recognized successors or
replacements thereof
TRADEMARKS
No right, title, or interest in or to any trademarks, service marks,
or trade names of IAIK or IAIK's licensors is granted hereunder.
Java and Java-related logos, marks and names are trademarks or
registered trademarks of Sun Microsystems, Inc. in the U.S. and
other countries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY
CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE
CORRECTED BY IAIK.
IAIK MAKES NO REPRESENTATIONS OR WARRANTIES,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR
ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS
WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS
OR OTHER RIGHTS. This document does not represent any commitment to
release or implement any portion of the Specification in any
product.
THE
SPECIFICATION
COULD
INCLUDE
TECHNICAL
INACCURACIES
OR
TYPOGRAPHICAL ERRORS.
CHANGES ARE PERIODICALLY ADDED TO THE
INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW
VERSIONS OF THE SPECIFICATION, IF ANY.
IAIK MAY MAKE IMPROVEMENTS
AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THE SPECIFICATION AT ANY TIME.
Any use of such changes in the
Specification will be governed by the then-current license for the
applicable version of the Specification.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL IAIK OR ITS
LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION,
LOST
REVENUE,
PROFITS
OR
DATA,
OR
FOR
SPECIAL,
INDIRECT,
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO
ANY
FURNISHING,
PRACTICING,
MODIFYING
OR
ANY
USE
OF
THE
SPECIFICATION, EVEN IF IAIK AND/OR ITS LICENSORS HAVE BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
You will hold IAIK (and its licensors) harmless from any claims
based on your use of the Specification for any purposes other than
the limited right of evaluation as described above, and from any
claims that later versions or releases of any Specification
furnished to you are incompatible with the Specification provided to
you under this license.
RESTRICTED RIGHTS LEGEND
If this Software is being acquired by or on behalf of the U.S.
Government or by a U.S. Government prime contractor or subcontractor
(at any tier), then the Government's rights in the Software and
accompanying documentation shall be only as set forth in this
license; this is in
accordance
with
48
C.F.R.
227.7201
through
227.7202-4
(for
Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101
and 12.212 (for non-DoD acquisitions).
REPORT
You may wish to report any ambiguities, inconsistencies or
inaccuracies you may find in connection with your evaluation of the
Specification ("Feedback").
To the extent that you provide IAIK
with any Feedback, you hereby: (i) agree that such Feedback is
provided on a non-proprietary and non-confidential basis, and (ii)
grant IAIK a perpetual, non-exclusive, worldwide, fully paid-up,
irrevocable license, with the right to sublicense through multiple
levels of sublicensees, to incorporate, disclose, and use without
limitation the Feedback for any purpose related to the Specification
and future versions, implementations, and test suites thereof.
GENERAL TERMS
Any action related to this Agreement will be governed by California
law and controlling U.S. federal law. The U.N. Convention for the
International Sale of Goods and the choice of law rules of any
jurisdiction will not apply.
The Specification is subject to U.S. export control laws and may be
subject to export or import regulations in other countries. Licensee
agrees to comply strictly with all such laws and regulations and
acknowledges that it has the responsibility to obtain such licenses
to export, re-export or import as may be required after delivery to
Licensee.
This Agreement is the parties' entire agreement relating to its
subject matter. It supersedes all prior or contemporaneous oral or
written communications, proposals, conditions, representations and
warranties and prevails over any conflicting or additional terms of
any quote, order, acknowledgment, or other communication between the
parties relating to its subject matter during the term of this
Agreement. No modification to this Agreement will be binding, unless
in writing and signed by an authorized representative of each party.
Rev. January 2006
V. References and Relevant Literature
[Berger]
S. Berger, R. Cáceres, K. Goldman, R. Perez, R. Sailer, L. van Doorn. vTPM: Virtualizing the
Trusted Platform Module. IBM Research Report, RC23879 (W0602-126), 2006.
[Challener]
D. Challener, K. Yoder, R. Catherman, D. Safford, L. van Doorn, A Practical Guide to Trusted
Computing, ISBN-13: 978-0-13-239842-8, IBM Press, 2008
[Kinney]
S. Kinney. Trusted Platform Module Basics: Using TPM in Embedded Systems. Elsevier,
Burlington, MA, USA, ISBN 13: 978-0-7506-7960-2, 2006.
[Mueller]
T. Müller, Trusted Computing Systeme: Konzepte und Anforderungen, Springer, 2008 (in
German).
[Gallery]
Eimear Gallery, Chris Mitchell. Trusted Computing Teaching Material, Royal Holloway
University of London, http://www.isg.rhul.ac.uk/msc/teaching/iy5608, 2009.
[Goldman]
Ken Goldman, Stan Potter, SHA-1 Uses in TPM v1.2, White Paper, TCG April 2, 2010,
https://www.trustedcomputinggroup.org/
[Sarmenta]
L. Sarmenta, J. Rhodes, and T. Müller. TPM/J Java-based API for the Trusted Platform
Module , http://projects.csail.mit.edu/tc/tpmj/ , 2007.
[Selhorst]
M. Selhorst, C. Stueble & F. Teerkorn TSS Study, Sirrix AG security technologies,
http://www.sirrix.com/content/pages/50590.htm, 2008
[STC]
R. Toegl, T. Winkler, M. Nauman, T. Hong - Towards Platform-Independent Trusted
Computing – ACM Workshop on Scalable Trusted Computing (STC) 2009 Proceedings; in CCS
2009 Co-Located Workshops' Compilation Proceedings, ACM, 2009
[TBS]
Microsoft Developer Network. TPM Base Services,
http://msdn2.microsoft.com/en-us/library/aa446796.aspx, 2007.
[TCGA]
Trusted Computing Group. TCG Specification Architecture Overview, Revision 1.4, 2007.
https://www.trustedcomputinggroup.org/
[Toegl]
R.Toegl, M. Pirker. An ongoing Game of Tetris: Integrating Trusted Computing in Java, blockby-block. In: Proceedings of Future of Trust in Computing Conference, Berlin,
Vieweg+Teubner, 2008.
[TrouSerS]
TrouSerS - An Open-Source TCG Software Stack Implementation.
http://trousers.sourceforge.net/, 2007.
[trustedJava]
M. Pirker, R. Toegl T. Winkler. Trusted Computing for the Java Platform,
http://trustedjava.sourceforge.net/, 2007-11.
[TPM1.2]
Trusted Computing Group. TCG Trusted Platform Module (TPM) Specifications, Version 1.2
Rev. 116, March 1, 2011. https://www.trustedcomputinggroup.org/
[TSS1.2]
Trusted Computing Group. TCG Software Stack (TSS) Specification, Version 1.2, Errata A,
March 7, 2007. https://www.trustedcomputinggroup.org/