hd-wallet-wasm 1.1.3 → 1.2.0

package/README.md

@@ -112,6 +112,50 @@ const xpub = master.toXpub();
 const pubOnly = master.neutered();
 ```
 
+### Signing & Encryption Keys (BIP-44)
+
+The library provides dedicated helpers for deriving separate signing and encryption
+keypairs from a single HD root. Signing keys use BIP-44 change=0 (external chain);
+encryption keys use change=1 (internal chain).
+
+```javascript
+import { getSigningKey, getEncryptionKey, buildSigningPath, buildEncryptionPath, WellKnownCoinType } from 'hd-wallet-wasm';
+
+const master = wallet.hdkey.fromSeed(seed);
+
+// Get signing keypair for Ethereum (m/44'/60'/0'/0/0)
+const signing = getSigningKey(master, 60);
+console.log('Signing pubkey:', wallet.utils.encodeHex(signing.publicKey));
+console.log('Path:', signing.path); // "m/44'/60'/0'/0/0"
+
+// Get encryption keypair for OrbPro marketplace (m/44'/9999'/0'/1/0)
+const encryption = getEncryptionKey(master, WellKnownCoinType.ORBPRO_MARKETPLACE);
+console.log('Encryption pubkey:', wallet.utils.encodeHex(encryption.publicKey));
+
+// Use encryption key for ECDH key agreement
+const shared = wallet.curves.secp256k1.ecdh(encryption.privateKey, otherPublicKey);
+
+// Multiple keys per account (e.g., one per plugin)
+const plugin0Key = getEncryptionKey(master, 9999, '0', '0');
+const plugin1Key = getEncryptionKey(master, 9999, '0', '1');
+
+// Path helpers are also available directly
+const sigPath = buildSigningPath(60);        // "m/44'/60'/0'/0/0"
+const encPath = buildEncryptionPath(9999);   // "m/44'/9999'/0'/1/0"
+
+// Clean up
+wallet.utils.secureWipe(signing.privateKey);
+wallet.utils.secureWipe(encryption.privateKey);
+master.wipe();
+```
+
+Also available as instance methods on the wallet module:
+
+```javascript
+const signing = wallet.getSigningKey(master, 60);
+const encryption = wallet.getEncryptionKey(master, 9999);
+```
+
 ### Multi-Curve Cryptography
 
 ```javascript
@@ -293,11 +337,51 @@ const wallet = await init();
 - Consider using hardware wallets for high-value operations
 - The library enforces key separation: external chain (0) for signing, internal chain (1) for encryption
 
-## FIPS Mode
+## FIPS 140-3 Mode
+
+The published NPM package includes OpenSSL 3.0.9 FIPS Provider support for compliance-critical applications.
+
+### Enabling FIPS Mode
+
+```javascript
+import init from 'hd-wallet-wasm';
+
+const wallet = await init();
+
+// Check if OpenSSL is available
+console.log('OpenSSL compiled:', wallet.isOpenSSL());
+
+// Initialize FIPS mode
+const fipsEnabled = wallet.initFips();
+console.log('FIPS active:', wallet.isOpenSSLFips());
+```
+
+### Algorithm Routing
+
+When FIPS mode is active, approved algorithms use OpenSSL FIPS provider:
+
+| Algorithm | FIPS Mode | Default |
+|-----------|-----------|---------|
+| SHA-256/384/512 | OpenSSL FIPS | Crypto++ |
+| AES-256-GCM | OpenSSL FIPS | Crypto++ |
+| ECDSA P-256/P-384 | OpenSSL FIPS | Crypto++ |
+| HKDF/PBKDF2 | OpenSSL FIPS | Crypto++ |
+| secp256k1 | Crypto++ | Crypto++ |
+| Ed25519 | Crypto++ | Crypto++ |
+| Keccak-256 | Crypto++ | Crypto++ |
+
+**Note:** secp256k1 (Bitcoin/Ethereum) and Ed25519 (Solana) are not FIPS-approved and always use Crypto++.
+
+### API Reference
+
+| Method | Description |
+|--------|-------------|
+| `wallet.isOpenSSL()` | Check if OpenSSL backend is compiled in |
+| `wallet.initFips()` | Initialize FIPS mode; returns true if successful |
+| `wallet.isOpenSSLFips()` | Check if FIPS provider is currently active |
+| `wallet.isFipsMode()` | Check if compiled with FIPS mode enabled |
 
-When built with FIPS mode enabled, only FIPS-approved algorithms are available:
-- P-256 and P-384 ECDSA (not secp256k1 or Ed25519)
-- FIPS-approved random number generation
+See the [main README](https://github.com/DigitalArsenal/hd-wallet-wasm#fips-140-3-compliance) for comprehensive FIPS documentation.
 
 ## License