-
Notifications
You must be signed in to change notification settings - Fork 16
5. Advanced Topics
This section outlines the internal architecture on which the app is built. SecureFolderFS employs a layered encryption and authentication model to maintain both the integrity and confidentiality of your data. The login process may vary slightly depending on the chosen authentication method.
If you selected a password or key file for authentication, the contents of the secret sequence are used to hash and derive the Key Encryption Key (KEK) along with a salt value retrieved from the keystore file.
Since Vault V3, the KEK is derived using the Argon2id Key Derivation Function (KDF) with the following parameters:
- 32MiB of allocated memory size
- 2 parallelism lanes
- 2 cipher iterations
If you have selected Windows Hello or Android Biometrics as one of your authentication options, a challenge value read from a separate configuration file is signed using your device's attestation. The resulting cryptographic signature is then used to hash and derive the KEK.
-
Android Biometrics: On Android, the non-exportable RSA private key pair is stored in the Android KeyStore, protected by your biometric data. During the authentication process, the challenge is signed (using RSASSA-PKCS1-v1_5 + SHA256) and passed into the KDF.
-
Windows Hello: On Windows, the non-exportable RSA private key pair is stored within the device’s TPM module. The cryptographic signature is passed into the KDF.
If you have selected biometric authentication on an Apple device, a secret key material is used as the main parameter for key derivation. Contrary to the challenge mode, the “masterkey” is encrypted and stored in a separate configuration file.
- Face ID and Touch ID: On Apple platforms, the non-exportable private key pair is stored in the Keychain. During the authentication routine, encryption and decryption operations take place within the Secure Enclave. The key itself is protected with Elliptic Curve cryptography (secp256r1 curve for ECIES with X9.63 KDF + SHA256 and AES-GCM).
If a second authentication method is configured, its resulting key is appended to the primary key. This combined key — referred to as the passkey — is then processed using Argon2id to derive the KEK. The final KEK produced from the KDF operation unwraps the Data Encryption Key (DEK) and Message Authentication Code (MAC) keys using the AES Key Wrap algorithm (RFC 3394).
If during the credentials configuration phase, “Complementation” is used as the second-stage method, the process changes. Instead of appending to the passkey, the result of a cryptographic operation (generated by a given authentication method) is used to derive a separate Key Encryption Key. This KEK is then used to unwrap the DEK and MAC keys embedded directly in the complemented configuration file. In this case, the output is not combined with the primary key, and the KEK is not used to decrypt primary keystore file keys.
To ensure the authenticity of the configuration file, its properties are cryptographically signed using the unwrapped MAC key. The resulting HMAC-SHA256 signature is then compared to the one stored in the file. If both hashes match, the vault is considered genuine.
This section describes the encryption steps of the XChaCha20-Poly1305 (Extended Nonce) AEAD cipher mode.
Each written-to file is initialized with a unique 72-byte file header, composed of the following components:
| Component | Size | Description |
|---|---|---|
| Cryptographic Nonce | 24 B | Used as the extended nonce for XChaCha20 |
| Block Encryption Key | 32 B | CSPRNG key used to encrypt the file blocks |
| MAC Authentication Tag | 16 B | Poly1305 tag used for authentication |
The block encryption key (32 bytes) is encrypted using XChaCha20-Poly1305, with the cryptographic nonce passed as part of the encryption process. The resulting ciphertext is stored in the header, with the nonce prepended (first 24 bytes) and the MAC tag appended (last 16 bytes). In total, the ciphertext header consists of 72 bytes.
After a file's header is initialized and stored, the file's contents are encrypted in fixed-sized blocks using the XChaCha20-Poly1305 authenticated encryption algorithm. Each block can contain a maximum of 32KiB (32,768 bytes) of plaintext data. For the final block, the data is not padded or extended to meet the size limit — only the remaining bytes are encrypted.
During encryption, each plaintext block is transformed into a ciphertext block with the following layout:
| Component | Size | Description |
|---|---|---|
| Block Nonce | 24 B | A unique nonce generated using CSPRNG |
| Encrypted Data | 32 KiB | Ciphertext resulting from encryption of the block |
| Authentication Tag | 16 B | Poly1305 MAC tag for verifying integrity |
-
For each block, a unique 24-byte nonce is generated using a cryptographically secure pseudorandom number generator (CSPRNG) whenever a change is registered in that block.
-
To bind each block cryptographically to its context, the following is used as Additional Authenticated Data (AAD):
- The block number (sequential index), encoded in big-endian format
- The nonce from the file header
These two values are concatenated to form the AAD input to the cipher.
- The block is then encrypted using XChaCha20-Poly1305 with the following parameters:
- Key: the 32-byte header block key imported from the plaintext file header
- Nonce: the per-block unique 24-byte nonce
- AAD: the concatenated additional authentication data
- The final ciphertext block is prepended with a nonce (first 24 bytes) and appended with a MAC tag (last 16 bytes), equating to a 40-byte larger data imprint than its plaintext counterpart.
By default, SecureFolderFS uses AES-CMAC-SIV with Base4K to encrypt and encode file names. Each directory in the file system has an associated Initialization Vector (IV), stored in a special file, named dirid.iv. The exception is the root directory (i.e., the "content" folder), where the IV is always considered empty.
During the encryption process, the IV is read from the corresponding dirid.iv file and used as Additional Authenticated Data (AAD). The encryption key for the AES-CMAC-SIV instance is derived from the vault’s MAC key. The plaintext name is then encrypted using this configuration.
Depending on the option chosen during vault creation, the resulting ciphertext is encoded with either Base4K or Base64Url encoders, and a ".sffs" extension is appended to the final ciphertext name.