Skip to content
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
wants to merge 44 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
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 Nov 22, 2024
585c402
feat: port definitions
coroiu Nov 22, 2024
bf8369d
feat: add first principle
coroiu Nov 22, 2024
e65f223
feat: add second principle
coroiu Nov 25, 2024
cebbeb3
feat: add third principle
coroiu Nov 25, 2024
40a8bb7
feat: add note about TEEs to P03
coroiu Nov 25, 2024
6e650d7
chore: change protection > security
coroiu Nov 25, 2024
bcd9467
feat: add forth principle
coroiu Nov 25, 2024
8da13ec
feat: add fifth principle
coroiu Nov 25, 2024
4c755bb
feat: add fifth principle
coroiu Nov 25, 2024
e958797
feat: add an overview page
coroiu Nov 25, 2024
5d8a121
fix: remove repetition
coroiu Nov 25, 2024
3247efe
chore: rename file to match content
coroiu Nov 25, 2024
f9e585d
refactor: use hyphen in title
coroiu Nov 25, 2024
425f808
fix: links
coroiu Nov 25, 2024
e4f44ea
refactor: remove any after comment
coroiu Nov 25, 2024
b4a8c8d
feat: add current version of requirements
coroiu Nov 26, 2024
0222f3f
feat: add introduction to requirement structure
coroiu Nov 26, 2024
663b464
feat: add Client definition
coroiu Dec 10, 2024
aaca302
fix: tweak user definition
coroiu Dec 10, 2024
0373e12
feat: add technical consideration section to P01
coroiu Dec 10, 2024
528330f
fix: clarify which data locking protects
coroiu Dec 10, 2024
d5548f7
fix: typo
coroiu Dec 10, 2024
563e3a7
fix: change `linger` to `not present in memory`
coroiu Jan 9, 2025
83f0d56
fix: re-define sharing to match EA, previous definition of sharing is…
coroiu Jan 9, 2025
8eceee3
fix: font-weight
coroiu Jan 22, 2025
952a43c
feat: add token protected in transit req
coroiu Jan 22, 2025
7de826f
feat: change AT.2 to `must`
coroiu Jan 22, 2025
43c1e0e
chore: move security under architecture
coroiu Jan 27, 2025
43675f6
fix: various copy feedback
coroiu Jan 27, 2025
e029710
Add end-to-end encryption as a principle
MGibson1 Jan 29, 2025
58f1f95
Merge branch 'main' into ps/include-end-to-end-encryption-in-security…
quexten Feb 4, 2025
9f7fec3
Clarify principle overview
MGibson1 Feb 6, 2025
ec84aaf
Prefer existing language for requirements
MGibson1 Feb 6, 2025
9d2fc0c
remove typo
MGibson1 Feb 6, 2025
599521c
Describe key connector for users
MGibson1 Feb 6, 2025
80334b5
Clarify icon service exception
MGibson1 Feb 6, 2025
b10e0d1
Prefer data as singular or uncountable
MGibson1 Feb 10, 2025
4623c49
Clarify degradation of security
MGibson1 Feb 10, 2025
e2753a5
Add clear text injection protection
MGibson1 Feb 10, 2025
7f3cf5d
simplify sentences
MGibson1 Feb 10, 2025
ccc448b
Use established terms and remove PM-centric phrases
MGibson1 Feb 10, 2025
d01c545
Clarify icon service purpose
MGibson1 Feb 11, 2025
937c91d
Tweak title and provide friendlier overview
MGibson1 Feb 27, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Copy link
Contributor

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:

Clients must ensure that highly sensitive vault data cannot be accessed in plain text once the vault has been locked

Or am I stretching it and it would be better to keep different use-cases separate?

Copy link
Contributor

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.

Copy link
Contributor

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 :)

Copy link
Member Author

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.

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.
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.
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.
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.
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.
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.