From 007de8bb870629a8831c829483ad675f9da2c50f Mon Sep 17 00:00:00 2001
From: Neeraj Gupta <254676+ua741@users.noreply.github.com>
Date: Thu, 3 Aug 2023 16:31:14 +0530
Subject: [PATCH] Document encrypted export format

---
 migration-guides/encrypted_export.md | 52 ++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 migration-guides/encrypted_export.md

diff --git a/migration-guides/encrypted_export.md b/migration-guides/encrypted_export.md
new file mode 100644
index 000000000..5b6e92fbd
--- /dev/null
+++ b/migration-guides/encrypted_export.md
@@ -0,0 +1,52 @@
+# Auth Encrypted Export format
+
+## Overview
+
+When we export the auth codes, the data is encrypted using a key derived from the user's password. 
+This document describes the JSON structure used to organize exported data, including versioning and key derivation parameters.
+
+## Export JSON Sample
+
+```json
+{
+  "version": 1,
+  "kdfParams": {
+    "memLimit": 4096,
+    "opsLimit": 3,
+    "salt": "example_salt"
+  },
+  "encryptedData": "encrypted_data_here",
+  "encryptionNonce": "nonce_here"
+}
+```
+
+The main object used to represent the export data. It contains the following key-value pairs:
+
+- `version`: The version of the export format.
+- `kdfParams`:  Key derivation function parameters.
+- `encryptedData"`:  The encrypted authentication data.
+- `encryptionNonce`: The nonce used for encryption.
+
+### Version 
+
+Export version is used to identify the format of the export data. 
+#### Ver: 1
+* KDF Algorithm: `ARGON2ID`
+* Decrypted data format: `otpauth://totp/...`, separated by a new line.
+* Encryption Algo: `XChaCha20-Poly1305`
+
+#### Key Derivation Function  Params (KDF)
+
+This section contains the parameters that were using during KDF operation:
+
+- `memLimit`: Memory limit for the algorithm.
+- `opsLimit`: Operations limit for the algorithm.
+- `salt`:  The salt used in the derivation process.
+
+#### Encrypted Data
+As mentioned above, the auth data is encrypted using a key that's derived by using user provided password & kdf params.
+For encryption, we are using `XChaCha20-Poly1305` algorithm. 
+
+## How to use the export data
+* **ente Authenticator app**: You can directly import the codes in the ente Authenticator app. 
+    >Settings -> Data -> Import Codes -> ente Encrypted export.