Trusted Computing 11 10 Final Eval Spec

8/10/2019 Trusted Computing 11 10 Final Eval Spec

1/99

JSR321

Trusted Computing API for Java

Java Community Process Specification

Final Release


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.


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


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.


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.


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.


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/99

8

Open Issues

Currently None.


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();


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


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.


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)


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.


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.


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.


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


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



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


18/99

18

Tspi_PcrComposite_

SetPcrValue

Set what values the PCRs in

a PcrComposite object

should have. This is

preparation for doing a seal.


Tspi_PcrComposite_

GetPcrValue

Returns the current value of

a PCR in a PcrCompositeobject.


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


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.


needed for

applications

- -

Tspi_NV_WriteValue Write a value to the NVRAM

space previously allocated.


needed for

applications

- -

Tspi_NV_ReadValue Read a value from NVRAM

space previously allocated.


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

- -


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


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


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


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


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


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


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.


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.


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/


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


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


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


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.


29/99

29

Class PCRsNotAccessibleExceptionjavax.trustedcomputing.tpm


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


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


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.


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( )


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:


isEnabled

bool ean isEnabled( )


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:



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:


getNumberPCR

i nt getNumberPCR( )


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:


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:


PCRsNotAccessi bl eExcept i on- If access to PCRs is blocked by the Operating System


34/99

34

extendPCR

voi d extendPCR( i nt PCRi ndex,

PCREvent event )


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:



readPCR

PCRI nf o readPCR( i nt [ ] PCRi ndi ces)


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:



stirRandom

voi d stirRandom(byte[] entropy)


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.


35/99

35

Throws:


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:


I l l egal Ar gument Except i on

{@l i nk- IllegalArgumentException} if wrong or illegal property is queried

Class TPMContextjavax.trustedcomputing.tpm


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.


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


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( )


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:



38/99

38

connect

publ i c abst r act voi d connect( URL r emoteAdress)


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:


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


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


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


getTPMInstance

publ i c abst r act TPM getTPMInstance( )


Creates an implementation-specific instance ofTPM.It is bound to thisTPMCont ext and to the hardware TPM.

Returns:

an initializedTPMobject for thisTPMCont ext

Throws:


isConnected

publ i c abst r act bool ean isConnected( )


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:



40/99

40

getKeyManager

publ i c abst r act KeyManager getKeyManager( )


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:


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:


getBinder

publ i c abst r act Bi nder getBinder( )


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:


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.


41/99

41

Returns:

aSi gner which is linked to this TPMContext

Throws:


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 onif 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.


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.


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:



getAttestor

publ i c abst r act At t est or getAttestor( )


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:


getCertifier

publ i c abst r act Cer t i f i er getCertifier( )

t hrowsTr ust edComput i ngExcept 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.


44/99

44

Throws:



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.


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


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


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


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


47/99

47

abst r act

Si gni ngKeycreateSigningKey( StorageKey par ent , Secr et usageSecr et, Secr et


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


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

Documents

Trusted Computing 11 10 Final Eval Spec