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