ospkg

Documentation

Index

• Constants
• Variables
• type Descriptor
  • func DescriptorFromBytes(data []byte) (*Descriptor, error)
  • func DescriptorFromFile(src string) (*Descriptor, error)
  • func (d *Descriptor) Bytes() ([]byte, error)
  • func (d *Descriptor) Validate() error
• type DummySigner
  • func (DummySigner) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)
  • func (DummySigner) Verify(sig, hash []byte, key crypto.PublicKey) error
• type ED25519Signer
  • func (ED25519Signer) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)
  • func (ED25519Signer) Verify(sig, hash []byte, key crypto.PublicKey) error
• type FetchMethod
  • func (f FetchMethod) IsValid() bool
  • func (f FetchMethod) MarshalJSON() ([]byte, error)
  • func (f FetchMethod) String() string
  • func (f *FetchMethod) UnmarshalJSON(data []byte) error
• type OSManifest
  • func NewOSManifest(label, kernelPath, initramfsPath, cmdline string) *OSManifest
  • func OSManifestFromBytes(data []byte) (*OSManifest, error)
  • func (m *OSManifest) Bytes() ([]byte, error)
  • func (m *OSManifest) Validate() error
  • func (m *OSManifest) Write(dir string) error
• type OSPackage
  • func CreateOSPackage(label, pkgURL, kernel, initramfs, cmdline string) (*OSPackage, error)
  • func NewOSPackage(archiveZIP, descriptorJSON []byte) (*OSPackage, error)
  • func (osp *OSPackage) ArchiveBytes() ([]byte, error)
  • func (osp *OSPackage) DescriptorBytes() ([]byte, error)
  • func (osp *OSPackage) LinuxImage() (boot.LinuxImage, error)
  • func (osp *OSPackage) Sign(keyBlock, certBlock *pem.Block) error
  • func (osp *OSPackage) Verify(rootCert *x509.Certificate) (found, valid int, err error)
• type RSAPSSSigner
  • func (RSAPSSSigner) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)
  • func (RSAPSSSigner) Verify(sig, hash []byte, key crypto.PublicKey) error
• type Signer

Constants

const (
	ErrOpDescFromFile  sterror.Op = "DescriptorFromFile"
	ErrOpDescFromBytes sterror.Op = "DescriptorFomBytes"
	ErrOpDescBytes     sterror.Op = "Descriptor.Bytes"
	ErrOpDValidate     sterror.Op = "Descriptor.Validate"
)

Operations used for raising Errors of this package.

const (
	DescriptorVersion int = 1
	// DescriptorExt is the file extension of OS package descriptor file.
	DescriptorExt string = ".json"
)

const (
	ErrOpOSMFromBytes sterror.Op = "OSManifestFromBytes"
	ErrOpOSMWrite     sterror.Op = "OSManifest.Write"
	ErrOpOSMBytes     sterror.Op = "OSManifest.Bytes"
	ErrOpOSMValidate  sterror.Op = "OSManifest.Validate"
)

Operations used for raising Errors of this package.

const (
	ManifestVersion int = 1
	// ManifestName is the name of OS packages' internal configuration file.
	ManifestName string = "manifest.json"
)

const (
	ErrScope                  sterror.Scope = "OS package"
	ErrOpCreateOSPkg          sterror.Op    = "CreateOSPackage"
	ErrOpNewOSPkg             sterror.Op    = "NewOSPackage"
	ErrOpOSPkgArchiveBytes    sterror.Op    = "OSPackage.ArchiveBytes"
	ErrOpOSPkgDescriptorBytes sterror.Op    = "OSPackage.DescriptorBytes"
	ErrOpOSPkgSign            sterror.Op    = "OSPackage.Sign"
	ErrOpOSPkgVerify          sterror.Op    = "OSPackage.Verify"
	ErrOpOSPkgvalidate        sterror.Op    = "OSPackage.validate"
	ErrOpOSPkgzip             sterror.Op    = "OSPackage.zip"
	ErrOpOSPkgunzip           sterror.Op    = "OSPackage.unzip"
	ErrOpOSPkgparseCert       sterror.Op    = "OSPackage.parseCert"
	ErrOpcalculateHash        sterror.Op    = "calculateHash"
	ErrOpOSImage              sterror.Op    = "OSImage"
)

Scope and operations used for raising Errors of this package.

const (
	ErrInfoFailedToReadFrom = "failed to read from %v"
	ErrInfoInvalidPath      = "missing %v path"
	ErrInfoInvalidVer       = "invalid version: %d, expected %d"
	ErrInfoMissingScheme    = "missing scheme"
	ErrInfoLengthOfZero     = "data %v has length of zero"
)

Additional information which might get included into Errors.

const (
	// DefaultOSPackageName is the file name of the archive, which is expected to contain
	// the stboot configuration file along with the corresponding files.
	DefaultOSPackageName string = "ospkg.zip"
	// OSPackageExt is the file extension of OS packages.
	OSPackageExt string = ".zip"
)

const (
	ErrOpDSSign       sterror.Op = "DummySigner.Sign"
	ErrOpRSASSign     sterror.Op = "RSAPSSSigner.Sign"
	ErrOpRSASVerify   sterror.Op = "RSAPSSSigner.Verify"
	ErrOpEDSSign      sterror.Op = "ED25519Signer.Sign"
	ErrOpEDSVerify    sterror.Op = "ED25519Signer.Verify"
	ErrInfoInvalidKey            = "got key of type %T, expected %v"
)

Scope and operations used for raising Errors of this package.

const (
	ErrOpunzip = "unzipFile"
)

Variables

var (
	ErrVrfy          = errors.New("signature verification failed")
	ErrParse         = errors.New("failed to parse")
	ErrSerialize     = errors.New("failed to serialize")
	ErrValidate      = errors.New("failed to validate")
	ErrSign          = errors.New("failed to sign")
	ErrWriteToFile   = errors.New("failed to write to file")
	ErrFailedToUnzip = errors.New("failed to unzip archive")
	ErrFailedToZip   = errors.New("failed to zip")
	ErrNotHashable   = errors.New("data not hashable")
	ErrGenerateData  = errors.New("failed to generate data")
	ErrMissingData   = errors.New("missing data")
	ErrOverwriteData = errors.New("failed to overwrite data")
)

Errors which may be raised and wrapped in this package.

var (
	ErrSigning      = errors.New("signature creation failed")
	ErrVerification = errors.New("signature verification failed")
	ErrInvalidKey   = errors.New("invalid key type")
)

Errors which may be raised and wrapped in this package.

Types

type Descriptor

type Descriptor struct {
	Version int    `json:"version"`
	PkgURL  string `json:"os_pkg_url"`

	Certificates [][]byte `json:"certificates"`
	Signatures   [][]byte `json:"signatures"`
}

Descriptor represents the descriptor JSON file of an OS package.

func DescriptorFromBytes

func DescriptorFromBytes(data []byte) (*Descriptor, error)

DescriptorFromBytes parses a manifest from a byte slice.

func DescriptorFromFile

func DescriptorFromFile(src string) (*Descriptor, error)

DescriptorFromFile parses a manifest from a json file.

func (*Descriptor) Bytes

func (d *Descriptor) Bytes() ([]byte, error)

Bytes serializes a manifest stuct into a byte slice.

func (*Descriptor) Validate

func (d *Descriptor) Validate() error

Validate returns true if d has valid content.

type DummySigner

type DummySigner struct{}

DummySigner implements the Signer interface. It creates signatures that are always valid.

func (DummySigner) Sign

func (DummySigner) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)

Sign returns a signature containing just 8 random bytes.

func (DummySigner) Verify

func (DummySigner) Verify(sig, hash []byte, key crypto.PublicKey) error

Verify will never return an error.

type ED25519Signer

type ED25519Signer struct{}

func (ED25519Signer) Sign

func (ED25519Signer) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)

Sign signes the provided data with the key named by privKey. Problems are reported by an error wrapping SigningError.

func (ED25519Signer) Verify

func (ED25519Signer) Verify(sig, hash []byte, key crypto.PublicKey) error

Verify checks if sig contains a valid signature of hash.

type FetchMethod

type FetchMethod int

FetchMethod controls where to load the OS package from.

const (
	FetchFromNetwork FetchMethod = iota + 1
	FetchFromInitramfs
)

Supported methods to fetch an OS package.

func (FetchMethod) IsValid

func (f FetchMethod) IsValid() bool

IsValid returns true if b is a defined FetchMethod value.

func (FetchMethod) MarshalJSON

func (f FetchMethod) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (FetchMethod) String

func (f FetchMethod) String() string

String implements fmt.Stringer.

func (*FetchMethod) UnmarshalJSON

func (f *FetchMethod) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type OSManifest

type OSManifest struct {
	Version int    `json:"version"`
	Label   string `json:"label"`

	KernelPath    string `json:"kernel"`
	InitramfsPath string `json:"initramfs"`
	Cmdline       string `json:"cmdline"`
}

OSManifest describes the content and configuration of an OS package loaded by stboot.

func NewOSManifest

func NewOSManifest(label, kernelPath, initramfsPath, cmdline string) *OSManifest

func OSManifestFromBytes

func OSManifestFromBytes(data []byte) (*OSManifest, error)

OSManifestFromBytes parses a manifest from a byte slice.

func (*OSManifest) Bytes

func (m *OSManifest) Bytes() ([]byte, error)

Bytes serializes a manifest stuct into a byte slice.

func (*OSManifest) Validate

func (m *OSManifest) Validate() error

Validate returns no.

func (*OSManifest) Write

func (m *OSManifest) Write(dir string) error

Write saves m to file named by stboot.ManifestName at a path named by dir.

type OSPackage

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

OSPackage represents an OS package ZIP archive and related data.

func CreateOSPackage

func CreateOSPackage(label, pkgURL, kernel, initramfs, cmdline string) (*OSPackage, error)

CreateOSPackage constructs a OSPackage from the passed files.

func NewOSPackage

func NewOSPackage(archiveZIP, descriptorJSON []byte) (*OSPackage, error)

NewOSPackage constructs a new OSPackage initialized with raw bytes and valid internal state.

func (*OSPackage) ArchiveBytes

func (osp *OSPackage) ArchiveBytes() ([]byte, error)

ArchiveBytes return the zip compressed archive part of osp.

func (*OSPackage) DescriptorBytes

func (osp *OSPackage) DescriptorBytes() ([]byte, error)

DescriptorBytes return the zip compressed archive part of osp.

func (*OSPackage) LinuxImage

func (osp *OSPackage) LinuxImage() (boot.LinuxImage, error)

OSImage returns a LinuxImage from osp. LinuxImage implements boot.

func (*OSPackage) Sign

func (osp *OSPackage) Sign(keyBlock, certBlock *pem.Block) error

Sign signes osp.HashValue using osp.Signer. Both, the signature and the certificate are stored into the OSPackage.

func (*OSPackage) Verify

func (osp *OSPackage) Verify(rootCert *x509.Certificate) (found, valid int, err error)

Verify first verifies the certificates stored together with the signatures in the os package descriptor against the provided root certificates and then verifies the signatures. The number of found signatures and the number of valid signatures are returned. A signature is valid if: * Its certificate was signed by the root certificate * It passed verification * Its certificate is not a duplicate of a previous one The validity bounds of all in volved certificates are ignored.

type RSAPSSSigner

type RSAPSSSigner struct{}

RSAPSSSigner implements the Signer interface. It uses SHA256 hashes and PSS signatures along with x509 certificates.

func (RSAPSSSigner) Sign

func (RSAPSSSigner) Sign(key crypto.PrivateKey, data []byte) ([]byte, error)

Sign signes the provided data with the key named by privKey. The returned byte slice contains a PSS signature value. Problems are reported by an error wrapping SigningError.

func (RSAPSSSigner) Verify

func (RSAPSSSigner) Verify(sig, hash []byte, key crypto.PublicKey) error

Verify checks if sig contains a valid signature of hash.

type Signer

type Signer interface {
	Sign(key crypto.PrivateKey, data []byte) ([]byte, error)
	Verify(sig, hash []byte, key crypto.PublicKey) error
}

Signer is used by OSPackage to sign and varify the OSPackage.