PipeComm Kit

Two-Factor Authentication

Two-Factor Authentication is a process which requires two elements to verify the user identity. To prove that the user is who it claims to be, the PipeComm® Kit library require two items: the mSETM card and the user pinTFA 

Secure File System

The Secure File System is a set of mSE based APIs which allow developers to use posix-like file system functions to manage secure files. After authenticating and logging in the mSE card, the Secure File System class implements a virtual clear file system on the top of the physical encrypted file system.

It provides encryption and signature facilities, starting from two master keys (EncDBKey, SigDBKey) which are generated by the user inside the mSE through its physical RNG and never go outside the card.

Every secure file is encrypted and signed, sector by sector, using dedicated keys derived by the two mSE master keys.



The Secure File System allows standard applications to access standard file systems through an HW cryptographic layer

which performs data encryption, signature 

and name remapping.

whereisThe Secure File System is a virtual layer on the top of the regular file system.

All the secure files can be stored on several places (microSD flash, mobile phone flash, cloud, etc.).

You just need your mSE and the right login password to access your files!

However, if you want to make your secure file system portable, we suggest you to collect all your secure files on the mSE NAND Flash. As a nice side effect when you remove your mSE from the mobile phone, no track of your secure files is left on the device.

When you create a Secure File, the file name is coded in a way that nobody can recognize it looking directly at the physical file system.

The Coded File Name is calculated inside the mSE by a SHA256 of the real file name and the two mSE master keys:

Coded File Name = SHA256(File Name | EncDBKey | SigDBKey)


seclokEach Secure File is made up of several encrypted and signed sectors.

The first sector is dedicated to the Secure File header, which provides information on the file.

Two header fields (Random Number and Unique ID) are not encrypted, but only signed.secstruc

The Secure File System header is made up of the following fields:

  • RND = Random Number generated by the mSE physical RNG (clear)
  • MAGIC = Secure File System magic number

  • VER = Secure File version
UID = File Unique ID (clear)
  • UID_CNT = Unique ID Counter (clear)
  • FNAME_LEN = File Name length
  • FNAME = File Name


cryptopageIn order to optimize the Secure File System access speed, a crypto cache layer is implemented:

  • Each Secure File is cached in Crypto Pages (~8KB per page),
  • Each Crypto Page is made up of 8 sectors (506B per sector). 

The Crypto Cache is used to cache the file clear data in the RAM (protected by the MPU/MMU).

To Encrypt/Decrypt and Sign/Verify, two crypto streams (EncGrub, SigGrub) are generated by the mSE for each Crypto Page.

The Crypto Cache size is configurable by the application developer.

EncGrub and SigGrub are generated by/inside the mSE starting from the following parameters:

  • Secure File UID                           (unique per Secure File)
  • Secure File RND                          (unique per Secure File)
  • Secure File CodedName            (unique per Secure File)
  • Secure File Sector index            (unique per Secure File)
  • mSE EncDBKey, SigDBKey         (unique per mSE)


EncGrub Generation(SigGrub generation starts from SigDBKey)

The versioning feature allows developers to freeze the current Secure File version and invalidate all the previous ones.

Referring to the example below, let’s suppose to take a copy of all the Secure file changes during its life:
  • Before t3 all the Secure File copies can be accessed through the Secure File System APIs, if the right mSE is plugged in the device
  • After t3, the copies taken at t0, t1, t2 cannot be accessed as they are invalidated by the SetVersion API
  • At time t6 only the copy taken at t5, t6 can be managed, all the others are invalidated.


Due to the cryptographic architecture, all the Secure Files created with an mSE, can only be managed (open, read, write, close, etc.) with the same mSE.

In order to allow Secure File Transfer, two additional functions are provided: SendTo and Receive.

The SendTo function prepares a Secure File which can be received only by one or more declared mSE cards. It starts from a regular Secure File and creates a transient Secure File, which can be sent to other mSE cards.

The Receive function processes the transient Secure File and creates a regular Secure File. In case the destination mSE is not the one which the transient Secure File was created for, an error occurs.


Secure Files are implemented in order to prevent corruption due to application crashes, unexpected power off, etc. If a Secure File is corrupted, it is 99% certain that it was due to a tampering action, so we really suggest you to invalidate it. Nevertheless, in some case you may want to operate on the Secure File as well.

The Secure File check is done during the open, read and write operations. In case of corrupted sectors, there is a way to keep using the Secure File:

  • If the SecureFile header is corrupted you cannot operate on the Secure File. 

  • If the ReadFile function detects a corrupted sector it does not return data (it is supposed to retrieve garbage). 

  • If the WriteFile function detects a corrupted sector, it can still write data using the forceWrite flag. 
 In this case the corrupted sector is supposed to be full of garbage but you can overwrite it. If you overwrite all the garbage, you purify the sector, otherwise the final sector is a mix of garbage and right data. 

  • The OpenFile function just checks the header and the last sector. If the last sector is corrupted, it can open the file using the forceOpen flag. In this case the last sector is supposed to be full of garbage.