Documentation
¶
Overview ¶
Package service is the HTTP control plane: an http.Handler for status, key listing, rotation, retirement, destruction, backup acknowledgement and the emergency procedures.
It is a thin adapter over the library. Every handler calls the same operations a program would call directly, and holds no logic of its own.
What the host supplies ¶
Authentication and mounting are the host's. The host mounts the handler under its own router, authenticates the caller in its own middleware, names them with audit.WithActor so that the events a request causes are attributed, and supplies an Authorizer that is asked before every action. There is no default: a service with no authorizer cannot be constructed, so it is never open by omission.
What it will not reveal ¶
An action is authorized before the resource is looked up, so a caller who may not rotate a purpose cannot tell from the response whether the purpose exists. Responses carry identifiers, states, counts and times, and never key material, wrapped keys or plaintext. An unexpected failure is reported with a code and a generic message, and the detail is the host's to log.
Index ¶
Constants ¶
const MaxBodyBytes = 1 << 20
MaxBodyBytes bounds a request body.
Variables ¶
var ErrUnauthenticated = errors.New("service: unauthenticated")
ErrUnauthenticated is returned by an Authorizer when there is no identity. The service answers 401 for it and 403 for any other refusal.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action names something a caller may be allowed to do.
const ( ActionStatus Action = "status.read" ActionKeysList Action = "keys.list" ActionRotate Action = "keys.rotate" ActionRollback Action = "keys.rollback" ActionRewrap Action = "keys.rewrap" ActionRetireRequest Action = "keys.retire.request" ActionRetireComplete Action = "keys.retire.complete" ActionRetireCancel Action = "keys.retire.cancel" ActionDestroy Action = "keys.destroy" ActionCompromiseKEK Action = "keys.compromise" ActionCompromiseDEK Action = "datakeys.compromise" ActionDestroyDEK Action = "datakeys.destroy" ActionVerify Action = "keys.verify" ActionBackupAck Action = "backup.ack" ActionShredRequest Action = "shred.request" ActionShredRead Action = "shred.read" )
Actions.
type Authorizer ¶
Authorizer decides whether the caller may perform an action. The caller's identity is whatever the host's middleware put on the context.
purpose is the purpose the action concerns, or empty for an action that is not about one purpose. Return nil to allow, ErrUnauthenticated if there is no usable identity, or any other error to forbid.
type AuthorizerFunc ¶
AuthorizerFunc adapts a function to an Authorizer.
func (AuthorizerFunc) Authorize ¶
Authorize implements Authorizer.
type BackupAcker ¶
type BackupAcker interface {
AckBackup(ctx context.Context, generation uint64, at time.Time, note string) error
}
BackupAcker records a backup acknowledgement for a provider's keyring. The local provider implements it.
type ErrorBody ¶
type ErrorBody struct {
Error ErrorDetail `json:"error"`
}
ErrorBody is the shape of every error response.
type ErrorDetail ¶
ErrorDetail is a stable code and a message that names no key material.
type Options ¶
type Options struct {
// Store is the registry. Required.
Store registry.Store
// Rotator performs the operations. Required.
Rotator *rotate.Rotator
// Reporter builds status. Required.
Reporter *status.Reporter
// Authorizer is asked before every action. Required.
Authorizer Authorizer
// Verifier round-trips a test value through each purpose's keys. A
// [keyforge.Client] satisfies it. Without one the verify endpoint is not
// offered.
Verifier Verifier
// Backups acknowledges backups by provider name.
Backups map[string]BackupAcker
// Audit receives an event for each administrative read. The default
// discards them.
Audit audit.Sink
// Clock defaults to the system clock.
Clock keyforge.Clock
}
Options configures a Service.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the HTTP control plane.
func (*Service) ServeHTTP ¶
func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.
Source Files