Documentation/pfk.txt

Introduction
============
Per-File-Key (PFK) driver.

This is part of solution to provide per-file encryption functionality
with ICE accelerated eCryptfs.

Objective
=========
Android devices are being used by individuals to access information on
the go. This increases the risk of their information being leaked if
device is stolen or lost. One of the security measures to protect the
user information on the device is to encrypt the data. If the device is
lost or stolen, it minimizes the risk that unknown person would be able
to extract the information from the device.

Android provides an encryption mechanism to encrypt the user data on the
device. However currently only Full-Disk encryption method is supported
there are other solutions via software only. While there
are filesystem-level encryption solutions (such as eCryptfs), non of
those are part of the Android and are user-space solution
based.

Andoid has open source stack file system with encryption. Up until now
it was not enabled for QTI targets. Starting now, it will be
enabled with enhanced hardware support provided by Inline Crypto Engine
(ICE).


Solution
========
The PFK driver is part of solution to provide per-file encryption
functionality. PFK is designed to provide three main services:
1. Store File Encryption Key (FEK) information for each inode in
eCryptfs system during runtime.
2. Provide interfaces for ICE Layer to store and remove FEK to/from ICE
engine.
3. Provide interface for Block Layer that will determine whether 2 requests
can be merged into one.


Hardware description
====================
PFK will only be invoked if hardware encryption is enabled and ICE is present.

Software description
====================

                            Software component diagram
                            --------------------------

   +++++++++++++++++++++++                   +++++++++++++++
   +        VFS          +                -- +    P F K    + ---
   +++++++++++++++++++++++               |   +++++++++++++++    |
   + EXT4   +  eCryptfs  + ---------------    | |               |
   +++++++++++++++++++++++                    | |               |
   +    Block Layer      + -------------------- |               |
   +++++++++++++++++++++++                      |               |
   +++++++++++++++++++++++                      |         ++++++++++++++
   +    ICE Driver       + ----------------------         +     TZ     +
   +++++++++++++++++++++++                                +            +
   +++++++++++++++++++++++                                +   +++++++  +
   +        ICE          + -----------------------------  +   + scm +  +
   +++++++++++++++++++++++                                ++++++++++++++

When eCryptfs  opens file, eCryptfs generates random File Encryption
Key and invokes callback in PFK module. PFK stores the key inside eCryptfs
file inode. Later, when ICE driver configures ICE hardware for a particular
request, it queries PFK with that request. PFK fetches the FEK that was
stored earlier in inode and loads it to available empty key index in TZ and
returns the index number back to ICE driver, which can now configure ICE
to use particular key index for encryption/decryption. PFK manages internal
cache table with keys that were loaded to TZ. If the number of files open
simultaneously is bigger than the table size, the oldest entry is evicted.
Key is loaded to TZ only if it is not present in cache table.
When file is released (was closed by all its users), another PFK callback
is invoked and it removes the entry from cache table and invalidates
file's FEK in TZ.
Additionally, when block layer tries to merge 2 requests it also queries
PFK to determine whether 2 blocks can be merged (belong to the same
encrypted file).

Power management
================
None.

SMP/multi-core
==============
Cache table in PFK can be modified/accessed from multiple threads/processes
therefore it is protected by mutexes/spinlocks.

Security
========
This module is part of secure Per File Encryption solution. Each file
is encrypted with its own random key, which in turn is encrypted with key
provided by user during mount.

Performance
===========
In general, eCryptfs with ICE acceleration gives practically line-rate
performance for encryption/decryption.

Interfaces
==========
Interface for eCryptfs
----------------------
pfk_open_cb() - callback invoked when file is opened.
pfk_release_cb() - callback invoked when file is released.
pfk_is_cipher_supported_cb() - determines whether a particular cipher
is supported by PFK module.
pfk_is_hw_crypt_cb() - tells whether PFK module uses HW encryption.

Interface for Block Layer
------------------------------------------
pfk_allow_merge_bio() - determine whether two requests can be merged.

Interface for ICE
------------------------------------------
pfk_load_key() - loads the key to TZ and returns key index.

Interfaces for external modules
------------------------------------------
pfk_remove_key() - allows removing key from TZ and from key cache at any
time for security reasons.

Dependency
==========
eCryptfs.

User space utilities
====================
None. User can't interract with PFK directly.

Known issues
============
None.

To do
=====
None.