First draft for AEX-3

AEXS/aex-3.md

@@ -0,0 +1,71 @@
+# AEX-3
+
+```
+AEX: 3
+Title: Secret storage format
+Author: Sascha Hanse <shanse@posteo.de>, Shubhendu Shekhar (@shekhar-shubhendu)
+License: BSD-3-Clause
+Status: Draft
+Type: Informational
+Created: 2019-04-03
+```
+
+## Simple Summary
+
+The document describes and defines the secret storage approach used by æternity.
+
+## Motivation
+
+The motivation for the AEX is to describe a standard way that is being used by æternity for secret storage.
+
+The secret storage specification, although is being currently used for secret-key storage, should not be limited to it and should be used as a standard way of storing secret text/plain text (esp. user related or user-owned) in an encrypted format.
+
+Having a standard way for encryption and storage of data enables
+
+- `Interoperability`, not only between æternity and æpps but also between the æpps.
+- `Easy migration` from an aeternity-supported `wallet` to another.
+
+## Specification
+
+- The `data` should always be stored in a `.json` file.
+- Each file should have a minimum of 1 JSON object with the following `required` fields
+
+  - `secret_type` specifies the type of the encrypted data. This is restricted to `ed25519` at this point.
+  - `symmetric_alg` specifies the algorithm used for symmetric encryption of the secret. This should be authenticated encryption and the only option is `xsalsa20-poly1305` currently.
+  - The `ciphertext` is the output of `symmectric_alg` , i.e. the output of libsodiums `crypto_secretbox_easy`, which is `MAC + CIPHER`.
+  - `cipher_params` params used for successful decryption of the ciphertext
+  - `kdf` specifies the methods used for key derivation.
+  - `kdf_params` are the params used by the `kdf`
+  - `id` is a Version 4 UUID
+  - `version` currently `1`. Defines the version of secret storage format.
+
+- Each JSON Object can also have an optional `name` field, which can be a human-readable name for the secret.
+
+### Example
+
+```json
+{
+  "crypto": {
+    "secret_type": "ed25519",
+    "symmetric_alg": "xsalsa20-poly1305",
+    "ciphertext":"66891af8a59e83f0c600435a0681413644588f296240ab922ee357fa5ffa857f2709f8753b2b70d35625203adc6bf6e8",
+    "cipher_params": {
+      "nonce": "b085597ac8351330b469e9845fc9fb8cefa07e51cb7736a"
+    },
+    "kdf": "argon2id",
+    "kdf_params": {
+      "memlimit_kib": 65536,
+      "opslimit": 3,
+      "salt": "somesaltyness",
+      "parallelism": 1,
+    }
+  },
+  "id": "b1ff1e48-4e3e-4caf-818e-c8a7c3559d97",
+  "name": "main",
+  "version": 1
+}
+```
+
+## Reference
+
+https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition