Key pair management in Chromia CLI

This document describes how key pairs are read and managed within the Chromia CLI for various commands.

Generate your key pair

Before managing key pairs, you need to generate them first. See the keygen command documentation for detailed instructions on how to create a new key pair.

Once you have generated your key pair, you can configure and manage how the CLI uses it across different operations.

🔑 New to key pairs? Learn why you need them and how they work

In blockchain development, key pairs are fundamental to security and identity:

• Private Key: Like a password - keep it secret! Used to sign transactions and prove you own an account.
• Public Key: Derived from your private key, safe to share. Used to verify signatures and generate your Account ID.
• Account ID: Generated by hashing your public key. This is your unique identifier on the blockchain.

The relationship:

Private Key (secret) → Public Key (shareable) → Account ID (your blockchain identity)

How it works in practice:

1. You generate a private key (using chr keygen)
2. Your public key is automatically derived from your private key
3. Your Account ID is calculated by hashing your public key
4. You sign transactions with your private key
5. Others verify your signature using your public key, without ever seeing your private key

Security note: Never share your private key! Anyone with your private key can control all accounts associated with it. If you lose your private key, you lose access to your accounts permanently.

For more about these concepts, see Terminology.

Key pair reading flow

The Chromia CLI follows a specific precedence order when determining which key pair to use for operations, from highest precedence to lowest:

1. Secret file option

   • The --secret option pointing to a file containing key pair information takes the highest precedence
   • This overrides all other key pair sources

2. Key ID option

   • If the user specifies a key ID directly using the --key-id option for a command, this takes precedence over all configuration files
   • Keys are still located and read from the ~/.chromia directory

3. Explicit configuration path

   • If a user specifies a configuration path using the --config option, the key.id from that configuration takes precedence
   • Keys are still located and read from the ~/.chromia directory

4. Project-specific configuration

   • If a project has a local configuration file at the default location <project-path>/.chromia/config, the property key.id = <key_id> specified there takes precedence over the global configuration
   • Keys are still located and read from the ~/.chromia directory

5. Global configuration

   • Finally, if none of the above are set, the CLI reads the property key.id = <key_id> from the global configuration file located at ~/.chromia/config
   • This global configuration applies to all commands unless overridden

Key storage

Key ID

Keys are stored in the ~/.chromia directory by default. When using the keygen command with the --key-id option, the following files are created:

• ~/.chromia/{key-id} – Contains the private key
• ~/.chromia/{key-id}.pubkey – Contains the public key
• ~/.chromia/{key-id}_mnemonic – Contains the mnemonic phrase for recovery

chr keygen --key-id=<value>

Secret file

When using the keygen command with the --file option the following files are created:

• <file_name> – Contains the keypair
• <file_name>_mnemonic – Contains the mnemonic phrase for recovery

chr keygen --file=<path>