From dd7432c6d8c32fee156ae6247fc026aa8afa82d8 Mon Sep 17 00:00:00 2001
From: Andreas Coroiu <andreas.coroiu@gmail.com>
Date: Tue, 21 Nov 2023 17:09:49 +0100
Subject: [PATCH] feat: add intro, symmetric and assymetric

---
 .vscode/settings.json                         |  6 +++-
 docs/contributing/cryptography/_category_.yml |  1 +
 .../contributing/cryptography/requirements.md | 30 +++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 docs/contributing/cryptography/_category_.yml
 create mode 100644 docs/contributing/cryptography/requirements.md

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 06d93e430..66c3832c8 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,3 +1,7 @@
 {
-  "cSpell.words": ["Bitwarden"]
+  "cSpell.words": [
+    "Bitwarden"
+  ],
+  "editor.formatOnSave": false,
+  "editor.formatOnPaste": false
 }
diff --git a/docs/contributing/cryptography/_category_.yml b/docs/contributing/cryptography/_category_.yml
new file mode 100644
index 000000000..305745429
--- /dev/null
+++ b/docs/contributing/cryptography/_category_.yml
@@ -0,0 +1 @@
+label: "Cryptography"
diff --git a/docs/contributing/cryptography/requirements.md b/docs/contributing/cryptography/requirements.md
new file mode 100644
index 000000000..ed594f5f2
--- /dev/null
+++ b/docs/contributing/cryptography/requirements.md
@@ -0,0 +1,30 @@
+# Requirements
+
+At Bitwarden we protect our users data depending heavily zero-knowledge cryptography. One of the
+most important way of achieving this is by living up to the high standard required from today's and
+tomorrow's cryptography. This document outlines the requirements we have to achieve those goals.
+
+:::info
+For more information about cryptography in Bitwarden, see
+[Bitwarden Security Whitepaper](https://bitwarden.com/help/bitwarden-security-white-paper/)
+:::
+
+## Symmetric encryption
+
+:::info
+All keys used for symmetric encryption should be 512 bits.
+:::
+
+The symmetric encryption
+algorithm used for encrypting vault data is AES-256 in CBC mode. The key size is 256 bits and the IV
+size is 128 bits. The IV is randomly generated for each field and stored along with the cipher text.
+Each operation is accompanied by an HMAC (message authentication code) verification to ensure
+integrity.
+
+The stored symmetric-key object consists of two concatenated keys, one used for encryption and one
+used for HMAC, both 256 bits. This is what we mean when saying that the "`UserKey` is 512 bits".
+
+### Asymmetric encryption
+
+The asymmetric encryption algorithm used for encrypting user data is RSA-2048. The key size is 2048
+bits.