DateKeys/capsule/open.go

package capsule

import (
	"bytes"
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"errors"
	"fmt"
	"io"
	"time"

	"filippo.io/age"

	datekeys "g.activething.com/go/DateKeys"
	"g.activething.com/go/DateKeys/accesskey"
	"g.activething.com/go/DateKeys/agewrap"
	"g.activething.com/go/DateKeys/extension"
	"g.activething.com/go/DateKeys/profile"
	"g.activething.com/go/DateKeys/provider"
)

// OpenOptions configures Open.
type OpenOptions struct {
	// Registry holds the locally pinned profiles. Required.
	Registry profile.Registry
	// Extensions lists the extensions the application implements; see
	// InspectOptions.Extensions.
	Extensions extension.Registry
	// Source fetches the release. Required. Its answer is always verified
	// locally, at step 10. A source that fetches releases over a network,
	// like provider/drand.Client, verifies each response itself and discards
	// the invalid ones, so that Open reports ErrReleaseUnavailable at step 9
	// when none is valid; a release that a source hands over as the caller
	// supplied it gets the codes of step 10 (spec §63).
	Source provider.ReleaseSource
	// Identities are the caller's own X25519 identities, for time_and_key
	// capsules encrypted to known recipients. Nil entries are ignored.
	Identities []age.Identity
	// AccessKey is a portable .dkk already decoded, for time_and_key
	// capsules.
	AccessKey *accesskey.AccessKey
	// AccessKeyFile is a portable .dkk still encoded, the alternative to
	// AccessKey: Open decodes it at step 9.a, and reads it only for a
	// time_and_key capsule, so that its errors, framing included, are
	// reported in the order of spec §63 (§69.1). A caller that decodes a .dkk
	// itself reports its decoding errors first, whatever the capsule. Open
	// wipes the key it decodes. At most one of AccessKey and AccessKeyFile
	// may be set.
	AccessKeyFile io.Reader
	// Now is the clock. Required: no package of this module reads the wall
	// clock on its own. Open does not ask Source for a round whose time has
	// not been reached.
	Now func() time.Time
}

// Opened describes a capsule that Open decrypted completely.
type Opened struct {
	Inspection *Inspection
	Release    provider.Release
	// ControlCritical and ControlNoncritical are the extensions of the sealed
	// CONTROL_CBOR, only visible after opening.
	ControlCritical    []extension.Extension
	ControlNoncritical []extension.Extension
	// UnusableControlExtensions and UnusableAccessKeyExtensions are the known
	// noncritical extensions of CONTROL_CBOR and of the .dkk whose data
	// OpenOptions.Extensions rejects. They do not fail Open; the application
	// must not use them (spec §54). The PUBLIC_HEADER ones are in Inspection.
	UnusableControlExtensions   []extension.Unusable
	UnusableAccessKeyExtensions []extension.Unusable
}

// Open runs the complete decryption flow of spec §63 and streams the
// plaintext to dst.
//
// Everything verifiable locally is checked before a release is requested or a
// secret is used (steps 1 to 8, the presence and capsule binding of access
// credentials, and the .dkk capsule_digest when r is seekable). The stanza
// rules are enforced again, as a MUST, by the identities that open each age
// file (steps 11, 13 and 17).
//
// Open returns nil only after age has authenticated the whole payload
// (step 18). On error, dst may hold a partial plaintext that MUST be
// discarded: write to a temporary file and publish it only on success
// (spec §56), as the datekeys CLI does.
func Open(ctx context.Context, dst io.Writer, r io.Reader, opts OpenOptions) (*Opened, error) {
	if opts.Source == nil {
		return nil, errors.New("capsule: OpenOptions.Source is required")
	}
	if opts.Now == nil {
		return nil, errors.New("capsule: OpenOptions.Now is required")
	}
	if opts.AccessKey != nil && opts.AccessKeyFile != nil {
		return nil, errors.New("capsule: set OpenOptions.AccessKey or AccessKeyFile, not both")
	}
	start, seekable := int64(0), false
	if s, ok := r.(io.Seeker); ok {
		if pos, err := s.Seek(0, io.SeekCurrent); err == nil {
			start, seekable = pos, true
		}
	}

	// Steps 1 to 8.
	in, st, err := inspect(r, InspectOptions{Registry: opts.Registry, Extensions: opts.Extensions})
	out := &Opened{Inspection: in}
	if err != nil {
		return out, err
	}
	h, p := in.Header, in.Profile

	// Access credentials are checked before any network request (spec §63
	// step 9), and only for time_and_key: under time_only they play no part.
	// The .dkk as an object first, decoded here when it is still encoded,
	// then its bindings to this capsule, the capsule_id and, when the reader
	// is seekable, the capsule_digest (spec §69.1). Then at least one
	// credential (9.b); nil identities are not credentials.
	var ids []age.Identity
	if h.Policy == TimeAndKey {
		for _, id := range opts.Identities {
			if id != nil {
				ids = append(ids, id)
			}
		}
		k := opts.AccessKey
		if opts.AccessKeyFile != nil {
			if k, err = accesskey.Decode(opts.AccessKeyFile); err != nil {
				return out, in.fail(9, "access credential", err)
			}
			defer k.Wipe()
		}
		if k != nil {
			id, err := checkAccessKey(k, h, opts.Extensions)
			if err != nil {
				return out, in.fail(9, "access credential", err)
			}
			out.UnusableAccessKeyExtensions = extension.CheckNoncriticalIn(extension.AccessKey, k.Noncritical, opts.Extensions)
			if k.Verification != nil && seekable {
				payload, err := checkCapsuleDigest(r.(io.ReadSeeker), start, in.PayloadOffset, k.Verification.CapsuleDigest)
				if err != nil {
					return out, in.fail(9, "access credential", err)
				}
				st.payload = payload
			}
			ids = append(ids, id)
		}
		if len(ids) == 0 {
			return out, in.fail(9, "access credential", fmt.Errorf("capsule: time_and_key capsule and no identity or .dkk supplied: %w", datekeys.ErrAccessRequired))
		}
		in.pass(9, "access credential", fmt.Sprintf("%d identities to try%s", len(ids), unusable(out.UnusableAccessKeyExtensions)))
	}

	// Step 9: obtain the release, never before its round time. A network
	// source has verified each response with the rules of step 10 and
	// discarded the invalid ones: none valid is ErrReleaseUnavailable here.
	cond := provider.Condition{Round: h.DateKey.Round}
	if now := opts.Now(); now.Before(in.UnlockAt) {
		err := fmt.Errorf("capsule: round %d is published at %s, it is %s: %w", cond.Round,
			in.UnlockAt.Format(time.RFC3339), now.UTC().Format(time.RFC3339), datekeys.ErrReleaseUnavailable)
		return out, in.fail(9, "release", err)
	}
	release, err := opts.Source.Fetch(ctx, p, cond)
	if err != nil {
		if datekeys.Code(err) == "" {
			err = fmt.Errorf("capsule: %v: %w", err, datekeys.ErrReleaseUnavailable)
		}
		return out, in.fail(9, "release", err)
	}
	in.pass(9, "release", fmt.Sprintf("round %d obtained", release.Round))

	// Step 10: verify the release locally.
	if err := provider.Verify(p, cond, release); err != nil {
		return out, in.fail(10, "release verification", err)
	}
	out.Release = release
	in.pass(10, "release verification", "BLS signature valid under the pinned key")

	// Step 11: open OUTER_TIME_AGE with the strict tlock identity.
	timeID, err := agewrap.NewTimeIdentity(p, cond.Round, release)
	if err != nil {
		return out, in.fail(11, "open sealed control", err)
	}
	inner, err := decryptAll(st.sealed, timeID)
	if err != nil {
		return out, in.fail(11, "open sealed control", err)
	}
	defer clear(inner)
	in.pass(11, "open sealed control", "one tlock stanza, header MAC valid")

	// Step 12: the structure must match access_policy (spec §36).
	var controlBytes []byte
	switch h.Policy {
	case TimeOnly:
		if looksLikeAge(inner) {
			return out, in.fail(12, "policy structure", fmt.Errorf("capsule: time_only capsule seals an age file: %w", datekeys.ErrPolicyStructureMismatch))
		}
		controlBytes = inner
		in.pass(12, "policy structure", "time_only: CONTROL_CBOR sealed directly")
	case TimeAndKey:
		stanzas, err := agewrap.Stanzas(bytes.NewReader(inner))
		if err != nil {
			return out, in.fail(12, "policy structure", fmt.Errorf("capsule: time_and_key capsule does not seal an age file: %w", datekeys.ErrPolicyStructureMismatch))
		}
		if err := agewrap.CheckAccessStanzas(stanzas); err != nil {
			return out, in.fail(12, "policy structure", err)
		}
		in.pass(12, "policy structure", fmt.Sprintf("time_and_key: INNER_ACCESS_AGE with %d X25519 stanzas", len(stanzas)))

		// Step 13: open INNER_ACCESS_AGE with the caller's identities.
		accessID, err := agewrap.NewAccessIdentity(ids...)
		if err != nil {
			return out, in.fail(13, "open access layer", err)
		}
		if controlBytes, err = decryptAll(inner, accessID); err != nil {
			return out, in.fail(13, "open access layer", err)
		}
		defer clear(controlBytes)
		in.pass(13, "open access layer", "identity matched exactly one stanza")
	}

	// Step 14: parse the canonical CONTROL_CBOR.
	control, err := DecodeControl(controlBytes)
	if err != nil {
		return out, in.fail(14, "control", err)
	}
	defer clear(control.PayloadIdentity[:])
	if err := extension.CheckCriticalIn(extension.Control, control.Critical, opts.Extensions); err != nil {
		return out, in.fail(14, "control", fmt.Errorf("capsule: CONTROL_CBOR: %w", err))
	}
	out.ControlCritical, out.ControlNoncritical = control.Critical, control.Noncritical
	out.UnusableControlExtensions = extension.CheckNoncriticalIn(extension.Control, control.Noncritical, opts.Extensions)
	in.pass(14, "control", "canonical CONTROL_CBOR"+unusable(out.UnusableControlExtensions))

	// Step 15: verify header_binding over the exact stored bytes.
	binding := HeaderBinding(st.prelude, in.PublicHeader)
	if !hmac.Equal(binding[:], control.HeaderBinding[:]) {
		return out, in.fail(15, "header binding", fmt.Errorf("capsule: header_binding does not match PRELUDE || PUBLIC_HEADER: %w", datekeys.ErrHeaderBinding))
	}
	in.pass(15, "header binding", "matches")

	// Steps 16 and 17: recover I_PAYLOAD and open PAYLOAD_AGE with it.
	payloadID, err := agewrap.NewPayloadIdentity(control.PayloadIdentity[:])
	if err != nil {
		return out, in.fail(16, "payload identity", err)
	}
	in.pass(16, "payload identity", "I_PAYLOAD recovered")
	pr, err := age.Decrypt(st.payload, payloadID)
	if err != nil {
		return out, in.fail(17, "open payload", classify("PAYLOAD_AGE", ageHeaderFailure, err))
	}
	w := &plaintextWriter{w: dst}
	if _, err := io.Copy(w, pr); err != nil {
		if w.err != nil {
			// dst failed, not age: the caller's own error keeps its text.
			return out, in.fail(17, "open payload", fmt.Errorf("capsule: PAYLOAD_AGE: writing the plaintext: %w: %w", w.err, datekeys.ErrIntegrity))
		}
		return out, in.fail(17, "open payload", classify("PAYLOAD_AGE", ageStreamFailure, err))
	}

	// Step 18: age completed without error.
	in.pass(18, "commit", "payload authenticated completely")
	return out, nil
}

// checkAccessKey validates a .dkk before it is used and returns its
// identity. The .dkk is checked as an object first, its semantic fields in
// ascending key order (spec §69.1, layer 4): access_type and access_material
// (keys 4 and 5), then its critical extensions as in step 4 (key 7). Only
// then its binding to this capsule: the capsule_id (key 3). The
// capsule_digest (key 6), a binding too, is checked last, by the caller.
func checkAccessKey(k *accesskey.AccessKey, h *Header, reg extension.Registry) (age.Identity, error) {
	id, err := k.Identity()
	if err != nil {
		return nil, err
	}
	if err := extension.CheckCriticalIn(extension.AccessKey, k.Critical, reg); err != nil {
		return nil, fmt.Errorf("capsule: .dkk: %w", err)
	}
	if k.CapsuleID != h.CapsuleID {
		return nil, fmt.Errorf("capsule: the .dkk is for capsule %x, this is %x: %w", k.CapsuleID, h.CapsuleID, datekeys.ErrAccessInvalid)
	}
	return id, nil
}

// checkCapsuleDigest compares the .dkk capsule_digest with SHA-256 of the
// .dkc (spec §43), then repositions r at the payload. The digest is a fast
// failure for a wrong file, not a security property.
func checkCapsuleDigest(r io.ReadSeeker, start, payloadOffset int64, want []byte) (io.Reader, error) {
	if _, err := r.Seek(start, io.SeekStart); err != nil {
		return nil, fmt.Errorf("capsule: %w", err)
	}
	sum := sha256.New()
	if _, err := io.Copy(sum, r); err != nil {
		return nil, fmt.Errorf("capsule: %w", err)
	}
	if !hmac.Equal(sum.Sum(nil), want) {
		return nil, fmt.Errorf("capsule: the .dkk capsule_digest does not match this .dkc: %w", datekeys.ErrAccessInvalid)
	}
	if _, err := r.Seek(start+payloadOffset, io.SeekStart); err != nil {
		return nil, fmt.Errorf("capsule: %w", err)
	}
	return r, nil
}

// decryptAll opens a bounded, in-memory age file. The plaintext is never
// longer than the ciphertext, so it is read into one buffer of that size:
// the plaintext may hold I_PAYLOAD, and no outgrown buffer is left behind.
// The caller wipes the result; on error it is wiped here.
func decryptAll(ciphertext []byte, id age.Identity) ([]byte, error) {
	r, err := age.Decrypt(bytes.NewReader(ciphertext), id)
	if err != nil {
		return nil, classify("age", ageHeaderFailure, err)
	}
	// Not io.ReadFull: it would turn the age reader's io.ErrUnexpectedEOF,
	// a truncated STREAM, into the end of a short read.
	out := make([]byte, len(ciphertext))
	for n := 0; ; {
		m, err := r.Read(out[n:])
		n += m
		switch {
		case err == io.EOF:
			clear(out[n:]) // Read may use the whole of its argument as scratch space.
			return out[:n], nil
		case err != nil:
			clear(out)
			return nil, classify("age", ageStreamFailure, err)
		case n == len(out):
			return out, nil
		}
	}
}

// The failures of age that no identity reports, by the phase in which they
// happen: age.Decrypt, which parses the header and checks its MAC once an
// identity has unwrapped the file key, and then reading the STREAM.
const (
	ageHeaderFailure = "the age header is malformed or truncated, or its MAC does not verify"
	ageStreamFailure = "the age payload is truncated, has trailing data or fails STREAM authentication"
)

// classify keeps the normative error an identity returned from Unwrap, and
// maps every other failure of age to ErrIntegrity with the fixed reason of
// its phase. The text of age's errors is not copied, as in package agewrap.
func classify(what, reason string, err error) error {
	if datekeys.Code(err) != "" {
		return fmt.Errorf("capsule: %s: %w", what, err)
	}
	return fmt.Errorf("capsule: %s: %s: %w", what, reason, datekeys.ErrIntegrity)
}

// plaintextWriter records the first error of the writer of the plaintext, so
// that a failure of the caller's writer is not reported as one of age.
type plaintextWriter struct {
	w   io.Writer
	err error
}

func (p *plaintextWriter) Write(b []byte) (int, error) {
	n, err := p.w.Write(b)
	if err != nil && p.err == nil {
		p.err = err
	}
	return n, err
}