diff --git a/docs/security/definitions.mdx b/docs/security/definitions.mdx new file mode 100644 index 00000000..09670113 --- /dev/null +++ b/docs/security/definitions.mdx @@ -0,0 +1,118 @@ +--- +sidebar_position: 2 +--- + +# 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".
+
diff --git a/docs/security/index.mdx b/docs/security/index.mdx new file mode 100644 index 00000000..e72dc10a --- /dev/null +++ b/docs/security/index.mdx @@ -0,0 +1,46 @@ +--- +sidebar_position: 1 +--- + +# Security + +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 + +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/01-locked-vault-is-secure.mdx b/docs/security/principles/01-locked-vault-is-secure.mdx new file mode 100644 index 00000000..84b87053 --- /dev/null +++ b/docs/security/principles/01-locked-vault-is-secure.mdx @@ -0,0 +1,13 @@ +# 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. + +## 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/02-limited-security-on-semi-compromised.mdx b/docs/security/principles/02-limited-security-on-semi-compromised.mdx new file mode 100644 index 00000000..e5b0dc8c --- /dev/null +++ b/docs/security/principles/02-limited-security-on-semi-compromised.mdx @@ -0,0 +1,17 @@ +# P02 - 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. diff --git a/docs/security/principles/03-no-security-on-fully-compromised.mdx b/docs/security/principles/03-no-security-on-fully-compromised.mdx new file mode 100644 index 00000000..7c8f58c5 --- /dev/null +++ b/docs/security/principles/03-no-security-on-fully-compromised.mdx @@ -0,0 +1,21 @@ +# P03 - 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. diff --git a/docs/security/principles/04-controlled-access.mdx b/docs/security/principles/04-controlled-access.mdx new file mode 100644 index 00000000..db0394e6 --- /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. diff --git a/docs/security/principles/05-minimized-impact-of-security-breaches.mdx b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx new file mode 100644 index 00000000..1081dbb2 --- /dev/null +++ b/docs/security/principles/05-minimized-impact-of-security-breaches.mdx @@ -0,0 +1,11 @@ +# 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 +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 + secrecy). +- Ensuring that any data added after a breach remains secure, maintaining post-compromise security. diff --git a/docs/security/principles/_category_.yml b/docs/security/principles/_category_.yml new file mode 100644 index 00000000..964bfd3b --- /dev/null +++ b/docs/security/principles/_category_.yml @@ -0,0 +1,2 @@ +label: "Principles" +position: 3 diff --git a/docs/security/requirements.mdx b/docs/security/requirements.mdx new file mode 100644 index 00000000..437509a0 --- /dev/null +++ b/docs/security/requirements.mdx @@ -0,0 +1,120 @@ +--- +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 + +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. diff --git a/docusaurus.config.js b/docusaurus.config.js index f37996e9..28c5e32a 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 27af065f..c9204dff 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;