Skip to content


AEX: 3
Title: Secret storage format
Author: Sascha Hanse <[email protected]>, 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.


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.


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


  "crypto": {
    "secret_type": "ed25519",
    "symmetric_alg": "xsalsa20-poly1305",
    "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