Documentation
¶
Overview ¶
Package usage implements a signed hash chain for usage journals.
Every event extends a SHA-256 hash chain that starts from an init hash over (domain, fingerprint, epoch). A Report carries a run of events, the hash before and after them, and an Ed25519 signature of the installation key.
This package provides pure data types, chain logic, signing and verification. The API methods (ReportUsage, Usage) live on *licensing.Machine in the parent licensing package, which can access the client's transport.
Journal (installation side):
ack := usage.Acked{} // zero = fresh
j := usage.NewJournal("komeet-usage/v1", key.Fingerprint(), epoch, ack)
seq, hash, err := j.Append([]byte("event-data"))
report, pending, err := j.AckPending("1.0.0")
report.Sign(key.PrivateKey())
// ... send report to server, then j.Ack(ack) ...
Server side verification:
pub, _ := installation.PublicKeyOf(machine) acked, err := report.Verify(pub, lastAcked)
Index ¶
- Constants
- Variables
- func DecodeEvents(r *Report) ([][]byte, error)
- type Acked
- type Event
- type IdempotencyKey
- type Journal
- type Report
- type ReportBuilder
- func (b *ReportBuilder) Build() (*Report, error)
- func (b *ReportBuilder) Commits(seqFrom, seqTo uint64, events [][]byte) *ReportBuilder
- func (b *ReportBuilder) Counters(counters map[string]int64) *ReportBuilder
- func (b *ReportBuilder) Epoch(epoch uint64) *ReportBuilder
- func (b *ReportBuilder) Head(head string) *ReportBuilder
- func (b *ReportBuilder) PrevHash(prevHash string) *ReportBuilder
- func (b *ReportBuilder) SetBuild(build string) *ReportBuilder
- type Response
- type ResponseEvent
- type ResponseHead
Constants ¶
const FormatV1 = 1
FormatV1 is the current report format version.
const MaxReportEvents = 10000
MaxReportEvents is the most events one report carries: a longer tail is reported in consecutive reports, each continuing the previous ack.
Variables ¶
var ( // ErrInvalidSignature reports a report whose Ed25519 signature does // not verify. ErrInvalidSignature = errors.New("report signature is invalid") // ErrGap reports a report with seq_from > last_acked_seq + 1. ErrGap = errors.New("report has a gap: sequences are not consecutive from the last acked point") // ErrFork reports a report whose prev_hash does not match the last // acked hash at the same epoch. ErrFork = errors.New("report forks from the accepted chain") // ErrChainBroken reports prev_hash does not match the computed // hash of the acked state (non-zero epoch). ErrChainBroken = errors.New("report prev_hash does not match the last accepted hash") // ErrFormat reports an unknown or unsupported report format version. ErrFormat = errors.New("unsupported report format") // ErrTooLarge reports a report of more than MaxReportEvents events. ErrTooLarge = errors.New("report carries more than MaxReportEvents events") )
Typed sentinels matched with errors.Is.
Functions ¶
func DecodeEvents ¶
DecodeEvents returns the decoded event bytes from the report.
Types ¶
type Acked ¶
Acked is the verifier's last accepted chain state, and the wire shape of the server's ack in a report-usage response.
type IdempotencyKey ¶
IdempotencyKey is the natural deduplication key for a report.
func (IdempotencyKey) String ¶
func (k IdempotencyKey) String() string
String returns a compact representation of the idempotency key.
type Journal ¶
type Journal struct {
// contains filtered or unexported fields
}
Journal maintains an in-memory usage hash chain for the installation side. It appends events and produces reports. Persistence is the product's responsibility.
func NewJournal ¶
NewJournal initializes a journal for the given domain, fingerprint and epoch. acked is the last state the server acknowledged (zero for a fresh journal).
func (*Journal) AckPending ¶
AckPending returns a report covering unacknowledged events (the next MaxReportEvents of them). pending is false, and the report nil, when all events have been acked.
func (*Journal) Append ¶
Append adds an event to the chain and returns its sequence number and hash. An event larger than the wire format's length prefix is refused without changing the chain.
type Report ¶
type Report struct {
// Format is the report format version (currently 1).
Format int `json:"format"`
// Domain identifies the product and report type, e.g. "komeet-usage/v1".
Domain string `json:"domain"`
// Fingerprint is the installation's hex fingerprint.
Fingerprint string `json:"fingerprint"`
// Epoch is the chain epoch (uint64).
Epoch uint64 `json:"epoch"`
// SeqFrom is the first sequence number in this report.
SeqFrom uint64 `json:"seqFrom"`
// SeqTo is the last sequence number in this report.
SeqTo uint64 `json:"seqTo"`
// PrevHash is the hex SHA-256 hash before seqFrom, or the init hash.
PrevHash string `json:"prevHash"`
// Events is the base64 (standard) of the canonical event encoding.
Events string `json:"events"`
// Head is the hex SHA-256 hash after seqTo.
Head string `json:"head"`
// Counters are informative per-kind counts set by the product.
Counters map[string]int64 `json:"counters,omitempty"`
// Build is the installation's build version.
Build string `json:"build,omitempty"`
// Signature is the Ed25519 signature (standard base64).
Signature string `json:"signature"`
}
Report is a signed usage report in JSON wire format.
func (*Report) IdempotencyKey ¶
func (r *Report) IdempotencyKey() IdempotencyKey
IdempotencyKey returns the natural deduplication key of the report: (fingerprint, epoch, seq_to, head).
func (*Report) IterEvents ¶
IterEvents returns a slice of (seq, event, hash) for each event in the report. The hashes are computed from the report's prevHash.
func (*Report) Sign ¶
func (r *Report) Sign(priv ed25519.PrivateKey)
Sign signs the report with priv and sets r.Signature.
func (*Report) SigningPayload ¶
SigningPayload returns the bytes the report signature covers:
"backplane-usage-sig/v1" || domain || fingerprint || epoch_be64 || seqFrom_be64 || seqTo_be64 || prevHash || head
type ReportBuilder ¶
type ReportBuilder struct {
// contains filtered or unexported fields
}
ReportBuilder constructs a Report step by step.
func NewReport ¶
func NewReport(domain, fingerprint string) *ReportBuilder
NewReport starts a report builder for the given domain and fingerprint.
func (*ReportBuilder) Build ¶
func (b *ReportBuilder) Build() (*Report, error)
Build returns the assembled Report (unsigned), or the error recorded by a builder step.
func (*ReportBuilder) Commits ¶
func (b *ReportBuilder) Commits(seqFrom, seqTo uint64, events [][]byte) *ReportBuilder
Commits sets the sequence range and the embedded events (raw bytes). An event too large for the wire format is remembered and reported by Build.
func (*ReportBuilder) Counters ¶
func (b *ReportBuilder) Counters(counters map[string]int64) *ReportBuilder
Counters sets the informative counters.
func (*ReportBuilder) Epoch ¶
func (b *ReportBuilder) Epoch(epoch uint64) *ReportBuilder
Epoch sets the epoch.
func (*ReportBuilder) Head ¶
func (b *ReportBuilder) Head(head string) *ReportBuilder
Head sets the hash after the last event.
func (*ReportBuilder) PrevHash ¶
func (b *ReportBuilder) PrevHash(prevHash string) *ReportBuilder
PrevHash sets the hash before the first event in this report.
func (*ReportBuilder) SetBuild ¶
func (b *ReportBuilder) SetBuild(build string) *ReportBuilder
SetBuild sets the build version string.
type Response ¶
type Response struct {
Epoch uint64 `json:"epoch"`
Events []ResponseEvent `json:"events"`
Head ResponseHead `json:"head"`
Acks []Acked `json:"acks"`
}
Response is the server's response to a Usage call.
type ResponseEvent ¶
type ResponseEvent struct {
Seq uint64 `json:"seq"`
Event string `json:"event"`
Hash string `json:"hash"`
}
ResponseEvent is a single event in a usage response.
type ResponseHead ¶
ResponseHead is the chain head in a usage response.