Merge pull request #2611 from yyforyongyu/task-btcutil-audit
What changed, and why it matters
This commit tightens two safety checks in btcd's helper libraries. First, it makes child key derivation reject rare 'cancellation' cases where a derived private key would become zero or a public key would become the point at infinity—both of which are unusable and could previously be returned silently. Second, it makes PSBT fee calculation reject inconsistent UTXO descriptions, so a malicious or buggy PSBT cannot report one input value via its non-witness UTXO and a different value via its witness UTXO. These are defensive hardening fixes rather than active remote-exploitable bugs.
Review downstream callers of Derive/DeriveNonStandard and PSBT GetTxFee/SumUtxoInputValues to ensure they already handle ErrInvalidChild and fee-calculation errors correctly. The PSBT change is behavior-changing: callers that previously supplied conflicting UTXO data and received a fee will now error, so update tests and documentation accordingly. No immediate emergency response is indicated.
Security signals we found
Rejection of zero private scalar and point-at-infinity in BIP32 derivation
Reconciliation of conflicting witness/non-witness UTXO descriptions in PSBT fee computation
Addition of unit tests exercising the new rejection paths
Comments clarifying that UTXO consistency does not imply UTXO authenticity
Evidence from the diff
The patch modifies btcutil/hdkeychain/extendedkey.go so both Derive and DeriveNonStandard return ErrInvalidChild when the final private scalar is zero modulo N or the resulting public Jacobian point is at infinity. It introduces a swappable hmacSHA512 variable to allow tests to inject the mathematically improbable HMAC outputs needed to reach these cancellation states. It also modifies psbt/utils.go so SumUtxoInputValues checks that NonWitnessUtxo and WitnessUtxo, when both present, describe the same previous output (via TxOutsEqual) and that the referenced output index exists. The PSBT comments explicitly note that consistency checks do not authenticate the UTXOs.
Changed components
btcutil/hdkeychain/extendedkey.gopsbt/utils.gopsbt/psbt.goInspect captured patch +254 / −21
### btcutil/go.mod
@@ -13,11 +13,15 @@ require (
github.com/davecgh/go-spew v1.1.1
github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1
github.com/kkdai/bstream v1.0.0
+ github.com/stretchr/testify v1.10.0
)
require (
github.com/btcsuite/btclog v1.0.0 // indirect
github.com/decred/dcrd/crypto/blake256 v1.1.0 // indirect
+ github.com/pmezard/go-difflib v1.0.0 // indirect
+ github.com/stretchr/objx v0.5.2 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect
+ gopkg.in/yaml.v3 v3.0.1 // indirect
)
### btcutil/go.sum
@@ -24,11 +24,14 @@ github.com/kkdai/bstream v1.0.0 h1:Se5gHwgp2VT2uHfDrkbbgbgEvV9cimLELwrPJctSjg8=
github.com/kkdai/bstream v1.0.0/go.mod h1:FDnDOHt5Yx4p3FaHcioFT0QjDOtgUpvjeZqAs+NVZZA=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
### btcutil/hdkeychain/extendedkey.go
@@ -70,11 +70,13 @@ var (
ErrNotPrivExtKey = errors.New("unable to create private keys from a " +
"public extended key")
- // ErrInvalidChild describes an error in which the child at a specific
- // index is invalid due to the derived key falling outside of the valid
- // range for secp256k1 private keys. This error indicates the caller
- // should simply ignore the invalid child extended key at this index and
- // increment to the next index.
+ // ErrInvalidChild describes an unusable child derivation, including
+ // an out-of-range intermediate scalar, a zero final private scalar,
+ // or a final public point at infinity. The caller should skip this
+ // child and increment to the next index.
+ //
+ // Final cancellation requires a particular HMAC output, making it
+ // impractical to exercise with natural derivation vectors.
ErrInvalidChild = errors.New("the extended key at this index is invalid")
// ErrUnusableSeed describes an error in which the provided seed is not
@@ -102,6 +104,14 @@ var (
// the master node in the hierarchical tree.
var masterKey = []byte("Bitcoin seed")
+// hmacSHA512 computes the HMAC used for child derivation. Tests replace this
+// function to reach cancellation results that natural vectors cannot exercise.
+var hmacSHA512 = func(chainCode, data []byte) []byte {
+ hmac512 := hmac.New(sha512.New, chainCode)
+ _, _ = hmac512.Write(data)
+ return hmac512.Sum(nil)
+}
+
// ExtendedKey houses all the information needed to support a hierarchical
// deterministic extended key. See the package overview documentation for
// more details on how to use extended keys.
@@ -275,9 +285,7 @@ func (k *ExtendedKey) Derive(i uint32) (*ExtendedKey, error) {
// Take the HMAC-SHA512 of the current key's chain code and the derived
// data:
// I = HMAC-SHA512(Key = chainCode, Data = data)
- hmac512 := hmac.New(sha512.New, k.chainCode)
- _, _ = hmac512.Write(data)
- ilr := hmac512.Sum(nil)
+ ilr := hmacSHA512(k.chainCode, data)
// Split "I" into two 32-byte sequences Il and Ir where:
// Il = intermediate key used to derive the child
@@ -317,7 +325,12 @@ func (k *ExtendedKey) Derive(i uint32) (*ExtendedKey, error) {
return nil, ErrInvalidChild
}
- childKeyBytes := ilNum.Add(&keyNum).Bytes()
+ // Valid operands can sum to zero modulo N even after Il passed
+ // its range check, leaving an unusable child private key.
+ if ilNum.Add(&keyNum).IsZero() {
+ return nil, ErrInvalidChild
+ }
+ childKeyBytes := ilNum.Bytes()
childKey = childKeyBytes[:]
// Strip leading zeroes from childKey, to match the expectation
@@ -364,6 +377,14 @@ func (k *ExtendedKey) Derive(i uint32) (*ExtendedKey, error) {
var childKeyPubJ btcec.JacobianPoint
btcec.AddNonConst(&ilJ, &pubKeyJ, &childKeyPubJ)
+ // Opposite valid points sum to infinity, which cannot represent
+ // a child public key. Check before affine conversion loses Z.
+ if (childKeyPubJ.X.IsZero() && childKeyPubJ.Y.IsZero()) ||
+ childKeyPubJ.Z.IsZero() {
+
+ return nil, ErrInvalidChild
+ }
+
// Convert the new child public key back to affine coordinates
// so we can serialize it in compressed format.
childKeyPubJ.ToAffine()
@@ -387,6 +408,10 @@ func (k *ExtendedKey) IsAffectedByIssue172() bool {
return len(k.key) < 32
}
+// DeriveNonStandard derives a child using the historical derivation behavior.
+// It returns ErrInvalidChild for a zero private child or a public point
+// at infinity.
+//
// Deprecated: This is a non-standard derivation that is affected by issue #172.
// 1-of-256 hardened derivations will be wrong. See note in the Derive method
// and IsAffectedByIssue172.
@@ -409,9 +434,7 @@ func (k *ExtendedKey) DeriveNonStandard(i uint32) (*ExtendedKey, error) {
}
binary.BigEndian.PutUint32(data[keyLen:], i)
- hmac512 := hmac.New(sha512.New, k.chainCode)
- _, _ = hmac512.Write(data)
- ilr := hmac512.Sum(nil)
+ ilr := hmacSHA512(k.chainCode, data)
il := ilr[:len(ilr)/2]
childChainCode := ilr[len(ilr)/2:]
@@ -427,6 +450,11 @@ func (k *ExtendedKey) DeriveNonStandard(i uint32) (*ExtendedKey, error) {
keyNum := new(big.Int).SetBytes(k.key)
ilNum.Add(ilNum, keyNum)
ilNum.Mod(ilNum, btcec.S256().N)
+ // Reject a zero sum of valid operands; serializing it would
+ // otherwise create an unusable child private key.
+ if ilNum.Sign() == 0 {
+ return nil, ErrInvalidChild
+ }
childKey = ilNum.Bytes()
isPrivate = true
} else {
@@ -454,6 +482,14 @@ func (k *ExtendedKey) DeriveNonStandard(i uint32) (*ExtendedKey, error) {
var childKeyPubJ btcec.JacobianPoint
btcec.AddNonConst(&ilJ, &pubKeyJ, &childKeyPubJ)
+ // Valid parent and intermediate points can cancel to infinity;
+ // reject the result before converting it for serialization.
+ if (childKeyPubJ.X.IsZero() && childKeyPubJ.Y.IsZero()) ||
+ childKeyPubJ.Z.IsZero() {
+
+ return nil, ErrInvalidChild
+ }
+
childKeyPubJ.ToAffine()
childKeyPub := btcec.NewPublicKey(
&childKeyPubJ.X, &childKeyPubJ.Y,
### btcutil/hdkeychain/extendedkey_test.go
@@ -19,8 +19,98 @@ import (
"github.com/btcsuite/btcd/chaincfg/v2"
secp_ecdsa "github.com/decred/dcrd/dcrec/secp256k1/v4"
+ "github.com/stretchr/testify/mock"
+ "github.com/stretchr/testify/require"
)
+// childHMACMock supplies cancellation outputs without searching for an
+// infeasible natural HMAC preimage.
+type childHMACMock struct {
+ mock.Mock
+}
+
+// sum records the child derivation request and returns its arranged HMAC
+// output so the real derivation code handles the cancellation.
+func (m *childHMACMock) sum(chainCode, data []byte) []byte {
+ args := m.Called(chainCode, data)
+ return args.Get(0).([]byte)
+}
+
+// TestExtendedKeyRejectInvalidChild checks that both derivation methods reject
+// final scalar/point cancellation instead of returning an unusable child.
+func TestExtendedKeyRejectInvalidChild(t *testing.T) {
+ // Arrange: use a valid parent and its matching public key. Negating a
+ // copy of the private scalar makes Il cancel either parent's key when
+ // added modulo N, producing zero privately and infinity publicly.
+ parent, err := NewMaster(
+ bytes.Repeat([]byte{1}, MinSeedBytes), &chaincfg.MainNetParams,
+ )
+ require.NoError(t, err)
+ publicParent, err := parent.Neuter()
+ require.NoError(t, err)
+ privateKey, err := parent.ECPrivKey()
+ require.NoError(t, err)
+ il := privateKey.Key
+ il.Negate()
+ ilBytes := il.Bytes()
+ forcedILR := make([]byte, 64)
+ copy(forcedILR, ilBytes[:])
+ originalHMAC := hmacSHA512
+
+ tests := []struct {
+ name string
+ parent *ExtendedKey
+ derive func(*ExtendedKey, uint32) (*ExtendedKey, error)
+ }{
+ {
+ name: "standardPrivateZero",
+ parent: parent,
+ derive: (*ExtendedKey).Derive,
+ },
+ {
+ name: "standardPublicInfinity",
+ parent: publicParent,
+ derive: (*ExtendedKey).Derive,
+ },
+ {
+ name: "nonStandardPrivateZero",
+ parent: parent,
+ derive: (*ExtendedKey).DeriveNonStandard,
+ },
+ {
+ name: "nonStandardPublicInfinity",
+ parent: publicParent,
+ derive: (*ExtendedKey).DeriveNonStandard,
+ },
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ // Arrange: force the cancelling Il at the hash boundary
+ // while the public method performs its normal key math.
+ // Run serially; restore the real hash after each case.
+ childHMAC := &childHMACMock{}
+ childHMAC.On(
+ "sum", test.parent.chainCode, mock.Anything,
+ ).Return(forcedILR).Once()
+ hmacSHA512 = childHMAC.sum
+ t.Cleanup(func() {
+ hmacSHA512 = originalHMAC
+ childHMAC.AssertExpectations(t)
+ })
+
+ // Act: call the selected public method at index zero.
+ // Its final addition must reach the cancellation guard,
+ // rather than failing an earlier input check.
+ child, err := test.derive(test.parent, 0)
+
+ // Assert: return ErrInvalidChild without a child key,
+ // allowing callers to skip this unusable index.
+ require.ErrorIs(t, err, ErrInvalidChild)
+ require.Nil(t, child)
+ })
+ }
+}
+
// TestBIP0032Vectors tests the vectors provided by [BIP32] to ensure the
// derivation works as intended.
func TestBIP0032Vectors(t *testing.T) {
### psbt/psbt.go
@@ -536,8 +536,10 @@ func (p *Packet) SanityCheck() error {
return nil
}
-// GetTxFee returns the transaction fee. An error is returned if a transaction
-// input does not contain any UTXO information.
+// GetTxFee returns the transaction fee using the supplied UTXO information.
+// An error is returned for missing UTXO information, an invalid previous-output
+// index, or conflicting witness and non-witness output descriptions. The caller
+// remains responsible for authenticating the supplied UTXOs.
func (p *Packet) GetTxFee() (btcutil.Amount, error) {
sumInputs, err := SumUtxoInputValues(p)
if err != nil {
### psbt/utils.go
@@ -336,8 +336,9 @@ func readTransaction(txBytes []byte, noWitness bool) (*wire.MsgTx, error) {
}
// SumUtxoInputValues tries to extract the sum of all inputs specified in the
-// UTXO fields of the PSBT. An error is returned if an input is specified that
-// does not contain any UTXO information.
+// UTXO fields of the PSBT. An error is returned for missing UTXO information,
+// an invalid previous-output index, or conflicting witness and non-witness
+// output descriptions. Consistency does not authenticate the supplied UTXOs.
func SumUtxoInputValues(packet *Packet) (int64, error) {
// We take the TX ins of the unsigned TX as the truth for how many
// inputs there should be, as the fields in the extra data part of the
@@ -350,10 +351,6 @@ func SumUtxoInputValues(packet *Packet) (int64, error) {
inputSum := int64(0)
for idx, in := range packet.Inputs {
switch {
- case in.WitnessUtxo != nil:
- // Witness UTXOs only need to reference the TxOut.
- inputSum += in.WitnessUtxo.Value
-
case in.NonWitnessUtxo != nil:
// Non-witness UTXOs reference to the whole transaction
// the UTXO resides in.
@@ -368,7 +365,20 @@ func SumUtxoInputValues(packet *Packet) (int64, error) {
"TxOut field", idx)
}
- inputSum += utxOuts[txIn.PreviousOutPoint.Index].Value
+ // Reconcile descriptions so their precedence cannot
+ // change the reported fee.
+ prevOut := utxOuts[opIdx]
+ if in.WitnessUtxo != nil &&
+ !TxOutsEqual(prevOut, in.WitnessUtxo) {
+
+ return 0, fmt.Errorf("input %d has "+
+ "conflicting UTXO information", idx)
+ }
+ inputSum += prevOut.Value
+
+ case in.WitnessUtxo != nil:
+ // Witness UTXOs only need to reference the TxOut.
+ inputSum += in.WitnessUtxo.Value
default:
return 0, fmt.Errorf("input %d has no UTXO information",
### psbt/utils_test.go
@@ -7,6 +7,7 @@ import (
"github.com/btcsuite/btcd/chainhash/v2"
"github.com/btcsuite/btcd/wire/v2"
+ "github.com/stretchr/testify/require"
)
func TestSumUtxoInputValues(t *testing.T) {
@@ -73,6 +74,93 @@ func TestSumUtxoInputValues(t *testing.T) {
}
}
+// TestGetTxFeeConflictingUtxos ensures dual UTXO descriptions must agree before
+// their input value can be used to report a transaction fee.
+func TestGetTxFeeConflictingUtxos(t *testing.T) {
+ // Arrange: vary only the witness description or selected output index
+ // against a fixed 100,000-sat previous output to isolate inconsistency.
+ tests := []struct {
+ name string
+ witnessValue int64
+ witnessScript []byte
+ outputIndex uint32
+ wantErr bool
+ }{
+ {
+ name: "matching descriptions",
+ witnessValue: 100_000,
+ witnessScript: []byte{0x51},
+ outputIndex: 0,
+ wantErr: false,
+ },
+ {
+ name: "conflicting amount",
+ witnessValue: 1_000_000,
+ witnessScript: []byte{0x51},
+ outputIndex: 0,
+ wantErr: true,
+ },
+ {
+ name: "conflicting script",
+ witnessValue: 100_000,
+ witnessScript: []byte{0x00},
+ outputIndex: 0,
+ wantErr: true,
+ },
+ {
+ name: "missing referenced output",
+ witnessValue: 100_000,
+ witnessScript: []byte{0x51},
+ outputIndex: 1,
+ wantErr: true,
+ },
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ // Arrange: attach both UTXO descriptions to an input
+ // that spends the supplied previous transaction, so
+ // the public fee API must reconcile them.
+ previous := wire.NewMsgTx(2)
+ previous.AddTxIn(
+ wire.NewTxIn(&wire.OutPoint{}, nil, nil),
+ )
+ previous.AddTxOut(wire.NewTxOut(100_000, []byte{0x51}))
+ previousHash := previous.TxHash()
+ spending := wire.NewMsgTx(2)
+ spending.AddTxIn(
+ wire.NewTxIn(
+ wire.NewOutPoint(
+ &previousHash, test.outputIndex,
+ ),
+ nil, nil,
+ ),
+ )
+ spending.AddTxOut(wire.NewTxOut(90_000, []byte{0x51}))
+ packet, err := NewFromUnsignedTx(spending)
+ require.NoError(t, err)
+ packet.Inputs[0].NonWitnessUtxo = previous
+ packet.Inputs[0].WitnessUtxo = wire.NewTxOut(
+ test.witnessValue, test.witnessScript,
+ )
+
+ // Act: call the public fee API to exercise error
+ // propagation from the input-value calculation.
+ fee, err := packet.GetTxFee()
+
+ // Assert: inconsistent data must return an error
+ // and zero fee; matching descriptions yield
+ // 100,000 minus 90,000 satoshis.
+ if test.wantErr {
+ require.Error(t, err)
+ require.Zero(t, fee)
+ return
+ }
+ require.NoError(t, err)
+ require.EqualValues(t, 10_000, fee)
+ })
+ }
+}
+
func TestTxOutsEqual(t *testing.T) {
testCases := []struct {
name stringWhy this scored 61/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.