Security/Tizen 4.X Ode/FOTA support

From Tizen Wiki
Jump to: navigation, search


  • Ode - "On device encryption". project providing components used for internal and external memory encryption.
  • oded - Ode daemon. A daemon responsible for internal and external memory encryption.
  • FOTA - "Firmware Over-The-Air update". A process of wireless update of the device's firmware by the manufacturer.
  • TrustZone - hardware based security solution by ARM.
  • TPM - "Trusted Platform Module". Microcontroller supporting several cryptographic operations with unique RSA private key embedded.

Internal memory encryption

A user may decide to encrypt the internal memory of the device. When he does, he is asked for a password that will be used to protect the master encryption key. Then the encryption of internal memory (the R/W partition containing user data) is started. After encryption is finished the device is rebooted. To mount the encrypted internal memory during booting, the user has to provide the password. Without the password the internal memory will be inaccessible.

The FOTA process

During the process of the FOTA a binary data necessary to perform the update (partition images/diff files) is firstly stored in device's internal memory. Then the device is rebooted to a special basic mode of operation to perform the actual upgrade. Neither services nor applications are allowed to run at this point. The binary data stored previously in internal memory is used to modify the existing partitions (initrd, kernel, binaries). After that, upgrade scripts are launched to perform necessary upgrades/migration of individual system components. The actual implementation of the FOTA process may differ between specific products.

If binary data used for the FOTA is stored in the encrypted internal memory, then it will be inaccessible after the reboot until user provides the password. However, because of upgrade state limitations, the password retrieving application as well as Ode daemon are not allowed to run. As a result, it is impossible to get user's password, mount the internal memory and read the data necessary to perform the FOTA. The master key must be obtained using different method.

As mentioned earlier, the implementation of the FOTA process may differ between products. Also the list of possible methods for providing the master key during the FOTA process depends on the availability of certain features (like TrustZone, TPM or other hardware supported security solutions) and limitations (like partition size, UI capabilities, etc.) of specific product.

In order to abstract from specific product, the platform provides a key storage plugin framework allowing each product development team to implement their own product specific plugin responsible for providing the master key for the purpose of the FOTA.

Key storage plugin framework

Key storage plugin framework flow & architecture

Key storage plugin

The plugin must provide the following 3 functions in its API:

  • int ode_ksp_store(const unsigned char* key, size_t key_len, unsigned char** token, size_t* token_len)
The function responsible for preparation for the FOTA process accepting the master key as an argument. The function is expected to return an identifier (token). After this function returns the plugin should be able to retrieve the master key using the token.
Typically, this function should be used to securely store the received master key. However, if the plugin uses the existing Ode key storage and is able to retrieve the password protecting it from the user during the FOTA then this function doesn't have to store any data.
  • int ode_ksp_load(const unsigned char* token, size_t token_len, unsigned char** key, size_t* key_len)
The function responsible for providing the master key during the FOTA. The token returned during the "store" operation will be used to identify the key that is requested.
  • int ode_ksp_remove(const unsigned char* token, size_t token_len)
The function responsible for removing any data stored by the plugin as a result of the "store" operation. This function should normally be called after the FOTA is finished and the stored data is no longer necessary.

Make sure that key related data is removed as soon as possible to limit the possibility of an attack.

The ode-ksp-devel rpm package build from the Ode repository provides a plugin API header and a *.pc file that can be used for key storage plugin development. The header also contains a detailed description of each API function.


Ode provides an API that allows to prepare for the FOTA using the existing key storage plugin (operation (1) on the diagram):

int ode_key_store_master_key(const char* device, const char* password).

The function requires a user's password to obtain the master key. Retrieved key is passed to the key storage plugin using ode_ksp_store() which may use the key to prepare for the FOTA (operation (3)). Returned token is saved in an unencrypted partition (operation (4)). If for some reason the token or key related data was not removed during the FOTA or the whole process failed, it may be removed using another Ode API function:

int ode_key_remove_master_key(const char* device)

This function will firstly call the plugin's ode_ksp_remove() and then remove the token from unencrypted partition.

Refer to the Ode API for detailed description of both functions.

Note that this API requires the presence of the key storage plugin.

Make sure that all key related data is removed as soon as possible to limit the possibility of an attack.

Ode-fota binary

Ode project provides an ode-fota binary that shares encryption module (responsible for internal memory encryption) and key storage module (responsible for master key & token management) with oded. The binary can be used to mount the encrypted partition during the FOTA and remove the key related data after the FOTA is finished. Binary forwards both these requests to the key storage plugin.

Refer to ode-fota for usage details.

Master key migration

There are products based on older Tizen versions using different, incompatible encryption scheme and footer format. To properly migrate their master key during the FOTA it has to be stored in unencrypted form using the key storage plugin and then encrypted and saved using the new scheme and footer format during the first device unlock.

Detailed steps:

  1. The ode-fota is used to mount the user partition using the master key retrieved from key storage plugin. It leaves a file flag (/opt/etc/.ode_upgrade_started) to mark the beginning of the upgrade process.
  2. Upgrade is performed.
  3. The oded is started and a the device is unlocked for the first time using a password.
  4. If oded detects the file flag left in step 1 it will use the key storage plugin to retrieve the master key once again. Otherwise it will try to decrypt the master key with password and mount the user partition as usual (remaining steps are skipped).
  5. If master key is retrieved oded encrypts it with a password received during the first unlock using the new encryption scheme. It is assumed that the password is verified elsewhere prior to ode_internal_encryption_set_mount_password().
  6. The master key in encrypted form is stored in the footer using the new footer format.
  7. The file flag is removed.

For unaffected products that do not require the key migration it's enough to remove the file flag or the master key stored for the purpose of the upgrade before calling ode_internal_encryption_set_mount_password(). Note that it is advised to remove the master key stored for the purpose of the upgrade as soon as possible after the upgrade due to security reasons. Even if the flag and master key are present, the encryption introduced in this commit won't break anything as long as the password is correct.


Ode provides a command line tool and a dummy key storage plugin that together with ode-fota allow testing the platform code by simulating the FOTA on encrypted internal memory.

Command line tool

ode-admin-cli provides a possibility to encrypt internal memory and store the master key using existing plugin. The ode-admin-cli uses Ode API underneath. Refer to ode-admin-cli for usage details. After the key has been stored the device can be rebooted and the encrypted partition can be mounted using ode-fota binary.

Dummy key storage plugin

The dummy key storage plugin is a test plugin implementing the required key storage plugin API. Ode provides it in ode-dummy-ksp rpm package. The plugin does not implement any protection of the stored key. The master key is simply copied to the token and returned. As a result it is exposed to an offline attack.

Do not use the dummy key storage plugin in the product as it will expose the master encryption key to an offline attack.