package metadata

const (
	KeyTypeEd25519                = "ed25519"
	KeyTypeECDSA_SHA2_P256_COMPAT = "ecdsa-sha2-nistp256"
	KeyTypeECDSA_SHA2_P256        = "ecdsa"
	KeyTypeRSASSA_PSS_SHA256      = "rsa"
	KeySchemeEd25519              = "ed25519"
	KeySchemeECDSA_SHA2_P256      = "ecdsa-sha2-nistp256"
	KeySchemeECDSA_SHA2_P384      = "ecdsa-sha2-nistp384"
	KeySchemeRSASSA_PSS_SHA256    = "rsassa-pss-sha256"
)

const (
	ROOT      = "root"
	SNAPSHOT  = "snapshot"
	TARGETS   = "targets"
	TIMESTAMP = "timestamp"
)

Define top level role names

const (
	SPECIFICATION_VERSION = "1.0.31"
)

Define version of the TUF specification

Variables ¶

var TOP_LEVEL_ROLE_NAMES = [...]string{ROOT, TIMESTAMP, SNAPSHOT, TARGETS}

Functions ¶

func SetLogger ¶

func SetLogger(logger Logger)

Types ¶

type DelegatedRole ¶

type DelegatedRole struct {
	Name               string         `json:"name"`
	KeyIDs             []string       `json:"keyids"`
	Threshold          int            `json:"threshold"`
	Terminating        bool           `json:"terminating"`
	PathHashPrefixes   []string       `json:"path_hash_prefixes,omitempty"`
	Paths              []string       `json:"paths,omitempty"`
	UnrecognizedFields map[string]any `json:"-"`
}

DelegatedRole represents a delegated role in TUF

func (*DelegatedRole) IsDelegatedPath ¶

func (role *DelegatedRole) IsDelegatedPath(targetFilepath string) (bool, error)

IsDelegatedPath determines whether the given "targetFilepath" is in one of the paths that "DelegatedRole" is trusted to provide

func (DelegatedRole) MarshalJSON ¶

func (role DelegatedRole) MarshalJSON() ([]byte, error)

func (*DelegatedRole) UnmarshalJSON ¶

func (role *DelegatedRole) UnmarshalJSON(data []byte) error

type Delegations ¶

type Delegations struct {
	Keys               map[string]*Key `json:"keys"`
	Roles              []DelegatedRole `json:"roles,omitempty"`
	SuccinctRoles      *SuccinctRoles  `json:"succinct_roles,omitempty"`
	UnrecognizedFields map[string]any  `json:"-"`
}

Delegations is an optional object which represents delegation roles and their corresponding keys

func (*Delegations) GetRolesForTarget ¶

func (role *Delegations) GetRolesForTarget(targetFilepath string) []RoleResult

GetRolesForTarget return the names and terminating status of all delegated roles who are responsible for targetFilepath Note the result should be an ordered list, ref. https://github.com/theupdateframework/go-tuf/security/advisories/GHSA-4f8r-qqr9-fq8j

func (Delegations) MarshalJSON ¶

func (d Delegations) MarshalJSON() ([]byte, error)

func (*Delegations) UnmarshalJSON ¶

func (d *Delegations) UnmarshalJSON(data []byte) error

type DiscardLogger ¶

type DiscardLogger struct{}

func (DiscardLogger) Error ¶

func (d DiscardLogger) Error(err error, msg string, kv ...any)

func (DiscardLogger) Info ¶

func (d DiscardLogger) Info(msg string, kv ...any)

type ErrBadVersionNumber ¶

type ErrBadVersionNumber struct {
	Msg string
}

ErrBadVersionNumber - An error for metadata that contains an invalid version number

func (*ErrBadVersionNumber) Error ¶

func (e *ErrBadVersionNumber) Error() string

func (*ErrBadVersionNumber) Is ¶

func (e *ErrBadVersionNumber) Is(target error) bool

ErrBadVersionNumber is a subset of ErrRepository

type ErrDownload ¶

type ErrDownload struct {
	Msg string
}

ErrDownload - An error occurred while attempting to download a file

func (*ErrDownload) Error ¶

func (e *ErrDownload) Error() string

func (*ErrDownload) Is ¶

func (e *ErrDownload) Is(target error) bool

type ErrDownloadHTTP ¶

type ErrDownloadHTTP struct {
	StatusCode int
	URL        string
}

ErrDownloadHTTP - Returned by Fetcher interface implementations for HTTP errors

func (*ErrDownloadHTTP) Error ¶

func (e *ErrDownloadHTTP) Error() string

func (*ErrDownloadHTTP) Is ¶

func (e *ErrDownloadHTTP) Is(target error) bool

ErrDownloadHTTP is a subset of ErrDownload

type ErrDownloadLengthMismatch ¶

type ErrDownloadLengthMismatch struct {
	Msg string
}

ErrDownloadLengthMismatch - Indicate that a mismatch of lengths was seen while downloading a file

func (*ErrDownloadLengthMismatch) Error ¶

func (e *ErrDownloadLengthMismatch) Error() string

func (*ErrDownloadLengthMismatch) Is ¶

func (e *ErrDownloadLengthMismatch) Is(target error) bool

ErrDownloadLengthMismatch is a subset of ErrDownload

type ErrEqualVersionNumber ¶

type ErrEqualVersionNumber struct {
	Msg string
}

ErrEqualVersionNumber - An error for metadata containing a previously verified version number

func (*ErrEqualVersionNumber) Error ¶

func (e *ErrEqualVersionNumber) Error() string

func (*ErrEqualVersionNumber) Is ¶

func (e *ErrEqualVersionNumber) Is(target error) bool

ErrEqualVersionNumber is a subset of both ErrRepository and ErrBadVersionNumber

type ErrExpiredMetadata ¶

type ErrExpiredMetadata struct {
	Msg string
}

ErrExpiredMetadata - Indicate that a TUF Metadata file has expired

func (*ErrExpiredMetadata) Error ¶

func (e *ErrExpiredMetadata) Error() string

func (*ErrExpiredMetadata) Is ¶

func (e *ErrExpiredMetadata) Is(target error) bool

ErrExpiredMetadata is a subset of ErrRepository

type ErrLengthOrHashMismatch ¶

type ErrLengthOrHashMismatch struct {
	Msg string
}

ErrLengthOrHashMismatch - An error while checking the length and hash values of an object

func (*ErrLengthOrHashMismatch) Error ¶

func (e *ErrLengthOrHashMismatch) Error() string

func (*ErrLengthOrHashMismatch) Is ¶

func (e *ErrLengthOrHashMismatch) Is(target error) bool

ErrLengthOrHashMismatch is a subset of ErrRepository

type ErrRepository ¶

type ErrRepository struct {
	Msg string
}

ErrRepository - an error with a repository's state, such as a missing file. It covers all exceptions that come from the repository side when looking from the perspective of users of metadata API or client

func (*ErrRepository) Error ¶

func (e *ErrRepository) Error() string

func (*ErrRepository) Is ¶

func (e *ErrRepository) Is(target error) bool

type ErrRuntime ¶

type ErrRuntime struct {
	Msg string
}

RuntimeError

func (*ErrRuntime) Error ¶

func (e *ErrRuntime) Error() string

func (*ErrRuntime) Is ¶

func (e *ErrRuntime) Is(err error) bool

type ErrType ¶

type ErrType struct {
	Msg string
}

TypeError

func (*ErrType) Error ¶

func (e *ErrType) Error() string

func (*ErrType) Is ¶

func (e *ErrType) Is(err error) bool

type ErrUnsignedMetadata ¶

type ErrUnsignedMetadata struct {
	Msg string
}

ErrUnsignedMetadata - An error about metadata object with insufficient threshold of signatures

func (*ErrUnsignedMetadata) Error ¶

func (e *ErrUnsignedMetadata) Error() string

func (*ErrUnsignedMetadata) Is ¶

func (e *ErrUnsignedMetadata) Is(target error) bool

ErrUnsignedMetadata is a subset of ErrRepository

type ErrValue ¶

type ErrValue struct {
	Msg string
}

ValueError

func (*ErrValue) Error ¶

func (e *ErrValue) Error() string

func (*ErrValue) Is ¶

func (e *ErrValue) Is(err error) bool

type Hashes ¶

type Hashes map[string]HexBytes

func (Hashes) Equal ¶

func (source Hashes) Equal(expected Hashes) bool

Equal checks whether one hash set equals another

type HexBytes ¶

type HexBytes []byte

func (HexBytes) MarshalJSON ¶

func (b HexBytes) MarshalJSON() ([]byte, error)

func (HexBytes) String ¶

func (b HexBytes) String() string

func (*HexBytes) UnmarshalJSON ¶

func (b *HexBytes) UnmarshalJSON(data []byte) error

type Key ¶

type Key struct {
	Type   string `json:"keytype"`
	Scheme string `json:"scheme"`
	Value  KeyVal `json:"keyval"`

	UnrecognizedFields map[string]any `json:"-"`
	// contains filtered or unexported fields
}

Key represents a key in TUF

func KeyFromPublicKey ¶

func KeyFromPublicKey(k crypto.PublicKey) (*Key, error)

KeyFromPublicKey generate metadata type Key from crypto.PublicKey

func (*Key) ID ¶

func (k *Key) ID() (string, error)

ID returns the keyID value for the given Key, or an error if the key cannot be canonically encoded.

func (Key) MarshalJSON ¶

func (key Key) MarshalJSON() ([]byte, error)

func (*Key) ToPublicKey ¶

func (k *Key) ToPublicKey() (crypto.PublicKey, error)

ToPublicKey generate crypto.PublicKey from metadata type Key

func (*Key) UnmarshalJSON ¶

func (key *Key) UnmarshalJSON(data []byte) error

type KeyVal ¶

type KeyVal struct {
	PublicKey          string         `json:"public"`
	UnrecognizedFields map[string]any `json:"-"`
}

func (KeyVal) MarshalJSON ¶

func (kv KeyVal) MarshalJSON() ([]byte, error)

func (*KeyVal) UnmarshalJSON ¶

func (kv *KeyVal) UnmarshalJSON(data []byte) error

type Logger ¶

type Logger interface {
	// Info logs a non-error message with key/value pairs
	Info(msg string, kv ...any)
	// Error logs an error with a given message and key/value pairs.
	Error(err error, msg string, kv ...any)
}

Logger partially implements the go-log/logr's interface: https://github.com/go-logr/logr/blob/master/logr.go

func GetLogger ¶

func GetLogger() Logger

type MetaFiles ¶

type MetaFiles struct {
	Length             int64          `json:"length,omitempty"`
	Hashes             Hashes         `json:"hashes,omitempty"`
	Version            int64          `json:"version"`
	UnrecognizedFields map[string]any `json:"-"`
}

MetaFiles represents the value portion of METAFILES in TUF (used in Snapshot and Timestamp metadata). Used to store information about a particular meta file.

func MetaFile ¶

func MetaFile(version int64) *MetaFiles

MetaFile return new metadata instance of type MetaFile

func (MetaFiles) MarshalJSON ¶

func (signed MetaFiles) MarshalJSON() ([]byte, error)

func (*MetaFiles) UnmarshalJSON ¶

func (signed *MetaFiles) UnmarshalJSON(data []byte) error

func (*MetaFiles) VerifyLengthHashes ¶

func (f *MetaFiles) VerifyLengthHashes(data []byte) error

VerifyLengthHashes checks whether the MetaFiles data matches its corresponding length and hashes

type Metadata ¶

type Metadata[T Roles] struct {
	Signed             T              `json:"signed"`
	Signatures         []Signature    `json:"signatures"`
	UnrecognizedFields map[string]any `json:"-"`
}

Metadata[T Roles] represents a TUF metadata. Provides methods to read and write to and from file and bytes, also to create, verify and clear metadata signatures.

func Root ¶

func Root(expires ...time.Time) *Metadata[RootType]

Root return new metadata instance of type Root

func Snapshot ¶

func Snapshot(expires ...time.Time) *Metadata[SnapshotType]

Snapshot return new metadata instance of type Snapshot

func Targets ¶

func Targets(expires ...time.Time) *Metadata[TargetsType]

Targets return new metadata instance of type Targets

func Timestamp ¶

func Timestamp(expires ...time.Time) *Metadata[TimestampType]

Timestamp return new metadata instance of type Timestamp

func (*Metadata[T]) ClearSignatures ¶

func (meta *Metadata[T]) ClearSignatures()

ClearSignatures clears Signatures

func (*Metadata[T]) FromBytes ¶

func (meta *Metadata[T]) FromBytes(data []byte) (*Metadata[T], error)

FromBytes deserialize metadata from bytes

func (*Metadata[T]) FromFile ¶

func (meta *Metadata[T]) FromFile(name string) (*Metadata[T], error)

FromFile load metadata from file

func (Metadata[T]) MarshalJSON ¶

func (meta Metadata[T]) MarshalJSON() ([]byte, error)

func (*Metadata[T]) Sign ¶

func (meta *Metadata[T]) Sign(signer signature.Signer) (*Signature, error)

Sign create signature over Signed and assign it to Signatures

func (*Metadata[T]) ToBytes ¶

func (meta *Metadata[T]) ToBytes(pretty bool) ([]byte, error)

ToBytes serialize metadata to bytes

func (*Metadata[T]) ToFile ¶

func (meta *Metadata[T]) ToFile(name string, pretty bool) error

ToFile save metadata to file

func (*Metadata[T]) UnmarshalJSON ¶

func (meta *Metadata[T]) UnmarshalJSON(data []byte) error

func (*Metadata[T]) VerifyDelegate ¶

func (meta *Metadata[T]) VerifyDelegate(delegatedRole string, delegatedMetadata any) error

VerifyDelegate verifies that delegatedMetadata is signed with the required threshold of keys for the delegated role delegatedRole

type Role ¶

type Role struct {
	KeyIDs             []string       `json:"keyids"`
	Threshold          int            `json:"threshold"`
	UnrecognizedFields map[string]any `json:"-"`
}

Role represents one of the top-level roles in TUF

func (Role) MarshalJSON ¶

func (role Role) MarshalJSON() ([]byte, error)

func (*Role) UnmarshalJSON ¶

func (role *Role) UnmarshalJSON(data []byte) error

type RoleResult ¶

type RoleResult struct {
	Name        string
	Terminating bool
}

RoleResult represents the name and terminating status of a delegated role that is responsible for targetFilepath

type Roles ¶

type Roles interface {
	RootType | SnapshotType | TimestampType | TargetsType
}

Generic type constraint

type RootType ¶

type RootType struct {
	Type               string           `json:"_type"`
	SpecVersion        string           `json:"spec_version"`
	ConsistentSnapshot bool             `json:"consistent_snapshot"`
	Version            int64            `json:"version"`
	Expires            time.Time        `json:"expires"`
	Keys               map[string]*Key  `json:"keys"`
	Roles              map[string]*Role `json:"roles"`
	UnrecognizedFields map[string]any   `json:"-"`
}

RootType represents the Signed portion of a root metadata

func (*RootType) AddKey ¶

func (signed *RootType) AddKey(key *Key, role string) error

AddKey adds new signing key for delegated role "role" keyID: Identifier of the key to be added for "role". key: Signing key to be added for "role". role: Name of the role, for which "key" is added.

func (*RootType) IsExpired ¶

func (signed *RootType) IsExpired(referenceTime time.Time) bool

IsExpired returns true if metadata is expired. It checks if referenceTime is after Signed.Expires

func (RootType) MarshalJSON ¶

func (signed RootType) MarshalJSON() ([]byte, error)

func (*RootType) RevokeKey ¶

func (signed *RootType) RevokeKey(keyID, role string) error

RevokeKey revoke key from “role“ and updates the Keys store. keyID: Identifier of the key to be removed for “role“. role: Name of the role, for which a signing key is removed.

func (*RootType) UnmarshalJSON ¶

func (signed *RootType) UnmarshalJSON(data []byte) error

type Signature ¶

type Signature struct {
	KeyID              string         `json:"keyid"`
	Signature          HexBytes       `json:"sig"`
	UnrecognizedFields map[string]any `json:"-"`
}

Signature represents the Signature part of a TUF metadata

func (Signature) MarshalJSON ¶

func (s Signature) MarshalJSON() ([]byte, error)

func (*Signature) UnmarshalJSON ¶

func (s *Signature) UnmarshalJSON(data []byte) error

type SnapshotType ¶

type SnapshotType struct {
	Type               string                `json:"_type"`
	SpecVersion        string                `json:"spec_version"`
	Version            int64                 `json:"version"`
	Expires            time.Time             `json:"expires"`
	Meta               map[string]*MetaFiles `json:"meta"`
	UnrecognizedFields map[string]any        `json:"-"`
}

SnapshotType represents the Signed portion of a snapshot metadata

func (*SnapshotType) IsExpired ¶

func (signed *SnapshotType) IsExpired(referenceTime time.Time) bool

IsExpired returns true if metadata is expired. It checks if referenceTime is after Signed.Expires

func (SnapshotType) MarshalJSON ¶

func (signed SnapshotType) MarshalJSON() ([]byte, error)

func (*SnapshotType) UnmarshalJSON ¶

func (signed *SnapshotType) UnmarshalJSON(data []byte) error

type SuccinctRoles ¶

type SuccinctRoles struct {
	KeyIDs             []string       `json:"keyids"`
	Threshold          int            `json:"threshold"`
	BitLength          int            `json:"bit_length"`
	NamePrefix         string         `json:"name_prefix"`
	UnrecognizedFields map[string]any `json:"-"`
}

SuccinctRoles represents a delegation graph that covers all targets, distributing them uniformly over the delegated roles (i.e. bins) in the graph.

func (*SuccinctRoles) GetRoles ¶

func (role *SuccinctRoles) GetRoles() []string

GetRoles returns the names of all different delegated roles

func (*SuccinctRoles) GetRolesForTarget ¶

func (role *SuccinctRoles) GetRolesForTarget(targetFilepath string) []RoleResult

GetRolesForTarget calculate the name of the delegated role responsible for "targetFilepath". The target at path "targetFilepath" is assigned to a bin by casting the left-most "BitLength" of bits of the file path hash digest to int, using it as bin index between 0 and “2**BitLength-1”.

func (*SuccinctRoles) GetSuffixLen ¶

func (role *SuccinctRoles) GetSuffixLen() (int, int)

func (*SuccinctRoles) IsDelegatedRole ¶

func (role *SuccinctRoles) IsDelegatedRole(roleName string) bool

IsDelegatedRole returns whether the given roleName is in one of the delegated roles that “SuccinctRoles“ represents

func (SuccinctRoles) MarshalJSON ¶

func (role SuccinctRoles) MarshalJSON() ([]byte, error)

func (*SuccinctRoles) UnmarshalJSON ¶

func (role *SuccinctRoles) UnmarshalJSON(data []byte) error

type TargetFiles ¶

type TargetFiles struct {
	Length             int64            `json:"length"`
	Hashes             Hashes           `json:"hashes"`
	Custom             *json.RawMessage `json:"custom,omitempty"`
	Path               string           `json:"-"`
	UnrecognizedFields map[string]any   `json:"-"`
}

TargetFiles represents the value portion of TARGETS in TUF (used Targets metadata). Used to store information about a particular target file.

func TargetFile ¶

func TargetFile() *TargetFiles

TargetFile return new metadata instance of type TargetFiles

func (*TargetFiles) Equal ¶

func (source *TargetFiles) Equal(expected TargetFiles) bool

Equal checks whether the source target file matches another

func (*TargetFiles) FromBytes ¶

func (t *TargetFiles) FromBytes(localPath string, data []byte, hashes ...string) (*TargetFiles, error)

FromBytes generate TargetFiles from bytes

func (*TargetFiles) FromFile ¶

func (t *TargetFiles) FromFile(localPath string, hashes ...string) (*TargetFiles, error)

FromFile generate TargetFiles from file

func (TargetFiles) MarshalJSON ¶

func (signed TargetFiles) MarshalJSON() ([]byte, error)

func (*TargetFiles) UnmarshalJSON ¶

func (signed *TargetFiles) UnmarshalJSON(data []byte) error

func (*TargetFiles) VerifyLengthHashes ¶

func (f *TargetFiles) VerifyLengthHashes(data []byte) error

VerifyLengthHashes checks whether the TargetFiles data matches its corresponding length and hashes

type TargetsType ¶

type TargetsType struct {
	Type               string                  `json:"_type"`
	SpecVersion        string                  `json:"spec_version"`
	Version            int64                   `json:"version"`
	Expires            time.Time               `json:"expires"`
	Targets            map[string]*TargetFiles `json:"targets"`
	Delegations        *Delegations            `json:"delegations,omitempty"`
	UnrecognizedFields map[string]any          `json:"-"`
}

TargetsType represents the Signed portion of a targets metadata

func (*TargetsType) AddKey ¶

func (signed *TargetsType) AddKey(key *Key, role string) error

AddKey adds new signing key for delegated role "role" key: Signing key to be added for "role". role: Name of the role, for which "key" is added. If SuccinctRoles is used then the "role" argument can be ignored.

func (*TargetsType) IsExpired ¶

func (signed *TargetsType) IsExpired(referenceTime time.Time) bool

IsExpired returns true if metadata is expired. It checks if referenceTime is after Signed.Expires

func (TargetsType) MarshalJSON ¶

func (signed TargetsType) MarshalJSON() ([]byte, error)

func (*TargetsType) RevokeKey ¶

func (signed *TargetsType) RevokeKey(keyID string, role string) error

RevokeKey revokes key from delegated role "role" and updates the delegations key store keyID: Identifier of the key to be removed for “role“. role: Name of the role, for which a signing key is removed.

func (*TargetsType) UnmarshalJSON ¶

func (signed *TargetsType) UnmarshalJSON(data []byte) error

type TimestampType ¶

type TimestampType struct {
	Type               string                `json:"_type"`
	SpecVersion        string                `json:"spec_version"`
	Version            int64                 `json:"version"`
	Expires            time.Time             `json:"expires"`
	Meta               map[string]*MetaFiles `json:"meta"`
	UnrecognizedFields map[string]any        `json:"-"`
}

TimestampType represents the Signed portion of a timestamp metadata

func (*TimestampType) IsExpired ¶

func (signed *TimestampType) IsExpired(referenceTime time.Time) bool

IsExpired returns true if metadata is expired. It checks if referenceTime is after Signed.Expires

func (TimestampType) MarshalJSON ¶

func (signed TimestampType) MarshalJSON() ([]byte, error)

func (*TimestampType) UnmarshalJSON ¶

func (signed *TimestampType) UnmarshalJSON(data []byte) error

Source Files ¶

errors.go keys.go logger.go marshal.go metadata.go types.go

Directories ¶

Path	Synopsis
metadata/config
metadata/fetcher
metadata/multirepo
metadata/trustedmetadata
metadata/updater

Version: v2.4.1 (latest)
Published: Jan 26, 2026
Platform: linux/amd64
Imports: 27 packages
Last checked: 3 hours ago –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples