This package contains the cryptohome daemon, which is responsible for the
creation and mounting/unmounting of per-user encrypted home directories.

Cryptohome makes use of ecryptfs for the underlying file and filename
encryption.  Keys for a user are maintained in an encrypted vault keyset that is
protected using a key derived from the user's password.  That protection may
be either through the TPM or through the use of Scrypt
(http://www.tarsnap.com/scrypt.html).

Cryptohome manages directories as follows:

/home/.shadow                            : Location for the system salt and
                                           individual users' salt/key/vault
/home/.shadow/<salted_hash_of_username>  : Each Chrome OS user gets a
                                           directory in the shadow root where
                                           their salts, keys, and vault are
                                           stored (s_h_o_u).
/home/.shadow/<s_h_o_u>/vault            : The user's vault (the encrypted
                                           version of their home directory)
/home/.shadow/<s_h_o_u>/master.0         : Vault keyset for the user.  The
                                           vault keyset contains the
                                           encrypted file encryption key and
                                           encrypted filename encryption key.
                                           It also contains the salt used to
                                           convert the user's passkey to an
                                           AES key, and may contain the
                                           TPM-encrypted intermediate key
                                           when TPM protection is enabled
                                           (see tpm.h for details).
/home/chronos/user                       : On successful login, the user's
                                           vault directory is mounted here
                                           using the symmetric key decrypted
                                           from master.X by the user's
                                           passkey.

Offline login and screen unlock is processed through cryptohome using a test
decryption of the user's master key using the passkey provided.  If the user
currently has their cryptohome mounted, then the credentials may be verified
against their session object instead, which provides quick credentials
verification without access to the key material.  This latter method uses the
UserSession object in user_session.cc.  A user session is established on
successful completion of MountCryptohome() in mount.cc.  The user session is
torn down when a call to UnmmountCryptohome, MountCryptohome,
MountGuestCryptohome, or MigratePasskey is made (regardless of success status).
If no user session exists for the Mount instance, offline credential test falls
back to attempting to decrypt the user's stored vault keyset.  The session
method is preferred because it does not attempt to decrypt key material, and
because it does not require a round-trip to the TPM when the TPM is used for
further protecting the keyset (which can be ~.7s, or close to 3s if the RSA
key was evicted from the TPM key slot it occupies).

A user's cryptohome is automatically created when the vault directory for the
user does not exist and the cryptohome service gets a call to mount the
user's home directory.  This assumes that the call to MountCryptohome contains
the correct user password--no verification can be done if the vault keyset for
the user does not exist.  TestCredentials should be used if implicit creation is
not desired (an of course, explicit mount).

Passkey change is implemented through a call to MigratePasskey.  MigratePasskey
will attempt to decrypt the vault keyset using the old credentials supplied, and
if successful, will re-save the vault keyset using the new credentials.
MigratePasskey can be called regardless of whether a user's (any user)
cryptohome is mounted.  However, it will always clear the current user's session
as described above.

Typical Mount Flow

1. Cryptohome's Mount() DBUS API is called with valid user credentials.
2. If a cryptohome does not exist for that user name, a new one is created.
   a. The cryptohome is located at /home/.shadow/<salted hash of user name>,
      where the encrypted hash is a SHA1 hash of the system salt concatenated
      to the user name.
   b. The crypthohome vault (the directory that is mounted via ecryptfs) is
      created at /home/.shadow/<s_h_o_u>/vault
   c. The vault keyset is stored at /home/.shadow/<s_h_o_u>/master.0
      i. The vault keyset stores an encrypted blob containing the ecryptfs file
         encryption key (FEK) and file name encryption key (FNEK).
      ii. The vault keyset stores non-sensitive information about the protection
          mechanism used to encrypt the keys, such as salt, password rounds,
          etc.  See the later discussion on protection mechanisms.
3. The encrypted blob in the vault keyset is decrypted using the user
   credentials supplied to the Mount() API.
   a. On failure one of several actions is taken:
      i. If the blob was protected using the TPM, and the TPM has been cleared
         and re-owned, then the user's cryptohome vault is removed and
         re-created.  This is because it is not possible to recover a keyset
         that is TPM-protected if the TPM has been cleared.  A status code
         is returned in this case, but the Mount() call returns success.  This
         is the only case where cryptohome will automatically re-create a user's
         home.
      ii. If the blob was protected using the TPM, and the TPM is unavailable,
          for example, it has been disabled, then the call returns an error code
          indicating that either there was a failure communicating with the TPM
          or that the TPM is in defend lock (a state where the TPM believes
          that a brute-force attack is happening, and so it temporarily blocks
          most API calls).  Communications failures are usually transient, and
          can be fixed by calling the API a second time.  (For example, some
          chips on resume from S3 require us to re-establish our long-lived
          session.)  If the device allows manual disabling of the TPM, this
          error would not be transient, and the user would have to re-enable the
          TPM.  Defend lock errors are always transient, but the back-off period
          is variable.  While sometimes it may be seconds, other times it is
          best to reboot the system to clear this state.
      iii. If the blob was protected using the TPM, and there is a failure in
           the TSS API (couldn't load the cryptohome TPM key, etc.) that
           doesn't correspond to a TPM clear, then a communications failure
           error is returned as decribed in (ii).
      iv. If there is a disk failure, specifically, the vault keyset file is
          corrupt, there is undefined behavior.
      v. If the following errors occur on creation, cryptohome returns an error
         and cannot remedy the problem:
         - If the TPM is unavailable, cryptohome falls back to Scrypt-based
           protection, and the call to scryptenc_buf fails for any reason.
         - If writing the encrypted vault keyset to disk fails for any reason
         - If creating the user's vault path fails for any reason
         - If setting the ownership of the user's vault path fails for any
           reason
         - If decrypting the vault keyset fails because the call to decrypt
           in the TPM fails, it is assumed that the password is incorrect.
           This may occur if the user changes their password, as the keyset
           would still be protected with the password used at last login, but
           the call to Mount() would presumably use the current credentials.
           In this case, the system is given a chance to migrate the keys by
           having the user supply the old password.
         - If decrypting the vault keyset fails because the call to decrypt
           using scrypt fails, it is assumed that the password is incorrect, as
           with the TPM above.
         - If adding the decrypted keyset to the kernel keyring before ecryptfs
           mount fails, it is assumed that the key material was decrytped
           properly but some other problem exists outside of the control of
           cryptohome.
         - If the call to mount the user's cryptohome fails, it is assumed that
           some other problem exists outside of the control of cryptohome.
         - If the user's cryptohome must be re-created due to condition (i),
           and the cryptohome cannot be removed, then some other problem exists
           outside of the control of cryptohome.


Protection Mechanisms

The vault keyset (vault_keyset.cc/h) contains the file encryption key and file
name encryption key used by ecryptfs.  This keyset encrypted and persisted to
disk.  Cryptohome may use either the TPM or Scrypt as the encryption/protection
mechanism.

If the TPM is available, cryptohome will prefer to use it.  If the TPM is not
available (either not present, not enabled, owned by another OS, or it is in the
middle of being owned), cryptohome will fall back to using scrypt-based
protection of the vault keyset.  If the TPM becomes available at a later login,
cryptohome will transparently migrate a user's keyset to TPM-based protection.

The method when the TPM is enabled can be described using the decryption
workflow as an example:

  UP -
      |
      + AES decrypt (no padding) => IEVKK -
      |                                    |
EVKK -                                     |
                                           + RSA decrypt (in TPM) => VKK
                                           |
                                           |
                                  TPM_CHK -

Where:
  UP - User Passkey
  EVKK - Ecrypted vault keyset key (stored on disk)
  IEVKK - Intermediate vault keyset key
  TPM_CHK - TPM-wrapped system-wide Cryptohome Key
  VKK - Vault Keyset Key

The end result, the Vault Keyset Key (VKK), is an AES key that is used to
decrypt the Vault Keyset, which holds the ecryptfs keys (filename encryption
key and file encryption key).  The VKK, when using the TPM for protection, is
a randomly-generated key.

The User Passkey (UP) is used as an AES key to do an initial decrypt of the
Encrypted Vault Keyset Key (EVKK, or the "tpm_key" field in the
SerializedVaultKeyset, see vault_keyset.proto).  This is done without padding as
the decryption is done in-place and the resulting buffer is the Intermediate
Vault Keyset Key (IEVKK), which is fed into an RSA decrypt on the TPM as the
cipher text.  That RSA decrypt uses the system-wide TPM-wrapped
cryptohome key.  In this manner, we can use a randomly-created system-wide
key (the TPM has a limited number of key slots), but still require the user's
passkey during the decryption phase.  This also increases the brute-force
cost of attacking the SerializedVaultKeyset offline as it means that the
attacker would have to do a TPM cipher operation per password attempt
(assuming that the wrapped key could not be recovered).

After obtaining the VKK, it is used to recover the vault keyset by using it as
an AES key to decrypt the Encrypted Vault Keyset (EVK, or the "wrapped_keyset"
field in the SerializedVaultKeyset):

VKK -
     |
     + AES (PKCS#5 padding + SHA1 verification) => VK
     |
EVK -

Where:
  EVK - Encrypted vault keyset
  VK - Vault keyset

Presented another way:

+----------------------------------+
| EVKK (persisted as "tpm_key")    |
+----------------------------------+
                              \   /
                               \ /   Final 128-bits decrypted     +----------+
                                +--- in-place using the user's ---+ UP (mem) |
                               / \   passkey                      +----------+
                              /   \
+----------------------------------+
| IEVKK (mem)                      |
+----------------------------------+
 \                                 /
  \                               /
   \                             /
    -----------      ------------
                \   /
                 \ /                       +---------------------+
                  +--- Decrypted on-TPM ---+ TPM_CHK (persisted, |
                 / \                       | sealed by the TPM)  |
                /   \                      +---------------------+
               /     \
              /       \
             /         \            +-------------------------------------+
            /           \           | EVK (persisted as "wrapped_keyset") |
           /             \          +-------------------------------------+
          /               \          \                                   /
         /                 \          ----------------   ----------------
        +-------------------+                         \ /
        | VKK (mem)         +--- AES decrypt ----------+
        +-------------------+                         / \
                                      ----------------   ----------------
                                     /                                   \
                                    +-------------------------------------+
                                    | VK (mem)                            |
                                    +-------------------------------------+

Encryption of the Vault Keyset (VK) is the reverse method (see WrapVaultKeyset
in crypto.cc).

By comparison, when the TPM is not enabled, the UP is used as the password
supplied to scryptbuf_enc, which will use memory-bound key strengthening and AES
to encrypt the VK.  The Scrypt method is simpler because of the high-level API
that Scrypt exposes for key strengthening and encryption in one function call.

TPM Initialization

Cryptohomed is responsible for initialization of the TPM once it has been
enabled and activated.  Ownership creates a Storage Root Key (SRK) on the TPM,
which is necessary to seal user keys (the system-wide cryptohome key and keys
used by opencryptoki+tpm are ultimately sealed by the SRK; see
http://trousers.sourceforge.net/pkcs11.html for more details on how opencryptoki
uses the SRK).  The ownership process is in the tpm_init library, separate from
cryptohome, but the basic process is as follows:

1. If /sys/class/misc/tpm0/device/owned is 0
   and
   /sys/class/misc/tpm0/device/enabled is 1
   then the initialize thread will attempt to initialize the TPM.
2. An Endorsement Key (EK) will be created if it doesn't exist (some vendors do
   not create one at the factory, as it is not required by the spec).
3. Tspi_TPM_TakeOwnership will be called with the Trousers default well-known
   ownership password, and the Chromium OS well-known SRK password.  This may
   take between 10s and 150s.
4. If successful, the SRK's password is reset to a NULL string, and its use is
   unrestricted (in other words, code using the SRK does not need to know the
   owner password).
5. Finally, the owner password is changed to a randomly-generated string that is
   available to the user for the duration of that boot.

Cryptohome uses the TPM merely for secure key storage to help protect the user
from data loss should their device be lost or compromised.  Keys sealed by the
TPM can only be used on the TPM itself, meaning that offline or brute-force
attacks are difficult.

DBUS API

Other programs communicate with cryptohomed using its DBUS API.  This API
exposes both synchronous and asychronous methods for mounting, unmounting,
removing, and changing passwords.  It also gives status information about the
TPM.  See cryptohome.xml for a brief listing of the APIs available.  Note that
the asyncrhonous APIs complete using a signal (AsyncCallStatus).  The completion
signals are guaranteed to be in-order.