Skip to main content

KeyStore Files

The Simple Way
var service = new KeyStoreService();
// Encrypt
var json = service.EncryptAndGenerateDefaultKeyStoreAsJson("password", keyBytes, address);
// Decrypt
var key = service.DecryptKeyStoreFromJson("password", json);

KeyStoreService defaults to Scrypt for encryption and auto-detects the KDF for decryption.

After generating or importing a private key (as covered in Keys & Accounts), you need a safe way to store it. KeyStore files encrypt private keys to JSON using the Web3 Secret Storage Definition — the same format used by MetaMask, Geth, and other wallets. The encrypted JSON can be safely stored on disk — the private key is only accessible with the correct password.

dotnet add package Nethereum.KeyStore

Encrypt a Key (Scrypt)​

Scrypt is the recommended KDF — it's memory-hard, making brute-force attacks expensive.

using Nethereum.KeyStore;
using Nethereum.Signer;

var ecKey = EthECKey.GenerateKey();
var address = ecKey.GetPublicAddress();
var privateKeyBytes = ecKey.GetPrivateKeyAsBytes();

var keyStoreService = new KeyStoreScryptService();
var json = keyStoreService.EncryptAndGenerateKeyStoreAsJson(
    "your-strong-password", privateKeyBytes, address);

File.WriteAllText($"keystore-{address}.json", json);

Custom Scrypt Parameters​

Tune the cost parameter for your platform. Lower values are faster but less secure:

// Default: N=262144 (strong, slow — desktop)
var json = keyStoreService.EncryptAndGenerateKeyStoreAsJson(
    "password", privateKeyBytes, address);

// Light: N=32 (fast — WASM, mobile, tests)
var scryptParams = new ScryptParams { N = 32, R = 8, P = 6 };
var json = keyStoreService.EncryptAndGenerateKeyStoreAsJson(
    "password", privateKeyBytes, address, scryptParams);

Encrypt a Key (PBKDF2)​

Legacy KDF — use for compatibility with older wallets:

var keyStoreService = new KeyStorePbkdf2Service();
var json = keyStoreService.EncryptAndGenerateKeyStoreAsJson(
    "password", privateKeyBytes, address);

Decrypt a KeyStore​

var json = File.ReadAllText("keystore-file.json");

// Auto-detect KDF type (scrypt or pbkdf2)
var keyStoreService = new KeyStoreService();
var privateKeyBytes = keyStoreService.DecryptKeyStoreFromJson("your-password", json);

var account = new Nethereum.Web3.Accounts.Account(privateKeyBytes, chainId: 1);

Detect KDF Type​

var kdfType = KeyStoreKdfChecker.GetKdfType(json);
// Returns "scrypt" or "pbkdf2"

Default KeyStore Service​

KeyStoreService is a convenience wrapper that defaults to Scrypt for encryption and auto-detects for decryption:

var service = new KeyStoreService();

// Encrypt (uses Scrypt by default)
var json = service.EncryptAndGenerateDefaultKeyStoreAsJson(
    "password", privateKeyBytes, address);

// Decrypt (auto-detects KDF)
var key = service.DecryptKeyStoreFromJson("password", json);

Next Steps​

  • HD Wallets — derive multiple accounts from a single mnemonic instead of managing individual keys
  • Hardware Wallets — if you need keys that never touch disk at all, use a hardware device
  • Keys & Accounts — account types and key generation