Keystore generation, encryption and decryption for Ethereum key files using the Web3 Secret Storage definition, https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition
Password-encrypted private key storage using the Web3 Secret Storage Definition standard.
Overview
Nethereum.KeyStore implements the Web3 Secret Storage Definition for encrypting and storing Ethereum private keys. This is a standard format for encrypted key storage used across the Ethereum ecosystem.
Key Features:
AES-128-CTR encryption with password-derived keys
Scrypt KDF (memory-hard, ASIC-resistant)
PBKDF2 KDF (legacy, faster but less secure)
Configurable KDF parameters for performance tuning
JSON serialization/deserialization
Use Cases:
Encrypted local key storage
Wallet file generation
Key import/export between applications
Performance-tuned encryption for constrained environments (WASM, mobile)
Installation
dotnet add package Nethereum.KeyStore
Dependencies
Nethereum:
Nethereum.Hex - Hex encoding/decoding
External:
BouncyCastle.Cryptography or Portable.BouncyCastle (conditional) - Cryptographic operations
Quick Start
using Nethereum.KeyStore;
using Nethereum.Signer;
using Nethereum.Hex.HexConvertors.Extensions;
// Generate a new key
var ecKey = EthECKey.GenerateKey();
// Encrypt and generate keystore JSON
var service = new KeyStoreScryptService();
string password = "testPassword";
string json = service.EncryptAndGenerateKeyStoreAsJson(
password,
ecKey.GetPrivateKeyAsBytes(),
ecKey.GetPublicAddress()
);
// Decrypt later
byte[] privateKey = service.DecryptKeyStoreFromJson(password, json);
Usage Examples
Example 1: Generate Key and Create Keystore (Scrypt)
using Nethereum.KeyStore;
using Nethereum.Signer;
using Nethereum.Hex.HexConvertors.Extensions;
var ecKey = EthECKey.GenerateKey();
var keyStoreScryptService = new KeyStoreScryptService();
string password = "testPassword";
// Encrypt and serialize to JSON
string json = keyStoreScryptService.EncryptAndGenerateKeyStoreAsJson(
password,
ecKey.GetPrivateKeyAsBytes(),
ecKey.GetPublicAddress()
);
// Save to file
File.WriteAllText($"keystore-{ecKey.GetPublicAddress()}.json", json);
// Decrypt to verify
byte[] key = keyStoreScryptService.DecryptKeyStoreFromJson(password, json);
Assert.Equal(ecKey.GetPrivateKey(), key.ToHex(true));
Example 2: Custom Scrypt Parameters (Performance Tuning)
using Nethereum.KeyStore;
using Nethereum.KeyStore.Model;
using Nethereum.Signer;
using Nethereum.Hex.HexConvertors.Extensions;
var keyStoreService = new KeyStoreScryptService();
// Lower N for faster encryption (WASM, mobile, testing)
// Default: N=262144, R=1, P=8, Dklen=32
var scryptParams = new ScryptParams { Dklen = 32, N = 32, R = 1, P = 8 };
var ecKey = EthECKey.GenerateKey();
string password = "testPassword";
// Encrypt with custom parameters
var keyStore = keyStoreService.EncryptAndGenerateKeyStore(
password,
ecKey.GetPrivateKeyAsBytes(),
scryptParams.N,
scryptParams.R,
scryptParams.P,
null // salt (null = auto-generate)
);
// Serialize to JSON
string json = keyStoreService.SerializeKeyStoreToJson(keyStore);
// Decrypt
byte[] decryptedKey = keyStoreService.DecryptKeyStoreFromJson(password, json);
using Nethereum.KeyStore;
using Nethereum.Signer;
using Nethereum.Hex.HexConvertors.Extensions;
var ecKey = EthECKey.GenerateKey();
var keyStorePbkdf2Service = new KeyStorePbkdf2Service();
string password = "testPassword";
// Encrypt with PBKDF2 (faster but less secure than Scrypt)
string json = keyStorePbkdf2Service.EncryptAndGenerateKeyStoreAsJson(
password,
ecKey.GetPrivateKeyAsBytes(),
ecKey.GetPublicAddress()
);
// Decrypt
byte[] key = keyStorePbkdf2Service.DecryptKeyStoreFromJson(password, json);
Assert.Equal(ecKey.GetPrivateKey(), key.ToHex(true));
Example 5: Detect KDF Type
using Nethereum.KeyStore;
string keystoreJson = File.ReadAllText("wallet.json");
var keyStoreKdfChecker = new KeyStoreKdfChecker();
var kdfType = keyStoreKdfChecker.GetKeyStoreKdfType(keystoreJson);
if (kdfType == KeyStoreKdfChecker.KdfType.scrypt)
{
var service = new KeyStoreScryptService();
byte[] privateKey = service.DecryptKeyStoreFromJson(password, keystoreJson);
}
else if (kdfType == KeyStoreKdfChecker.KdfType.pbkdf2)
{
var service = new KeyStorePbkdf2Service();
byte[] privateKey = service.DecryptKeyStoreFromJson(password, keystoreJson);
}
Example 6: Default Keystore Service
using Nethereum.KeyStore;
using Nethereum.Signer;
using Nethereum.Hex.HexConvertors.Extensions;
var ecKey = EthECKey.GenerateKey();
var keyStoreService = new KeyStoreService();
string password = "testPassword";
// Uses default Scrypt parameters
string json = keyStoreService.EncryptAndGenerateDefaultKeyStoreAsJson(
password,
ecKey.GetPrivateKeyAsBytes(),
ecKey.GetPublicAddress()
);
byte[] key = keyStoreService.DecryptKeyStoreFromJson(password, json);
Assert.Equal(ecKey.GetPrivateKey(), key.ToHex(true));
API Reference
KeyStoreScryptService
Scrypt-based keystore encryption (recommended).
public class KeyStoreScryptService
{
// Encrypt and generate JSON (default parameters)
public string EncryptAndGenerateKeyStoreAsJson(string password, byte[] privateKey, string address);
// Encrypt with custom Scrypt parameters
public KeyStore<ScryptParams> EncryptAndGenerateKeyStore(
string password,
byte[] privateKey,
int n, int r, int p,
byte[] salt = null
);
// Serialize keystore to JSON
public string SerializeKeyStoreToJson(KeyStore<ScryptParams> keyStore);
// Deserialize JSON to keystore
public KeyStore<ScryptParams> DeserializeKeyStoreFromJson(string json);
// Decrypt from JSON
public byte[] DecryptKeyStoreFromJson(string password, string json);
// Decrypt from keystore object
public byte[] DecryptKeyStore(string password, KeyStore<ScryptParams> keyStore);
}
Default Scrypt Parameters:
N = 262144 // CPU/memory cost (2^18)
R = 1 // Block size
P = 8 // Parallelization
Dklen = 32 // Derived key length
KeyStorePbkdf2Service
PBKDF2-based keystore encryption (legacy).
public class KeyStorePbkdf2Service
{
// Same methods as KeyStoreScryptService but using PBKDF2
public string EncryptAndGenerateKeyStoreAsJson(string password, byte[] privateKey, string address);
public KeyStore<Pbkdf2Params> DeserializeKeyStoreFromJson(string json);
public byte[] DecryptKeyStoreFromJson(string password, string json);
public byte[] DecryptKeyStore(string password, KeyStore<Pbkdf2Params> keyStore);
}
KeyStoreService
Unified service with default encryption.
public class KeyStoreService
{
// Encrypt with default Scrypt parameters
public string EncryptAndGenerateDefaultKeyStoreAsJson(string password, byte[] privateKey, string address);
// Decrypt (auto-detects KDF type)
public byte[] DecryptKeyStoreFromJson(string password, string json);
}
KeyStoreKdfChecker
Detect KDF type from JSON.
public class KeyStoreKdfChecker
{
public enum KdfType { scrypt, pbkdf2 }
public KdfType GetKeyStoreKdfType(string json);
public bool IsScryptKdf(string json);
public bool IsPbkdf2Kdf(string json);
}
Model Classes
public class ScryptParams
{
public int Dklen { get; set; } // Derived key length (32)
public int N { get; set; } // CPU/memory cost (262144)
public int R { get; set; } // Block size (1)
public int P { get; set; } // Parallelization (8)
public string Salt { get; set; } // Random salt (hex)
}
public class Pbkdf2Params
{
public int Dklen { get; set; } // Derived key length (32)
public int C { get; set; } // Iteration count (262144)
public string Prf { get; set; } // PRF algorithm (hmac-sha256)
public string Salt { get; set; } // Random salt (hex)
}
public class KeyStore<TKdfParams>
{
public CryptoInfo<TKdfParams> Crypto { get; set; }
public string Id { get; set; } // UUID
public int Version { get; set; } // Always 3
public string Address { get; set; } // Ethereum address (optional)
}
Scrypt Parameter Tuning
Default Parameters (Desktop/Server)
N = 262144 // 2^18 - Strong security, ~100ms encryption
R = 1
P = 8
Use for: Desktop applications, servers, production wallets
Low-Cost Parameters (WASM/Mobile/Testing)
N = 32 // 2^5 - Fast encryption, weaker security
R = 1
P = 8
Use for: Browser WASM, mobile apps, development/testing
High-Security Parameters
N = 1048576 // 2^20 - Very strong security, ~3s encryption
R = 8
P = 1
Use for: Cold storage, high-value accounts, paranoid security
Parameter Effects
Parameter
Effect
Security Impact
Performance Impact
N
CPU/memory cost
Exponential
Exponential
R
Block size
Linear
Linear
P
Parallelization
Linear
Linear (if parallel)
N dominates: Doubling N doubles time and memory. N=262144 uses ~256MB RAM.