Key pair management in Chromia CLI
This document describes how key pairs are read and managed within the Chromia CLI for various commands.
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:
-
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
- The
-
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
- If the user specifies a key ID directly using the
-
Explicit configuration path
- If a user specifies a configuration path using the
--config
option, thekey.id
from that configuration takes precedence - Keys are still located and read from the
~/.chromia
directory
- If a user specifies a configuration path using the
-
Project-specific configuration
- If a project has a local configuration file at the default location
<project-path>/.chromia/config
, the propertykey.id = <key_id>
specified there takes precedence over the global configuration - Keys are still located and read from the
~/.chromia
directory
- If a project has a local configuration file at the default location
-
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
- Finally, if none of the above are set, the CLI reads the property
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>