-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add end-to-end encryption as a principle #535
Open
MGibson1
wants to merge
44
commits into
main
Choose a base branch
from
ps/include-end-to-end-encryption-in-security-principles
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+125
−0
Open
Changes from all commits
Commits
Show all changes
44 commits
Select commit
Hold shift + click to select a range
648221f
feat: add new security section
coroiu 585c402
feat: port definitions
coroiu bf8369d
feat: add first principle
coroiu e65f223
feat: add second principle
coroiu cebbeb3
feat: add third principle
coroiu 40a8bb7
feat: add note about TEEs to P03
coroiu 6e650d7
chore: change protection > security
coroiu bcd9467
feat: add forth principle
coroiu 8da13ec
feat: add fifth principle
coroiu 4c755bb
feat: add fifth principle
coroiu e958797
feat: add an overview page
coroiu 5d8a121
fix: remove repetition
coroiu 3247efe
chore: rename file to match content
coroiu f9e585d
refactor: use hyphen in title
coroiu 425f808
fix: links
coroiu e4f44ea
refactor: remove any after comment
coroiu b4a8c8d
feat: add current version of requirements
coroiu 0222f3f
feat: add introduction to requirement structure
coroiu 663b464
feat: add Client definition
coroiu aaca302
fix: tweak user definition
coroiu 0373e12
feat: add technical consideration section to P01
coroiu 528330f
fix: clarify which data locking protects
coroiu d5548f7
fix: typo
coroiu 563e3a7
fix: change `linger` to `not present in memory`
coroiu 83f0d56
fix: re-define sharing to match EA, previous definition of sharing is…
coroiu 8eceee3
fix: font-weight
coroiu 952a43c
feat: add token protected in transit req
coroiu 7de826f
feat: change AT.2 to `must`
coroiu 43c1e0e
chore: move security under architecture
coroiu 43675f6
fix: various copy feedback
coroiu e029710
Add end-to-end encryption as a principle
MGibson1 58f1f95
Merge branch 'main' into ps/include-end-to-end-encryption-in-security…
quexten 9f7fec3
Clarify principle overview
MGibson1 ec84aaf
Prefer existing language for requirements
MGibson1 9d2fc0c
remove typo
MGibson1 599521c
Describe key connector for users
MGibson1 80334b5
Clarify icon service exception
MGibson1 b10e0d1
Prefer data as singular or uncountable
MGibson1 4623c49
Clarify degradation of security
MGibson1 e2753a5
Add clear text injection protection
MGibson1 7f3cf5d
simplify sentences
MGibson1 ccc448b
Use established terms and remove PM-centric phrases
MGibson1 d01c545
Clarify icon service purpose
MGibson1 937c91d
Tweak title and provide friendlier overview
MGibson1 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
48 changes: 48 additions & 0 deletions
48
docs/architecture/security/principles/01-servers-are-not-trusted.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
# P01 - Servers are zero knowledge | ||
|
||
There is no possibility for an attacker or Bitwarden employee to access your unencrypted data by | ||
compromising Bitwarden's infrastructure. Bitwarden has no ability to decrypt or add to your data. | ||
Your key, which Bitwarden cannot access, is the only thing that can be used to decrypt your data or | ||
create new encrypted data. | ||
|
||
More precisely, the special status of providing a network sync for client data does not grant the | ||
server, or any intermediary between the server and client, the ability to reduce the effective | ||
security of the protections that guard a user's data. If a user chooses a weaker form of protection | ||
(e.g., a password instead of a passkey), that is an intentional user decision, but the server must | ||
not be able to manipulate or coerce a client into reducing security beyond what the user knowingly | ||
configures. Additionally. the server and any necessary infrastructure cannot masquerade chosen clear | ||
text data as belonging in the set of a users encrypted data. The total sum of a user's encrypted | ||
data is fully isolated from the server and infrastructure. It cannot be read nor expanded outside of | ||
the user's client context. | ||
|
||
This is what we mean when we sometimes refer to "End-to-end encrypted" or "Zero Knowledge." | ||
|
||
## Account key sharing as a feature | ||
|
||
This principle does not mean that clear text data is never shared, but rather that any such exposure | ||
requires informed and explicit consent from the user and is exclusively between accounts, never to | ||
the server or infrastructure. | ||
|
||
## Exceptions | ||
|
||
On occasion, product features require breaking this principle in a controlled manner. These | ||
exceptions are always a last resort, tightly limited scope, and we are always looking for | ||
improvements to remove them. All exceptions are outlined here. | ||
|
||
### Key Connector | ||
|
||
Key connector is a self-host only feature that allows an organization user to log in and unlock with | ||
SSO and no password input. This feature is specifically limited to self-hosted instances due to this | ||
principle. It is possible for a Bitwarden server to create an authentication token, contact the Key | ||
Connector server, and retrieve key material that will allow decryption of a user's encrypted data. | ||
For these reasons we encourage strict isolation of key connector servers to private networks and | ||
only to be used by advanced self-hosted users. | ||
|
||
### Icons service | ||
|
||
The Bitwarden icons service provides site favicons to decorate vault items in the Bitwarden clients. | ||
To enable this functionality, clients need to send clear text domain name information to the | ||
service. Communicated information is limited to vault item URIs. These URIs are part of a user's | ||
encrypted content, but we do this to speed up loading of vaults, ensure favicons accurately | ||
represent the associated URI, and avoid leaking vault contents to local network administrators. This | ||
feature is easily disabled in client settings. |
21 changes: 21 additions & 0 deletions
21
docs/architecture/security/principles/02-locked-vault-is-secure.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
# P02 - A locked vault is secure | ||
|
||
Clients must ensure that highly sensitive vault data cannot be accessed in plain text once the vault | ||
has been locked, even if the device becomes compromised after the lock occurs. Protections are not | ||
guaranteed if the device is compromised before the vault is locked. | ||
|
||
## Technical Considerations | ||
|
||
Achieving this principle depends on the limitations of the platform and environment. For instance, | ||
in environments like JavaScript, where memory management is not fully under the control of the | ||
client, there may be residual plaintext in memory after the vault is locked. While ideal protection | ||
cannot be guaranteed in such cases, efforts must be made to minimize these risks through techniques | ||
such as clearing memory buffers and leveraging platform security features when available. | ||
|
||
## Key storage mechanisms must provide adequate protection | ||
|
||
Mechanisms used for storing encryption keys when the vault is locked, such as PINs or auto-login, | ||
must provide an appropriate level of security. If encryption keys are stored in less secure | ||
environments (e.g. in the OS's keyring), the associated risks must be carefully considered and | ||
mitigated to ensure that unauthorized access to the vault remains limited, even when convenience | ||
features are used. |
17 changes: 17 additions & 0 deletions
17
docs/architecture/security/principles/03-limited-security-on-semi-compromised.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
# P03 - Limited security for vaults on semi-compromised devices | ||
|
||
:::info Note | ||
|
||
This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details | ||
on protections for locked vaults. | ||
|
||
::: | ||
|
||
A semi-compromised device is one where malware exists in User Space but has not breached Kernel or | ||
OS-level protections. On such devices, clients must leverage available protections to prevent | ||
malware from accessing plaintext vault data while the vault is unlocked. | ||
|
||
- **Technical controls** (e.g., data compartmentalization or HSMs): Clients should maximize the use | ||
of Kernel/OS-level protections or other available system mechanisms to safeguard vault data. | ||
- **Administrative controls** (e.g., biometrics, 2FA, approval flows): Clients should balance | ||
security and usability, avoiding excessive complexity in the user flow. |
21 changes: 21 additions & 0 deletions
21
docs/architecture/security/principles/04-no-security-on-fully-compromised.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
# P04 - No security on fully compromised systems | ||
|
||
:::info Note | ||
|
||
This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details | ||
on protections for locked vaults. | ||
|
||
::: | ||
|
||
:::info Note | ||
|
||
Bitwarden does not currently support Trusted Execution Environments (TEEs). While TEEs could | ||
potentially provide a secure processing space for vault data on compromised devices, their use is | ||
limited by the environments in which Bitwarden operates. For this reason, TEEs are not considered | ||
when defining what constitutes a fully compromised device. | ||
|
||
::: | ||
|
||
When hardware or OS-level integrity is fully compromised, vault data may become accessible to | ||
attackers. While Bitwarden continuously strives to provide robust protections, certain threats fall | ||
beyond the reach of software-based security measures. |
7 changes: 7 additions & 0 deletions
7
docs/architecture/security/principles/05-controlled-access.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# P05 - Controlled access to vault data | ||
|
||
Clients must ensure that vault data, whether at rest or in use, is accessible only to authorized | ||
parties and always under the user's explicit control. Even when unlocked, access to vault data must | ||
be carefully restricted to specific contexts, such as autofill or explicit user actions. Isolation | ||
mechanisms must be employed, particularly in environments prone to unauthorized access—such as | ||
browsers—to prevent exposure to third parties without the user's consent. |
11 changes: 11 additions & 0 deletions
11
docs/architecture/security/principles/06-minimized-impact-of-security-breaches.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
# P06 - Minimized impact of security breaches | ||
|
||
Even with robust security measures in place, user error or unforeseen vulnerabilities can lead to | ||
various security breaches, including the compromise of encryption keys or data leaks. Bitwarden | ||
should take available actions to help users limit the damage caused by such breaches, both in scope | ||
and duration. This includes: | ||
|
||
- Detecting and invalidating compromised device sessions. | ||
- Rotating encryption keys to reduce the risk of “harvest now, decrypt later” attacks (forward | ||
secrecy). | ||
- Ensuring that any data added after a breach remains secure, maintaining post-compromise security. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And one more general question/suggestion, what would you think about moving this down one step to P02? In my head this could be seen as an extension to
P01 - Locked vault is secure
if we define that a locked vault is what is sent to the server:Or am I stretching it and it would be better to keep different use-cases separate?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would highly recommend keeping the locally encrypted state separate from the cloud encrypted shared state TBH.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah you are probably right, disregard this :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not necessarily against moving, but I put this first because I feel it's the justification for why we exist, we make software that is end-to-end encrypted and we need to be clear about what that means.