Cardano Key Pairs

From Cardano Blockchain Wiki
Jump to navigation Jump to search
Key Types
Wallet address
payment.vkeypayment verification key
payment.skeypayment signing key
payment.addrfunded address linked to stake
Stake pool address
stake.vkeystaking verification key
stake.skeystaking signing key
stake.addrregistered stake address
Stake pool cold keys
cold.skeycold signing key
cold.vkeycold verification key
cold.counterissue counter
Stake pool hot keys
vrf.skeyVRF signing key
vrf.vkeyVRF verification key
kes.vkeyKES verification key
kes.skeyKES 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 \
   #--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 \
   #--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) \
   #--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