⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

Key Rotation

Key rotation on Aptos allows users to change their account's authentication key while preserving the account address, enabling recovery from compromised keys, upgrading security schemes, and transitioning to different authentication methods without losing assets or on-chain identity.

Overview#

Unlike traditional blockchains where accounts are permanently tied to a single private key, Aptos separates account addresses from authentication keys. This architecture enables users to rotate their keys for security purposes while maintaining the same address. Key rotation supports both proven rotations (where you have the old key) and unproven rotations (using social recovery or multi-sig authorization).

How Key Rotation Works#

Every Aptos account has two components: the permanent address derived from the initial public key, and a mutable authentication key that controls access. When you rotate keys, only the authentication key changes while the address remains constant.

// Using Aptos CLI for key rotation
aptos account rotate-key \
  --new-private-key-file ~/.aptos/new_key.key \
  --profile mainnet

// Programmatic key rotation
module 0x1::key_manager {
    use std::signer;
    use aptos_framework::account;

    public entry fun rotate_authentication_key(
        account: &signer,
        new_auth_key: vector<u8>
    ) {
        account::rotate_authentication_key(account, new_auth_key);
    }
}

Proven Rotation#

Proven rotation requires the current private key to authorize the key change:

import { Aptos, Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";

const aptos = new Aptos();

// Current account (old key)
const oldPrivateKey = new Ed25519PrivateKey("0x...");
const account = Account.fromPrivateKey({ privateKey: oldPrivateKey });

// Generate new key
const newPrivateKey = Ed25519PrivateKey.generate();
const newAuthKey = newPrivateKey.publicKey().authKey();

// Rotate to new key
const transaction = await aptos.rotateAuthKey({
  sender: account,
  newAuthKey: newAuthKey
});

console.log(`Key rotated: ${transaction.hash}`);

Unproven Rotation#

Unproven rotation allows key changes through alternative authorization mechanisms like multi-sig or social recovery when the original key is lost:

module 0x1::recovery {
    use std::signer;
    use aptos_framework::account;

    struct RecoveryConfig has key {
        guardians: vector<address>,
        threshold: u64
    }

    public entry fun setup_recovery(
        account: &signer,
        guardians: vector<address>,
        threshold: u64
    ) {
        move_to(account, RecoveryConfig { guardians, threshold });
    }

    public entry fun recover_account(
        recovered_addr: address,
        new_auth_key: vector<u8>,
        guardian_signatures: vector<vector<u8>>
    ) acquires RecoveryConfig {
        let config = borrow_global<RecoveryConfig>(recovered_addr);
        // Verify threshold of guardian signatures
        // Then rotate to new key
        // account::rotate_authentication_key_call(recovered_addr, new_auth_key);
    }
}

Real-World Use Cases#

  1. Security Incidents: Immediately rotate keys when you suspect a private key has been compromised, protecting assets before an attacker can act.

  2. Hardware Wallet Migration: Transition from a software wallet to a hardware wallet for enhanced security without changing your on-chain address.

  3. Social Recovery: Implement social recovery systems where trusted friends or family can help recover accounts if keys are lost.

  4. Corporate Key Management: Rotate employee access keys when staff changes while maintaining consistent corporate account addresses.

  5. Multi-Sig Evolution: Upgrade from single-key control to multi-sig authorization as account value or importance grows.

  6. Custody Transitions: Transfer custody of accounts between different custodians or security providers without asset transfers.

Best Practices#

Verify New Keys: Always verify you can sign with new keys before finalizing rotation. Test on testnet first for critical accounts.

Secure Key Generation: Generate new keys using cryptographically secure random number generators in isolated environments.

Backup Immediately: Back up new private keys in multiple secure locations before completing rotation.

Document Rotation: Maintain records of key rotations including dates, reasons, and new key fingerprints for audit purposes.

Test Recovery Procedures: Regularly test your recovery mechanisms to ensure they work before an emergency.

Use Time Locks: Consider implementing time-delayed rotations for high-value accounts to allow cancellation if unauthorized.

Monitor After Rotation: Watch account activity closely after rotation to detect any unauthorized access attempts.

Key Rotation with Multi-Sig#

Combine key rotation with multi-sig for enhanced security:

module 0x1::multisig_rotation {
    use aptos_framework::account;
    use aptos_framework::multisig_account;

    public entry fun propose_key_rotation(
        proposer: &signer,
        multisig_address: address,
        new_auth_key: vector<u8>
    ) {
        // Create proposal to rotate multisig account key
        // Requires threshold approval from signers
    }

    public entry fun approve_key_rotation(
        approver: &signer,
        multisig_address: address,
        proposal_id: u64
    ) {
        // Approve the key rotation proposal
    }
}

Security Considerations#

Old Key Compromise: After rotation, the old private key can no longer control the account, but it could still be used to attempt social engineering attacks.

Rotation Timing: Complete rotations quickly once initiated to minimize the window where multiple keys could theoretically control the account.

Authentication vs Address: Remember that rotating the authentication key doesn't change the account address, so on-chain references remain valid.

Transaction Replay: Signed but unsubmitted transactions from before rotation will fail after the key changes.

Emergency Contacts: Maintain emergency contact information with trusted parties who can assist with recovery if needed.

CLI Commands#

# Generate new key pair
aptos key generate --output-file ~/.aptos/new_key.key

# Rotate to new key
aptos account rotate-key \
  --new-private-key-file ~/.aptos/new_key.key \
  --profile mainnet

# Verify rotation
aptos account lookup-address \
  --profile mainnet

# Test signing with new key
aptos move run \
  --function-id 0x1::aptos_account::test_transaction \
  --profile mainnet