Merge branch 'main' into fil-570-stream-api

Author: bajtos

README.md

@@ -379,6 +379,16 @@ recipient   = [ {1: alg}, {4: kid, ...}, wrappedKey ]           # alg -31 or -5
   against a count re-derived from the plaintext length.
 - **Chunk count** (label −65791) — advisory metadata for range/seek consumers,
   emitted only when the plaintext length is known; not required to decrypt.
+- **ECDH-ES key derivation** (alg −31) — HKDF-SHA-256 (RFC 5869) over the X25519
+  shared secret, as RFC 9053 §6.3.1 requires, with the §5.2 `COSE_KDF_Context`
+  as the info parameter: `AlgorithmID` −5 (A256KW), empty PartyU/PartyV,
+  `keyDataLength` 256, and the recipient's serialized protected header
+  `h'a101381e'`. JOSE derives ECDH-ES differently (RFC 7518 §4.6 uses the NIST
+  SP 800-56A single-step KDF); a KEK derived that way will not unwrap. v0.1.0
+  used the COSE Concat-KDF here, so envelopes it encrypted to X25519 recipients
+  need decrypting with v0.1.0 and re-encrypting with this version; see the
+  [`ecdhkw` package documentation](https://pkg.go.dev/github.com/filecoin-project/go-fee/ecdhkw)
+  for the API change that comes with it.
 
 ## Security notes
 
@@ -407,7 +417,8 @@ recipient   = [ {1: alg}, {4: kid, ...}, wrappedKey ]           # alg -31 or -5
   [RFC 9053](https://www.rfc-editor.org/rfc/rfc9053) COSE algorithms,
   [RFC 9596](https://www.rfc-editor.org/rfc/rfc9596) COSE `typ` header,
   [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) CBOR,
-  [RFC 3394](https://www.rfc-editor.org/rfc/rfc3394) AES Key Wrap
+  [RFC 3394](https://www.rfc-editor.org/rfc/rfc3394) AES Key Wrap,
+  [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869) HKDF
 - [Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance](https://eprint.iacr.org/2015/189)
   — the STREAM construction
 

cose/cose_test.go

@@ -297,3 +297,26 @@ func TestEncStructure(t *testing.T) {
 		require.Equal(t, want, got)
 	})
 }
+
+// TestProtectedBytesIsolated pins ProtectedBytes against aliasing: the caller
+// gets a copy, so writing to the result cannot rewrite the decoded envelope's
+// protected header and with it the AAD and the recipient KDF context.
+func TestProtectedBytesIsolated(t *testing.T) {
+	encoded, err := sampleEnvelope().Encode()
+	require.NoError(t, err)
+	decoded, _, err := Decode(encoded)
+	require.NoError(t, err)
+
+	first, err := decoded.ProtectedBytes()
+	require.NoError(t, err)
+	require.NotEmpty(t, first, "sample envelope has a non-empty protected header")
+	want := bytes.Clone(first)
+
+	for i := range first {
+		first[i] ^= 0xFF
+	}
+
+	second, err := decoded.ProtectedBytes()
+	require.NoError(t, err)
+	require.Equal(t, want, second, "mutating the returned slice changed the protected header")
+}

cose/envelope.go

@@ -1,6 +1,7 @@
 package cose
 
 import (
+	"bytes"
 	"fmt"
 
 	"github.com/fxamacker/cbor/v2"
@@ -44,7 +45,7 @@ func (e *Envelope) isEncrypt0() bool { return len(e.Recipients) == 0 }
 // ciphertext after the returned bytes. Encoding is RFC 8949 core deterministic,
 // so the same envelope always produces identical bytes.
 func (e *Envelope) Encode() ([]byte, error) {
-	prot, err := e.Headers.protectedBytes()
+	prot, err := e.Headers.ProtectedBytes()
 	if err != nil {
 		return nil, fmt.Errorf("cose: encoding protected header: %w", err)
 	}
@@ -67,7 +68,7 @@ func (e *Envelope) Encode() ([]byte, error) {
 		if r == nil {
 			return nil, fmt.Errorf("cose: recipient %d is nil", i)
 		}
-		rprot, err := r.Headers.protectedBytes()
+		rprot, err := r.Headers.ProtectedBytes()
 		if err != nil {
 			return nil, fmt.Errorf("cose: encoding recipient %d protected header: %w", i, err)
 		}
@@ -100,7 +101,7 @@ func (e *Envelope) Encode() ([]byte, error) {
 // Headers.Protected). external_aad is the caller's additional data; pass nil for
 // none, which encodes as an empty byte string.
 func (e *Envelope) EncStructure(externalAAD []byte) ([]byte, error) {
-	prot, err := e.Headers.protectedBytes()
+	prot, err := e.Headers.ProtectedBytes()
 	if err != nil {
 		return nil, fmt.Errorf("cose: building Enc_structure: %w", err)
 	}
@@ -115,9 +116,9 @@ func (e *Envelope) EncStructure(externalAAD []byte) ([]byte, error) {
 // the byte string that appears on the wire and inside the Enc_structure. It is
 // RawProtected for a decoded envelope and the deterministic serialization of
 // Headers.Protected otherwise. The result is empty when the protected header is
-// empty.
+// empty, and is always a fresh slice the caller owns.
 func (e *Envelope) ProtectedBytes() ([]byte, error) {
-	return e.Headers.protectedBytes()
+	return e.Headers.ProtectedBytes()
 }
 
 // encStructureBytes builds the CBOR-encoded COSE Enc_structure (RFC 9052 §5.3)
@@ -136,14 +137,21 @@ func encStructureBytes(context string, protected, externalAAD []byte) ([]byte, e
 	return out, nil
 }
 
-// protectedBytes returns the protected header byte-string content for this
+// ProtectedBytes returns the protected header byte-string content for this
 // Headers value: the on-wire RawProtected when present (set by Decode),
 // otherwise a fresh deterministic serialization of Protected. An empty protected
 // header serializes to an empty (zero-length) byte string, per COSE's
 // empty_or_serialized_map rule, rather than to an encoded empty map.
-func (h Headers) protectedBytes() ([]byte, error) {
+//
+// Recipient headers need this as well as body headers: a key-agreement recipient
+// binds its own protected bytes into the KDF context (RFC 9053 §5.2).
+//
+// The result is a fresh slice the caller owns. These bytes decide whether an
+// envelope verifies and which KEK a recipient derives, so handing out the
+// RawProtected slice itself would let a caller rewrite them by accident.
+func (h Headers) ProtectedBytes() ([]byte, error) {
 	if h.RawProtected != nil {
-		return h.RawProtected, nil
+		return bytes.Clone(h.RawProtected), nil
 	}
 	if len(h.Protected) == 0 {
 		return []byte{}, nil

ecdhkw/ecdhkw.go

@@ -6,11 +6,12 @@
 // identified by an X25519 public key (the sibling fee/aeskw package is the
 // other, wrapping directly under a symmetric KEK). A fresh
 // ephemeral X25519 key pair is generated for every Wrap; an ECDH against the
-// recipient's static public key yields a shared secret, the COSE Concat-KDF
-// (RFC 9053 §5.1, see kdf.go) turns that secret into a 256-bit key-encryption
-// key, and AES Key Wrap (RFC 3394, the sibling fee/aeskw package) wraps the CEK
-// under it. Unwrap reverses the process with the recipient's private key. Two
-// useful consequences fall out of the construction:
+// recipient's static public key yields a shared secret, HKDF-SHA-256 over the
+// COSE_KDF_Context (RFC 9053 §5.1 and §5.2, see kdf.go) turns that secret into
+// a 256-bit key-encryption key, and AES Key Wrap (RFC 3394, the sibling
+// fee/aeskw package) wraps the CEK under it. Unwrap reverses the process with
+// the recipient's private key. Two useful consequences fall out of the
+// construction:
 //
 //   - Recovery is self-checking. AES-KW carries an integrity check, so an
 //     unwrap with the wrong private key — or against a tampered wrapped key or
@@ -25,6 +26,30 @@
 // CEK as the recipient ciphertext, keyed by a kid) is the job of the
 // higher-level fee package. Keys are passed as crypto/ecdh values directly; any
 // custody or key-provider abstraction lives above this layer.
+//
+// # Migrating from v0.1.0
+//
+// v0.1.0 derived the KEK with the COSE Concat-KDF and took no protected header:
+// Wrap(recipientPub, cek) and Unwrap(recipientPriv, w). Both signatures now take
+// the serialized COSE_Recipient protected header as a trailing argument, and the
+// derivation is HKDF-SHA-256 as RFC 9053 §6.3.1 requires.
+//
+// Callers that build the recipient with the cose package pass the bytes that
+// package produces:
+//
+//	protected, err := cose.Headers{Protected: hdr}.ProtectedBytes()
+//	w, err := ecdhkw.Wrap(recipientPub, cek, protected)
+//
+// A recipient with an empty protected bucket takes a nil or zero-length slice,
+// which reproduces v0.1.0's context except for the KDF itself. On the unwrap
+// side, pass the recipient's protected bytes exactly as they arrived on the
+// wire; cose.Headers.ProtectedBytes returns those for a decoded envelope.
+//
+// Wraps written by v0.1.0 do not survive the change. The two derivations produce
+// different KEKs from the same ECDH secret, so Unwrap on an old wrap fails with
+// aeskw.ErrIntegrity, and nothing on the wire distinguishes the two: both use
+// alg -31. Envelopes encrypted to X25519 recipients under v0.1.0 have to be
+// decrypted with v0.1.0 and re-encrypted with this version.
 package ecdhkw
 
 import (
@@ -45,7 +70,7 @@ const AlgorithmECDHESA256KW = -31
 
 // algA256KW is the COSE algorithm identifier for AES-256 Key Wrap. It is the
 // algorithm the derived key feeds, so it is the AlgorithmID embedded in the
-// Concat-KDF context (RFC 9053 §5.2) that binds the KEK to its purpose.
+// COSE_KDF_Context (RFC 9053 §5.2) that binds the KEK to its purpose.
 const algA256KW = -5
 
 // kekLen is the length in bytes of the A256KW key-encryption key the KDF
@@ -76,7 +101,12 @@ type Wrapped struct {
 // recipientPub must be an X25519 key. cek must be a valid AES key — a multiple
 // of 8 bytes, at least 16 (so 16, 24, or 32 bytes). The cek slice is not
 // retained or modified.
-func Wrap(recipientPub *ecdh.PublicKey, cek []byte) (*Wrapped, error) {
+//
+// protected is the serialized protected header of the COSE_Recipient this wrap
+// will be encoded into, which RFC 9053 §5.2 binds into the key derivation; pass
+// a zero-length slice if that bucket is empty. Unwrap must receive the same
+// bytes, so the caller has to feed the encoder and the KDF from one value.
+func Wrap(recipientPub *ecdh.PublicKey, cek, protected []byte) (*Wrapped, error) {
 	if recipientPub == nil {
 		return nil, errors.New("ecdhkw nil recipient public key")
 	}
@@ -97,7 +127,7 @@ func Wrap(recipientPub *ecdh.PublicKey, cek []byte) (*Wrapped, error) {
 		return nil, fmt.Errorf("ecdhkw generating ephemeral key: %w", err)
 	}
 
-	kek, err := deriveKEK(ephemeral, recipientPub)
+	kek, err := deriveKEK(ephemeral, recipientPub, protected)
 	if err != nil {
 		return nil, err
 	}
@@ -117,11 +147,15 @@ func Wrap(recipientPub *ecdh.PublicKey, cek []byte) (*Wrapped, error) {
 // key-encryption key by ECDH between recipientPriv and the ephemeral public key
 // in w, then AES-KW-unwraps the CEK.
 //
+// protected is the serialized protected header of the COSE_Recipient the wrap
+// arrived in, exactly as received; see [Wrap]. Because it feeds the derivation,
+// a header rewritten in transit yields a different KEK and fails the unwrap.
+//
 // It returns an error if recipientPriv is the wrong key for this wrap, if the
-// ephemeral key or wrapped CEK was tampered with, or if either key is not
-// X25519. A wrong-key unwrap surfaces as aeskw.ErrIntegrity (wrapped), so
-// callers may match it with errors.Is.
-func Unwrap(recipientPriv *ecdh.PrivateKey, w *Wrapped) ([]byte, error) {
+// ephemeral key, protected header, or wrapped CEK was tampered with, or if
+// either key is not X25519. A wrong-key unwrap surfaces as aeskw.ErrIntegrity
+// (wrapped), so callers may match it with errors.Is.
+func Unwrap(recipientPriv *ecdh.PrivateKey, w *Wrapped, protected []byte) ([]byte, error) {
 	if recipientPriv == nil {
 		return nil, errors.New("ecdhkw nil recipient private key")
 	}
@@ -138,7 +172,7 @@ func Unwrap(recipientPriv *ecdh.PrivateKey, w *Wrapped) ([]byte, error) {
 		return nil, errors.New("ecdhkw ephemeral public key is not X25519")
 	}
 
-	kek, err := deriveKEK(recipientPriv, w.EphemeralPublicKey)
+	kek, err := deriveKEK(recipientPriv, w.EphemeralPublicKey, protected)
 	if err != nil {
 		return nil, err
 	}
@@ -152,22 +186,26 @@ func Unwrap(recipientPriv *ecdh.PrivateKey, w *Wrapped) ([]byte, error) {
 }
 
 // deriveKEK performs the ECDH-ES key derivation shared by Wrap and Unwrap: an
-// X25519 ECDH between local and remote, then the COSE Concat-KDF over the
-// shared secret to produce the A256KW key-encryption key. ECDH symmetry is what
-// makes the two paths — (ephemeral private, recipient public) on wrap and
-// (recipient private, ephemeral public) on unwrap — derive the same KEK.
+// X25519 ECDH between local and remote, then HKDF-SHA-256 over the shared
+// secret to produce the A256KW key-encryption key. ECDH symmetry is what makes
+// the two paths — (ephemeral private, recipient public) on wrap and (recipient
+// private, ephemeral public) on unwrap — derive the same KEK.
 //
 // crypto/ecdh's X25519 ECDH returns an error for a low-order ephemeral point
 // (one that would force the shared secret to all-zeros), which propagates here.
-func deriveKEK(local *ecdh.PrivateKey, remote *ecdh.PublicKey) ([]byte, error) {
+func deriveKEK(local *ecdh.PrivateKey, remote *ecdh.PublicKey, protected []byte) ([]byte, error) {
 	z, err := local.ECDH(remote)
 	if err != nil {
 		return nil, fmt.Errorf("ecdhkw ECDH: %w", err)
 	}
 	defer zero(z)
 
-	context := kdfContext(algA256KW, kekLen*8, nil)
-	return concatKDF(z, context, kekLen), nil
+	context := kdfContext(algA256KW, kekLen*8, protected)
+	kek, err := hkdfKEK(z, context, kekLen)
+	if err != nil {
+		return nil, fmt.Errorf("ecdhkw deriving KEK: %w", err)
+	}
+	return kek, nil
 }
 
 // zero overwrites b, a best-effort wipe of derived key material (the KEK and