PFK (Per-File-Key) driver architecture document.

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.