Skip to main content

Keystore Management

In SUBFROST, a keystore is a file that securely stores all the sensitive cryptographic material for a user. This includes the user's master secret (their mnemonic phrase) and their shares of any FROST group keys they are a part of.

The SUBFROST Keystore​

The SUBFROST keystore is designed to be both secure and portable. It is a JSON file that contains all the information needed to participate in FROST signing ceremonies and to manage your frBTC and other assets.

Here are the key components of a SUBFROST keystore:

  • Encrypted Mnemonic: The user's mnemonic phrase (the master secret) is never stored in plaintext. Instead, it is encrypted with a user-provided passphrase and stored in the keystore.
  • Public Key and Metadata: The keystore contains the user's public key, the group public key for any FROST groups they are a part of, and other metadata such as the key derivation path.
  • Encrypted FROST Shares: For each FROST group the user is a part of, the keystore contains their encrypted secret share of the group's private key.

Encryption​

The security of the SUBFROST keystore relies on a strong encryption scheme that protects the user's secrets from unauthorized access.

When a user creates a new keystore, they are prompted to enter a passphrase. This passphrase is then used to encrypt the user's mnemonic phrase and their FROST shares using the following process:

  1. Key Derivation (PBKDF2): The user's passphrase is not used directly as an encryption key. Instead, it is fed into the PBKDF2 (Password-Based Key Derivation Function 2) algorithm, along with a random salt. PBKDF2 is a computationally intensive algorithm that makes it very difficult for an attacker to guess the passphrase, even if they have access to the encrypted keystore.

  2. Authenticated Encryption (AES-GCM): The key derived from PBKDF2 is then used to encrypt the user's secrets using AES-256-GCM (Advanced Encryption Standard in Galois/Counter Mode). AES-GCM is a modern, authenticated encryption cipher that provides both confidentiality (the data is encrypted) and integrity (the data cannot be tampered with).

This combination of PBKDF2 and AES-GCM provides a very high level of security for the user's secrets.

ASCII Armoring​

To make the encrypted data easy to store and transport, it is ASCII armored. This means that the binary encrypted data is encoded into a human-readable text format. This allows the keystore to be easily copied, pasted, and stored in any text-based format, such as a JSON file.

By combining strong encryption with a user-friendly file format, the SUBFROST keystore provides a secure and convenient way for users to manage their cryptographic keys and to participate in the SUBFROST ecosystem.

Keystore Management in SUBFROST​

The subfrost-cli provides a set of commands for managing the SUBFROST keystore. These commands allow you to:

  • Create a new keystore: The subfrost-cli keystore new command creates a new keystore file and prompts you to enter a passphrase to encrypt it.
  • Import a keystore: The subfrost-cli keystore import command allows you to import a keystore from a file.
  • Export a keystore: The subfrost-cli keystore export command allows you to export a keystore to a file.
  • List keys: The subfrost-cli keystore list command lists the keys in a keystore.

Example Keystore File​

Here is an example of a SUBFROST keystore file:

{
  "crypto": {
    "cipher": "aes-128-ctr",
    "cipherparams": {
      "iv": "83dbcc02d8ccb40e46619102d57e33be"
    },
    "ciphertext": "d1728d7c6c34c235c893f87b8a0a82a3a2fb23c855884b6b9548547065a0463c",
    "kdf": "pbkdf2",
    "kdfparams": {
      "c": 262144,
      "dklen": 32,
      "prf": "hmac-sha256",
      "salt": "ae3cd4e7013836a3df6bd7241b12db061dbe2c678585344e472434e37146434f"
    },
    "mac": "517ead924a9d0dc3124507e3393d195ce33377b4737974ac46cc3b529526a7ea"
  },
  "id": "3a1b7547-d4b4-4612-863f-34354f232a2a",
  "version": 3
}