Some of the directories in UBFS, or the whole UBIFS volume, which are used to store important data need to be encrypted, the FS-Crypt service encrypts the directories/volumes.

FS-Crypt provides interfaces that create encryption directories. Working with FS-Crypt, client applications can lock/unlock specified directories. This component generates 156-bit AES keys, sets policy to specified directories with the generated key, and locks/unlocks data by adding/removing keys to/from the kernel keyring.

IPC interfaces binding

The functions of this API are provided by the tafKeyStoreSvc application service.

The following example illustrates how to bind to the FS-Crypt service.

bindings:
{
    clientExe.clientComponent.taf_fsc -> tafKeyStoreSvc.taf_fsc
}

Storage management

FS-Crypt storage can be initialized by calling taf_fsc_GetStorageRef() with the specified directory path as the input parameter. If the specified directory doesn't exist in the current system, a new one with the given name will be created. A storage reference is returned to the client for FS-Crypt storage operations.

Applications only call the following interfaces to finish storage manipulation and there is no need to care about key management or encryption and decryption operation as these actions will be maintained at the service backend. The following storage APIs are supported.

taf_fsc_GetStorageRef() – Gets the FS-Crypt storage object reference.
taf_fsc_LockStorage() – Removes an FS-Crypt key from the kernel keyring to lock the directory.
taf_fsc_UnlockStorage() – Adds an FS-Crypt key to the kernel keyring to unlock the directory.
taf_fsc_DeleteStorage() – Cleans the FS-Crypt directory and ecryption key.

The following example illustrates how to initialize FS-Crypt storage and lock the directory.

le_result_t result;
taf_fsc_StorageRef_t storageRef = taf_fsc_GetStorageRef("/app/test", &result);
if(LE_OK == result){
    // Process of the storage
}
else{
    // Error process
}
result == taf_fsc_LockStorage(storageRef);
if(LE_OK == result){
    // Process of the storage
}
else{
    // Error process
}

Note: Storage will be unlocked after calling taf_fsc_GetStorageRef.

After calling taf_fsc_GetStorageRef, the generated key for the specified directory is added to the kernel keyring, meaning that the storage is in the Unlocked state and the client app can access the directory without calling taf_fsc_UnlockStorage().

Note: The key removing mechanism will be triggered during shutdown.

To avoid raw keys being copied from non-volatile storage, the service removes all keys from the kernel keyring when the system is shutting down.

The FS-Crypt encryption feature only supports "UBIFS on-flash format version 5", trying to encrypt for unexpected UBIFS format versions results in an error.