seal

Documentation

Overview

Package seal provides HMAC-SHA256 sealing for scan reports. The intent is auditor-grade tamper detection on saved or exported reports: an operator configures a secret with --seal-key, the same secret is used to produce a "seal" alongside the bundle, and "fleetsweeper verify" checks that the bundle's report bytes match the seal. The signature format and header conventions mirror the inbound webhook signature scheme so a single secret style is reusable across the tool.

Index

• Constants
• Variables
• func Sign(data []byte, key string) (string, error)
• func SignReader(r io.Reader, key string) (string, error)
• func Verify(data []byte, signature, key string) error
• func VerifyReader(r io.Reader, signature, key string) error

Constants

const FileName = "report.sig"

FileName is the conventional filename used inside an export bundle to carry the signature of report.json. Kept as a constant so the export and verify code paths cannot drift apart.

const Prefix = "sha256="

Prefix is the algorithm tag emitted on every signature. The canonical header form is "sha256=<lowercase hex>", chosen for consistency with the inbound webhook signature header.

const SourceFile = "report.json"

SourceFile is the bundle entry that the signature in FileName covers. Verification always re-signs SourceFile and compares against FileName.

Variables

var ErrMalformed = errors.New("seal: signature is malformed")

ErrMalformed is returned when a signature header is missing the expected "sha256=" prefix or is not valid hex.

var ErrMismatch = errors.New("seal: signature mismatch")

ErrMismatch is returned when a signature does not match the data. This is the value to look for when reporting tamper detection.

var ErrMissingKey = errors.New("seal: secret key is required")

ErrMissingKey is returned when sealing or verifying without a secret.

Functions

func Sign

func Sign(data []byte, key string) (string, error)

Sign returns the canonical "sha256=<hex>" signature for data using key. Returns ErrMissingKey when key is empty so callers cannot accidentally produce a constant-zero seal.

func SignReader

func SignReader(r io.Reader, key string) (string, error)

SignReader streams from r and returns the canonical signature. Useful when sealing large reports without holding the full byte slice in memory.

func Verify

func Verify(data []byte, signature, key string) error

Verify recomputes the signature for data with key and constant-time compares it against signature. Returns ErrMalformed, ErrMissingKey, or ErrMismatch on failure so callers can distinguish operator error (missing key, wrong header format) from tamper detection.

func VerifyReader

func VerifyReader(r io.Reader, signature, key string) error

VerifyReader is the streaming variant of Verify. It exists so the verify command can validate a multi-megabyte report.json without allocating the full body up front.