Cardano Key Pairs
| Wallet address | |
|---|---|
| payment.vkey | payment verification key |
| payment.skey | payment signing key |
| payment.addr | funded address linked to stake |
| Stake pool address | |
| stake.vkey | staking verification key |
| stake.skey | staking signing key |
| stake.addr | registered stake address |
| Stake pool cold keys | |
| cold.skey | cold signing key |
| cold.vkey | cold verification key |
| cold.counter | issue counter |
| Stake pool hot keys | |
| vrf.skey | VRF signing key |
| vrf.vkey | VRF verification key |
| kes.vkey | KES verification key |
| kes.skey | KES signing key |
Cardano cryptographic keys are ed25519 key pairs of a public verification key and a secret key. The public key file is commonly referred to as keyname.vkey, whereas the private key file is referred to as keyname.skey. The private key file, which is used to sign transactions, is extremely sensitive and should be adequately safeguarded.
Under all circumstances, this entails limiting third-party access to your private keys. The most effective technique to prevent private key exposure is to guarantee that the necessary private key is never held for any length of time on any internet-connected machine (hot node). Please note that key pair filenames are completely random and can be named whatever you want.
It's critical to understand the numerous cryptographic key pairs connected with Cardano, as well as the purpose of each key pair and best practices for securing those keys, before you start working with it. Every ambitious Cardano developer and stake pool operator should get a complete grasp of these key pairs, as well as the ramifications of a single secret (private) key being hacked. Any Cardano developer or stake pool operator must learn how to manage, safeguard, and store private keys in order to succeed.
Keys generation is done with cardano-cli - a CLI application that provides functionalities like generating keys, building and submitting transactions, managing stake pools certificates, simple blockchain queries like wallet address UTXO and more.
--mainnet identifies the Cardano mainnet
--testnet-magic 1097911063 for testnets use.
Wallet address key pairs
Currently, Cardano wallet addresses only have two parts: a payment address and a counterpart staking address. A payment address (together with its associated key pairs) is used to store, receive, and send money. In the Shelley era of Cardano, every stakeholder can have two sets of keys and addresses. Both verification keys (payment.vkey and stake.vkey) are used to build the address and the resulting payment address is associated with these keys. - Payment Keys and addresses: To send and receive transactions - Stake Keys and addresses: To control protocol participation, create a stake pool, delegate, and receive rewards.
| Key | Purpose | Sensitivity |
|---|---|---|
| payment.vkey | Public verification key file for the payment address | May be shared publicly |
| payment.skey | Payment address secret(private) signing key file - gives you access to monies in your payment address and should be kept safe at all times. | Highly sensitive private signing key |
to generate a payment key pair: payment.vkey and payment.skey
cardano-cli address key-gen \
--verification-key-file payment.vkey \
--signing-key-file payment.skey
Stake pool address key pairs
A stake address (and related keys) is used to store and withdraw rewards, as well as to define the stake pool owner and rewards accounts, as well as the wallet's target stake pool delegation.
| Key | Purpose | Sensitivity |
|---|---|---|
| stake.vkey | stake address public verification key file | Not sensitive, may be shared publicly |
| stake.skey | stake address secret signing key file. This private signing key file gives you access to any awards cash held in the stake address, as well as the ability to delegate the wallet to a pool. It's also a good idea to keep an eye on the stake.skey. | Highly sensitive private signing key |
| payment.addr | Cardano wallet payment address that is usually generated with the help of both a payment.vkey and a stake. As inputs, use the vkey file. If a payment address is merely going to be used to send and receive money, no crucial components need to be staked. In addition, there is a single payment. Multiple unique stake.vkey files can be coupled with vkey to establish different payment addresses that can be staked independently. | Shared publicly |
| stake.addr | stake address for a Cardano wallet and is generated using the stake.vkey file | Shared publicly |
To generate a stake key pair:
cardano-cli stake-address key-gen \
--verification-key-file stake.vkey \
--signing-key-file stake.skey
to generate a payment address associated with our stake keys:
cardano-cli address build \
--payment-verification-key-file payment.vkey \
--stake-verification-key-file stake.vkey \
--out-file payment.addr \
--mainnet
#--testnet-magic 1097911063
to generate a stake address, mind this address CAN'T receive payments but will receive the rewards from participating in the protocol:
cardano-cli stake-address build \
--stake-verification-key-file stake.vkey \
--out-file stake.addr \
--mainnet
#--testnet-magic 1097911063
to query the balance of an address we need a running node and the environment variable CARDANO_NODE_SOCKET_PATH set to the path of the node.socket:
cardano-cli query utxo \
--address $(cat payment.addr) \
--mainnet
#--testnet-magic 1097911063
Stake pool hot and cold key pairs
It is the responsibility of the operator to manage both the hot (online), and cold (offline) keys for the pool. Cold keys must be secure and should not reside on a device that has internet connectivity. It is recommended that you have multiple backups of your cold keys.
The KES key, or hotkey as mentioned above, is a node operational key that authenticates who you are. You specify the validity of the KES key using the start time and key period parameters and this KES key need to be updated every 90 days. The VRF key is a signing verification key and is stored within the operational certificate.
Stake pool cold keys
| Key | Purpose | Sensitivity |
|---|---|---|
| cold.skey | secret signing key file for a Cardano stake pool (extremely sensitive). The cold.skey - is required to register a stake pool, to update a stake pool registration certificate parameters, to rotate a stake pool KES(Key Evolving Signature) keys and to retire a stake pool. | Highly sensitive private key |
| cold.vkey | public verification key file for a stake pool's cold.skey private signing key file | Not sensitive, can be shared publicly |
| cold.counter | incrementing counter file that tracks the number of times an operational certificate (opcert) has been generated for the relevant stake | Sensitive, can't be shared publicly |
To generate cold keys:
cardano-cli node key-gen \
--cold-verification-key-file cold.vkey \
--cold-signing-key-file cold.skey \
--operational-certificate-issue-counter-file cold.counter
Always rotate KES keys using the latest cold.counter.
Stake pool hot keys
When a new staking pool or validating node joins the Cardano network, they must broadcast two public keys along with its registration certificate: a VRF and a KES key. "KES" stands for Key Evolving Signature, which means that after a certain period, the key will evolve to a new key and discard its old version. This is useful, because it means that even if an attacker compromises the key and gets access to the signing key, he can only use that to sign blocks from now on, but not blocks dating from earlier periods, making it impossible for the attacker to rewrite history. To generate a new KES key pair, see below. A KES key can only evolve for a certain number of periods and becomes useless afterwards. This means that before that number of periods has passed, the node operator has to generate a new KES key pair, issue a new operational node certificate with that new key pair and restart the node with the new certificate.
| Key | Purpose | Sensitivity |
|---|---|---|
| vrf.skey | secret signing key file for a Cardano stake pool's VRF (cryptographic mechanism known as Verifiable Random Function) key required to start a stake pool's block producing node secret (private) signature key file for the stake pool's KES key (needed to start the stake pool's block producing node;). KES keys are needed to establish a stake pool's operating certificate, which expires 90 days after the opcert's defined KES period has passed. As a result, fresh KES keys must be generated along with a new opcert every 90 days or sooner for a Cardano Stake pool to continue minting blocks. | private sensitive key, but must be placed on a hot node in order to start a stake pool and rotated on a regular basis |
| vrf.vkey | public verification key file for a Cardano stake pool's kes.skey | not sensitive and is not required to a block producer. |
generate VRF hotkeys
cardano-cli node key-gen-VRF \
--verification-key-file vrf.vkey \
--signing-key-file vrf.skey
generate KES hotkeys
cardano-cli node key-gen-KES \
--verification-key-file kes.vkey \
--signing-key-file kes.skey