trusted computing 11 10 final eval spec
TRANSCRIPT
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
1/99
JSR321
Trusted Computing API for Java
Java Community Process Specification
Final Release
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
2/99
2
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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
3/99
3
Table of ContentsI. Preface ......................................................................................................................................................... 4
1. Revision History ........................................................................................................................................... 4
2. Who Should Use This Specification ............................................................................................................. 4
3. Outline ......................................................................................................................................................... 44. 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
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
4/99
4
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, 2010Updated Nov. 19
November 26, 2010
January 3, 2011
Public Review Release
11.04 March 25, 2011 April 8, 2011 Proposed Final Draft
11.10 October 11, 2011
upd. October 31, 2011
Submission to Final
Approval Ballot
Who Should Use This SpecificationThis 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
5/99
5
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.
TheNormative 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 theLicense chapter.
References and Relevant Literature conclude this document.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
6/99
6
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 limitedsoftware 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
7/99
7
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 athttp://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 athttp://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 softwareunder 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.
http://www.jcp.org/en/jsr/detail?id=321http://www.jcp.org/en/jsr/detail?id=321http://www.jcp.org/en/jsr/detail?id=321http://jsr321.java.net/http://jsr321.java.net/http://jsr321.java.net/http://jsr321.java.net/http://www.jcp.org/en/jsr/detail?id=321 -
8/10/2019 Trusted Computing 11 10 Final Eval Spec
8/99
8
Open Issues
Currently None.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
9/99
9
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
abst r act publ i c Obj ect get Pr oper t y( St r i ng pr oper t y)
throws TrustedComputingException, IllegalArgumentException;
Attestor and Remote Attestor
publ i c abst r act bool ean val i dat eQuot e( Val i dat i onDat a dat aToVal i dat e,
RSAPubl i cKey i dent i t yKey, Di gest nonce, PCRI nf o expect edVal ues)
throws GeneralSecurityException, TrustedComputingException;
Signer and RemoteSigner
publ i c abst r act bool ean val i dat e( byte[ ] si gnat ur e, byt e[ ] dat a, RSAPubl i cKeykey)
t hr ows Trust edComput i ngExcept i on;
throws GeneralSecurityException;
Certifier and RemoteCertifier
publ i c abst r act bool ean val i dat e( Val i dat i onDat a dat aToVal i dat e,
RSAPubl i cKey cer t i f i edKey, RSAPubl i cKey cer t i f yi ngKey, Di gest nonce)
throws GeneralSecurityException;
TPMContext
publ i c abst r act Secr et get Secr et ( char [ ] passwor d, bool ean addNul l Ter mi nat i on,Charset encodi ng)
throws CharacterCodingException;
public abstract RemoteAttestor getRemoteAttestor();
public abstract RemoteBinder getRemoteBinder();
public abstract RemoteCertifier getRemoteCertifier();
public abstract RemoteSigner getRemoteSigner();
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
10/99
10
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 theTrusted 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
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
11/99
11
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 APIslibraries, such as PKCS#11 or as
a Cryptographic Service Provider (CSP) in Microsoft CAPI. This enables the use of the cryptographic primitives
provided by the TPM. A limitation of this approach is that these legacy cryptographic APIs do not account for high-
level TC concepts such as Sealing.
JSR321 API Design Considerations
Design Goals
The EG has decided on a number of design goals for the JSR321 API.
Integration with Existing Trusted Computing Platforms. To the OS, the Java Virtual Machine appears justas an ordinary application. Therefore, the TPM access mechanisms need to integrate with the surrounding
environment, be it virtualized or not, and management services.
Simplified Interface. To make the new API fit into the Java ecosystem, a completely new and fully object-
oriented interface is to be designed. For instance, generic objects (e.g., keys) in the TSS should be
replaced with instances of specific classes that represent the different types. This allows the set of offered
operations to be limited to those actually applicable for a certain object type, thus furthering usability.
Reduced Overhead. The TSS API requires a substantial amount of boilerplate code for routine tasks, such
as key creation, data encryption or password management. The proposed API should attempt to replace
these lengthy code fragments with simple calls using sensible default parameters where required.
Conceptual Consistency. Names in the API should be consistent not only within the API but also with the
nomenclature used by the TCG and in Trusted Computing literature. This will allow users to easily switch
from other environments to the proposed API. Still, naming conventions of Java must be adhered to.
Testable and Implementable Specifications. The API design should target a small core set of functionality,
based on the essential use cases of Trusted Computing. This restriction in size will allow for complete
implementations and functional testing thereof.
Extendability. The API should allow implementers and vendors to add functionality which is optional or
dependent on the capabilities of the surrounding platform.
Limitation from the TCG Architecture
Required by the very nature of Java, the JSR321 approach builds on and extends the TSS services offered by the
operating system environment. However, while TSS and JSR321 are strongly relatedin the technical sense, there
are significant differences, which stem from the requirements of the design processes and the targeted
developer audience. This leads to different functional scopes.
In the process that had been employed to conceive the original TSS specification of the TCG, a working group
devised a set of APIs to form an industry specification, covering no less than 757 pages. It not only covers a user-
oriented API (the TSPI), but also architectural and internal details clearly intended for developers who plan to
build a complete TSS. On the other hand, the actual functionalities are not elaborated in detail; especially the
relationship of different commands on the different layers (TSP, TCS, TDDL, and TPM) is not specified.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
12/99
12
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 testedsince 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
SHA1wi t hRSA 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], theimpact 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 specifyfunctionality 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 naturalrestrictions 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)
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
13/99
13
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 isj avax. t r ust edcomput i ng. Within this space, a number of
packages has been specified, each representing a well defined set of functionality. These packages are:
j avax. t r ust edcomput i ng. t pmThis package contains all relevant functionality for connecting to a
TPM. A TPM connection is represented by the centralTPMContext object that acts as a factory for
other objects specified by the API such as the KeyManager or the Seal er . TheTPMinterface is also
defined in this package, which provides general TPM related information such as its version andmanufacturer. Additionally, it allows PCR registers to be read and extended.
j avax. t r ust edcomput i ng. t pm. 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.
j avax. t r ust edcomput i ng. t pm. st r uct ures This package holds data structures required for
certain TPM operations. They include the PCREvent structure required for operations on the
measurement log, PCRI nf oused as part of platform attestation and Val i dat i onDat aas returned by
the TPM quote operation.
j avax. t r ust edcomput i ng. t pm. t ool s In this package, there are interface definitions for helpers
classes to perform TPM operations such as binding, sealing, signing and remote attestation.
j avax. t r ust edcomput i ng. t pm. t ool s. r emot e 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 Tr ust edComput i ngExcept i on 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
14/99
14
In JSR321, the KeyManager interface defines methods for creating newTPMKeys. 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
Bi nder allows the caller to bind data under a Bi ndi ngKeyand a Secr et , 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 (Si gner , Bi nder , Seal er ,
Attestor ), implementers of JSR321 may add further sets of functionality. An example is the tool
I ni t i al i zer which manages TPM ownership. It is only needed, if the Java library is implemented on an OS
without tools for doing so.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
15/99
15
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 Tr ust edComput i ngExcept i on 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
16/99
16
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 Secr et object
Tspi_Context_Close Close a context. Context Sessions are
essential to TPM
Yes TPMContext
Tspi_Context_Connect Connect to a context after itis created.
Context Sessions areessential 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 Secr et 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 Secret destruction could
be difficult in actual
implementations
(delayed garbage
collection)
Tspi_Policy_AssignTo
Object
How one assigns a policy to
an objectfor example, a
key.
Essential for
processing
commands
No Hidden. Configured
using Secr et object
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
17/99
17
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 Si gner
Tspi_Hash_VerifySign
ature
Verifies the signature of
given data.
Useful feature No Remot eSi gner
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 Bi nder
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 Seal er
Tspi_PcrComposite_
SelectPcrIndex
Select a particular set of
PCRs in a PcrComposite
object.
Vital Feature Yes PCRI nf o
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
18/99
18
Tspi_PcrComposite_
SetPcrValue
Set what values the PCRs in
a PcrComposite object
should have. This is
preparation for doing a seal.
Vital Feature Yes PCRI nf o
Tspi_PcrComposite_
GetPcrValue
Returns the current value of
a PCR in a PcrCompositeobject.
Vital Feature Yes PCRI nf o
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 At t est or
Tspi_PcrComposite_
SetPcrLocality
Set the locality settings for a
PcrComposite structure.
Nice to have No PCRI nf o
Tspi_PcrComposite_
GetPcrLocality
Return the locality settings
of a PcrComposite structure.
Nice to have No PCRI nf o
Tspi_PcrComposite_
GetCompositeHash
Return the Composite hash
of the PcrComposite
structure.
Vital Feature No PCRI nf o
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
19/99
19
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 PCRI nf o
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 toverify either a message or
an AIK.
NV RAM Access is notneeded 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
- -
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
20/99
20
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 Seal er
Tspicb_CollateIdenti
ty Because it isn't clear whatencryption algorithms will
be required by a certificate
authority, this command
can be used to encrypt the
collated information with
any encryption algorithm.
Optionalfunctionality for AIK
Cycle
No-
Tspicb_ActivateIdent
ity
Similarly, when a certificate
is encrypted by the
certificate authority, the
decryption will be doneentirely 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
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
21/99
21
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 At t est or
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_SetSecret
How one associatesauthorization data with a
policy, to be used, for
example, in creating or
using a key.
Key Feature No Hidden using Secr et
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 Remot eBi nder
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
22/99
22
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 Seal er
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 non-
migratable key by signing it
and its characteristics withan 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
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
23/99
23
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 Groups 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
24/99
24
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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
25/99
25
Detailed API Specifications
JSR321API10/11/11 12:15 PM
Package Summary Page
javax.trustedcomputingThis 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.keysThis package allows the creation, storage, loading and unloading of
hierarchies of TPM keys.45
javax.trustedcomputing.tpm.structuresThis 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.remoteThis 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 thej avax. t r ust edcomput i ngpackage. 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.
https://jsr321.java.net/https://jsr321.java.net/https://jsr321.java.net/ -
8/10/2019 Trusted Computing 11 10 Final Eval Spec
26/99
26
Class TrustedComputingExceptionjavax.trustedcomputing
j ava. l ang. Obj ect
j ava. l ang. Throwabl e
j ava. l ang. Except i on
javax.trustedcomputing.TrustedComputingException
Al l Implemented Interfaces:
Serializable
abst r act publ i c cl ass TrustedComputingException
ext ends Except i on
The default Exception used in the j avax. t r ust edcomputi ngpackage. It covers all unexpected behaviors on all levels of
the trusted platform. This includes also the errors raised in lower layers of the TCG architecture such as error codes returned
from the TPM, and the TSS and its sub-layers.
Field Summary Page
s tat i c
l ong
HIGH_LEVEL_API_LAYER_ERROR
Numeric Error code returned when theTr ust edComput i ngExcept i on was raised at JSR 321
level.
27
Constructor Summary Page
TrustedComputingException( ) 27
Method Summary Page
abstract
Throwabl egetCause( )
Returns the originally thrown Exception.27
abstract
l onggetLowLevelErrorCode( )
Returns the detailed C-styled error code that is generated by lower-level software components that
connect to the TPM.
27
abstract
Str i nggetMessage( )
Returns a detailed text description of the error cause.
27
abstract
Str i ng
getShortMessage( )
Returns a short, one-line text description of the error cause.
28
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
27/99
27
Field Detail
HIGH_LEVEL_API_LAYER_ERROR
publ i c stat i c f i nal l ong HIGH_LEVEL_API_LAYER_ERROR
Numeric Error code returned when theTr ust edComput i ngExcept i on was raised at JSR 321 level. The value is0x00004000.
Constructor Detail
TrustedComputingException
publ i c TrustedComputingException( )
Method Detail
getCause
publ i c abst r act Thr owabl e getCause( )
Returns the originally thrown Exception. The returned type is implementation specific and may be nul l .
Overrides:
get Causein classThrowabl e
getLowLevelErrorCode
publ i c abst r act l ong 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 generalHI GH_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
publ i c abst r act St r i ng getMessage( )
Returns a detailed text description of the error cause. If available, this includes indication of TCG error codes and
layer information.
Overrides:
getMessagein classThrowabl e
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
28/99
28
getShortMessage
publ i c abst r act St r i ng 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 SummaryPage
TPM This represents the hardware TPM and the basic functionalities it offers. 29
Class Summary Page
TPMContext The Context class is the centerpiece of the JSR321 API. 35
Exception Summary Page
PCRsNotAccessibleException This Exception is thrown if an operation that access the PCRs is blocked by theoperating system.
29
Package javax.trustedcomputing.tpm Description
This package allows to connect to a Trusted Platform Module (TPM). TheTPMCont ext 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
29/99
29
Class PCRsNotAccessibleExceptionjavax.trustedcomputing.tpm
j ava. l ang. Obj ect
j ava. l ang. Throwabl e
j ava. l ang. Except i on
j ava. l ang. Runt i meExcept i on
javax.trustedcomputing.tpm.PCRsNotAccessibleException
Al l Implemented Interfaces:
Serializable
publ i c cl ass PCRsNotAccessibleException
extends Runt i meExcept i on
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
PCRsNotAccessibleException(St r i ng st r i ng) 29
Constructor Detail
PCRsNotAccessibleException
publ i c PCRsNotAccessibleException(St r i ng st r i ng)
Interface TPMjavax.trustedcomputing.tpm
publ i c i nt er f ace 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 byTPMCont ext .
Field Summary Page
Str i ng PROPERTY_JSR_REVISION
Property key to query the JSR321 specification revision.31
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
30/99
30
Str i ng PROPERTY_JSR_VERSION
Property key to query the JSR321 implementation version.31
Str i ng PROPERTY_TPM_FIRMWARE_VERSION
Property key to query the TPM firmware version.31
Str i ng PROPERTY_TPM_MANUFACTURER
Property key to query the TPM manufacturer.31
Str i ng PROPERTY_TPM_VERSION
Property key to query the TPM specification version.31
Str i ng PROPERTY_TSS_VENDOR
Property key to query the vendor of the underlying TSS.31
Str i ng PROPERTY_TSS_VERSION
Property key to query the version of the underlying TSS.31
Method Summary Page
voi d extendPCR( i nt PCRi ndex, Di gest dat a)
Performs the Extend operation with the given data on the selected PCR.33
voi d extendPCR( i nt PCRi ndex, PCREvent event )
Performs the Extend operation with the given event on the selected PCR.
34
i nt getNumberPCR( )
Provides the number of PCR registers provided by this TPM.33
Obj ect getProperty( St r i ng pr oper t y)
Allows to query properties and information on the Trusted Computing mechanisms of this platform.35
byte[] getRandom( i nt l engt h)
Returns an array of random numbers, generated by the cryptographic true random number
generator of the TPM.
32
bool ean isActivated( )
Determines the status of the TPM operation mode (Activated/Deactivate).
32
bool ean isEnabled( )
Determines the status of the TPM operation mode (Enables/Disabled).
32
bool ean isOwned( )
Determines the status of the TPM operation mode (Owned or no ownership taken).33
PCRI nfo readPCR( i nt [ ] PCRi ndi ces)
Reads the current values of a set of PCR registers from the TPM.
34
voi d stirRandom( byte[ ] ent r opy)
Allows to add entropy to the hardware Random Number Generator of the TPM.34
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
31/99
31
Field Detail
PROPERTY_TPM_MANUFACTURER
publ i c stat i c f i nal St r i ng PROPERTY_TPM_MANUFACTURER
Property key to query the TPM manufacturer. Returned type is Str i ng. The TPM vendor ID string will have amaximum string length of four characters and it will not have a terminating zero.
PROPERTY_TPM_VERSION
publ i c stat i c f i nal St r i ng PROPERTY_TPM_VERSION
Property key to query the TPM specification version. Returned type is Str i ng. For example, a version 1.2 TPM this
will return "1.2".
PROPERTY_TPM_FIRMWARE_VERSION
publ i c stat i c f i nal St r i ng PROPERTY_TPM_FIRMWARE_VERSION
Property key to query the TPM firmware version. Returned type is Str i ng.
PROPERTY_TSS_VENDOR
publ i c stat i c f i nal St r i ng PROPERTY_TSS_VENDOR
Property key to query the vendor of the underlying TSS. Returned type is Str i ng.
PROPERTY_TSS_VERSION
publ i c stat i c f i nal St r i ng PROPERTY_TSS_VERSION
Property key to query the version of the underlying TSS. Returned type is Str i ng.
PROPERTY_JSR_REVISION
publ i c stat i c f i nal St r i ng PROPERTY_JSR_REVISION
Property key to query the JSR321 specification revision. Returned type is Str i ng.
PROPERTY_JSR_VERSION
publ i c stat i c f i nal St r i ng PROPERTY_JSR_VERSION
Property key to query the JSR321 implementation version. Returned type is Str i ng.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
32/99
32
Method Detail
getRandom
byte[] getRandom( i nt l engt h)
t hrows Tr ust edComput i ngExcept i on
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:
l engt h- 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:
Tr ust edComput i ngExcept i on
isActivated
bool ean isActivated( )
t hrows Tr ust edComput i ngExcept i on
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 temporarilyuntil the next system restart.
Returns:
t rueif the TPM is activated.
Throws:
Tr ust edComput i ngExcept i on
isEnabled
bool ean isEnabled( )
t hrows Tr ust edComput i ngExcept i on
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:
t rueif the TPM is enabled.
Throws:
Tr ust edComput i ngExcept i on
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
33/99
33
isOwned
bool ean isOwned( )
t hrowsTr ust edComput i ngExcept i on
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:
t rueif the TPM is enabled.
Throws:
Tr ust edComput i ngExcept i on
getNumberPCR
i nt getNumberPCR( )
t hrows Tr ust edComput i ngExcept i on
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:
Tr ust edComput i ngExcept i on
extendPCR
voi d extendPCR( i nt PCRi ndex,
Di gest dat a)
t hrows Tr ust edComput i ngExcept i on,
PCRsNotAccessi bl eExcepti on
Performs the Extend operation with the given data on the selected PCR. On Windows systems, any PCR access is by
default blocked.
Parameters:
PCRi ndex- The PCR to be changed
data- This will be passed to the TPM unchanged.
Throws:
Tr ust edComput i ngExcept i on
PCRsNotAccessi bl eExcept i on- If access to PCRs is blocked by the Operating System
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
34/99
34
extendPCR
voi d extendPCR( i nt PCRi ndex,
PCREvent event )
t hrows Tr ust edComput i ngExcept i on
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:
PCRi ndex- The PCR to be changed
event - Contains the event description and the value passed on to the TPM.
Throws:
Tr ust edComput i ngExcept i on
PCRsNotAccessi bl eExcept i on- If access to PCRs is blocked by the Operating System
readPCR
PCRI nf o readPCR( i nt [ ] PCRi ndi ces)
t hrowsTr ust edComput i ngExcept i on
Reads the current values of a set of PCR registers from the TPM. On Windows OS, any PCR access is by default
blocked.
Parameters:
PCRi ndi ces- 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:
Tr ust edComput i ngExcept i on
PCRsNotAccessi bl eExcept i on- If access to PCRs is blocked by the Operating System
stirRandom
voi d stirRandom(byte[] entropy)
t hrowsTr ust edComput i ngExcept i on
Allows to add entropy to the hardware Random Number Generator of the TPM.
Parameters:
ent r opy- Data to add entropy to the TPM's hardware true RNG state. Length must not exceed 256.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
35/99
35
Throws:
Tr ust edComput i ngExcept i on
getProperty
Obj ect getProperty( St r i ng proper t y)
t hrowsTr ust edComput i ngExcept i on,
I l l egal Ar gument Except i on
Allows to query properties and information on the Trusted Computing mechanisms of this platform. Valid keys are:
PROPERTY_ TPM_MANUFACTURER
PROPERTY_TPM_VERSI ON
PROPERTY_ TPM_FI RMWARE_VERSI ON
PROPERTY_ TSS_VENDOR
PROPERTY_TSS_VERSI ON
PROPERTY_J SR_REVI SI ON
PROPERTY_J SR_VERSI ON
Parameters:
pr oper t y- The key of the property to be queried.
Returns:
The property value.
Throws:
Tr ust edComput i ngExcept i on
I l l egal Ar gument Except i on
{@l i nk- IllegalArgumentException} if wrong or illegal property is queried
Class TPMContextjavax.trustedcomputing.tpm
j ava. l ang. Obj ect
javax.trustedcomputing.tpm.TPMContext
abst r act publ i c cl ass TPMContext
ext ends Obj ect
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 severalTPMCont ext at the same time, all derived Objects (such as keys) are only valid
within oneTPMContext 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.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
36/99
36
Method Summary Page
abst r act voi d close( )
Closes the connection to theTPMCont ext session.37
abst r act voi d connect( URL r emot eAdress)
Connects thisTPMCont ext to a TPM context session.38
abst r act
At t estor getAttestor( )
Creates an instance ofAt t est or that provides all services for remote attestation.43
abst r act Bi nder getBinder( )
Creates aBi nder object that provides functionality for TPM-based binding.40
abst r act
Cer t i f i er getCertifier( )
Creates an instance of the optional Cer t i f i er tool that provides all services for key
certification.
43
abst r act Di gest getDigest( byt e[ ] di gest)
Creates aDi gest ,which holds a given SHA-1 hash.41
abst r act
I ni t i al i z er getInitializer( )
Returns anI ni t i al i zer that allows the initial configuration of the TPM, for instance taking
ownership.
43
s tat i c
TPMCont ext getInstance( )
returns an instance of aTPMCont ext implementation.
38
s tat i c
TPMCont ext getInstance( St r i ng cl assName)
returns an Instance of a TPMContext implementation.38
abst r act
KeyManager getKeyManager( )
Creates an instance of KeyManager which handles all operations to create, store and load
keys.
40
abst r act
PCREvent getPCREvent( l ong event Type, Di gest dat a, St r i ng event Descri pt i on)
Returns an initializedPCREvent object.42
abst r act
PCRI nfo getPCRInfo( )
Creates aPCRI nf oobject with default number of PCRs 1.2 in TPMs (24).41
abst r act
PCRI nfogetPCRInfo( i nt number Of PCRs)
Creates aPCRI nf o object with a given number of PCR registers, which cannot be changed
once set.
41
abst r act
RemoteAt t est or getRemoteAttestor( )
Creates an instance of theRemot eAt t est or tool which can be used to validate TPM Quote
data on a remote host without a TPM.
44
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
37/99
37
abst r act
Remot eBi nder getRemoteBinder( )
Creates an instance of theRemot eBi nder tool which can be used to bind data on a remote
host to a TPM-protectedBi ndi ngKey.
44
abst r act
RemoteCert i f i er getRemoteCertifier( )
Creates an instance of theRemoteCert i f i er tool which can be used to validate the policies
of TPM-protected keys a remote host without a TPM.
44
abst r act
Remot eSi gner getRemoteSigner( )
Creates an instance of theRemot eSi gner tool which helps verifying cryptographic signatures
performed by the TPM.
44
abst r act Seal er getSealer( )
Creates aSeal er object that provides functionality for TPM-based data sealing.40
abst r act Secr et getSecret( char[ ] password)
A Secr et is a convenient representation of hashed passwords used to authenticateoperations with the TPM.
42
abst r act Secr et getSecret( char[ ] password, bool ean addNul l Ter mi nati on, Char set encodi ng)
Creates aSecr et 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.
42
abst r act Secr et getSecret( Di gest hashedSecr et )
Creates aSecr et object directly from a SHA-1 hash.41
abst r act Si gner getSigner( )
Creates aSi gner object that provides functionality for signing data with TPM-protected keys.40
abst r actTPM getTPMInstance( )
Creates an implementation-specific instance ofTPM.39
abst r act
bool eanisConnected( )
Determines if aTPMCont ext is connected to the session context of a hardware TPM.39
Method Detail
close
publ i c abst r act voi d close( )
t hrows Tr ust edComput i ngExcept i on
Closes the connection to theTPMContext session. Invalidates all objects that depend on it. It is not possible to
revert to a previous session once it is closed.
Throws:
Tr ust edComput i ngExcept i on
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
38/99
38
connect
publ i c abst r act voi d connect( URL r emoteAdress)
t hrowsTr ust edComput i ngExcept i on
Connects thisTPMContext 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:
r emot eAdress - The URLto connect to. If nul l , the local TPM is accessed.
Throws:
Tr ust edComput i ngExcept i on
getInstance
publ i c stat i cTPMCont ext getInstance( )
t hr ows Cl assCastExcept i on,
Cl assNotFoundExcept i on,
I nstant i at i onExcept i on,
I l l egal AccessExcept i on
returns an instance of aTPMCont ext implementation. The returned context is not connected yet.
As part of its initialization, theTPMCont ext 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:
j sr 321. t pmcont ext i mpl =f oo. bah. TPMCont ext I mpl
Returns:
an implementation specific instance ofTPMCont ext .
Throws:
Cl assCastExcept i on
Cl assNot FoundExcept i on
I nst ant i at i onExcept i on
I l l egal AccessExcept i on
getInstance
publ i c stat i cTPMCont ext getInstance( St r i ng cl assName)
t hr ows Cl assCastExcept i on,
Cl assNotFoundExcept i on,
I nstant i at i onExcept i on,I l l egal AccessExcept i on
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
39/99
39
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:
cl assName- The name of the class that extends and implementsTPMContext .
Returns:
an implementation specific instance ofTPMCont ext .
Throws:
Cl assCastExcept i on
Cl assNot FoundExcept i on
I nst ant i at i onExcept i on
I l l egal AccessExcept i on
getTPMInstance
publ i c abst r act TPM getTPMInstance( )
t hrows Tr ust edComput i ngExcept i on
Creates an implementation-specific instance ofTPM.It is bound to thisTPMCont ext and to the hardware TPM.
Returns:
an initializedTPMobject for thisTPMCont ext
Throws:
Tr ust edComput i ngExcept i on
isConnected
publ i c abst r act bool ean isConnected( )
t hrowsTr ust edComput i ngExcept i on
Determines if a TPMCont ext is connected to the session context of a hardware TPM. All functionality of
TPMContext and derived objects can only be accessed if connected.
Returns:
t rueif thisTPMCont ext is currently connected to a hardware TPM
Throws:
Tr ust edComput i ngExcept i on
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
40/99
40
getKeyManager
publ i c abst r act KeyManager getKeyManager( )
t hrowsTr ust edComput i ngExcept i on
Creates an instance ofKeyManager which handles all operations to create, store and load keys.
Returns:
aKeyManager which is linked to thisTPMCont ext and its hardware TPM.
Throws:
Tr ust edComput i ngExcept i on
getSealer
publ i c abst r act Seal er getSealer( )t hrows Tr ust edComput i ngExcept i on
Creates aSeal er object that provides functionality for TPM-based data sealing. Sealing is the encryption of data to
a TPM-protected key and PCR configuration.
Returns:
aSeal er which is linked to this TPMContext
Throws:
Tr ust edComput i ngExcept i on
getBinder
publ i c abst r act Bi nder getBinder( )
t hrows Tr ust edComput i ngExcept i on
Creates aBi nder object that provides functionality for TPM-based binding. Binding is the encryption of data to a
TPM-protected key.
Returns:
aBi nder which is linked to this TPMContext
Throws:
Tr ust edComput i ngExcept i on
getSigner
publ i c abst r act Si gner getSigner( )t hrows Tr ust edComput i ngExcept i on
Creates aSi gner object that provides functionality for signing data with TPM-protected keys.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
41/99
41
Returns:
aSi gner which is linked to this TPMContext
Throws:
Tr ust edComput i ngExcept i on
getDigest
publ i c abst r act Di gest getDigest( byt e[ ] di gest)
Creates aDi gest ,which holds a given SHA-1 hash. This class allows for more convenient use of the API, but does
not perform hashing operations.
Parameters:
di gest - An array of bytes, with an exact length of 20 bytes.
Throws:
I l l egal Ar gument Except i on- if the size of di gest is not exactly 20.
getPCRInfo
publ i c abst r act PCRI nf o getPCRInfo( )
Creates a PCRI nf o object with default number of PCRs 1.2 in TPMs (24). Platform Configuration Registers holddisgests that describe a system's configuration.
getPCRInfo
publ i c abst r act PCRI nf o getPCRInfo( i nt number Of PCRs)
Creates aPCRI nf oobject with a given number of PCR registers, which cannot be changed once set.
Parameters:
number Of PCRs- The number of PCRs to consider. Must be greater than zero. TPM 1.2 typically provide 24
PCRs or more.
getSecret
publ i c abst r act Secr et getSecret( Di gest hashedSecret )
Creates aSecr et object directly from a SHA-1 hash. Secrets are convenient representations of hashed passwords
used to authenticate operations with the TPM.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
42/99
42
Parameters:
hashedSecr et - The already hashed secret.
getSecret
publ i c abst r act Secr et getSecret( char[ ] password)
ASecr et 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:
passwor d- The plaintext password as character array.
getSecret
publ i c abst r act Secr et getSecret( char [ ] passwor d,
bool ean addNul l Ter mi nati on,
Char set encodi ng)
t hr ows Char acterCodi ngExcept i on
Creates aSecr et 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:
passwor d- The plaintext password as character array.
addNul l Ter mi nati on- indicates if a trailing zero is appended before hashing.
encodi ng - indicated the Charset that is used to generate the byte-stream to be hashed. For example
Charset . f orName(" ASCI I " ) . Relevent charsets may be "UTF-16LE" or "ASCII".
Returns:
The created Secret.
Throws:
Char acterCodi ngExcept i on- when a character decoding or encoding error occurs.
getPCREvent
publ i c abst r act PCREvent getPCREvent( l ong event Type,
Di gest dat a,
St r i ng event Descr i pt i on)
Returns an initializedPCREvent object.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
43/99
43
Parameters:
event Type- A numerical representation of the event type.
data- The hash digest of the data to be extended.
event Descr i pt i on- A description that is added to the system's Stored Measurement Log.
getInitializer
publ i c abst r act I ni t i al i zer getInitializer( )
t hrows Tr ust edComput i ngExcept i on,
Unsuppor t edOper at i onExcept i on
Returns an I ni t i al i zer that allows the initial configuration of the TPM, for instance taking ownership. It will
throw an Unsupport edOper at i onExcept i onif this optional tool is not implemented.
Throws:
Tr ust edComput i ngExcept i on
Unsuppor t edOper at i onExcept i on
getAttestor
publ i c abst r act At t est or getAttestor( )
t hrows Tr ust edComput i ngExcept i on
Creates an instance ofAt t est or that provides all services for remote attestation.
Returns:
aAt t est or which is linked to thisTPMCont ext and its hardware TPM.
Throws:
Tr ust edComput i ngExcept i on
getCertifier
publ i c abst r act Cer t i f i er getCertifier( )
t hrowsTr ust edComput i ngExcept i on,
Unsuppor t edOper at i onExcept i on
Creates an instance of the optionalCer t i f i er tool that provides all services for key certification. It will throw an
Unsuppor t edOper at i onExcept i onif this optional tool is not implemented.
Returns:
aCer t i f i er which is linked to thisTPMCont ext and its hardware TPM.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
44/99
44
Throws:
Tr ust edComput i ngExcept i on
Unsuppor t edOper at i onExcept i on
getRemoteAttestor
publ i c abst r act Remot eAt t est or getRemoteAttestor( )
Creates an instance of theRemot eAt t est or 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:
aRemot eAt t est or ,which can act without a local hardware TPM.
getRemoteBinder
publ i c abst r act Remot eBi nder getRemoteBinder( )
Creates an instance of theRemot eBi nder tool which can be used to bind data on a remote host to a TPM-protected
Bi ndi ngKey.It can be used even if the TPMContext is not connected.
Returns:
aRemot eBi nder ,which can act without a local hardware TPM.
getRemoteCertifier
publ i c abst r act RemoteCert i f i er getRemoteCertifier( )
Creates an instance of theRemoteCert i f i er 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:
aRemoteCer t i f i er ,which can act without a local hardware TPM.
getRemoteSigner
publ i c abst r act Remot eSi gner getRemoteSigner( )
Creates an instance of the Remot eSi gner tool which helps verifying cryptographic signatures performed by the
TPM. It can be used even if the TPMContext is not connected.
Returns:
aRemot eSi gner ,which can act without a local hardware TPM.
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
45/99
45
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
LegacyKeyLegacyKeys 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. 46
Exception Summary Page
KeyNotMigratableExceptionThis 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 centralKeyManager class
must be created by TPMCont ext .
The TPM enforces different usage policies for different types of keys, this is reflected in the set of key types in this package.
Interface BindingKeyjavax.trustedcomputing.tpm.keys
Al l Super inter faces:
RSAKey,TPMKey,TPMRSAKey
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
46/99
Interface BindingKey
46
publ i c i nt er f ace BindingKey
extends TPMKey, TPMRSAKey
Binding keys protect data which is bound to a specific platform.
Interface IdentityKeyjavax.trustedcomputing.tpm.keys
Al l Super inter faces:
RSAKey,TPMKey,TPMRSAKey
publ i c i nt er f ace 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 KeyManagerjavax.trustedcomputing.tpm.keys
j ava. l ang. Obj ect
javax.trustedcomputing.tpm.keys.KeyManager
abst r act publ i c cl ass KeyManager
ext ends Obj ect
Provides management functionality for TPM-based cryptographic keys. It allows to create, store and delete keys for different
operations. A KeyManager object may only exist within a TPMContext. While the KeyManager provides a number of
methods to persistently store keys and to retrieve them, it does not automatically store them at creation or loading. Note
there are separate storages for keys belonging to the current user and the system.
Method Summary Page
abst r act
Bi ndi ngKeycreateBindingKey( StorageKey par ent , Secr et usageSecr et, Secr et
mi gr at i onSecr et , bool ean i sMi gr at abl e, bool ean i sVol at i l e, bool ean
needsAut hor i zat i on, i nt RSAKeyLengt h, PCRI nf o pcr I nf o)
Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.
48
-
8/10/2019 Trusted Computing 11 10 Final Eval Spec
47/99
47
abst r act
Si gni ngKeycreateSigningKey( StorageKey par ent , Secr et usageSecr et, Secr et
mi gr at i onSecr et , bool ean i sMi gr at abl e, bool ean i sVol at i l e, bool ean
needsAut hor i zat i on, i nt RSAKeyLengt h, PCRI nf o pcr I nf o)
Creates a cryptographic RSA key pair for signing operations in the TPM and loads it into a TPM
key slot.
48
abst r act
StorageKeycreateStorageKey( StorageKey par ent , Secr et usageSecr et, Secr et
mi gr at i onSecr et , bool ean i sMi gr at abl e, bool ean i sVol at i l e, bool ean
needsAut hor i zat i on, PCRI nf o pcr I nf o)
Creates a cryptographic RSA key pair in the TPM and loads it into a TPM key slot.
49
abst r act voi d deleteTPMKey( UUI D i dent i f i er )
Removes a key from the user persistent key storage permanently.
50
abst r act voi d deleteTPMSystemKey( UUI D i dent i f i er)
Removes a key from the system persistent key storage permanently.50
abs