AEX-3

AEX: 3
Title: Secret storage format
Author: Sascha Hanse <[email protected]>, Shubhendu Shekhar (@shekhar-shubhendu)
License: BSD-3-Clause
Discussions-To: https://forum.aeternity.com/t/aex-3-secure-storage-format/3220
Status: Active
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.

  • (optional) secret_format specifies the format of the encrypted data, if not specified then a consumer should assume raw bytes

  • 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 with an upper-limit of 512 bytes.

  • 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.

Secret types

Specifying an appropriate secret_type helps consumers to decide the proper way of handling the decrypted data without having to store additional metadata.

The following secret_type values have been proposed:

• ed25519-bip39-mnemonic

• ed25519-slip0010-masterkey

This list should be expanded with adoption.

It is not advised to use this format as a store for arbitrary binary data.

Example

{
  "crypto": {
    "secret_type": "ed25519-slip0010-masterkey",
    "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