Add security foundations section

docs/security/definitions.mdx

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# Definitions
+
+<dl>
+  <dt>Vault data</dt>
+  <dd>
+    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.
+
+  </dd>
+  <dt>User</dt>
+  <dd>The owner of the vault data.</dd>
+  <dt>Protected data</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Communication channel</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Secure channel</dt>
+  <dd>
+    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.
+
+  </dd>
+  <dt>Trusted channel</dt>
+  <dd>
+    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.
+
+  </dd>
+  <dt>Partially trusted channel</dt>
+  <dd>
+    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).
+  </dd>
+  <dt>Fully trusted Channel</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Data at rest</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Data in use</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Data in transit</dt>
+  <dd>
+    Data that is actively being transferred from one location to another, such as between memory locations, processes,
+    or between devices across a network.
+  </dd>
+  <dt>Data sharing</dt>
+  <dd>
+    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.
+  </dd>
+  <dt>Data leaking</dt>
+  <dd>
+    The process in which data unintentionally leaves the Bitwarden secure environment unprotected.
+  </dd>
+  <dt>Informed and explicit consent</dt>
+  <dd>
+    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.
+
+  </dd>
+  <dt>Certify</dt>
+  <dd>Officially recognize (someone or something) as possessing certain qualifications or meeting certain standards.</dd>
+  <dt>Bitwarden secure environment</dt>
+  <dd>Any process or application that adheres to the "Security" section is treated as "within the Bitwarden secure environment".</dd>
+</dl>

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.

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.

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.

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.

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.

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.

docs/security/principles/_category_.yml

@@ -0,0 +1,2 @@
+label: "Principles"
+position: 3

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.

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",

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;