From 648221fc67b01c7c90b7e6752a6407496a89852c Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Fri, 22 Nov 2024 16:34:24 +0100 Subject: [PATCH 01/22] feat: add new security section --- docs/security/index.mdx | 5 +++++ docusaurus.config.js | 6 ++++++ sidebars.js | 1 + 3 files changed, 12 insertions(+) create mode 100644 docs/security/index.mdx diff --git a/docs/security/index.mdx b/docs/security/index.mdx new file mode 100644 index 000000000..0118e1cfa --- /dev/null +++ b/docs/security/index.mdx @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Security diff --git a/docusaurus.config.js b/docusaurus.config.js index f37996e94..28c5e32ad 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -74,6 +74,12 @@ async function createConfig() { label: "Architecture", sidebarId: "architecture", }, + { + type: "docSidebar", + position: "left", + label: "Security", + sidebarId: "security", + }, { type: "custom-dev", position: "right", diff --git a/sidebars.js b/sidebars.js index 27af065fb..c9204dffa 100644 --- a/sidebars.js +++ b/sidebars.js @@ -16,6 +16,7 @@ const sidebars = { getting_started: ["index", { type: "autogenerated", dirName: "getting-started" }], contributing: [{ type: "autogenerated", dirName: "contributing" }], architecture: [{ type: "autogenerated", dirName: "architecture" }], + security: [{ type: "autogenerated", dirName: "security" }], }; module.exports = sidebars; From 585c402242632de88dda2aabeaa6c1c179c52411 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Fri, 22 Nov 2024 16:34:50 +0100 Subject: [PATCH 02/22] feat: port definitions --- docs/security/definitions.mdx | 114 ++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/security/definitions.mdx diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx new file mode 100644 index 000000000..a550e453f --- /dev/null +++ b/docs/security/definitions.mdx @@ -0,0 +1,114 @@ +# Definitions + +
+
Vault data
+
+ The collection of a user’s sensitive and private information that they choose to store +securely within Bitwarden's secure environment. This data typically includes: + + - **Passwords**: Credentials for various websites, applications, and services. + - **Usernames**: Associated usernames for accounts. + - **Secure Notes**: Encrypted notes containing sensitive information that the user wants to keep + secure. + - **Credit Card Information**: Payment card details like card number, expiration date, CVV, etc. + - **Identities**: Personal information such as names, addresses, phone numbers, and email addresses + that can be used to autofill forms. + - **Attachments**: Any files uploaded by the user to be stored securely within the vault. + +
+
User
+
The owner of the vault data.
+
Protected data
+
+ Data stored in a format that is unreadable without additional information. Usually synonymous to + encrypted, but with additional expectations about how the key is stored. Encrypted data which is + stored together with its decryption key in plain text is not considered to be protected, even + thought it is encrypted. +
+
Communication channel
+
+ A medium through which two or more entities, such as processes, +applications, or systems, exchange data or messages. This can include communication between +components on the same machine, such as inter-process communication (IPC), or over a network, such +as between a client and a server. Common types of communication channels include sockets, APIs, +message queues, shared memory, and HTTP connections. +
+
Secure channel
+
+ A communication channel that provides confidentiality and integrity for the data transmitted + between two or more parties. + + - **Confidentiality**: The data is unreadable to unauthorized + parties, typically using encryption. + - **Integrity**: The data cannot be altered or tampered with + without detection during transmission. + +
+
Trusted channel
+
+ A secure channel that also provides authenticity. + + - **Authenticity**: The identities of the + communicating parties are verified, ensuring that data is exchanged only between the intended + parties. + +
+
Partially trusted channel
+
+ A communication channel where trust is asymmetrical, meaning only some of the parties trust the + channel. One party may have verified the other(s) and thus trusts the channel, while the other + party or parties may not have done so, making the channel trusted by one party but untrusted by + the other(s). +
+
Fully trusted Channel
+
+ A communication channel where all parties have verified each other’s identities. This means the + channel provides confidentiality, integrity, and authenticity, ensuring that the data is secure, + unaltered, and exchanged only between the trusted parties. +
+
Data at rest
+
+ Any data that is stored on a device or medium that is not actively being used, processed, or + transmitted. This includes (but is not limited to) data stored on disk on the users devices, or on + disk on the server side. +
+
Data in use
+
+ Any data that is actively being used, processed or accessed. This includes (but is not limited to) data that is + temporarily held in volatile memory (like RAM) for quick access, computation, or rendering. +
+
Data in transit
+
+ Data that is actively being transferred from one location to another, such as between memory locations, processes, + or between devices across a network. +
+
Data sharing
+
+ The controlled process in which data leaves the Bitwarden secure environment unprotected. As a consequence the + guarantees made by this document will no longer apply. The receiving party may or may not have its own guarantees. +
+
Data leaking
+
+ The process in which data unintentionally leaves the Bitwarden secure environment unprotected. +
+
Informed and explicit consent
+
+ The process by which the User is provided with all relevant information regarding an action, understands it, and + agrees to the terms in a clear and unmistakable way. + + - **Informed**: The person giving consent must have all necessary information to understand what they are agreeing to. + All or parts of the information may be assumed to be implicitly provided/understood by the context in which the user + is giving consent. This includes: + - **Purpose**: A clear explanation of what the consent is for, such as how their data will be used or what actions will be taken. + - **Risks and Benefits**: Disclosure of any potential risks, benefits, or consequences associated with their consent. + - **Alternatives**: Information about any alternatives to consenting and what happens if they choose not to consent. + - **Rights**: A description of their rights, such as the right to withdraw consent at any time without penalty. + - **Explicit consent**: Consent must be given clearly and unambiguously, typically through a direct and affirmative action, + such as clicking "I agree" or a similar action. + +
+
Certify
+
Officially recognize (someone or something) as possessing certain qualifications or meeting certain standards.
+
Bitwarden secure environment
+
Any process or application that adheres to the "Security" section is treated as "within the Bitwarden secure environment".
+
From bf8369dc939400edce343a13d911214ec35064df Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Fri, 22 Nov 2024 16:47:08 +0100 Subject: [PATCH 03/22] feat: add first principle --- docs/security/index.mdx | 8 ++++++++ .../principles/01-locked-vault-protected.mdx | 13 +++++++++++++ docs/security/principles/_category_.yml | 1 + 3 files changed, 22 insertions(+) create mode 100644 docs/security/principles/01-locked-vault-protected.mdx create mode 100644 docs/security/principles/_category_.yml diff --git a/docs/security/index.mdx b/docs/security/index.mdx index 0118e1cfa..ab8e13f2d 100644 --- a/docs/security/index.mdx +++ b/docs/security/index.mdx @@ -3,3 +3,11 @@ sidebar_position: 1 --- # Security + +:::info + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this section are to be interpreted as described in +[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). + +::: diff --git a/docs/security/principles/01-locked-vault-protected.mdx b/docs/security/principles/01-locked-vault-protected.mdx new file mode 100644 index 000000000..b042a9d85 --- /dev/null +++ b/docs/security/principles/01-locked-vault-protected.mdx @@ -0,0 +1,13 @@ +# 01: A locked vault must be and stay protected + +Clients must ensure that once the vault has been locked, no vault data can be accessed in plain +text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed +if the device is compromised before the vault is locked. + +## 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. diff --git a/docs/security/principles/_category_.yml b/docs/security/principles/_category_.yml new file mode 100644 index 000000000..32d3a14aa --- /dev/null +++ b/docs/security/principles/_category_.yml @@ -0,0 +1 @@ +label: "Principles" From e65f22323f0f3a45a536c3c15e260971bf9b5747 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 13:38:33 +0100 Subject: [PATCH 04/22] feat: add second principle --- .../principles/02-safeguards-on-semi-compromised.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/security/principles/02-safeguards-on-semi-compromised.mdx diff --git a/docs/security/principles/02-safeguards-on-semi-compromised.mdx b/docs/security/principles/02-safeguards-on-semi-compromised.mdx new file mode 100644 index 000000000..85ccd9410 --- /dev/null +++ b/docs/security/principles/02-safeguards-on-semi-compromised.mdx @@ -0,0 +1,10 @@ +# 02. Safeguards for vaults on semi-compromised devices + +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. From cebbeb39c107022183739f4180ebd6c9dc4839cd Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 13:52:30 +0100 Subject: [PATCH 05/22] feat: add third principle --- .../principles/01-locked-vault-protected.mdx | 2 +- ...=> 02-limited-protection-on-semi-compromised.mdx} | 9 ++++++++- .../03-no-protection-on-fully-compromised.mdx | 12 ++++++++++++ 3 files changed, 21 insertions(+), 2 deletions(-) rename docs/security/principles/{02-safeguards-on-semi-compromised.mdx => 02-limited-protection-on-semi-compromised.mdx} (74%) create mode 100644 docs/security/principles/03-no-protection-on-fully-compromised.mdx diff --git a/docs/security/principles/01-locked-vault-protected.mdx b/docs/security/principles/01-locked-vault-protected.mdx index b042a9d85..70095c58d 100644 --- a/docs/security/principles/01-locked-vault-protected.mdx +++ b/docs/security/principles/01-locked-vault-protected.mdx @@ -1,4 +1,4 @@ -# 01: A locked vault must be and stay protected +# P01: A locked vault must be and stay protected Clients must ensure that once the vault has been locked, no vault data can be accessed in plain text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed diff --git a/docs/security/principles/02-safeguards-on-semi-compromised.mdx b/docs/security/principles/02-limited-protection-on-semi-compromised.mdx similarity index 74% rename from docs/security/principles/02-safeguards-on-semi-compromised.mdx rename to docs/security/principles/02-limited-protection-on-semi-compromised.mdx index 85ccd9410..d856d594a 100644 --- a/docs/security/principles/02-safeguards-on-semi-compromised.mdx +++ b/docs/security/principles/02-limited-protection-on-semi-compromised.mdx @@ -1,4 +1,11 @@ -# 02. Safeguards for vaults on semi-compromised devices +# P02. Limited protection for vaults on semi-compromised devices + +:::info Note + +This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-protected) 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 diff --git a/docs/security/principles/03-no-protection-on-fully-compromised.mdx b/docs/security/principles/03-no-protection-on-fully-compromised.mdx new file mode 100644 index 000000000..4b1d4d253 --- /dev/null +++ b/docs/security/principles/03-no-protection-on-fully-compromised.mdx @@ -0,0 +1,12 @@ +# P03. No protection on fully compromised systems + +:::info Note + +This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-protected) for details +on protections for locked vaults. + +::: + +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. From 40a8bb7392aaf97069674e14f2b7adf083b9690d Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 13:59:34 +0100 Subject: [PATCH 06/22] feat: add note about TEEs to P03 --- .../principles/03-no-protection-on-fully-compromised.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/security/principles/03-no-protection-on-fully-compromised.mdx b/docs/security/principles/03-no-protection-on-fully-compromised.mdx index 4b1d4d253..14907f0e7 100644 --- a/docs/security/principles/03-no-protection-on-fully-compromised.mdx +++ b/docs/security/principles/03-no-protection-on-fully-compromised.mdx @@ -7,6 +7,15 @@ 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. From 6e650d754806930833c8982f5c0f42119bacc0ba Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 14:05:29 +0100 Subject: [PATCH 07/22] chore: change protection > security --- ...locked-vault-protected.mdx => 01-locked-vault-is-secure.mdx} | 2 +- ...promised.mdx => 02-limited-security-on-semi-compromised.mdx} | 2 +- ...-compromised.mdx => 03-no-security-on-fully-compromised.mdx} | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename docs/security/principles/{01-locked-vault-protected.mdx => 01-locked-vault-is-secure.mdx} (93%) rename docs/security/principles/{02-limited-protection-on-semi-compromised.mdx => 02-limited-security-on-semi-compromised.mdx} (92%) rename docs/security/principles/{03-no-protection-on-fully-compromised.mdx => 03-no-security-on-fully-compromised.mdx} (93%) diff --git a/docs/security/principles/01-locked-vault-protected.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx similarity index 93% rename from docs/security/principles/01-locked-vault-protected.mdx rename to docs/security/principles/01-locked-vault-is-secure.mdx index 70095c58d..c874201c1 100644 --- a/docs/security/principles/01-locked-vault-protected.mdx +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -1,4 +1,4 @@ -# P01: A locked vault must be and stay protected +# P01: A locked vault is secure Clients must ensure that once the vault has been locked, no vault data can be accessed in plain text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed diff --git a/docs/security/principles/02-limited-protection-on-semi-compromised.mdx b/docs/security/principles/02-limited-security-on-semi-compromised.mdx similarity index 92% rename from docs/security/principles/02-limited-protection-on-semi-compromised.mdx rename to docs/security/principles/02-limited-security-on-semi-compromised.mdx index d856d594a..06f33f149 100644 --- a/docs/security/principles/02-limited-protection-on-semi-compromised.mdx +++ b/docs/security/principles/02-limited-security-on-semi-compromised.mdx @@ -1,4 +1,4 @@ -# P02. Limited protection for vaults on semi-compromised devices +# P02. Limited security for vaults on semi-compromised devices :::info Note diff --git a/docs/security/principles/03-no-protection-on-fully-compromised.mdx b/docs/security/principles/03-no-security-on-fully-compromised.mdx similarity index 93% rename from docs/security/principles/03-no-protection-on-fully-compromised.mdx rename to docs/security/principles/03-no-security-on-fully-compromised.mdx index 14907f0e7..299e9dd9f 100644 --- a/docs/security/principles/03-no-protection-on-fully-compromised.mdx +++ b/docs/security/principles/03-no-security-on-fully-compromised.mdx @@ -1,4 +1,4 @@ -# P03. No protection on fully compromised systems +# P03. No security on fully compromised systems :::info Note From bcd9467f7618451f98a19131cd2d6c68863f6239 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 14:36:23 +0100 Subject: [PATCH 08/22] feat: add forth principle --- docs/security/principles/01-locked-vault-is-secure.mdx | 2 +- docs/security/principles/04-controlled-access.mdx | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/security/principles/04-controlled-access.mdx diff --git a/docs/security/principles/01-locked-vault-is-secure.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx index c874201c1..96bbdfa7f 100644 --- a/docs/security/principles/01-locked-vault-is-secure.mdx +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -1,4 +1,4 @@ -# P01: A locked vault is secure +# P01. A locked vault is secure Clients must ensure that once the vault has been locked, no vault data can be accessed in plain text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed diff --git a/docs/security/principles/04-controlled-access.mdx b/docs/security/principles/04-controlled-access.mdx new file mode 100644 index 000000000..68063f28c --- /dev/null +++ b/docs/security/principles/04-controlled-access.mdx @@ -0,0 +1,7 @@ +# P04. 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. From 8da13ec18383bee520b16bfb65fa3a56eab02b68 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 14:43:17 +0100 Subject: [PATCH 09/22] feat: add fifth principle --- .../security/principles/05-minimize-data-exposure.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/security/principles/05-minimize-data-exposure.mdx diff --git a/docs/security/principles/05-minimize-data-exposure.mdx b/docs/security/principles/05-minimize-data-exposure.mdx new file mode 100644 index 000000000..14bc0359d --- /dev/null +++ b/docs/security/principles/05-minimize-data-exposure.mdx @@ -0,0 +1,11 @@ +# P6: 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 any available action to help users limit the damage caused by such breaches, both in +scope and duration. This involves: + +- 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. From 4c755bb9772d3a20b0d22421156ab050253d04b7 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 14:43:47 +0100 Subject: [PATCH 10/22] feat: add fifth principle --- docs/security/principles/05-minimize-data-exposure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/principles/05-minimize-data-exposure.mdx b/docs/security/principles/05-minimize-data-exposure.mdx index 14bc0359d..493e49daf 100644 --- a/docs/security/principles/05-minimize-data-exposure.mdx +++ b/docs/security/principles/05-minimize-data-exposure.mdx @@ -1,4 +1,4 @@ -# P6: Minimized impact of security breaches +# P5: 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 From e95879784b60fd7fd7475a8359b21a8b4f9b614e Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 15:06:30 +0100 Subject: [PATCH 11/22] feat: add an overview page --- docs/security/definitions.mdx | 4 +++ docs/security/index.mdx | 39 +++++++++++++++++++++++-- docs/security/principles/_category_.yml | 1 + 3 files changed, 42 insertions(+), 2 deletions(-) diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx index a550e453f..096701131 100644 --- a/docs/security/definitions.mdx +++ b/docs/security/definitions.mdx @@ -1,3 +1,7 @@ +--- +sidebar_position: 2 +--- + # Definitions
diff --git a/docs/security/index.mdx b/docs/security/index.mdx index ab8e13f2d..6b8fd82a1 100644 --- a/docs/security/index.mdx +++ b/docs/security/index.mdx @@ -4,10 +4,45 @@ sidebar_position: 1 # Security -:::info +The Security section of this documentation outlines the foundational approach Bitwarden takes to +ensure the safety and integrity of user data. It provides a structured framework for understanding +Bitwarden's security philosophy, the principles it adheres to, and the specific requirements it +implements to meet its commitments. + +## Conventions + +### Key words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this section are to be interpreted as described in [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). -::: +### References + +Principles in this documentation are labeled with unique identifiers (e.g., P01, P02, etc.) for easy +reference throughout the document and in related discussions. When referencing a principle, simply +use its identifier (e.g. P01). + +Requirements in this documentation use a shorthand format (e.g. XX.N.y) to indicate their specific +location and context (e.g. VD.3.b). + +## Structure of the security section + +This section is divided into three parts: + +1. **Definitions** This part establishes the foundational terminology used throughout the document. + By clearly defining key concepts—such as what constitutes "vault data"—it ensures that the rest + of the document is precise and unambiguous. +2. **Principles** The principles describe the overarching philosophies and commitments that guide + Bitwarden's approach to security. These principles are not actionable rules but rather serve as + the justifications for the requirements that follow. They define what Bitwarden aims to achieve + in its security posture and why certain decisions are made. +3. **Requirements** Building on the principles, the requirements are concrete, actionable steps that + Bitwarden is required to implement. These requirements ensure that the principles are upheld in + practice and provide a measurable way to assess Bitwarden's security efforts. + +This structure is meant to avoid unnecessary repetition and establish a logical flow from high-level +philosophies to specific actions. It ensures that every requirement is tied to a well-defined +principle, making it clear why it exists and what it is meant to achieve. The document is designed +for both internal stakeholders and external users who seek to understand the company's security +model. diff --git a/docs/security/principles/_category_.yml b/docs/security/principles/_category_.yml index 32d3a14aa..964bfd3b6 100644 --- a/docs/security/principles/_category_.yml +++ b/docs/security/principles/_category_.yml @@ -1 +1,2 @@ label: "Principles" +position: 3 From 5d8a12191140cd993476ceeedabbfbd578951de9 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 15:07:05 +0100 Subject: [PATCH 12/22] fix: remove repetition --- docs/security/index.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/security/index.mdx b/docs/security/index.mdx index 6b8fd82a1..e72dc10a1 100644 --- a/docs/security/index.mdx +++ b/docs/security/index.mdx @@ -28,8 +28,6 @@ location and context (e.g. VD.3.b). ## Structure of the security section -This section is divided into three parts: - 1. **Definitions** This part establishes the foundational terminology used throughout the document. By clearly defining key concepts—such as what constitutes "vault data"—it ensures that the rest of the document is precise and unambiguous. From 3247efecd445b566836962e32f76c51b65173a19 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 15:09:01 +0100 Subject: [PATCH 13/22] chore: rename file to match content --- ...-exposure.mdx => 05-minimized-impact-of-security-breaches.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/security/principles/{05-minimize-data-exposure.mdx => 05-minimized-impact-of-security-breaches.mdx} (100%) diff --git a/docs/security/principles/05-minimize-data-exposure.mdx b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx similarity index 100% rename from docs/security/principles/05-minimize-data-exposure.mdx rename to docs/security/principles/05-minimized-impact-of-security-breaches.mdx From f9e585d23b256e08468e4b8870a664d8deab9490 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 15:09:56 +0100 Subject: [PATCH 14/22] refactor: use hyphen in title --- docs/security/principles/01-locked-vault-is-secure.mdx | 2 +- .../principles/02-limited-security-on-semi-compromised.mdx | 2 +- .../security/principles/03-no-security-on-fully-compromised.mdx | 2 +- docs/security/principles/04-controlled-access.mdx | 2 +- .../principles/05-minimized-impact-of-security-breaches.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/security/principles/01-locked-vault-is-secure.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx index 96bbdfa7f..84b870530 100644 --- a/docs/security/principles/01-locked-vault-is-secure.mdx +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -1,4 +1,4 @@ -# P01. A locked vault is secure +# P01 - A locked vault is secure Clients must ensure that once the vault has been locked, no vault data can be accessed in plain text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed diff --git a/docs/security/principles/02-limited-security-on-semi-compromised.mdx b/docs/security/principles/02-limited-security-on-semi-compromised.mdx index 06f33f149..6c4b478c0 100644 --- a/docs/security/principles/02-limited-security-on-semi-compromised.mdx +++ b/docs/security/principles/02-limited-security-on-semi-compromised.mdx @@ -1,4 +1,4 @@ -# P02. Limited security for vaults on semi-compromised devices +# P02 - Limited security for vaults on semi-compromised devices :::info Note diff --git a/docs/security/principles/03-no-security-on-fully-compromised.mdx b/docs/security/principles/03-no-security-on-fully-compromised.mdx index 299e9dd9f..ca4424115 100644 --- a/docs/security/principles/03-no-security-on-fully-compromised.mdx +++ b/docs/security/principles/03-no-security-on-fully-compromised.mdx @@ -1,4 +1,4 @@ -# P03. No security on fully compromised systems +# P03 - No security on fully compromised systems :::info Note diff --git a/docs/security/principles/04-controlled-access.mdx b/docs/security/principles/04-controlled-access.mdx index 68063f28c..db0394e6c 100644 --- a/docs/security/principles/04-controlled-access.mdx +++ b/docs/security/principles/04-controlled-access.mdx @@ -1,4 +1,4 @@ -# P04. Controlled access to vault data +# P04 - 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 diff --git a/docs/security/principles/05-minimized-impact-of-security-breaches.mdx b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx index 493e49daf..d5ce9f991 100644 --- a/docs/security/principles/05-minimized-impact-of-security-breaches.mdx +++ b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx @@ -1,4 +1,4 @@ -# P5: Minimized impact of security breaches +# P05 - 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 From 425f808873584095d73eb32c065ef28a8a2bda3b Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 15:10:45 +0100 Subject: [PATCH 15/22] fix: links --- .../principles/02-limited-security-on-semi-compromised.mdx | 2 +- .../security/principles/03-no-security-on-fully-compromised.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security/principles/02-limited-security-on-semi-compromised.mdx b/docs/security/principles/02-limited-security-on-semi-compromised.mdx index 6c4b478c0..e5b0dc8ce 100644 --- a/docs/security/principles/02-limited-security-on-semi-compromised.mdx +++ b/docs/security/principles/02-limited-security-on-semi-compromised.mdx @@ -2,7 +2,7 @@ :::info Note -This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-protected) for details +This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details on protections for locked vaults. ::: diff --git a/docs/security/principles/03-no-security-on-fully-compromised.mdx b/docs/security/principles/03-no-security-on-fully-compromised.mdx index ca4424115..7c8f58c51 100644 --- a/docs/security/principles/03-no-security-on-fully-compromised.mdx +++ b/docs/security/principles/03-no-security-on-fully-compromised.mdx @@ -2,7 +2,7 @@ :::info Note -This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-protected) for details +This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details on protections for locked vaults. ::: From e4f44ea633a40c51a4d89c8e214438aa679bbb1f Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Mon, 25 Nov 2024 17:37:44 +0100 Subject: [PATCH 16/22] refactor: remove any after comment --- .../principles/05-minimized-impact-of-security-breaches.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security/principles/05-minimized-impact-of-security-breaches.mdx b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx index d5ce9f991..1081dbb2d 100644 --- a/docs/security/principles/05-minimized-impact-of-security-breaches.mdx +++ b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx @@ -2,8 +2,8 @@ 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 any available action to help users limit the damage caused by such breaches, both in -scope and duration. This involves: +should take available actions to help users limit the damage caused by such breaches, both in scope +and duration. This involves: - Detecting and invalidating compromised device sessions. - Rotating encryption keys to reduce the risk of “harvest now, decrypt later” attacks (forward From b4a8c8da3424c63653ca7ca3e7e41e22c01c2749 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 26 Nov 2024 11:32:51 +0100 Subject: [PATCH 17/22] feat: add current version of requirements --- docs/security/requirements.mdx | 114 +++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/security/requirements.mdx diff --git a/docs/security/requirements.mdx b/docs/security/requirements.mdx new file mode 100644 index 000000000..e2b5201b1 --- /dev/null +++ b/docs/security/requirements.mdx @@ -0,0 +1,114 @@ +--- +sidebar_position: 4 +--- + +# Requirements + +## Vault data (VD) + +:::warning Draft - Early version + +This section is still in its early stages and does not yet reflect current or future standards. + +::: + +1. Vault data **MUST** be protected _at rest_. + + - a. The Client **MUST** encrypt vault data stored on disk. + - b. The Client **MUST** use the UserKey to encrypt vault data stored on the Server. + - c. The Client **SHOULD** ensure that no mechanisms exists such that vault data may be stored to + disk unencrypted without user consent. This includes cases where it is not the Client itself + that stores the data to disk. + - d. The Client **MUST** encrypt any vault data derivatives that can be used to re-create the + original form or are considered to be vault data on their own. + - e. The Client **MUST NOT** store any artifacts (e.g. encryption keys) on disk such that the + encrypted vault data can be decrypted without any additional information provided by the User. + - i. The Client **MAY** store such artifacts if given an _informed and explicit consent_ by the + User. + - f. The Client **MUST NOT** store any artifacts (e.g. encryption keys) such that the vault data + can be decrypted by the Server, regardless of consent. + +2. Vault data **MAY** be unprotected while _in use_. + + - a. The Client **MAY** decrypt all vault data during vault unlock. + - i. The Client **SHOULD** minimize the quantity of decrypted vault data. + - b. The Client **MAY** leave vault data encrypted after unlock. + - c. The Client **MUST** ensure that unprotected data does not linger when no longer _in use_. + +3. Vault data **SHOULD** be protected while _in transit_. + + - 1. The Client **MAY** use unprotected transmissions to the display/monitor. + - 2. The Client **SHOULD** use a trusted channel when the transmission crosses process + boundaries. + - 3. The Client **MUST** use a trusted channel if there is a risk that the data can be + eavesdropped by unintended parties. + - 4. The Client **MUST** certify that the receiver is within the Bitwarden secure environment. + - 5. The Client **MUST** use a trusted channel when the transmission crosses device boundaries. + +4. Vault data **MUST NOT** be shared without an _informed and explicit consent_ by the User. + + - 1. The Client **MAY** trust the OS to gather consent. + - 2. The Client **MAY** augment the OS when the consent process is not sufficiently clear or + explicit. + - 3. The Client **SHOULD** guarantee that the third party is the receiver. + +## Encryption keys (EK) + +:::warning Draft - Early version + +This section is still in its early stages and does not yet reflect current or future standards. + +::: + +1. The UserKey **MUST** have 256 bits of security. +2. The UserKey **MUST** be protected _at rest_. +3. The UserKey **MAY** be unprotected while _in use_. +4. The UserKey **MUST** be protected while _in transit_. +5. The UserKey **MUST NOT** be shared. + +## Authentication tokens (AT) + +:::warning Draft - Early version + +This section is still in its early stages and does not yet reflect current or future standards. + +::: + +1. The authentication tokens MUST be protected at rest if the client provides a mechanism for secure + storage. + +## Secure channels (SC) + +:::info Reviewed - Awaiting implementation + +This section has been reviewed and is awaiting implementation. + +::: + +1. A secure channel **MUST NOT** transmit unprotected data. + - a. Metadata related to the communication protocol **MAY** be transmitted unprotected. + - b. Metadata related to the communication protocol **MUST** be authenticated. +2. A secure channel **MUST** protect against unauthorized modifications of the data. +3. A secure channel **MUST** protect against replay of messages. +4. A secure channel **MAY** detect loss of data (e.g. dropped messages). +5. A long-lived secure channel **MUST** protect against the decryption of previously transmitted + data in the event of a future key compromise. + - a. High-traffic channels **MAY** expose a greater amount of data during key compromise to + maintain an acceptable user experience. +6. A long-lived secure channel **MUST** recover from key compromise to restore full confidentiality. + - a. High-traffic channels **MAY** experience a longer recovery period to maintain an acceptable + user experience. + +## Trusted channels (TC) + +:::warning Draft - Early version + +This section is still in its early stages and does not yet reflect current or future standards. + +::: + +1. A trusted channel **MUST** also be a secure channel. +2. A trusted channel **MUST** guarantee the receiver(s), including unintended ones. + - a. The OS **MAY** be trusted to provide this guarantee. + - b. The User **MAY** be trusted to provide this guarantee (e.g. using fingerprints) +3. A trusted channel **MAY** be partially trusted. From 0222f3f83bc1cb6ad1813c8166338b098f1e8a50 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 26 Nov 2024 11:33:51 +0100 Subject: [PATCH 18/22] feat: add introduction to requirement structure --- docs/security/requirements.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/security/requirements.mdx b/docs/security/requirements.mdx index e2b5201b1..437509a06 100644 --- a/docs/security/requirements.mdx +++ b/docs/security/requirements.mdx @@ -4,6 +4,12 @@ sidebar_position: 4 # Requirements +The requirements in this section are organized hierarchically, with top-level requirements defining +the core rules and obligations that must be met, serving as broad objectives for Bitwarden's +security model. Sub-requirements expand on these by addressing specific scenarios, exceptions, or +clarifications, and may override their parent requirement when explicitly stated. Sibling +requirements at the same level must remain independent and free of contradictions. + ## Vault data (VD) :::warning Draft - Early version From 663b464e633d14d4d99a14bfec520aa0dd370c8e Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 10 Dec 2024 14:54:47 +0100 Subject: [PATCH 19/22] feat: add Client definition --- docs/security/definitions.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx index 096701131..2b69845c8 100644 --- a/docs/security/definitions.mdx +++ b/docs/security/definitions.mdx @@ -22,6 +22,12 @@ securely within Bitwarden's secure environment. This data typically includes:
User
The owner of the vault data.
+
Client
+
+ The software application that the User interacts with to access their vault data. This includes + the official Bitwarden web vault, desktop applications, mobile applications, browser extensions, and any + other software provided by Bitwarden that interacts with the Bitwarden server to access or manage vault data. +
Protected data
Data stored in a format that is unreadable without additional information. Usually synonymous to From aaca302a5bb5422a0fae83702added4f2ef2d76a Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 10 Dec 2024 14:57:10 +0100 Subject: [PATCH 20/22] fix: tweak user definition --- docs/security/definitions.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx index 2b69845c8..0954bbe0c 100644 --- a/docs/security/definitions.mdx +++ b/docs/security/definitions.mdx @@ -21,7 +21,9 @@ securely within Bitwarden's secure environment. This data typically includes:
User
-
The owner of the vault data.
+
+ An individual who uses Bitwarden to store, manage, and access vault data. +
Client
The software application that the User interacts with to access their vault data. This includes From 0373e1243cc556d22d5f44b8eb655745660f67d1 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 10 Dec 2024 15:01:41 +0100 Subject: [PATCH 21/22] feat: add technical consideration section to P01 --- docs/security/principles/01-locked-vault-is-secure.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/security/principles/01-locked-vault-is-secure.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx index 84b870530..ad06c4c7e 100644 --- a/docs/security/principles/01-locked-vault-is-secure.mdx +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -4,6 +4,14 @@ Clients must ensure that once the vault has been locked, no vault data can be ac text, 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, From 528330f2ddcc25bbacb24976572e3bf96afe6c1a Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Tue, 10 Dec 2024 15:09:43 +0100 Subject: [PATCH 22/22] fix: clarify which data locking protects --- docs/security/definitions.mdx | 25 +++++++++++-------- .../principles/01-locked-vault-is-secure.mdx | 6 ++--- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx index 0954bbe0c..7ff00bf41 100644 --- a/docs/security/definitions.mdx +++ b/docs/security/definitions.mdx @@ -7,17 +7,22 @@ sidebar_position: 2
Vault data
- The collection of a user’s sensitive and private information that they choose to store -securely within Bitwarden's secure environment. This data typically includes: + The collection of a user's private information that they choose to store securely within Bitwarden's secure environment. + This typically includes highly sensitive data such as: - - **Passwords**: Credentials for various websites, applications, and services. - - **Usernames**: Associated usernames for accounts. - - **Secure Notes**: Encrypted notes containing sensitive information that the user wants to keep - secure. - - **Credit Card Information**: Payment card details like card number, expiration date, CVV, etc. - - **Identities**: Personal information such as names, addresses, phone numbers, and email addresses - that can be used to autofill forms. - - **Attachments**: Any files uploaded by the user to be stored securely within the vault. + - **Passwords**: Credentials for various websites, applications, and services. + - **Usernames**: Associated usernames for accounts. + - **Secure Notes**: Encrypted notes containing sensitive information that the user wants to keep + secure. + - **Credit Card Information**: Payment card details like card number, expiration date, CVV, etc. + - **Identities**: Personal information such as names, addresses, phone numbers, and email addresses + that can be used to autofill forms. + - **Attachments**: Any files uploaded by the user to be stored securely within the vault. + + Vault data may also refer to less sensitive data such as metadata: + + - **Last Updated**: The last time an item was updated. + - **Created Date**: The date an item was created.
User
diff --git a/docs/security/principles/01-locked-vault-is-secure.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx index ad06c4c7e..57124a2b3 100644 --- a/docs/security/principles/01-locked-vault-is-secure.mdx +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -1,8 +1,8 @@ # P01 - A locked vault is secure -Clients must ensure that once the vault has been locked, no vault data can be accessed in plain -text, even if the device becomes compromised after the lock occurs. Protections are not guaranteed -if the device is compromised before the vault is locked. +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