SPB Git

Repository Public

export.go 11.6 KB 329 lines go

1package audit23import (4	"bufio"5	"bytes"6	"context"7	"crypto/ed25519"8	"crypto/sha256"9	"encoding/base64"10	"encoding/hex"11	"encoding/json"12	"errors"13	"fmt"14	"io"15	"strings"16	"time"1718	"github.com/google/uuid"19	"github.com/jackc/pgx/v5"20)2122// Signed export of a range of the audit log.23//24// Format: JSON Lines. One ExportEntry per line in ascending seq, then ONE25// final line {"manifest":{…},"signature":"<key id>:<base64>"}.26//27// The manifest states the range, the number of entries, the first and last28// seq, the chain hash before the first entry (prev_hash), the hash of the29// last entry (head_hash) and the SHA-256 of every byte that precedes the30// manifest line. The signature is Ed25519 over a domain prefix followed by31// the exact bytes of the manifest object. Because the body is streamed, its32// hash is only known at the end: that is why the signed manifest is the last33// line of the file rather than an HTTP header. (The response headers carry34// the head hash, known beforehand, and a detached signature of it.)35//36// VerifyExport needs nothing but the file and the public key. It checks the37// signature, the byte hash, the counts, that every entry's hash matches its38// content, and that the entries form an unbroken chain from prev_hash to39// head_hash. Any changed, removed, added or reordered byte fails one of them.4041const (42	exportDomain = "mcc-audit-export-v1\x00"43	headDomain   = "mcc-audit-head-v1\x00"44)4546type ExportEntry struct {47	Seq           int64           `json:"seq"`48	TS            time.Time       `json:"ts"`49	ActorKind     string          `json:"actor_kind"`50	ActorID       *uuid.UUID      `json:"actor_id,omitempty"`51	ActorLabel    string          `json:"actor_label"`52	DeviceID      *uuid.UUID      `json:"device_id,omitempty"`53	SessionID     *uuid.UUID      `json:"session_id,omitempty"`54	IP            *string         `json:"ip,omitempty"`55	Action        string          `json:"action"`56	TargetKind    string          `json:"target_kind,omitempty"`57	TargetID      string          `json:"target_id,omitempty"`58	Params        json.RawMessage `json:"params"`59	Outcome       string          `json:"outcome"`60	Detail        string          `json:"detail"`61	CorrelationID uuid.UUID       `json:"correlation_id"`62	PrevHash      string          `json:"prev_hash"`63	Hash          string          `json:"hash"`64}6566// contentHash recomputes the chain hash of an entry from its exported fields.67func (x ExportEntry) contentHash(prev []byte) []byte {68	e := Entry{ActorKind: x.ActorKind, ActorID: x.ActorID, ActorLabel: x.ActorLabel, DeviceID: x.DeviceID, SessionID: x.SessionID, Action: x.Action,69		TargetKind: x.TargetKind, TargetID: x.TargetID, Outcome: Outcome(x.Outcome), Detail: x.Detail, CorrelationID: x.CorrelationID}70	return entryHash(prev, x.TS.UTC(), e, x.Params, x.IP)71}7273type Manifest struct {74	V          int       `json:"v"`75	From       time.Time `json:"from"`76	To         time.Time `json:"to"`77	Count      int64     `json:"count"`78	FirstSeq   int64     `json:"first_seq"`79	LastSeq    int64     `json:"last_seq"`80	PrevHash   string    `json:"prev_hash"` // chain hash before the first exported entry ("" when empty)81	HeadHash   string    `json:"head_hash"` // hash of the last exported entry ("" when empty)82	SHA256     string    `json:"sha256"`    // of all bytes before the manifest line83	KeyID      string    `json:"key_id"`84	ExportedAt time.Time `json:"exported_at"`85}8687type manifestLine struct {88	Manifest  json.RawMessage `json:"manifest"`89	Signature string          `json:"signature"`90}9192func sign(priv ed25519.PrivateKey, keyID, domain string, msg []byte) string {93	return keyID + ":" + base64.StdEncoding.EncodeToString(ed25519.Sign(priv, append([]byte(domain), msg...)))94}9596func checkSig(pub ed25519.PublicKey, domain string, msg []byte, sig string) (keyID string, err error) {97	keyID, b64, ok := strings.Cut(sig, ":")98	raw, derr := base64.StdEncoding.DecodeString(b64)99	if !ok || derr != nil || len(pub) != ed25519.PublicKeySize || !ed25519.Verify(pub, append([]byte(domain), msg...), raw) {100		return keyID, errors.New("signature does not verify")101	}102	return keyID, nil103}104105// SignHead signs the hex head hash (X-MCC-Audit-Signature header).106func SignHead(priv ed25519.PrivateKey, keyID, headHex string) string {107	return sign(priv, keyID, headDomain, []byte(headHex))108}109110// VerifyHead checks a detached head-hash signature.111func VerifyHead(pub ed25519.PublicKey, headHex, sig string) error {112	_, err := checkSig(pub, headDomain, []byte(headHex), sig)113	return err114}115116const exportColumns = `seq, ts, actor_kind, actor_id, actor_label, device_id, session_id, host(ip), action, coalesce(target_kind,''), coalesce(target_id,''),117	params, outcome::text, detail, correlation_id, prev_hash, hash`118119func scanExport(rows pgx.Rows) (ExportEntry, []byte, []byte, error) {120	var x ExportEntry121	var params, prev, hash []byte122	err := rows.Scan(&x.Seq, &x.TS, &x.ActorKind, &x.ActorID, &x.ActorLabel, &x.DeviceID, &x.SessionID, &x.IP, &x.Action, &x.TargetKind, &x.TargetID,123		&params, &x.Outcome, &x.Detail, &x.CorrelationID, &prev, &hash)124	x.TS = x.TS.UTC()125	x.Params = params126	x.PrevHash, x.Hash = hex.EncodeToString(prev), hex.EncodeToString(hash)127	return x, prev, hash, err128}129130// Head returns the hex hash of the last entry of [from, to) ("" when empty).131func Head(ctx context.Context, q interface {132	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row133}, from, to time.Time) (string, error) {134	var h []byte135	err := q.QueryRow(ctx, `select hash from audit_log where ts >= $1 and ts < $2 order by seq desc limit 1`, from, to).Scan(&h)136	if errors.Is(err, pgx.ErrNoRows) {137		return "", nil138	}139	return hex.EncodeToString(h), err140}141142// WriteExport streams the entries of [from, to) and the signed manifest line.143// q should be a transaction with a stable snapshot (repeatable read) when the144// head hash was announced beforehand.145func WriteExport(ctx context.Context, q querier, w io.Writer, from, to time.Time, priv ed25519.PrivateKey, keyID string, now time.Time) (Manifest, error) {146	m := Manifest{V: 1, From: from.UTC(), To: to.UTC(), KeyID: keyID, ExportedAt: now.UTC()}147	rows, err := q.Query(ctx, `select `+exportColumns+` from audit_log where ts >= $1 and ts < $2 order by seq`, from, to)148	if err != nil {149		return m, err150	}151	defer rows.Close()152	sum := sha256.New()153	out := io.MultiWriter(w, sum)154	enc := json.NewEncoder(out)155	enc.SetEscapeHTML(false)156	for rows.Next() {157		x, _, _, err := scanExport(rows)158		if err != nil {159			return m, err160		}161		if m.Count == 0 {162			m.FirstSeq, m.PrevHash = x.Seq, x.PrevHash163		}164		m.Count++165		m.LastSeq, m.HeadHash = x.Seq, x.Hash166		if err := enc.Encode(x); err != nil {167			return m, err168		}169	}170	if err := rows.Err(); err != nil {171		return m, err172	}173	m.SHA256 = hex.EncodeToString(sum.Sum(nil))174	raw, err := json.Marshal(m)175	if err != nil {176		return m, err177	}178	line, err := json.Marshal(manifestLine{Manifest: raw, Signature: sign(priv, keyID, exportDomain, raw)})179	if err != nil {180		return m, err181	}182	_, err = w.Write(append(line, '\n'))183	return m, err184}185186// VerifyExport checks an export file offline. It returns the manifest when187// (and only when) everything verifies.188func VerifyExport(r io.Reader, pub ed25519.PublicKey) (Manifest, error) {189	var m Manifest190	br := bufio.NewReaderSize(r, 1<<20)191	sum := sha256.New()192	var (193		pending  []byte // the previous line: an entry unless it turns out to be the last line194		prev     []byte195		count    int64196		first    int64197		last     int64198		firstPrv string199		head     string200	)201	entry := func(line []byte) error {202		var x ExportEntry203		dec := json.NewDecoder(bytes.NewReader(line))204		dec.DisallowUnknownFields()205		if err := dec.Decode(&x); err != nil {206			return fmt.Errorf("line %d: not an audit entry: %v", count+1, err)207		}208		ph, err1 := hex.DecodeString(x.PrevHash)209		hh, err2 := hex.DecodeString(x.Hash)210		if err1 != nil || err2 != nil || len(ph) != sha256.Size || len(hh) != sha256.Size {211			return fmt.Errorf("seq %d: malformed hash", x.Seq)212		}213		if count == 0 {214			first, firstPrv = x.Seq, x.PrevHash215		} else {216			if !bytes.Equal(ph, prev) {217				return fmt.Errorf("seq %d: prev_hash does not match the previous entry (entry removed, added or reordered)", x.Seq)218			}219			if x.Seq <= last {220				return fmt.Errorf("seq %d: sequence not increasing", x.Seq)221			}222		}223		if !bytes.Equal(x.contentHash(ph), hh) {224			return fmt.Errorf("seq %d: content does not match its hash (entry modified)", x.Seq)225		}226		prev, last, head = hh, x.Seq, x.Hash227		count++228		sum.Write(line)229		return nil230	}231	for {232		line, err := br.ReadBytes('\n')233		if len(line) > 0 {234			if pending != nil {235				if err := entry(pending); err != nil {236					return m, err237				}238			}239			pending = line240		}241		if err == io.EOF {242			break243		}244		if err != nil {245			return m, err246		}247	}248	if pending == nil {249		return m, errors.New("empty file: no manifest")250	}251	if !bytes.HasSuffix(pending, []byte("\n")) {252		return m, errors.New("truncated file: the last line is incomplete")253	}254	var ml manifestLine255	dec := json.NewDecoder(bytes.NewReader(pending))256	dec.DisallowUnknownFields()257	if err := dec.Decode(&ml); err != nil || len(ml.Manifest) == 0 {258		return m, errors.New("the last line is not a signed manifest (truncated export?)")259	}260	if want, _ := json.Marshal(manifestLine{Manifest: ml.Manifest, Signature: ml.Signature}); !bytes.Equal(append(want, '\n'), pending) {261		return m, errors.New("the manifest line is not in canonical form")262	}263	keyID, err := checkSig(pub, exportDomain, ml.Manifest, ml.Signature)264	if err != nil {265		return m, fmt.Errorf("manifest: %w (key %q)", err, keyID)266	}267	mdec := json.NewDecoder(bytes.NewReader(ml.Manifest))268	mdec.DisallowUnknownFields()269	if err := mdec.Decode(&m); err != nil {270		return m, fmt.Errorf("manifest: %v", err)271	}272	switch {273	case m.V != 1:274		return m, fmt.Errorf("manifest: unsupported version %d", m.V)275	case m.KeyID != keyID:276		return m, errors.New("manifest: key id differs from the signature")277	case m.SHA256 != hex.EncodeToString(sum.Sum(nil)):278		return m, errors.New("the content does not match the SHA-256 of the manifest (bytes changed)")279	case m.Count != count:280		return m, fmt.Errorf("the file holds %d entries, the manifest says %d", count, m.Count)281	case count > 0 && (m.FirstSeq != first || m.LastSeq != last || m.HeadHash != head || m.PrevHash != firstPrv):282		return m, errors.New("first/last entries do not match the manifest")283	case count == 0 && (m.HeadHash != "" || m.PrevHash != ""):284		return m, errors.New("empty export with a head hash")285	}286	return m, nil287}288289// VerifyFrom recomputes the chain from fromSeq (anchored on the hash of the290// entry just before it). fromSeq <= 1 verifies the whole log.291func VerifyFrom(ctx context.Context, q interface {292	querier293	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row294}, fromSeq int64) (VerifyResult, error) {295	if fromSeq <= 1 {296		return Verify(ctx, q)297	}298	prev := genesis299	if err := q.QueryRow(ctx, `select hash from audit_log where seq < $1 order by seq desc limit 1`, fromSeq).Scan(&prev); err != nil && !errors.Is(err, pgx.ErrNoRows) {300		return VerifyResult{}, err301	}302	rows, err := q.Query(ctx, `select `+exportColumns+` from audit_log where seq >= $1 order by seq`, fromSeq)303	if err != nil {304		return VerifyResult{}, err305	}306	defer rows.Close()307	res := VerifyResult{OK: true, HeadHash: prev}308	for rows.Next() {309		x, ph, hh, err := scanExport(rows)310		if err != nil {311			return res, err312		}313		if res.Entries == 0 {314			res.FirstSeq = x.Seq315		}316		res.Entries++317		if !bytes.Equal(ph, prev) {318			res.OK, res.BrokenSeq, res.Reason = false, x.Seq, "prev_hash does not match the previous entry (entry removed or reordered)"319			return res, nil320		}321		if !bytes.Equal(x.contentHash(prev), hh) {322			res.OK, res.BrokenSeq, res.Reason = false, x.Seq, "entry content does not match its hash (entry modified)"323			return res, nil324		}325		prev, res.LastSeq, res.HeadHash = hh, x.Seq, hh326	}327	return res, rows.Err()328}329
Files main
Menu

Theme