architecture

Your data is end-to-end encrypted with ente. Meaning, they are encrypted with your keys before they leave your device.

These keys are available only to you. Meaning only you can access your data else where.

What follows is an explanation of how we do what we do.

Key Encryption

Fundamentals

Master Key

When you sign up for ente, your client generates a masterKey for you. This never leaves your device unencrypted.

Key Encryption Key

Once you choose a password, a keyEncryptionKey is derived from it. This never leaves your device.

Flows

Primary Device

During registration, your masterKey is encrypted with your keyEncryptionKey, and the resultant encryptedMasterKey is then sent to our servers for storage.

Secondary Device

When you sign in on a secondary device, after you successfully verify your email, our servers give you back your encryptedMasterKey that was sent to us by your primary device.

You are then prompted to enter your password. Once entered, your keyEncryptionKey is derived, and the client decrypts your encryptedMasterKey with this, to yield your original masterKey.

If the decryption fails, the client will know that the derived keyEncryptionKey was wrong, indicating an incorrect password, and will surface this information to you.

Privacy

  • Since only you know your password, only you can derive your keyEncryptionKey.
  • Since only you can derive your keyEncryptionKey, only you have access to your masterKey.

Keep reading to learn about how this masterKey is used to encrypt your data.


File Encryption

Fundamentals

Collection Key

Each of your files in ente belong to what we call a collection. A collection can be either a folder (like "Camera" or "Screenshots") or an album (like "Awkward Team Lunch").

Each collection has a collectionKey. These never leave your device unencrypted.

File Key

Each of your files have a fileKey. These never leave your device unencrypted.

Flows

Upload

  • Each file and associated metadata is encrypted with randomly generated fileKeys.
  • Each fileKey is encrypted with the collectionKey of the collection (folder/album) the file belongs to. In case such a collection does not exist, one is created with a randomly generated collectionKey. All collection metadata (like name, folder-path, etc) are encrypted with this collectionKey.
  • Each collectionKey is then encrypted with your masterKey.
  • All of the above mentioned encrypted data is then pushed to the server for storage.

Download

  • All of the above mentioned encrypted data is pulled from the server.
  • You first decrypt each file’s collectionKey with your masterKey.
  • You then decrypt each file’s fileKey with their respective collectionKeys.
  • Finally, you decrypt each file and associated metadata with the respective fileKeys.

Privacy

  • As explained in the previous section, only you have access to your masterKey.
  • Since only you have access to your masterKey, only you can decrypt the collectionKeys.
  • Since only you have access to the collectionKeys, only you can decrypt the fileKeys.
  • Since only you have access to the fileKeys, only you can decrypt the files and their associated metadata.

Sharing

Fundamentals

Public Key

When you sign up for ente, your app generates a publicKey for you. This is public, and is stored at our servers in plain text.

Private Key

Along with the publicKey, your app also generates a corresponding privateKey for you. This never leaves your device unencrypted.

The privateKey is encrypted with your masterKey that only you have access to. This encryptedPrivateKey is stored at our servers

Flow

Sharing is similar to the previous section, except that the collectionKey of a collection is shared with a receiver after encrypting it with the receiver's publicKey. To elaborate,

Sender

  • Each file and associated metadata was already encrypted with randomly generated fileKeys.
  • Each of these fileKeys were also encrypted with the collectionKey of the collection (folder/album) that is now being shared.
  • The collectionKey is now encrypted with the publicKey of the receiver.
  • All of the above mentioned encrypted data is then pushed to the server for storage.

Receiver

  • All of the above mentioned encrypted data is pulled from the server.
  • The receiver first decrypts the collectionKey with their privateKey.
  • They then decrypt each file’s fileKey with their respective collectionKeys.
  • Finally, they decrypt each file and associated metadata with the respective fileKeys.

Privacy

  • Since only the receiver has access to their masterKey, only they can decrypt their encryptedPrivateKey to access their privateKey.
  • Since only the receiver has access to their privateKey, only they can decrypt the collectionKey that was sent to them.
  • Since only the receiver has access to the collectionKey, only they can decrypt the fileKeys of files belonging to that album/folder.
  • Since only the receiver has access to the fileKeys of files belonging to that album/folder, only they can decrypt the files and associated metadata.
Currently you have to trust our servers to give you the correct publicKey. It's technically possible for the receiver to share this information with you on a separate channel. This feature (to export and import public keys) is currently not available, and will be added if necessary. If you care about this, please upvote this feature within the "roadmap" section of the app, or email [email protected]. It will be prioritized.

Key Recovery

Fundamentals

Recovery Key

When you sign up for ente, your app generates a recoveryKey for you. This never leaves your device unencrypted.

Flow

Storage

Your recoveryKey and masterKey are encrypted with each other and stored on the server.

Access

This encrypted recoveryKey is downloaded when you sign in on a new device. This is decrypted with your masterKey and surfaced to you whenever you request for it.

Recovery

Post email verification, if you’re unable to unlock your account because you have forgotten your password, the client will prompt you to enter your recoveryKey.

The client then pulls the masterKey that was earlier encrypted and pushed to the server (as discussed in Key Encryption), and decrypts it with the entered recoveryKey. If the decryption succeeds, the client will know that you have entered the correct recoveryKey.

Now that you have your masterKey, the client will prompt you to set a new password, using which it will derive a new keyEncryptionKey. This is then used to encrypt your masterKey and this new encryptedMasterKey is uploaded to our servers, similar to what was earlier discussed in Key Encryption.

Privacy

  • Since only you have access to your masterKey, only you can access your recoveryKey.
  • Since only you can access your recoveryKey, only you can reset your password.

Authentication

Fundamentals

One Time Token

When you attempt to verify ownership of an email address, our server generates a oneTimeToken, that if presented confirms your access to the said email address. This token is valid for a short time and can only be used once.

Authentication Token

When you successfully authenticate yourself against our server by proving ownership of your email (and in future any other configured vectors), the server generates an authToken, that can from there on be used to authenticate against our private APIs.

Encrypted Authentication Token

A generated authToken is returned to your client after being encrypted with your publicKey. This encryptedAuthToken can only be decrypted with the your privateKey

Flow

  • You are asked for an email address, to which a oneTimeToken is sent.
  • Once you present this information correctly to our server, an authToken is generated and an encryptedAuthToken is returned to you, along with your other encrypted keys.
  • You are then prompted to enter your password, using which your masterKey is derived (as discussed here).
  • Using this masterKey, the rest of your keys, including your privateKey is decrypted (as discussed here).
  • Using your privateKey, the client will then decrypt the encryptedAuthToken that was encrypted by our server with your publicKey.
  • This decrypted authToken can then from there on be used to authenticate all API calls against our servers.

Security

Only by verifying access to your email and knowing your password can you obtain an authToken that can be used to authenticate yourself against our servers.


Implementation Details

We rely on the high level APIs exposed by this wonderful library called libsodium.

Key Generation

crypto_secretbox_keygen is used to generate all random keys within the application. Your masterKey, recoveryKey, collectionKey, fileKey are all 256-bit keys generated using this API.

Key Pair Generation

crypto_box_keypair is used to generate your publicKey and privateKey pairs.

Key Derivation

crypto_pwhash is used to derive your keyEncryptionKey from your password.

crypto_pwhash_OPSLIMIT_SENSITIVE and crypto_pwhash_MEMLIMIT_SENSITIVE are used as the limits for computation and memory respectively. If the operation fails due to insufficient memory, the former is doubled and the latter is halved progressively, until a key can be derived. If during this process the memory limit is reduced to a value less than crypto_pwhash_MEMLIMIT_MIN, the client will not let you register from that device.

Internally, this uses Argon2 v1.3, which is regarded as one of the best hashing algorithms currently available.

Symmetric Encryption

crypto_secretbox_easy is used to encrypt your masterKey, recoveryKey, privateKey, collectionKey s and fileKeys.
Internally, this uses XSalsa20 stream cipher with Poly1305 MAC for authentication.

crypto_secretstream_* APIs are used to encrypt your file data in chunks.
Internally, this uses XChaCha20 stream cipher with Poly1305 MAC for authentication.

Asymmetric Encryption

crypto_box_seal is used to encrypt collectionKey along with the receiver's publicKey for a folder/album that is to be shared with them.

Salt & Nonce Generation

randombytes_buf is used to generate a new salt/nonce every time data needs to be hashed/encrypted.


Further Details

Thank you for reading so far! For deeper implementation details, we request you to kindly checkout our code.

If you have any questions or concerns, or if you'd like to add yourself to the list of reviewers below, please drop an email to [email protected].


Reviewers

ente - play store