Breaking changes from 3.x to 4.0 (WIP)

[chjj]

Some major backward-incompatible changes coming for the next version. Documenting them here.

AES

• ./lib/aes has been removed. Use ./lib/cipher instead (maybe -- on the fence with this one).

Base32

• Decoding is now much stricter and will throw properly on a malformed string (affects HNS consensus).
• base32.test() now throws if a non-string is passed.

Base58

• base58.test() now throws if a non-string is passed.

Bech32

• bech32.decode() now returns an array of [hrp, version, hash].
• bech32.test() now throws if a non-string is passed.

Bcrypt

• bcrypt.hash192() has been modified to accurately replicate bsd bcrypt.

BN

• BN#divmod(), BN#div(), and BN#mod() now perform euclidean division and modulo. Use BN#quorem(), BN#quo(), and BN#rem() for the truncated counterparts (go-style API).
• BN#umod() has been removed. Use BN#mod() instead.
• BN#bincn() has been removed.
• BN#invm() and BN#redInvm() have been renamed to BN#invert() and BN#redInvert() respectively.
• BN#finvm() and BN#redFinvm() have been renamed to BN#fermat() and BN#redFermat() respectively.
• Subtle changes to BN#egcd() have been made to accurately replicate GMP behavior (only affects negative numbers).

cash32/cashaddr

• cash32.decode() now returns an array of [prefix, type, hash].
• cash32.test() now throws if a non-string is passed.

ccmp

• ./lib/ccmp has been removed. Use ./lib/safe instead.

DRBG

• ./lib/drbg has been removed. Use ./lib/hmac-drbg, ./lib/hash-drbg, or ./lib/ctr-drbg instead.

DSA

• dsa.dh() has been removed. Use dsa.derive() instead.
• dsa.derive() now zero pads the resulting secret to the prime length.

ECDSA

• ec.generatePrivateKey() has been removed. Use ec.privateKeyGenerate() instead.
• ec.toDER() and ec.fromDER() have been removed. Use ec.signatureExport() and ec.signatureImport() instead.
• ec.ecdh() has been removed. Use ec.derive() instead.
• ec.signRecoverable() and ec.signRecoverableDER() now return an array of [sig, param].
• The recovery parameter is now mandatory for ec.recover() and ec.recoverDER().

ECIES/DSAIES/RSAIES

ECIES, DSAIES, and RSAIES have switched to using a variation of secretbox as a backend (xsalsa20poly1305). The legacy version will no longer be supported.

HKDF

• bcrypto.hkdf has been renamed to bcrypto.HKDF.

Internal

We shouldn't have been using this, but here are the changes:

• All trimming and padding functions have been moved to ./lib/encoding/util.
• trimZeroes has been renamed to trimLeft.
• leftPad has been renamed to padLeft.
• ./lib/internal/base64 has been moved to ./lib/encoding/base64.
• ./lib/internal/signature has changed significantly.

Random

• random.randomBytesAsync() has been removed.
• random.randomFillAsync() has been removed.

safe-equal

• ./lib/safe-equal has been removed. Use ./lib/safe instead.

siphash

• siphash.siphash256 has been removed. Use siphash.siphash instead.

---

I took a quick look through our ecosystem and here are the projects that are affected:

• bledger - Usage of toDER() and fromDER().
• bns - Usage of trimZeroes() and leftPad().
• hs-airdrop - Usage of trimZeroes() and internal/base64.
• bterm - Usage of signRecoverable().