Configuration

Configure passkey, salt, KDF iterations and runtime options for @tetherto/wdk-secret-manager

This page shows how to configure the Secret Manager instance, what parameters matter for security, and how to use environment/runtime options.

Constructor

Create Secret Manager

import WdkSecretManager from '@tetherto/wdk-secret-manager'

const passkey = 'correct horse battery staple'   // ≥ 12 chars (or Buffer/Uint8Array ≥ 12 bytes)
const salt    = WdkSecretManager.generateSalt()  // 16‑byte Buffer

// Optional: PBKDF2 iterations (default 100,000)
const sm = new WdkSecretManager(passkey, salt, { iterations: 100_000 })

Parameters

• passkey (string | Buffer | Uint8Array): User secret used to derive the encryption key. Must be at least 12 characters/bytes. Prefer a strong, user‑specific passkey from secure storage (e.g., Keychain/Keystore).

• salt (Buffer): 16‑byte random Buffer. The salt is not secret but must be unique per user/session. Store the salt alongside the encrypted payload.

• kdfParams.iterations (number, optional): PBKDF2 iterations (default 100_000). Increase for stronger resistance (with performance trade‑off).

Static Utilities

generateSalt()

Generate Salt

const salt = WdkSecretManager.generateSalt() // Buffer(16)

Recommended Settings

• Use at least 100_000 PBKDF2 iterations in mobile/desktop; consider higher values on powerful backends.

• Enforce passkeys ≥ 12 characters with mixed entropy (or binary secrets of similar strength).

• Generate a fresh 16‑byte salt per user/session; never reuse salts with the same passkey.

• Store salt with the encrypted payload; never store plaintext passkeys or mnemonics.

Runtime Notes

• Node.js: Uses sodium-native and Node crypto (PBKDF2).

• Bare runtime: A bare build is provided; PBKDF2 is handled by the bare crypto shim.

Examples

Generate and Encrypt Seed + Entropy

Generate & Encrypt

const { encryptedEntropy, encryptedSeed } = await sm.generateAndEncrypt()

// Decrypt later
const entropy = sm.decrypt(encryptedEntropy) // Buffer(16)
const seed    = sm.decrypt(encryptedSeed)    // Buffer(64)

Encrypt/Decrypt Arbitrary Data (16–64 bytes)

Encrypt/Decrypt Data

// Data length must be between 16 and 64 bytes
import { randomBytes } from 'crypto'
const data    = randomBytes(32)              // Buffer(32)
const payload = sm.encrypt(data)             // Buffer(header + ciphertext)
const out     = sm.decrypt(payload)          // Buffer(32)

Skip PBKDF2 with a Master Key

If you already have a 32‑byte key (e.g., derived via a KMS), you can skip PBKDF2:

Master Key Mode

import { pbkdf2Sync } from 'crypto'
import b4a from 'b4a'

const masterKey = b4a.from(pbkdf2Sync(b4a.from(passkey), b4a.from(salt), 100_000, 32, 'sha256'))

const cipher = sm.encrypt(Buffer.from('0123456789abcdef0123456789abcdef'), masterKey)
const plain  = sm.decrypt(cipher, masterKey)

Mnemonic Helpers

Entropy ↔ Mnemonic

const entropy16 = sm.generateRandomBuffer()         // Buffer(16)
const mnemonic  = sm.entropyToMnemonic(entropy16)   // 12 words
const entropy2  = sm.mnemonicToEntropy(mnemonic)    // Buffer(16)

Memory Management

Dispose

// Wipes internal passkey/salt/iteration state from memory
sm.dispose()

Constraints & Validation

• encrypt(data) requires data to be a Buffer of length 16–64 bytes.

• mnemonicToEntropy expects a 12‑word BIP39 mnemonic; throws on invalid input.

• Constructor validates passkey length/type and salt length (16 bytes).

Security Checklist

• Use strong, unique passkeys per user; never persist them in plaintext

• Generate a fresh 16‑byte salt per user/session

• Tune PBKDF2 iterations appropriate to your platform

• Encrypt before storing/sending secrets; keep operations in memory and call dispose() when done

---

Need Help?

Discord Community

Connect with developers, ask questions, share your projects

Join Community

GitHub Issues

Report bugs, request features, and get technical help

Open an Issue

Email Contact

For sensitive or private matters, contact our team directly

Send an email