v1manifest

package
v0.0.0-...-a027a2a Latest Latest
Warning

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

Go to latest
Published: Jan 26, 2022 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ManifestTypeRoot      = "root"
	ManifestTypeIndex     = "index"
	ManifestTypeSnapshot  = "snapshot"
	ManifestTypeTimestamp = "timestamp"
	ManifestTypeComponent = "component"
	// Manifest URLs in a repository.
	ManifestURLRoot      = "/root.json"
	ManifestURLIndex     = "/index.json"
	ManifestURLSnapshot  = "/snapshot.json"
	ManifestURLTimestamp = "/timestamp.json"
	// Manifest filenames when stored locally.
	ManifestFilenameRoot      = "root.json"
	ManifestFilenameIndex     = "index.json"
	ManifestFilenameSnapshot  = "snapshot.json"
	ManifestFilenameTimestamp = "timestamp.json"

	// SpecVersion of current, maybe we could expand it later
	CurrentSpecVersion = "0.1.0"

	// AnyPlatform is the ID for platform independent components
	AnyPlatform = "any/any"

	// Acceptable values for hash kinds.
	SHA256 = "sha256"
	SHA512 = "sha512"
)

Names of manifest ManifestsConfig

View Source
const ShortKeyIDLength = 16

ShortKeyIDLength is the number of bytes used for filenames

Variables

View Source
var ErrLoadManifest = &LoadManifestError{}

ErrLoadManifest is an empty object of LoadManifestError, useful for type check

View Source
var ErrorInsufficientKeys = stderrors.New("not enough keys supplied")

ErrorInsufficientKeys indicates that the key number is less than threshold

View Source
var ErrorNotPrivateKey = errors.New("not a private key")

ErrorNotPrivateKey indicate that it need a private key, but the supplied is not.

View Source
var ManifestsConfig = map[string]ty{
	ManifestTypeRoot: {
		Filename:  ManifestFilenameRoot,
		Versioned: true,
		Expire:    time.Hour * 24 * 365,
		Threshold: 3,
	},
	ManifestTypeIndex: {
		Filename:  ManifestFilenameIndex,
		Versioned: true,
		Expire:    time.Hour * 24 * 365,
		Threshold: 1,
	},
	ManifestTypeComponent: {
		Filename:  "",
		Versioned: true,
		Expire:    time.Hour * 24 * 365 * 5,
		Threshold: 1,
	},
	ManifestTypeSnapshot: {
		Filename:  ManifestFilenameSnapshot,
		Versioned: false,
		Expire:    time.Hour * 24 * 30,
		Threshold: 1,
	},
	ManifestTypeTimestamp: {
		Filename:  ManifestFilenameTimestamp,
		Versioned: false,
		Expire:    time.Hour * 24 * 30,
		Threshold: 1,
	},
}

ManifestsConfig for different manifest ManifestsConfig

Functions

func BatchSaveManifests

func BatchSaveManifests(dst string, manifestList map[string]*Manifest) error

BatchSaveManifests write a series of manifests to disk Manifest in the manifestList map should already be signed, they are not checked for signature again.

func CheckExpiry

func CheckExpiry(fname, expires string) error

CheckExpiry return not nil if it's expired.

func ComponentManifestFilename

func ComponentManifestFilename(id string) string

ComponentManifestFilename returns the expected filename for the component manifest identified by id.

func ExpiresAfter

func ExpiresAfter(m1, m2 ValidManifest) error

ExpiresAfter checks that manifest 1 expires after manifest 2 (or are equal) and returns an error otherwise.

func GenAndSaveKeys

func GenAndSaveKeys(keys map[string][]*KeyInfo, ty string, num int, dir string) error

GenAndSaveKeys generate private keys to keys param and save key file to dir

func Init

func Init(dst, keyDir string, initTime time.Time) (err error)

Init creates and initializes an empty reposityro

func IsExpirationError

func IsExpirationError(err error) bool

IsExpirationError checks if the err is an ExpirationError.

func IsSignatureError

func IsSignatureError(err error) bool

IsSignatureError check if the err is SignatureError.

func ReadManifestDir

func ReadManifestDir(dir string, roles ...string) (map[string]ValidManifest, error)

ReadManifestDir reads manifests from a dir

func RenewManifest

func RenewManifest(m ValidManifest, startTime time.Time, extend ...time.Duration)

RenewManifest resets and extends the expire time of manifest

func RootManifestFilename

func RootManifestFilename(version uint) string

RootManifestFilename returns the expected filename for the root manifest with the given version.

func SaveKeyInfo

func SaveKeyInfo(key *KeyInfo, ty, dir string) (string, error)

SaveKeyInfo saves a KeyInfo object to a JSON file

func SignAndWrite

func SignAndWrite(out io.Writer, role ValidManifest, keys ...*KeyInfo) error

SignAndWrite creates a manifest and writes it to out.

func SignManifestData

func SignManifestData(data []byte, ki *KeyInfo) ([]byte, error)

SignManifestData add signatures to a manifest data

func WriteManifest

func WriteManifest(out io.Writer, m *Manifest) error

WriteManifest writes a Manifest object to writer in JSON format

func WriteManifestFile

func WriteManifestFile(fname string, m *Manifest) error

WriteManifestFile writes a Manifest object to file in JSON format

Types

type Component

type Component struct {
	SignedBase
	ID          string `json:"id"`
	Description string `json:"description"`
	Nightly     string `json:"nightly"` // version of the latest daily build
	// platform -> version -> VersionItem
	Platforms map[string]map[string]VersionItem `json:"platforms"`
}

Component manifest.

func NewComponent

func NewComponent(id, desc string, initTime time.Time) *Component

NewComponent creates a Component object

func (*Component) Base

func (manifest *Component) Base() *SignedBase

Base implements ValidManifest

func (*Component) Filename

func (manifest *Component) Filename() string

Filename implements ValidManifest

func (*Component) HasNightly

func (manifest *Component) HasNightly(platform string) bool

HasNightly return true if the component has nightly version.

func (*Component) VersionItem

func (manifest *Component) VersionItem(plat, ver string, includeYanked bool) *VersionItem

VersionItem returns VersionItem by platform and version

func (*Component) VersionList

func (manifest *Component) VersionList(platform string) map[string]VersionItem

VersionList return all versions exclude yanked versions

func (*Component) VersionListWithYanked

func (manifest *Component) VersionListWithYanked(platform string) map[string]VersionItem

VersionListWithYanked return all versions include yanked versions

type ComponentItem

type ComponentItem struct {
	Yanked     bool   `json:"yanked"`
	Owner      string `json:"owner"`
	URL        string `json:"url"`
	Standalone bool   `json:"standalone"`
	Hidden     bool   `json:"hidden"`
}

ComponentItem object

type ExpirationError

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

ExpirationError the a manifest has expired.

func (*ExpirationError) Error

func (s *ExpirationError) Error() string

type FileHash

type FileHash struct {
	Hashes map[string]string `json:"hashes"`
	Length uint              `json:"length"`
}

FileHash is the hashes and length of a file.

type FileVersion

type FileVersion struct {
	Version uint `json:"version"`
	Length  uint `json:"length"`
}

FileVersion is just a version number.

type FsManifests

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

FsManifests represents a collection of v1 manifests on disk. Invariant: any manifest written to disk should be valid, but may have expired. (It is also possible the manifest was ok when written and has expired since).

func NewManifests

func NewManifests(profile *localdata.Profile) (*FsManifests, error)

NewManifests creates a new FsManifests with local store at root. There must exist a trusted root.json.

func (*FsManifests) ComponentInstalled

func (ms *FsManifests) ComponentInstalled(component, version string) (bool, error)

ComponentInstalled implements LocalManifests.

func (*FsManifests) InstallComponent

func (ms *FsManifests) InstallComponent(reader io.Reader, targetDir, component, version, filename string, noExpand bool) error

InstallComponent implements LocalManifests.

func (*FsManifests) KeyStore

func (ms *FsManifests) KeyStore() *KeyStore

KeyStore implements LocalManifests.

func (*FsManifests) LoadComponentManifest

func (ms *FsManifests) LoadComponentManifest(item *ComponentItem, filename string) (*Component, error)

LoadComponentManifest implements LocalManifests.

func (*FsManifests) LoadManifest

func (ms *FsManifests) LoadManifest(role ValidManifest) (*Manifest, bool, error)

LoadManifest implements LocalManifests.

func (*FsManifests) ManifestVersion

func (ms *FsManifests) ManifestVersion(filename string) uint

ManifestVersion implements LocalManifests.

func (*FsManifests) SaveComponentManifest

func (ms *FsManifests) SaveComponentManifest(manifest *Manifest, filename string) error

SaveComponentManifest implements LocalManifests.

func (*FsManifests) SaveManifest

func (ms *FsManifests) SaveManifest(manifest *Manifest, filename string) error

SaveManifest implements LocalManifests.

func (*FsManifests) TargetRootDir

func (ms *FsManifests) TargetRootDir() string

TargetRootDir implements LocalManifests.

type Index

type Index struct {
	SignedBase
	Owners            map[string]Owner         `json:"owners"`
	Components        map[string]ComponentItem `json:"components"`
	DefaultComponents []string                 `json:"default_components"`
}

Index manifest.

func NewIndex

func NewIndex(initTime time.Time) *Index

NewIndex creates a Index object

func (*Index) Base

func (manifest *Index) Base() *SignedBase

Base implements ValidManifest

func (*Index) ComponentList

func (manifest *Index) ComponentList() map[string]ComponentItem

ComponentList returns non-yanked components

func (*Index) ComponentListWithYanked

func (manifest *Index) ComponentListWithYanked() map[string]ComponentItem

ComponentListWithYanked return all components

func (*Index) Filename

func (manifest *Index) Filename() string

Filename implements ValidManifest

type KeyInfo

type KeyInfo struct {
	Type   string            `json:"keytype"`
	Value  map[string]string `json:"keyval"`
	Scheme string            `json:"scheme"`
}

KeyInfo is the manifest structure of a single key

func FreshKeyInfo

func FreshKeyInfo() (*KeyInfo, string, crypto.PrivKey, error)

FreshKeyInfo generates a new key pair and wraps it in a KeyInfo. The returned string is the key id.

func GenKeyInfo

func GenKeyInfo() (*KeyInfo, error)

GenKeyInfo generate a new private KeyInfo

func NewKeyInfo

func NewKeyInfo(privKey []byte) *KeyInfo

NewKeyInfo make KeyInfo from private key, public key should be load from json

func (*KeyInfo) ID

func (ki *KeyInfo) ID() (string, error)

ID returns the hash id of the key

func (*KeyInfo) IsPrivate

func (ki *KeyInfo) IsPrivate() bool

IsPrivate detect if this is a private key

func (*KeyInfo) Public

func (ki *KeyInfo) Public() (*KeyInfo, error)

Public returns the public keyInfo

func (*KeyInfo) SignManifest

func (ki *KeyInfo) SignManifest(m ValidManifest) (string, error)

SignManifest wrap Signature with the param manifest

func (*KeyInfo) Signature

func (ki *KeyInfo) Signature(payload []byte) (string, error)

Signature sign a signature with the key for payload

func (*KeyInfo) Verify

func (ki *KeyInfo) Verify(payload []byte, sig string) error

Verify check the signature is right

type KeyStore

type KeyStore struct {
	sync.Map
}

KeyStore tracks roles, keys, etc. and verifies signatures against this metadata. (map[string]roleKeys)

func NewKeyStore

func NewKeyStore() *KeyStore

NewKeyStore return a KeyStore

func (*KeyStore) AddKeys

func (s *KeyStore) AddKeys(role string, threshold uint, expiry string, keys map[string]*KeyInfo) error

AddKeys clears all keys for role, then adds all supplied keys and stores the threshold value.

type LoadManifestError

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

LoadManifestError is the error type used when loading manifest failes

func (*LoadManifestError) Error

func (e *LoadManifestError) Error() string

Error implements the error interface

func (*LoadManifestError) Is

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

Is implements the error interface

func (*LoadManifestError) Unwrap

func (e *LoadManifestError) Unwrap() error

Unwrap implements the error interface

type LocalManifests

type LocalManifests interface {
	// SaveManifest saves a manifest to disk, it will overwrite filename if it exists.
	SaveManifest(manifest *Manifest, filename string) error
	// SaveComponentManifest saves a component manifest to disk, it will overwrite filename if it exists.
	SaveComponentManifest(manifest *Manifest, filename string) error
	// LoadManifest loads and validates the most recent manifest of role's type. The returned bool is true if the file
	// exists.
	LoadManifest(role ValidManifest) (*Manifest, bool, error)
	// LoadComponentManifest loads and validates the most recent manifest at filename.
	LoadComponentManifest(item *ComponentItem, filename string) (*Component, error)
	// ComponentInstalled is true if the version of component is present locally.
	ComponentInstalled(component, version string) (bool, error)
	// InstallComponent installs the component from the reader.
	InstallComponent(reader io.Reader, targetDir, component, version, filename string, noExpand bool) error
	// Return the local key store.
	KeyStore() *KeyStore
	// ManifestVersion opens filename, if it exists and is a manifest, returns its manifest version number. Otherwise
	// returns 0.
	ManifestVersion(filename string) uint

	// TargetRootDir returns the root directory of target
	TargetRootDir() string
}

LocalManifests methods for accessing a store of manifests.

type Manifest

type Manifest struct {
	// Signatures value
	Signatures []Signature `json:"signatures"`
	// Signed value; any value here must have the SignedBase base.
	Signed ValidManifest `json:"signed"`
}

Manifest representation for ser/de.

func ReadComponentManifest

func ReadComponentManifest(input io.Reader, com *Component, item *ComponentItem, keys *KeyStore) (*Manifest, error)

ReadComponentManifest reads a component manifest from input and validates it.

func ReadManifest

func ReadManifest(input io.Reader, role ValidManifest, keys *KeyStore) (*Manifest, error)

ReadManifest reads a manifest from input and validates it, the result is stored in role, which must be a pointer type.

func ReadNoVerify

func ReadNoVerify(input io.Reader, role ValidManifest) (*Manifest, error)

ReadNoVerify will read role from input and will not do any validation or verification. It is very dangerous to use this function and it should only be used to read trusted data from local storage.

func SignManifest

func SignManifest(role ValidManifest, keys ...*KeyInfo) (*Manifest, error)

SignManifest signs a manifest with given private key

func (*Manifest) AddSignature

func (manifest *Manifest) AddSignature(sigs []Signature)

AddSignature adds one or more signatures to the manifest

type MockInstalled

type MockInstalled struct {
	Version    string
	Contents   string
	BinaryPath string
}

MockInstalled is used by MockManifests to remember what was installed for a component.

type MockManifests

type MockManifests struct {
	Manifests map[string]*Manifest
	Saved     []string
	Installed map[string]MockInstalled
	Ks        *KeyStore
}

MockManifests is a LocalManifests implementation for testing.

func NewMockManifests

func NewMockManifests() *MockManifests

NewMockManifests creates an empty MockManifests.

func (*MockManifests) ComponentInstalled

func (ms *MockManifests) ComponentInstalled(component, version string) (bool, error)

ComponentInstalled implements LocalManifests.

func (*MockManifests) InstallComponent

func (ms *MockManifests) InstallComponent(reader io.Reader, targetDir string, component, version, filename string, noExpand bool) error

InstallComponent implements LocalManifests.

func (*MockManifests) KeyStore

func (ms *MockManifests) KeyStore() *KeyStore

KeyStore implements LocalManifests.

func (*MockManifests) LoadComponentManifest

func (ms *MockManifests) LoadComponentManifest(item *ComponentItem, filename string) (*Component, error)

LoadComponentManifest implements LocalManifests.

func (*MockManifests) LoadManifest

func (ms *MockManifests) LoadManifest(role ValidManifest) (*Manifest, bool, error)

LoadManifest implements LocalManifests.

func (*MockManifests) ManifestVersion

func (ms *MockManifests) ManifestVersion(filename string) uint

ManifestVersion implements LocalManifests.

func (*MockManifests) SaveComponentManifest

func (ms *MockManifests) SaveComponentManifest(manifest *Manifest, filename string) error

SaveComponentManifest implements LocalManifests.

func (*MockManifests) SaveManifest

func (ms *MockManifests) SaveManifest(manifest *Manifest, filename string) error

SaveManifest implements LocalManifests.

func (*MockManifests) TargetRootDir

func (ms *MockManifests) TargetRootDir() string

TargetRootDir implements LocalManifests.

type Owner

type Owner struct {
	Name      string              `json:"name"`
	Keys      map[string]*KeyInfo `json:"keys"`
	Threshold int                 `json:"threshold"`
}

Owner object.

type RawManifest

type RawManifest struct {
	// Signatures value
	Signatures []Signature `json:"signatures"`
	// Signed value; raw json message
	Signed json.RawMessage `json:"signed"`
}

RawManifest representation for ser/de.

type Role

type Role struct {
	URL       string              `json:"url"`
	Keys      map[string]*KeyInfo `json:"keys"`
	Threshold uint                `json:"threshold"`
}

Role object.

type Root

type Root struct {
	SignedBase
	Roles map[string]*Role `json:"roles"`
}

Root manifest.

func NewRoot

func NewRoot(initTime time.Time) *Root

NewRoot creates a Root object

func (*Root) AddKey

func (manifest *Root) AddKey(roleName string, key *KeyInfo) error

AddKey adds a public key info to a role of Root

func (*Root) Base

func (manifest *Root) Base() *SignedBase

Base implements ValidManifest

func (*Root) Filename

func (manifest *Root) Filename() string

Filename implements ValidManifest

func (*Root) SetRole

func (manifest *Root) SetRole(m ValidManifest, keys ...*KeyInfo) error

SetRole populates role list in the root manifest

type Signature

type Signature struct {
	KeyID string `json:"keyid"`
	Sig   string `json:"sig"`
}

Signature represents a signature for a manifest

type SignatureError

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

SignatureError the signature of a file is incorrect.

func (*SignatureError) Error

func (s *SignatureError) Error() string

type SignedBase

type SignedBase struct {
	Ty          string `json:"_type"`
	SpecVersion string `json:"spec_version"`
	Expires     string `json:"expires"`
	// 0 => no version specified
	Version uint `json:"version"`
}

SignedBase represents parts of a manifest's signed value which are shared by all manifests.

func (*SignedBase) Filename

func (s *SignedBase) Filename() string

Filename returns the unversioned name that the manifest should be saved as based on the type in s.

func (*SignedBase) SetExpiresAt

func (s *SignedBase) SetExpiresAt(t time.Time)

SetExpiresAt set manifest expires at the specified time.

func (*SignedBase) Versioned

func (s *SignedBase) Versioned() bool

Versioned indicates whether versioned versions of a manifest are saved, e.g., 42.foo.json.

type Snapshot

type Snapshot struct {
	SignedBase
	Meta map[string]FileVersion `json:"meta"`
}

Snapshot manifest.

func NewSnapshot

func NewSnapshot(initTime time.Time) *Snapshot

NewSnapshot creates a Snapshot object.

func (*Snapshot) Base

func (manifest *Snapshot) Base() *SignedBase

Base implements ValidManifest

func (*Snapshot) Filename

func (manifest *Snapshot) Filename() string

Filename implements ValidManifest

func (*Snapshot) SetVersions

func (manifest *Snapshot) SetVersions(manifestList map[string]*Manifest) (*Snapshot, error)

SetVersions sets file versions to the snapshot

func (*Snapshot) VersionedURL

func (manifest *Snapshot) VersionedURL(url string) (string, *FileVersion, error)

VersionedURL looks up url in the snapshot and returns a modified url with the version prefix, and that file's length.

type Timestamp

type Timestamp struct {
	SignedBase
	Meta map[string]FileHash `json:"meta"`
}

Timestamp manifest.

func NewTimestamp

func NewTimestamp(initTime time.Time) *Timestamp

NewTimestamp creates a Timestamp object

func (*Timestamp) Base

func (manifest *Timestamp) Base() *SignedBase

Base implements ValidManifest

func (*Timestamp) Filename

func (manifest *Timestamp) Filename() string

Filename implements ValidManifest

func (*Timestamp) SetSnapshot

func (manifest *Timestamp) SetSnapshot(s *Manifest) (*Timestamp, error)

SetSnapshot hashes a snapshot manifest and update the timestamp manifest

func (*Timestamp) SnapshotHash

func (manifest *Timestamp) SnapshotHash() FileHash

SnapshotHash returns the hashes of the snapshot manifest as specified in the timestamp manifest.

type ValidManifest

type ValidManifest interface {

	// Base returns this manifest's SignedBase which is values common to all manifests.
	Base() *SignedBase
	// Filename returns the unversioned name that the manifest should be saved as based on its Go type.
	Filename() string
	// contains filtered or unexported methods
}

ValidManifest is a manifest which includes SignedBase and can be validated.

type VersionItem

type VersionItem struct {
	URL          string            `json:"url"`
	Yanked       bool              `json:"yanked"`
	Entry        string            `json:"entry"`
	Released     string            `json:"released"`
	Dependencies map[string]string `json:"dependencies"`

	FileHash
}

VersionItem is the manifest structure of a version of a component

Jump to

Keyboard shortcuts

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