+
+
+
+Fully open source end-to-end encrypted photos, authenticators and more.
+
+
+
+# Ente
+
+Ente is a service that provides a fully open source, end-to-end encrypted
+platform for you to store your data in the cloud without needing to trust the
+service provider. On top of this platform, we have built two apps so far: Ente
+Photos (an alternative to Apple and Google Photos) and Ente Auth (a 2FA
+alternative to the deprecated Authy).
+
+This monorepo contains all our source code - the client apps (iOS / Android /
+F-Droid / Web / Linux / macOS / Windows) for both the products (and more planned
+future ones!), and the server that powers them.
+
+Our source code and cryptography have been externally audited by Cure53 (a
+German cybersecurity firm, arguably the world's best), Symbolic Software (French
+cryptography experts) and Fallible (an Indian penetration testing firm).
+
+Learn more at [ente.io](https://ente.io).
+
+
+
+Fully open source end-to-end encrypted photos, authenticators and more.
+
++ +## Ente Photos + + + +Our flagship product. 3x data replication. On device machine learning. Cross +platform. Private sharing. Collaborative albums. Family plans. Easy import, +easier export. Background uploads. The list goes on. And of course, all of this, +while being fully end-to-end encrypted. + +Ente Photos is a paid service, but we offer a free trial. You can also clone +this repository and choose to self host. + +
+ +
+
+[
](https://apps.apple.com/app/id1542026904)
+[
](https://play.google.com/store/apps/details?id=io.ente.photos)
+[
](https://f-droid.org/packages/io.ente.photos.fdroid/)
+[
](https://ente.io/download/desktop)
+[
](https://web.ente.io)
+
+
+
+](https://apps.apple.com/app/id1542026904)
+[](https://play.google.com/store/apps/details?id=io.ente.photos)
+[](https://f-droid.org/packages/io.ente.photos.fdroid/)
+[](https://ente.io/download/desktop)
+[](https://web.ente.io)
+
++ +## Ente Auth + + + +Our labour of love. Two years ago, while building Ente Photos, we realized that +there was no open source end-to-end encrypted authenticator app. We already had +the building blocks, so we built one. + +Ente Auth is currently free. If in the future we convert this to a paid service, +existing users will be grandfathered in. + +
+ +
+
+[](https://play.google.com/store/apps/details?id=io.ente.auth)
+[](https://play.google.com/store/apps/details?id=io.ente.auth)
+[](https://f-droid.org/packages/io.ente.auth/)
+[](https://auth.ente.io)
+
+
+
+](https://play.google.com/store/apps/details?id=io.ente.auth)
+[](https://play.google.com/store/apps/details?id=io.ente.auth)
+[](https://f-droid.org/packages/io.ente.auth/)
+[](https://auth.ente.io)
+
++ +## Contributing + +Want to get aboard the Ente hype train? Welcome along! Don't hesitate if you're +not a developer, there are many other important ways in which [you can +contribute](CONTRIBUTING.md). + +## Support + +We are never more than an email away. For the various ways to ask for help, +please see our [support guide](SUPPORT.md). + +## Community + +
+
+Please visit our [community page](https://ente.io/community) for all the ways to
+connect with the community.
+
+[](https://discord.gg/z2YVKkycX3)
+[](https://ente.io/blog/rss.xml)
+
+---
+
+## Security
+
+If you believe you have found a security vulnerability, please responsibly
+disclose it by emailing security@ente.io or [using this
+link](https://github.com/ente-io/ente/security/advisories/new) instead of
+opening a public issue. We will investigate all legitimate reports. To know
+more, please see our [security policy](SECURITY.md).
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..59efbca83
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,51 @@
+Ente believes that working with security researchers across the globe is crucial
+to keeping our users safe. If you believe you've found a security issue in our
+product or service, we encourage you to notify us, by email (security@ente.io)
+or by [filling this
+form](https://github.com/ente-io/ente/security/advisories/new) We welcome
+working with you to resolve the issue promptly. Thanks in advance!
+
+## Disclosure Policy
+
+- Let us know as soon as possible upon discovery of a potential security issue,
+ and we'll make every effort to quickly resolve the issue.
+- Provide us a reasonable amount of time to resolve the issue before any
+ disclosure to the public or a third-party. We may publicly disclose the issue
+ before resolving it, if appropriate.
+- Make a good faith effort to avoid privacy violations, destruction of data, and
+ interruption or degradation of our service. Only interact with accounts you
+ own or with explicit permission of the account holder.
+- If you would like to encrypt your report, please use the PGP key with long ID
+ `E273695C0403F34F74171932DF6DDDE98EBD2394` (available in the public keyserver
+ pool).
+
+## In-scope
+
+- Security issues in any current release of Ente's services. Product downloads
+ are available at https://ente.io. Source code is available at
+ https://github.com/ente-io.
+
+## Exclusions
+
+The following bug classes are out-of scope:
+
+- Bugs that are already reported on any of [Ente's issue
+ trackers](https://github.com/ente-io), or that we already know of (Note that
+ some of our issue tracking is private)
+- Issues in an upstream software dependency (ex: Flutter, Next.js etc) which are
+ already reported to the upstream maintainer
+- Attacks requiring physical access to a user's device
+- Self-XSS
+- Issues related to software or protocols not under ente's control
+- Vulnerabilities in outdated versions of ente
+- Missing security best practices that do not directly lead to a vulnerability
+- Issues that do not have any impact on the general public
+
+While researching, we'd like to ask you to refrain from:
+
+- Denial of service
+- Spamming
+- Social engineering (including phishing) of Ente staff or contractors
+- Any physical attempts against Ente property or data centers
+
+Thank you for helping keep Ente and our users safe!
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 000000000..78de03fcf
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,19 @@
+# Support
+
+We provide human support to our customers.
+
+Please write to [support@ente.io](mailto:support@ente.io) sharing as many
+details as possible about whatever it is that you need help with, and we will
+get back to you as soon as possible.
+
+In some cases, your query might already have been answered in our help
+documentation (_Coming soon!_).
+
+Other ways to get in touch are:
+
+* [Ask in our Discord](https://discord.gg/z2YVKkycX3)
+* [Start a new
+ discussion](https://github.com/ente-io/ente/discussions/new?category=q-a)
+* [Open a bug report in our issue
+ tracker](https://github.com/ente-io/ente/issues/)
+
diff --git a/architecture/README.md b/architecture/README.md
new file mode 100644
index 000000000..eef26f2fb
--- /dev/null
+++ b/architecture/README.md
@@ -0,0 +1,376 @@
+# Architecture
+
+Your data is end-to-end encrypted with Ente.
+
+Meaning, they are encrypted with your `keys` before they leave your device.
+
+
+
+Our source code has been [audited](https://ente.io/blog/cryptography-audit/) to
+verify that these `keys` are available only to you.
+
+Meaning, only you can access your data.
+
+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 this
+information will be surfaced 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.
+
+---
+
+## Data Encryption
+
+### Fundamentals
+
+#### Collection Key
+
+Each of your items 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 Reunion"). In case of Auth, we create a default root collection.
+
+Each `collection` has a `collectionKey`. These never leave your device
+unencrypted.
+
+
+
+#### File Key
+
+Every piece of your data has a `fileKey`. These never leave your device
+unencrypted.
+
+### Flows
+
+#### Upload
+
+- Each file and associated metadata is encrypted with randomly generated
+ `fileKey`s.
+- 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 `collectionKey`s.
+- Finally, you decrypt each file and associated metadata with the respective
+ `fileKey`s.
+
+### 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
+ `collectionKey`s.
+- Since only you have access to the `collectionKey`s, only you can decrypt the
+ `fileKey`s.
+- Since only you have access to the `fileKey`s, 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.
+
+#### Verification ID
+
+Verification ID is a human readable representation of a `publicKey`, that is
+accessible within the clients for verifying the identity of a receiver.
+
+#### 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 `fileKey`s.
+- Each of these `fileKey`s 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
+ `collectionKey`s.
+- Finally, they decrypt each file and associated metadata with the respective
+ `fileKey`s.
+
+
+
+### 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 `fileKey`s of files belonging to that album/folder.
+- Since only the receiver has access to the `fileKey`s of files belonging to
+ that album/folder, only they can decrypt the files and associated metadata.
+
+> A sender can view the Verification ID of the receiver within the app's sharing
+> screen, and compare this with the Verification ID displayed on the receiver's
+> device. The two identifiers matching across devices verifies the security of
+> end-to-end encryption between the two parties.
+
+------------------------------------------------------------------------
+
+## 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](#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](#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 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](#key-encryption-flows-secondary-device)).
+- Using this `masterKey`, the rest of your keys, including your `privateKey` is
+ decrypted (as discussed [here](#private-key)).
+- Using your `privateKey`, the client will then decrypt the `encryptedAuthToken`
+ that was earlier 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](https://libsodium.gitbook.io/doc/).
+
+#### Key Generation
+
+[`crypto_secretbox_keygen`](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes)
+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`](https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption#key-pair-generation)
+is used to generate your `publicKey` and `privateKey` pairs.
+
+#### Key Derivation
+
+[`crypto_pwhash`](https://libsodium.gitbook.io/doc/password_hashing/default_phf)
+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](https://github.com/P-H-C/phc-winner-argon2/raw/master/argon2-specs.pdf),
+which is regarded as [one of the best hashing
+algorithms](https://en.wikipedia.org/wiki/Argon2) currently available.
+
+#### Symmetric Encryption
+
+[`crypto_secretbox_easy`](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretbox)
+is used to encrypt your `masterKey`, `recoveryKey`, `privateKey`,
+`collectionKey`s and `fileKey`s. Internally, this uses
+[XSalsa20](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xsalsa20)
+stream cipher with [Poly1305
+MAC](https://datatracker.ietf.org/doc/html/rfc8439#section-2.5) for
+authentication.
+
+[`crypto_secretstream_*`](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream)
+APIs are used to encrypt your file data in chunks. Internally, this uses
+[XChaCha20](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xchacha20)
+stream cipher with [Poly1305
+MAC](https://datatracker.ietf.org/doc/html/rfc8439#section-2.5) for
+authentication.
+
+#### Asymmetric Encryption
+
+[`crypto_box_seal`](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes)
+is used in sharing to encrypt a `collectionKey` with the receiver's `publicKey`.
+It is also used to encrypt an `authToken` that is issued to a user, with their
+`publicKey`.
+
+Internally, this uses [X25519](https://en.wikipedia.org/wiki/Curve25519) for key
+exchange,
+[XSalsa20](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xsalsa20)
+stream cipher for encryption and [Poly1305
+MAC](https://datatracker.ietf.org/doc/html/rfc8439#section-2.5) for
+authentication.
+
+#### Salt & Nonce Generation
+
+[`randombytes_buf`](https://libsodium.gitbook.io/doc/generating_random_data) is
+used to generate a new salt/nonce every time data needs to be hashed/encrypted.
+
+#### Verification ID Generation
+Verification ID is generated by converting the `sha256` value of a `publicKey`
+to it's corresponding [BIP39](https://en.bitcoin.it/wiki/BIP_0039) mnemonic
+phrase.
+
+---
+
+## Further Details
+
+Thank you for reading this far! For implementation details, we request you to
+checkout [our code](https://github.com/ente-io).
+
+If you'd like to help us improve this document, kindly email
+[security@ente.io](mailto:security@ente.io).
+
+We have a [separate document](https://ente.io/reliability) that outlines how we
+replicate your data across 3 different cloud providers to ensure reliability.
diff --git a/architecture/assets/authentication.svg b/architecture/assets/authentication.svg
new file mode 100644
index 000000000..73c8c90b6
--- /dev/null
+++ b/architecture/assets/authentication.svg
@@ -0,0 +1,35 @@
+
diff --git a/architecture/assets/e2ee.svg b/architecture/assets/e2ee.svg
new file mode 100644
index 000000000..e77bcb9a2
--- /dev/null
+++ b/architecture/assets/e2ee.svg
@@ -0,0 +1,11 @@
+
diff --git a/architecture/assets/file-encryption.svg b/architecture/assets/file-encryption.svg
new file mode 100644
index 000000000..f9f8b2b37
--- /dev/null
+++ b/architecture/assets/file-encryption.svg
@@ -0,0 +1,26 @@
+
diff --git a/architecture/assets/key-derivation.svg b/architecture/assets/key-derivation.svg
new file mode 100644
index 000000000..a26ac115d
--- /dev/null
+++ b/architecture/assets/key-derivation.svg
@@ -0,0 +1,17 @@
+
diff --git a/architecture/assets/recovery.svg b/architecture/assets/recovery.svg
new file mode 100644
index 000000000..6ec619d41
--- /dev/null
+++ b/architecture/assets/recovery.svg
@@ -0,0 +1,33 @@
+
diff --git a/architecture/assets/sharing.svg b/architecture/assets/sharing.svg
new file mode 100644
index 000000000..a5c4d5dce
--- /dev/null
+++ b/architecture/assets/sharing.svg
@@ -0,0 +1,21 @@
+