🔑 Key Derivation (KDF)

IBEx.Fi deterministically derives wallet keys from a single master secret tied to the user's passkey. One passkey → one master → addresses on every supported blockchain. The server never stores private keys in plaintext.

What is a KDF?

A Key Derivation Function (KDF) takes a high-entropy secret (the master) and produces one or more cryptographic keys. IBEx uses HKDF-SHA256 (RFC 5869):

derivedKey = HKDF(SHA-256, masterBytes, salt, info, length)
                                         │       │      │
                    "ibexfi:derivation:v1"┘       │      └── 32 bytes
                                 ecosystem label ─┘

The info string uniquely identifies the target ecosystem, ensuring each chain gets a different key from the same master — without the master being recoverable from any derived key.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│  Passkey (FIDO2 authenticator)                                   │
│                                                                  │
│  Option 1: PRF extension (preferred)                             │
│    salt = SHA-256("ibexfi:prf:v1:master|rpId:<rpId>")            │
│    → authenticator returns prf.first bytes (32 bytes)            │
│                                                                  │
│  Option 2: Sealed master fallback                                │
│    → backend generates 32 random bytes                           │
│    → encrypted with AES-256-GCM, stored in DB                    │
│    → decrypted at runtime when derivations needed                │
└──────────────────────────────────────────────────────────────────┘
                              │
                      masterBytes (32 bytes)
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌─────────────┐ ┌───────────┐ ┌──────────────┐
       │  EVM EOA     │ │  Solana   │ │  Bitcoin     │
       │  secp256k1   │ │  ed25519  │ │  secp256k1   │
       └─────────────┘ └───────────┘ └──────────────┘
              │               │               │
              ▼               ▼               ▼
     And also: Cosmos, Polkadot, Tezos, NEAR, Stellar, Cardano

Master Secret: How It's Obtained

Option 1 — PRF (Preferred)

The WebAuthn PRF extension lets the authenticator evaluate a pseudorandom function over a server-provided salt. The result is deterministic for the same passkey + salt, but unpredictable to anyone without the authenticator.

// PRF salt (tenant-scoped, deterministic)
salt = SHA-256("ibexfi:prf:v1:master|rpId:" + effectiveRpId)

// Browser sends to authenticator → returns prf.first (32 bytes)

With PRF, no secret material is stored server-side — the master only exists transiently in memory during the authentication response.

Option 2 — Sealed Master (Fallback)

When the authenticator doesn't support PRF, the backend generates 32 random bytes and stores them encrypted in the database:

// Encryption key
key = SHA-256(DERIVATION_SECRET + "|" + DERIVATION_SALT)   // 32 bytes

// Seal
AES-256-GCM(key, nonce=12 bytes, plaintext=masterBytes)
→ stored as { ct, iv, tag } in Signer.data.derivation.sealedMaster

Decryption requires both the database (ciphertext) and the server secrets (DERIVATION_SECRET / DERIVATION_SALT).

Sealed Envelope in Practice

The choice between PRF and sealed master is made automatically at each authentication ceremony. Here is the concrete flow:

Sign-Up

1. User registers a passkey (WebAuthn)
2. Browser returns clientExtensionResults.prf.results.first?
   • Yes (PRF capable) → use it as masterBytes (32 bytes)
   • No (PRF not supported) → backend generates 32 random bytes, encrypts them with sealMaster() (AES-256-GCM), stores { ct, iv, tag } in Signer.data.derivation.sealedMaster
3. From masterBytes, all chain addresses are derived via HKDF
4. Derived addresses are stored in Signer.data.derivation

Sign-In

1. User authenticates with passkey
2. Check prf.results.first:
   • Present → use as masterBytes, source = PRF
   • Absent → check for sealedMaster in DB:
     • Found → unsealMaster() to decrypt, source = SEALED
     • Not found → generate fresh 32 bytes, seal and persist, source = FRESH
3. Re-derive all chain addresses (refresh in case new ecosystems were added)
4. Update Signer.data.derivation in DB

Note: PRF-capable devices produce the same masterBytes every time for the same passkey + salt. The master only exists transiently in memory — it is never stored. Non-PRF devices rely on the sealed envelope, which requires both DB access and server secrets to unlock.

Derivation Table

All derivations use HKDF(SHA-256, masterBytes, salt, info, 32) with salt = "ibexfi:derivation:v1":

Ecosystem	Info Label	Curve / Algo	Address Format
EVM (EOA)	global:single_eoa	secp256k1	Keccak-256, last 20 bytes, checksum
Solana	solana:global	Ed25519	base58-encoded public key
Bitcoin P2WPKH	bitcoin:global	secp256k1	bech32 (witness v0, bc1q...)
Bitcoin Taproot	bitcoin:taproot	secp256k1 + TapTweak	bech32m (witness v1, bc1p...)
Cosmos	cosmos:<hrp>	secp256k1	bech32 (cosmos1..., osmo1...)
Polkadot	polkadot:ss58	Ed25519	SS58 (base58 + BLAKE2b)
Tezos tz1	tezos:tz1	Ed25519	tz1... (base58check)
Tezos tz2	tezos:tz2	secp256k1	tz2... (base58check)
Tezos tz3	tezos:tz3	P-256	tz3... (base58check)
NEAR	near:implicit	Ed25519	hex public key (implicit account)
Stellar	stellar:global	Ed25519	G... (StrKey)
Cardano	cardano:enterprise	Ed25519	addr1... (bech32, BLAKE2b-224)

EVM Derivation: Step by Step

// 1. HKDF-SHA256 extract + expand
ikm  = masterBytes                         // 32 bytes
salt = "ibexfi:derivation:v1"
info = "global:single_eoa"
okm  = HKDF(SHA-256, ikm, salt, info, 32)  // 32 bytes output

// 2. Reduce mod secp256k1 curve order
n   = secp256k1.CURVE.n                    // ~1.158 × 10⁷⁷
num = bytesToNumberBE(okm) % n
if (num == 0) num = 1                      // avoid zero scalar

// 3. Derive public key + Ethereum address
privateKey  = numberToBytesBE(num, 32)
publicKey   = secp256k1.getPublicKey(privateKey, false).slice(1)  // 64 bytes uncompressed
addressHash = Keccak-256(publicKey)
address     = "0x" + last20bytes(addressHash)                     // checksum

Safe Wallet vs Derived Wallets

The Safe{Wallet} and derived wallets use different mechanisms from the same identity anchor (the passkey Signer):

Aspect	Safe{Wallet}	Derived Wallets (EOA, Solana, BTC...)
Type	Smart contract wallet	Native chain addresses
Derivation	X/Y coordinates of the P-256 passkey public key → WebAuthn signer contract → Safe address	Master bytes (PRF or sealed) → HKDF → chain-specific key
Private key	None (smart contract, no ECDSA key)	Derived in-memory, never stored
Signing	WebAuthn assertion (authenticator signs)	Passkey PRF → master → derive key → sign

PIN/KDF Wallet Mode

For clients that cannot use passkeys, IBEx supports a PIN/KDF mode (wallet=kdf) where the master is derived client-side from a PIN or password:

1. Client derives private key from secret (PIN + KDF parameters)
2. Client signs a challenge, sends signature + public key to server
3. Server verifies signature — confirms the client holds the key
4. Server stores only the public address (no private key)
5. Safe address is computed deterministically from the EOA address

Key difference: In passkey mode, the server can request WebAuthn signatures via the authenticator. In KDF mode, the client must sign explicitly — the server only verifies.

Security Model

Threat	Protection
DB breach (read sealed master)	AES-256-GCM — requires server secrets to decrypt
Server secret leak	Without DB ciphertext, secrets alone are useless
Both DB + secrets compromised	Can derive keys — mitigate with KMS, rotation, monitoring
PRF mode: backend compromise	Master never stored — only in memory during auth, from authenticator
Derived key recovery from address	HKDF is a one-way function — address → key is infeasible

Recommendations

• Enforce DERIVATION_SECRET / DERIVATION_SALT at startup (no defaults)
• Store secrets in a KMS, not environment files
• Prefer PRF-capable authenticators for zero server-side custody
• Never log PRF outputs, unsealed master, or derived private keys

⚠️ Warning: If the master secret is lost — passkey deleted without PRF backup, or DERIVATION_SECRET/DERIVATION_SALT lost for sealed envelopes — all derived wallets become permanently inaccessible. Funds on those addresses cannot be recovered.

The only safety net is the Recovery module: when enabled, a secondary signer (recovery key or social recovery guardian) can regain control of the Safe{Wallet}. Recovery does not restore the derived multi-chain addresses (Solana, Bitcoin…), only the Safe smart wallet.

Implementation

The derivation logic is in derivationService.ts, using @noble/hashes and @noble/curves:

• deriveGlobalPrivateKeyFromPrf() — EVM EOA (secp256k1)
• deriveSolanaAddressFromPrf() — Solana (Ed25519)
• deriveBitcoinP2WPKHFromPrf() — Bitcoin P2WPKH (bech32)
• deriveBitcoinP2TRFromPrf() — Bitcoin Taproot (bech32m)
• deriveCosmosAddressFromPrf() — Cosmos (bech32)
• derivePolkadotAddressFromPrf() — Polkadot (SS58)
• deriveTezosTz1/Tz2/Tz3FromPrf() — Tezos (base58check)
• deriveNearImplicitFromPrf() — NEAR (hex)
• deriveStellarFromPrf() — Stellar (StrKey)
• deriveCardanoAddrFromPrf() — Cardano (bech32)
• sealMaster() / unsealMaster() — AES-256-GCM fallback

See Also

• Passkeys — How They Work
• Safe Global Wallets
• EOA Wallets (EIP-7702)
• Supported Blockchains