audit

Documentation

Overview

Package audit defines the events keyforge emits for key lifecycle changes and the sink that receives them.

An event records who did what to which key, when, and with what outcome. It never carries key material, wrapped keys, plaintext or additional data. Ordinary encrypt and decrypt are not events: their rates and failures are metered instead.

Index

• Variables
• func ActorFrom(ctx context.Context) string
• func NotRecorded(err error) error
• func WithActor(ctx context.Context, actor string) context.Context
• type Action
• type Event
• type Outcome
• type Recorder
  • func (r *Recorder) Actions() []Action
  • func (r *Recorder) Emit(_ context.Context, e Event) error
  • func (r *Recorder) Events() []Event
• type Sink

Variables

var ErrNotRecorded = errors.New("audit: the change was made but its event was not recorded")

ErrNotRecorded is returned, wrapping the sink's error, when an operation succeeded but its audit event could not be delivered. The change was made; the caller must treat the gap in the trail as an incident.

Functions

func ActorFrom

func ActorFrom(ctx context.Context) string

ActorFrom returns the actor named by WithActor, or "".

func NotRecorded

func NotRecorded(err error) error

NotRecorded wraps a sink error as ErrNotRecorded.

func WithActor

func WithActor(ctx context.Context, actor string) context.Context

WithActor returns a context that names who is acting. keyforge does not authenticate anyone: the host application does, and passes the result here so the events it causes are attributed.

Types

type Action

type Action string

Action names what happened.

const (
	KeyCreated           Action = "key.created"
	KeyRotated           Action = "key.rotated"
	KeyActivated         Action = "key.activated"
	KeyRolledBack        Action = "key.rolled_back"
	KeyRetireRequested   Action = "key.retire_requested"
	KeyRetireCancelled   Action = "key.retire_cancelled"
	KeyRetired           Action = "key.retired"
	KeyDestroyed         Action = "key.destroyed"
	KeyCompromised       Action = "key.compromised"
	DataKeyCompromised   Action = "dek.compromised"
	DataKeyDestroyed     Action = "dek.destroyed"
	WrapFailed           Action = "wrap.failed"
	AdminRead            Action = "admin.read"
	GuardDenied          Action = "guard.denied"
	GuardPending         Action = "guard.pending"
	JobFailed            Action = "job.failed"
	BackupStale          Action = "backup.stale"
	SubjectShredRequest  Action = "subject.shred_requested"
	SubjectShredComplete Action = "subject.shred_completed"
)

Actions. The set is closed: a sink can switch on it.

type Event

type Event struct {
	// ID identifies the event.
	ID string
	// Time is when it happened, from the emitter's clock.
	Time time.Time
	// Actor is who did it, as the host application supplied it: see
	// [WithActor]. It is empty for work the scheduler does on its own.
	Actor string
	// Action is what happened.
	Action Action
	// Purpose is the purpose concerned, if any.
	Purpose string
	// KEKID and Version identify the key version concerned, if any, and DEKID
	// the data key. They are identifiers, never material.
	KEKID   string
	Version uint32
	DEKID   string
	// Outcome is how it went, and Reason is why, in words that name no key
	// material.
	Outcome Outcome
	Reason  string
}

Event is one audit record.

type Outcome

type Outcome string

Outcome says how it went.

const (
	Success Outcome = "success"
	Failure Outcome = "failure"
	Denied  Outcome = "denied"
	Pending Outcome = "pending"
)

Outcomes.

type Recorder

type Recorder struct {

	// Err, when set, is returned by Emit instead of recording.
	Err error
	// contains filtered or unexported fields
}

Recorder is a sink that keeps events in memory, for tests and examples. It is safe for concurrent use.

func (*Recorder) Actions

func (r *Recorder) Actions() []Action

Actions returns the recorded actions in order.

func (*Recorder) Emit

func (r *Recorder) Emit(_ context.Context, e Event) error

Emit implements Sink.

func (*Recorder) Events

func (r *Recorder) Events() []Event

Events returns a copy of the recorded events.

type Sink

type Sink interface {
	Emit(ctx context.Context, e Event) error
}

Sink receives events. It must be safe for concurrent use.

var Discard Sink = discard{}

Discard is a sink that drops every event.