| # Unlock |
| |
| [TOC] |
| |
| ## Overview |
| |
| Before the user's cryptohome can be used by the rest of the system, it should be |
| decrypted and mounted. Cryptohome encryption keys are stored on disk and are |
| encrypted themselves. There are multiple protection mechanisms employed for the |
| purpose, and they are also used as a secondary - offline - authentication |
| mechanism for the user supplied credentials/secrets/etc. Regardless of the |
| mechanism employed, the filesystem encryption keys are encrypted either though |
| TPM or through the use of ['scrypt']. |
| |
| ## VKK (current, to be deprecated) |
| |
| The vault keyset (vault_keyset.cc/h) contains the file encryption key and file |
| name encryption key is used by filesystem encryption mechanisms. 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 attempt 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) follows the above operations in reverse |
| (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. |
| |
| [`scrypt`]: http://www.tarsnap.com/scrypt.html |
| |
| ## AuthSession + USS (in development) |
| |
| *TBD* |
| See [architecture.md](architecture.md) |
| |
| ## LockScreen |
| |
| Offline login and screen unlock is processed through cryptohome using a test |
| decryption of the user's keyset 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 during |
| mount attempt and preserved throughout the life time of the mount. The user |
| session is torn down upon unmount, or have the verifier changed upon key change. |
| If user session doesn't contain a valid verifier for the user, 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). |
| |
| ## Vault creation and password change |
| |
| 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 (and 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. |
