Crypto API

The Crypto API provides key generation, signing, hashing, encoding helpers, and CIP-1852 HD derivation utilities used across the Cardano Client Library.

Overview

• Key generation: Ed25519 keys and key pairs
• Mnemonic management: BIP39 generation and validation
• HD derivation: CIP-1852 paths for Cardano
• Sign/verify: Ed25519/BIP32-Ed25519 signing
• Hashing: Blake2b helpers
• Encoding: Bech32 and hex utilities

Key Generation

Keys keyPair = KeyGenUtil.generateKey();
SecretKey privateKey = keyPair.getSkey();
VerificationKey publicKey = keyPair.getVkey();

byte[] keyHashBytes = Blake2bUtil.blake2bHash224(publicKey.getBytes());
String keyHashHex = HexUtil.encodeHexString(keyHashBytes);

// Convenience: 28-byte key hash as hex
String keyHash = KeyGenUtil.getKeyHash(publicKey);

Mnemonic Management

// Generate mnemonic
String mnemonic24 = MnemonicUtil.generateNew(Words.TWENTY_FOUR);

// Validate mnemonic
MnemonicUtil.validateMnemonic(mnemonic24);

// Convert to entropy and seed
byte[] entropy = MnemonicCode.INSTANCE.toEntropy(mnemonic24);
byte[] seed = MnemonicCode.toSeed(Arrays.asList(mnemonic24.split(" ")), "");

Derive directly from entropy (e.g., when you already have raw bytes):

byte[] entropyBytes = ...;
HdKeyPair rootFromEntropy = new HdKeyGenerator().getRootKeyPairFromEntropy(entropyBytes);

CIP-1852 HD Derivation

Common derivation helpers (no createAccountDerivationPath factory exists):

• External address: DerivationPath.createExternalAddressDerivationPath(index)
• Internal address: DerivationPath.createInternalAddressDerivationPath(index)
• Stake address: DerivationPath.createStakeAddressDerivationPath()
• Account-specific variants: createExternalAddressDerivationPathForAccount, createInternalAddressDerivationPathForAccount, createStakeAddressDerivationPathForAccount
• Other roles: createDRepKeyDerivationPathForAccount, createCommitteeColdKeyDerivationPathForAccount, createCommitteeHotKeyDerivationPathForAccount

CIP1852 cip1852 = new CIP1852();
String mnemonic = "...";

DerivationPath externalPath = DerivationPath.createExternalAddressDerivationPath(0);
HdKeyPair keyPair = cip1852.getKeyPairFromMnemonic(mnemonic, externalPath);

HdKeyPair rootKeyPair = cip1852.getRootKeyPairFromMnemonic(mnemonic);

Advanced derivation options

// Specify derivation type and passphrase
HdKeyPair ledgerPair = cip1852.getKeyPairFromMnemonic(
        mnemonic,
        "optional-passphrase",
        externalPath,
        Bip32Type.LEDGER);

HdKeyPair trezorRoot = cip1852.getRootKeyPairFromMnemonic(mnemonic, Bip32Type.TREZOR);

Deriving from existing keys

byte[] accountXprv = ...; // account private key (xprv)
DerivationPath rolePath = DerivationPath.createExternalAddressDerivationPathForAccount(0);

// Get child key pair from account key
HdKeyPair fromAccount = cip1852.getKeyPairFromAccountKey(accountXprv, rolePath);

byte[] accountXpub = ...; // account public key
HdPublicKey paymentPub = cip1852.getPublicKeyFromAccountPubKey(accountXpub, 0, 0); // role 0, index 0

byte[] rootKey = ...; // root private key bytes
HdKeyPair fromRoot = cip1852.getKeyPairFromRootKey(rootKey, rolePath);

Signing and Verification

SigningProvider signingProvider = new EdDSASigningProvider();

byte[] message = "Hello, Cardano!".getBytes();
byte[] sk = privateKey.getBytes();       // 32 bytes
byte[] xsk = new byte[64];               // extended private key if available

byte[] sig1 = signingProvider.sign(message, sk);
byte[] sig2 = signingProvider.signExtended(message, xsk); // 64-byte extended key

// Legacy overload (with explicit public key) remains for compatibility
byte[] sig3 = signingProvider.signExtended(message, xsk, publicKey.getBytes());

boolean isValid = signingProvider.verify(sig1, message, publicKey.getBytes());

Configure a custom provider:

CryptoConfiguration.INSTANCE.setSigningProvider(new CustomSigningProvider());
SigningProvider provider = CryptoConfiguration.INSTANCE.getSigningProvider();

Hash Functions

byte[] input = "Hello, Cardano!".getBytes();

byte[] hash160 = Blake2bUtil.blake2bHash160(input);
byte[] hash224 = Blake2bUtil.blake2bHash224(input);
byte[] hash256 = Blake2bUtil.blake2bHash256(input);

String hex160 = HexUtil.encodeHexString(hash160);

Encoding and Decoding

// Bech32
String bech32Key = Bech32.encode(publicKey.getBytes(), "addr_vk");
Bech32.Bech32Data decoded = Bech32.decode(bech32Key);

// Hex
String hex = HexUtil.encodeHexString(new byte[]{0x01, 0x02});
byte[] bytes = HexUtil.decodeHexString(hex);

Error Handling

Handle failures explicitly, e.g., invalid mnemonics or derivation errors:

try {
    MnemonicUtil.validateMnemonic(mnemonic);
} catch (AddressRuntimeException e) {
    // invalid mnemonic
}

try {
    HdKeyPair keyPair = cip1852.getKeyPairFromMnemonic(mnemonic, externalPath);
} catch (CryptoException e) {
    // derivation failed
}

Best Practices

• Never log or persist raw private keys or mnemonics; clear sensitive byte arrays after use.
• Validate mnemonics before derivation.
• Reuse signing providers for performance in hot paths.
• Pick the correct derivation helper for the role (external/internal/stake/drep/committee).