Chaps Technical Design

Objective

Chaps is a PKCS #11 implementation that provides trusted platform module (TPM) backed cryptographic services. It replaces openCryptoki as the provider of TPM-backed cryptographic services on Chrome OS. It aims to improve speed and reliability of cryptographic token operations as well as to provide a simpler and more flexible codebase for future enhancements. Chaps works with a TCG Software Stack (TSS). On Chrome OS the TrouSerS TSS implementation is used, but Chaps is not limited to working with TrouSerS. The name "Chaps" has no real significance other than its fitness as a name for a layer above TrouSerS.

The following diagram illustrates where Chaps fits in the cryptographic services stack.

Rationale

The motivation for creating Chaps and phasing out openCryptoki is threefold:

• Stability - There have been numerous bugs and quirks that are difficult to find and sometimes messy to fix. We want a module that is designed to be highly testable and that lends itself to automated testing.
• Performance - TPMs are notoriously slow, and we want to both leverage security and optimize performance.
• Integration - We want a module that integrates well with Chrome OS and how Chrome OS uses TPM-backed cryptographic services. openCryptoki does not meet this criteria, and some future considerations, such as multi-token scenarios, are not possible with openCryptoki. We also want code that will be easy to enhance in the future.

Audience

This document is for engineers, system integrators, and security analysts interested in the details of Chrome OS security.

Resources

The following resources provide useful background to this document:

• TrouSers PKCS #11 Interface Docs: OpenCryptoki is currently used with a plugin from the TrouSerS project to provide the TPM-specific implementation. This link provides details on the plugin and the model it implements.
• PKCS #11: Cryptographic Token Interface Standard
• TCG Software Stack Specification

Overview

Chaps has two major components:

• chapsd - A daemon that receives and handles PKCS #11 calls via the D-Bus. This daemon is always running and starts at boot.
• libchaps.so - A library that exports the PKCS #11 interface and communicates with chapsd. An application loads and uses this library like any other PKCS #11 library.

Chaps reports two slots: (1) a system slot (not currently enabled) and (2) a user slot. The system slot will always have a token available. The user slot will have a token available while a user is logged in. chapsd receives login/logout notifications from cryptohome. The login notification must provide the user password (or some password-derived value) that will be used as authorization data for TPM-protected keys. Cryptohome derives the authorization data from the user password and a user-and-system-specific salt value using the scrypt key derivation scheme.

This diagram shows the Chaps high-level architecture:

Staging

• Phase 1 (enabled in Chrome OS version 18) - Introduce chapsd:
  • Marshaling of all PKCS #11 calls from libchaps.so to chapsd.
  • chapsd redirection to openCryptoki.
  • Integration of libchaps.so with all PKCS #11 applications.
  • chapsd runs as chronos to play nice with existing openCryptoki files and facilitate a rollback in the event of unexpected problems.
• Phase 2 (enabled in Chrome OS version 20) - Replace openCryptoki:
  • chapsd implementation (redirection to openCryptoki is removed).
  • chapsd runs as a system user named "chaps."
  • OpenCryptoki is removed from the system.
• Phase 3 (optional) - Do more in software:
  • TPM-encrypted key store for faster RSA operations. A TPM-protected symmetric key is used to encrypt a key store outside of the TPM. This symmetric key will be much faster to load than RSA keys and can be temporarily cached. The RSA keys are then stored in the key store and the cryptographic operations are performed in software.

Infrastructures

Inter-Process Communication (IPC)

All IPC with chapsd is performed using D-Bus. Both the Chaps client and daemon use dbus-c++ to generate proxy and adaptor classes.

Persistence

Object data is stored in /var/lib/chaps for the system token and in ~/.chaps for each user. The object database is implemented using LevelDB.

TPM Software Layers

The TrouSers library is used to access TPM services from the TSPI layer.

Testing

Unit tests for Chaps use the gtest and gmock frameworks. End-to-end tests use the autotest framework.

Detailed Design

TPM Interaction

Phase 1 - Introduce chapsd:

In Phase 1 all TPM interaction is still controlled by openCryptoki. The introduction of chapsd does not change TPM interaction in any way.

Phase 2 - Replace openCryptoki:

All RSA private keys with the attribute CKA_TOKEN set to TRUE will be bound to the TPM (wrapped by the Storage Root Key) and will not be extractable. All other private data and non-RSA keys are stored encrypted by the User Encryption Key which is protected by the TPM’s SRK but is extractable. This diagram depicts the key hierarchy:

Authorization Data

Authorization data for the User Authorization Key is derived from the user password using the scrypt scheme. Salt is stored in a root-accessible file in the user’s home directory and is unique per user account per system. This ensures that authorization data for the same user on two different systems is different. The scrypt parameters are tuned to perform the computation in about 100ms.

All other authorization data is randomly generated and stored encrypted with the User Encryption Key. This authorization data is not directly encrypted with the User Authorization Key for performance reasons. This does not reduce security since any attack on the key would require access to the TPM (and so decryption of authorization data by the TPM would be possible).

Migration

Existing TPM-protected keys cannot be migrated to this hierarchy. The existing hierarchy is supported so that existing keys can continue to be used. All other data including meta-data associated with TPM-protected keys that was previously stored in the openCryptoki object store can be migrated to the new persistent object store. This migration will take place when valid openCryptoki object data is found in a user’s home directory and migration has not previously taken place.

Multiple Users

In the future, simultaneous multiple user logins may need to be supported, and this design must accommodate this scenario. Each slot maintains a distinct object database, a distinct User Authorization Key and User Encryption Key, and uses a distinct password. Currently, only the "system" and "user" slots exist, but adding a new user would be as simple as adding another slot.

Phase 3 - Do more in software:

The key hierarchy for Phase 3 is the same as for Phase 2. The difference is that in Phase 3 some RSA keys can be protected by the User Encryption Key rather than being directly TPM-protected. Keys that require higher performance and do not require the high security of direct TPM binding are candidates for this. There is no migration of existing RSA keys because they are not extractable.

Chaps Classes

Chaps is implemented in C++ and makes wide use of mockable interfaces. This structure allows for a high level of unit test coverage. In general, all classes inherit from an interface class, and when one class interacts with another, it references the interface, not the implementation class.

• ChapsInterface - This interface is the C++ equivalent of the IPC contract between the Chaps client and daemon. The actual interface used by dbus-c++ is described in XML. ChapsInterface is implemented on the client side by ChapsProxyImpl and on the daemon side by ChapsServiceRedirect (Phase 1) and ChapsServiceImpl (Phase 2). The following diagram shows the class hierarchy and how the classes interact in practice.

• ChapsProxyImpl - This class implements ChapsInterface and forwards all calls to an instance of the dbus-c++ generated proxy class.
• ChapsAdaptor - This class implements the dbus-c++ generated adaptor interface and forwards all dbus calls to a ChapsInterface instance.
• ChapsServiceRedirect - This class implements ChapsInterface and forwards all calls to a PKCS #11 library. In Phase 1 this class is hooked up to ChapsAdaptor and forwards incoming calls to openCryptoki. In Phase 2 this class will no longer be used.
• ChapsServiceImpl - This class implements ChapsInterface and provides the actual Chaps implementation (in contrast to ChapsServiceRedirect). This class is hooked up to ChapsAdaptor (in Phase 2) and serves as the entry point of all calls to chapsd.
• ChapsFactory - This class creates default instances of interface classes. In a test environment, a mock of this class can be configured to create the desired combination of real and mock objects.
• SlotManager / SlotManagerImpl - This mockable class manages the state of all slots, the tokens in them, and maintains a list of sessions for each token.
• Session / SessionImpl - This mockable class represents a session and manages all contextual information for a single session.
• ObjectPolicy - An instance of this class is bound to each object; it enforces all policies specified in PKCS #11 for the particular object type. There is a subclass of this interface for each object type.
• Object / ObjectImpl - This mockable class represents an object and is optionally persistent.
• ObjectPool / ObjectPoolImpl - This mockable class represents an unordered group of objects. An ObjectPool may or may not be backed by an ObjectStore.
• ObjectStore / ObjectStoreImpl - This mockable class implements a persistent object store. This is the only class that references the LevelDB API.
• TPMUtility / TPMUtilityImpl - This mockable class interfaces with the TrouSerS library for interaction with the TPM.
• ObjectImporter / OpencryptokiImporter - This mockable class imports objects from an external source. The openCryptoki-specific implementation imports objects from an openCryptoki database.

Marshalling

All marshalling is performed by dbus-c++ with the exception of template arguments (that is, CK_ATTRIBUTE lists), which are serialized using the protobuf library.

Schema

LevelDB is not relational, so a relational schema is not used. Objects are serialized and assigned a unique identifier. The keys in LevelDB are the object identifiers, and the values are serialized object blobs.

Deployment

Phase 1

Phase 1 deployment has the following goals:

• The PKCS #11 system is fully functional following each individual CL. This is necessary because multiple repositories are involved (for example, chaps, cryptohome, chrome, init, …).
• A full rollback is possible at any time.

The following ordered deployment plan meets these goals:

1. Both chapsd and libchaps.so are installed and fully functional. chapsd runs as chronos:pkcs11 in order to play nice with other applications loading openCryptoki directly.
2. An upstart configuration file is added for chapsd so it starts before login and respawns automatically. It depends on tcsd and dbus.
3. Chaps is added as a run-time dependency to the cryptohome ebuild.
4. The cryptohome upstart configuration is modified to depend on chapsd.
5. Cryptohome is modified to link against Chaps rather than openCryptoki.
6. All other modules that use openCryptoki are modified (in any order) to use Chaps. This includes but is not limited to:
   1. NSS in Chrome
   2. vpn_manager
   3. flimflam
   4. wpa_supplicant
   5. entd

Phase 2

Phase 2 deployment has the following goals:

• The PKCS #11 system is fully functional at all times.
• Migration is seamless to all users.
• A partial rollback is possible for a limited time that will put a migrated user token back in the state it was in before migration. Modifications since migration will be lost; this works like restoring a backup.

The following deployment plan meets these goals:

1. When a token is migrated, all existing files are left intact and a database record is created to indicate that migration has taken place. Upon rollback, openCryptoki simply keeps working with these files as it did before migration.
2. The switch is in the chapsd upstart configuration: the target library argument is removed to enable Phase 2 logic and is re-added in order to roll back.
3. Finally, once confidence is established in the Phase 2 logic, cleanup tasks can be performed that preclude future rollbacks. These include:
   1. Remove all openCryptoki-related files in the user token directory.
   2. Remove all openCryptoki-related logic from cryptohome code.
   3. Remove openCryptoki from the build.

Project Information

The Chaps code resides in a Chromium OS git repository at http://git.chromium.org/gitweb/?p=chromiumos/platform/chaps.git;a=summary.

Internationalization and Localization

The Chaps library returns the following strings which may need to be translated. It is assumed that manufacturer ID strings do not require translation. If a string does not appear in the Chrome OS user interface, it may not require translation.

• C_GetInfo returns a library description.
• C_GetSlotInfo returns a slot description.
• C_GetTokenInfo returns a token label, token model, and token description.

Security Considerations

The following table lists some threats that are mitigated by the Chaps system and provides details on how the threat is mitigated.

If a user is logged in and an attacker gains chapsd privilege, then nothing prevents this attacker from reading all private data and keys that are not TPM-protected and non-extractable or from creating digital signatures using TPM-protected, non-extractable keys. The following are TPM-protected:

• RSA private keys (with modulus 2048 bits or less) that have CKA_TOKEN=TRUE.

All objects with CKA_PRIVATE=TRUE are encrypted on disk with a TPM-protected key, even if they are not themselves TPM-protected. The following are not themselves TPM-protected (other than the on-disk encryption):

• RSA private keys with modulus larger than 2048 bits.
• RSA private keys with CKA_TOKEN=FALSE.
• All objects that are not RSA private keys (for example, AES keys, data objects).

Key Storage Example

Suppose you have a certificate with an associated private key used to negotiate 802.1x and/or VPN connections. The following PKCS #11 objects would exist in the Chaps database:

• Certificate: This object is public and is not encrypted.
• Public Key: This object is public and is not encrypted.
• Private Key: This object is private and is encrypted with the User Encryption Key. It holds the following attributes:
  • Authorization Data: This is random and specific to this key.
  • Private Key Blob: This is a TPM-wrapped blob.
• Encrypted User Encryption Key: This is encrypted by the User Authorization Key.
• User Authorization Key Blob: This is a TPM-wrapped blob.

The following information would be in chapsd process memory while the token is loaded:

• User Encryption Key: This has been decrypted using the User Authorization Key and the password-derived secret as authorization data.
• The Certificate, Public Key, and Private Key, as listed above. The Private Key has been decrypted using the User Encryption Key.

Cryptography

This section lists each way in which Chaps uses cryptography and gives details as to how it is used. In all cases where cryptography is used in software, Chaps uses the openssl crypto library to provide the underlying algorithm implementations.

Random Numbers

The openssl cryptographically strong pseudo-random-number-generator (PRNG) is used as a source of random numbers. It is seeded using the default openssl seeding mechanism (/dev/urandom on Chrome OS) in combination with 128 random bytes from the TPM. This seeding occurs only once per chapsd process.

PKCS #11 Software Mechanisms

Chaps supports a number of mechanisms in software that are not supported by the TPM (for example, SHA, HMAC, AES). The implementation of these mechanisms pass through directly to openssl, including padding and cipher modes, with the following exceptions:

• The construction of RSA signing data. Chaps constructs the signing data itself and then employs the openssl RSA primitive. This approach guarantees signature compatibility between openssl and a TPM.
• The generation of DES / DES3 keys. Chaps is still using openssl functions such as DES_is_weak_key() and the openssl PRNG.

Encryption / Authentication of Persistent Objects

Private object blobs are encrypted using AES-256-CBC with PKCS padding. An initialization vector (IV) is randomly generated for each encryption operation; it is appended to the encrypted blob. An HMAC-SHA512 mac is appended to each encrypted blob. This mac is verified before the decryption is attempted. Verification uses a version of memcmp that reads and compares all bytes regardless of where a mismatch is found.

Authorization Data Hashes

Once authorization data is derived from the user password or similar using scrypt, it is processed as follows:

• An SHA-1 hash of the authorization data is computed and sent to the TPM. This hash is never stored on disk and is considered as sensitive as the user password.
• An SHA-512 hash of the authorization data is computed and the first byte of the hash is stored in the token database. This allows Chaps to sanity-check incoming authorization data before sending it to the TPM. Only a single byte is stored because it allows a reasonable sanity check but it is not very useful for a brute-force attack against the authorization data or the user password.

Logging Plan

All errors are logged using the facility provided by base/logging.h.

Testing Plan

Chaps is tested using both unit and integration tests. All unit tests are run from the ebuild test phase. The integration tests can be run manually or with the autotest framework.

Unit / Integration Tests

The classes generated by dbus-c++ are not suitable for stubbing / mocking for two reasons:

• We don’t want dbus code running in the unit test environment. Problems with this approach have been noted on other projects.
• The classes are tightly coupled with types and conventions that are specific to dbus-c++.

A C++ interface is defined (ChapsInterface) that is very close to the generated proxy and adaptor interfaces but suitable for using and mocking in a test environment.

Client-side Unit Tests

The client-side code is unit tested by using a mock proxy and calling the PKCS #11 C interface. Because the code being tested is called by external code, all argument validation and internal state validation is tested thoroughly resulting in a high level of code coverage.

Daemon-side Unit / Integration Tests

Phase 1: There are no unit tests per se for the chapsd code in Phase 1 because each layer is either tightly coupled with D-Bus or tightly coupled with openCryptoki. The chapsd code is tested by a suite that verifies basic functionality of ChapsInterface methods. This test suite is then run on both a ChapsServiceRedirect instance and on a ChapsProxyImpl instance. These tests require a configured openCryptoki and, in the ChapsProxyImpl case, a running chapsd instance. Because of this requirement, the tests must be run on a live system, and they do not run as part of the ebuild test phase.

Phase 2: The tests from Phase 1 are reused and are run on a ChapsServiceImpl instance and a ChapsProxyImpl instance. In the case of ChapsServiceImpl, a mock persistence object can be used, and the suite can run as a unit test. In the case of ChapsProxyImpl, the suite is run as an integration test and requires a running chapsd instance as in Phase 1. In addition to this, unit tests which are specific to a single class are run for the following classes:

• SlotManager
• Session
• ObjectPolicy
• Object
• ObjectPool
• ObjectStore
• TPMUtility

For each of these unit tests, any references to other objects are mocks. The following mocks are available:

• ChapsFactoryMock
• SlotManagerMock
• SessionMock
• ObjectPolicyMock
• ObjectMock
• ObjectPoolMock
• ObjectStoreMock
• ObjectImporterMock
• TPMUtilityMock