Cryptohome manages a tamper-evident file which is meant to contain install-lifetime system attributes.
Tamper-evident storage can be accessed by consumers over D-Bus using the InstallAttributes* calls. Essentially, this provides a name-value storage interface for Get()ing and Set()ing values during install. The datastore is made tamper-evident by serializing it to a bytestream and persisting it to the filesystem via the Lockbox class. This is done when InstallAttributes::Finalize() is called. After finalization, the data becomes read-only.
The Lockbox class provides a clear interface for implemented TPM NVRAM-backed, tamper-evident data storage. It allows for the creation, destruction, storage, and retrieval of tamper-evident data. InstallAttributes stores its serialized data via this mechanism and reloads it similarly to ensure data integrity.
Each lockbox assures tamper-evidence cryptographically by storing a SHA256 digest of the supplied data blob in a TPM NVRAM space. The space itself is logically defined as follows:
struct { uint32_t data_size; uint8_t flags; uint8_t salt[SHA256_DIGEST_LENGTH]; uint8_t hash[SHA256_DIGEST_LENGTH]; } __attribute__((packed));
The data size is the expected size of the “locked” data. This provides a simple validity check and ensures collision attacks against the stored data are size-limited.
Flags is reserved for future use, primarily in anticipation of future digest changes or data serialization changes (encrypted versus not). At present, flags is always 0.
The salt is 32 bytes of randomly generated data sourced from the TPM itself. This also aids in collision attack deterrence. Many devices will likely share the same file. If a collision is found for the hash of that file, arbitrary replacement attacks would be feasible. The added salt serves to increase the difficulty of these forms of attack.
The hash is computed as SHA256(data||salt).
Once the struct is filled, it is written to the NVRAM space. A subsequent 0 byte write locks the NVRAM space (bWriteDefine) from future modification without redefinition using the TPM Owner passphrase or by asserting physical presence.
See cryptohome.xml for the exact D-Bus API calls. See lockbox.h and install_attributes.h for more information on what each provides.
InstallAttributes and Lockbox are initialized by default whenever the cryptohomed service is started. On any system that is upgraded to support InstallAttributes, it will treat the InstallAttributes as an empty-locked store by observing that no NVRAM space was defined nor backing lockbox file created.
On a fresh installation, cryptohomed will start and immediately begin the TPM ownership process. Upon completion, InstallAttributes will perform one-time initialization that creates its Lockbox and destroys any existing Lockbox data. cryptohomed will then “forget” the TPM owner password when told to by Chrome (such as at the end of the EULA view or at the login screen). Chrome will populate the InstallAttributes during the system's first boot and call Finalize() upon completion. In addition, cryptohomed will call Finalize() any time a (Async)Mount request is received over D-Bus. This is to ensure that the InstallAttributes are fully populated prior to the system going into general use. On first login, a very fast user may perform the first Mount call prior to the TPM being owned. In that case, the InstallAttributes will remain freshly initialized and unlocked until the next Mount attempt occurs (after TPM ownership has completed).
Recovery from a corrupt Lockbox requires the TPM to be cleared of a TPM owner. This can be triggered by toggling the developer mode switch and rebooting, or by going through the system recovery flow.
This value was picked by reviewing the related specification documents. The index is a managed namespace as laid out below:
3 2 1 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |T|P|U|D| resvd | Purview | Index | (T=TPM, P=platform maker, U=platform user, D=pre-defined)
(from TCG TPM Structures rev 103)
Some ranges have been declared reserved in other specs:
0xFFFFFFFF is the NVRAM lock (permanent).0x50010000 is reserved for BIOS use.0x0000Fxxx preallocated/reserved by for locality use.0x0001xxxx are a handful of TSS reserved ranges.0x10000001 is the deprecated NV_INDEX_DIR.0x00000000 is the bGlobalLock index.In addition, there is at least one other major user. For tboot, Intel uses:
0x20000001: 001000000000000000000000000000010x20000002: 00100000000000000000000000000010in the Platform User range. It‘s unclear if they’ll expand further out in the future, so we leave room for them to add a single space.
0x20000004: 00100000000000000000000000000100Arguably, we could use a ‘P’ space, but that would complicate Chromium OS use on non-Chrome hardware.