securityfeed

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package securityfeed authenticates a common public security catalog using the maintained TUF client. Feed authorization never authorizes an executable; release signatures and exact compatibility routes are independently required.

Index

Constants

View Source
const (
	CatalogPath      = "security/catalog.json"
	MaxDocumentBytes = 4 << 20
)

Variables

This section is empty.

Functions

func CreateRoot

func CreateRoot(c RootConfig) ([]byte, error)

CreateRoot creates a self-authenticated TUF root, or a consecutive rotation authenticated by both the old and new root thresholds. It never generates keys or changes Hikyo's release-signing trust.

func LoadPublicKey

func LoadPublicKey(path string) (crypto.PublicKey, error)

LoadPublicKey parses a protected local PEM through the maintained Sigstore parser. Public keys are never selected from downloaded catalog evidence.

func LoadSigner

func LoadSigner(path string) (signature.Signer, error)

LoadSigner loads a protected local PEM without logging or returning private key bytes. Encrypted keys are refused; hardware/out-of-band signers can be supplied directly to CreateRoot and BuildPublication instead.

func ReadPublicFile

func ReadPublicFile(path string, max int64) ([]byte, error)

ReadPublicFile reads operator-owned public policy/evidence without following symlink authority or accepting group/world writable files or ancestors.

Types

type Config

type Config struct {
	MetadataURL      string
	TargetsURL       string
	StateDirectory   string
	TrustedRoot      []byte
	Client           *http.Client
	OfflineDirectory string
	// VolumeRoot is the mounted volume holding StateDirectory, when the platform owns its mode.
	VolumeRoot string
	// AcceptWorldWritableVolumeRoot accepts a VolumeRoot any local user can write
	// (mode 0777 without the sticky bit). Another user could replace the state in it.
	AcceptWorldWritableVolumeRoot bool
}

Config is installation-owned. TrustedRoot is an explicitly provisioned feed root, separate from Hikyo's independently provisioned release trust. Mirrors may change URLs while retaining the same state directory and bootstrap root.

type Document

type Document struct {
	Data    []byte
	Version uint64
	Expires time.Time
}

Document contains only freshly authenticated bytes. Version is the TUF targets-metadata version; the catalog's own schema and sequence are separate.

type Expirations

type Expirations struct {
	Targets   time.Time
	Snapshot  time.Time
	Timestamp time.Time
}

Expirations are explicit operator decisions. The earliest role expiration bounds a client's catalog eligibility, even when another role lives longer.

type Publication

type Publication struct {
	// contains filtered or unexported fields
}

Publication is constructed only by verifying all role signatures and exact metadata hash bindings. Files returns copies; no private key is retained.

func BuildPublication

func BuildPublication(c PublishConfig) (*Publication, error)

func BuildRefresh

func BuildRefresh(c RefreshConfig) (*Publication, error)

BuildRefresh re-signs only snapshot and timestamp at a higher version around the existing targets metadata. Liveness never needs the targets key.

func (*Publication) Files

func (p *Publication) Files() map[string][]byte

func (*Publication) Write

func (p *Publication) Write(directory string) (returnErr error)

Write stages immutable targets and versioned metadata before atomically publishing timestamp.json last. Existing immutable bytes cannot be replaced. Public hosting and production root enrollment remain separate operator work. publish.lock is local coordination in the repository root; only metadata/ and targets/ are the public tree.

type PublishConfig

type PublishConfig struct {
	Root              []byte
	PreviousRoot      []byte
	Catalog           []byte
	PreviousTimestamp []byte
	Version           uint64
	Expires           Expirations
	Signers           map[string][]signature.Signer
}

type Published

type Published struct {
	Catalog        []byte
	TargetsExpires time.Time
	Version        uint64
	// contains filtered or unexported fields
}

Published is the current content of a prepared repository, authenticated under the supplied root. Expiry is deliberately not checked here, because a lapsed feed must remain recoverable by its online roles.

func ReadPublished

func ReadPublished(directory string, root, previousRoot []byte) (Published, bool, error)

ReadPublished authenticates the existing timestamp, snapshot, targets and catalog chain. It reports false only when the repository has no timestamp.

type RefreshConfig

type RefreshConfig struct {
	Root             []byte
	Published        Published
	SnapshotExpires  time.Time
	TimestampExpires time.Time
	Signers          map[string][]signature.Signer
}

type Repository

type Repository struct {
	// contains filtered or unexported fields
}

func New

func New(c Config) (*Repository, error)

New validates configuration without contacting the network or resetting any cached trust. Refresh serializes all mutation of the local trust cache.

func (*Repository) Refresh

func (r *Repository) Refresh(ctx context.Context) (document Document, returnErr error)

Refresh always runs the normal TUF update workflow, including for an offline import. A feed failure returns no document and never resets a cached root, rollback floor, expiration or an independently admitted serving application.

type RoleKeys

type RoleKeys struct {
	PublicKeys []crypto.PublicKey
	Threshold  int
}

RoleKeys contains public authorization only. Private keys remain with their role owners and are supplied separately when a publication is signed.

type RootConfig

type RootConfig struct {
	Version      uint64
	Expires      time.Time
	Roles        map[string]RoleKeys
	Signers      []signature.Signer
	PreviousRoot []byte
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL