gring - a Gear Keystore Manager

Command-line tools for developers remain an expansive subject. While these may not appeal to non-technical, modern browser users, command-line tools continue to play a pivotal role universally. This prevalence is partly because developing and maintaining user interfaces is time-consuming.

For the Vara Network, the command-line tool, gcli, has provided comprehensive functionality for interacting with the network. However, to simplify and manage growth, the keystore component has been separated and developed into a standalone, lightweight keyring implementation.

Gring is this command-line keyring implementation, designed specifically for managing Vara Network keypairs.

$ gring
Gear keyring

Usage: gring [OPTIONS] <COMMAND>

Commands:
  add     Imports a keystore file generated by polakdot-js extension
  new     Generate a new key
  list    List all keys in keyring [aliases: l]
  use     Use the provided key as primary key
  sign    Sign a message
  verify  Verify a message
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  The verbosity level
  -h, --help        Print help

Keyring 101

A keyring shares similarities with a blockchain wallet, offering greater flexibility.

For blockchain wallet browser extensions, the initial step involves creating an account, remembering, and securely saving the passphrase to avoid future loss. Subsequently, the wallet generates additional keypairs from the root account upon request.

A critical point often overlooked is the loss of the passphrase for the root account results in the loss of all keypairs within the wallet. In contrast, keyrings operate differently; each keypair in a keyring possesses its own passphrase. Losing one keypair does not compromise the security of others.

	Keyring	Wallet
Multiple Keypairs	Yes	Yes
Standalone Passphrase	Yes	No

Keyring aligns with the basic concept of browser extension blockchain wallets but is more straightforward and flexible. Keyring's primary function is to generate and store keypairs on disk, encrypting and decrypting them with cryptography.

Keystore 101

A keyring is a ring of keystores, analogous to how a blockchain comprises a series of blocks.

A keystore secures the private keys of keypairs through encryption. For gring, adherence to the encryption standard of the Polkadot-JS wallet is maintained, facilitating the sharing of keystore files between the two systems.

How it works

This chapter delves into the technical specifics of gring, illustrated with examples.

Encrypt keypair into keystore

$ gring new -p password my-first-wallet

This command creates a keystore named my-first-keystore using the passphrase password. Delving into the details, the gring program performs the following actions:

1. Generates a random [schnorrkel][https://github.com/w3f/schnorrkel] keypair.
2. Encodes the keypair into a specific byte format termed keypair-info.

Keypair Info: [PAIR_HEADER, SECRET_KEY, DIVIDER, PUBLIC_KEY]

3. Encrypt the passphrase with [scrypt][https://en.wikipedia.org/wiki/Scrypt] to get a password for the secret box.
4. Pack the keypair-info in [NaCl Secretbox][https://en.wikipedia.org/wiki/NaCl_(software)] with the passwored from 3.

After all, the encrypted keypair will be like:

slot	1	2	3
bytes	scrypt config	random nonce	secret box (keypaire-info, nonce, encrypted_passphrase)

Generally, developers include additional information about the keypair in the keystore file, rather than just the raw encoded data, to enhance human readability. In Polkadot-js or gring, this is accomplished as follows:

{
    "encoded": "<encrypted-keypair-in-base64>"
    "encoding": {
        "content": ["pkcs8", "sr25519"],
        "ty": ["scrypt", "xsalsa20-poly1305"],
        "version": "3"
    },
    "address": "<The-address-of-the-keypair-in-ss58>",
    "meta": {
        "name": "<the-name-of-the-keypair>"
    }
}

Decrypt Keypair from Keystore

This section describes the inverse process of section 1. It becomes straightforward when the correct passphrase and corresponding keystore file are available, particularly the encoded field in your keystore.json.

1. Decode the encoded field using base64 to retrieve the secret box.
2. Extract the first 32 bytes of the encoded data, which represent the scrypt configuration.
3. Use the scrypt configuration and your passphrase to derive the secret box password.
4. Decode the nonce from the subsequent encoded data.
5. Unlock the secret box using the correct nonce and password.

This completes the process. Polkadot-JS adopts a similar approach, allowing keystore files to be shared with gring.

And more ...

Within the Polkadot ecosystem, there was no existing tool fulfilling this need, prompting the development of gring. gring serves as a command within gcli, sharing keystore paths. Ideally, gring can be utilized to manage Vara keys, and gcli can be used for interactions with the Vara network using stored keypairs.