Documentation ¶
Overview ¶
Package sif implements data structures and routines to create and access SIF files.
Layout of a SIF file (example):
.================================================. | GLOBAL HEADER: Sifheader | | - launch: "#!/usr/bin/env..." | | - magic: "SIF_MAGIC" | | - version: "1" | | - arch: "4" | | - uuid: b2659d4e-bd50-4ea5-bd17-eec5e54f918e | | - ctime: 1504657553 | | - mtime: 1504657653 | | - ndescr: 3 | | - descroff: 120 | --. | - descrlen: 432 | | | - dataoff: 4096 | | | - datalen: 619362 | | |------------------------------------------------| <-' | DESCR[0]: Sifdeffile | | - Sifcommon | | - datatype: DATA_DEFFILE | | - id: 1 | | - groupid: 1 | | - link: NONE | | - fileoff: 4096 | --. | - filelen: 222 | | |------------------------------------------------| <-----. | DESCR[1]: Sifpartition | | | | - Sifcommon | | | | - datatype: DATA_PARTITION | | | | - id: 2 | | | | - groupid: 1 | | | | - link: NONE | | | | - fileoff: 4318 | ----. | | - filelen: 618496 | | | | | - fstype: Squashfs | | | | | - parttype: System | | | | | - content: Linux | | | | |------------------------------------------------| | | | | DESCR[2]: Sifsignature | | | | | - Sifcommon | | | | | - datatype: DATA_SIGNATURE | | | | | - id: 3 | | | | | - groupid: NONE | | | | | - link: 2 | ------' | - fileoff: 622814 | ------. | - filelen: 644 | | | | | - hashtype: SHA384 | | | | | - entity: @ | | | | |------------------------------------------------| <-' | | | Definition file data | | | | . | | | | . | | | | . | | | |------------------------------------------------| <---' | | File system partition image | | | . | | | . | | | . | | |------------------------------------------------| <-----' | Signed verification data | | . | | . | | . | `================================================'
Index ¶
- Constants
- Variables
- type AddOpt
- type Buffer
- type CreateOpt
- func OptCreateWithCloseOnUnload(b bool) CreateOpt
- func OptCreateWithDescriptorCapacity(n int64) CreateOpt
- func OptCreateWithDescriptors(dis ...DescriptorInput) CreateOpt
- func OptCreateWithID(id string) CreateOpt
- func OptCreateWithLaunchScript(s string) CreateOpt
- func OptCreateWithTime(t time.Time) CreateOpt
- type DataType
- type DeleteOpt
- type Descriptor
- func (d Descriptor) CreatedAt() time.Time
- func (d Descriptor) CryptoMessageMetadata() (FormatType, MessageType, error)
- func (d Descriptor) DataType() DataType
- func (d Descriptor) GetData() ([]byte, error)
- func (d Descriptor) GetIntegrityReader() io.Reader
- func (d Descriptor) GetReader() io.Reader
- func (d Descriptor) GroupID() uint32
- func (d Descriptor) ID() uint32
- func (d Descriptor) LinkedID() (id uint32, isGroup bool)
- func (d Descriptor) ModifiedAt() time.Time
- func (d Descriptor) Name() string
- func (d Descriptor) Offset() int64
- func (d Descriptor) PartitionMetadata() (fs FSType, pt PartType, arch string, err error)
- func (d Descriptor) SignatureMetadata() (ht crypto.Hash, fp []byte, err error)
- func (d Descriptor) Size() int64
- type DescriptorInput
- type DescriptorInputOpt
- func OptCryptoMessageMetadata(ft FormatType, mt MessageType) DescriptorInputOpt
- func OptGroupID(groupID uint32) DescriptorInputOpt
- func OptLinkedGroupID(groupID uint32) DescriptorInputOpt
- func OptLinkedID(id uint32) DescriptorInputOpt
- func OptNoGroup() DescriptorInputOpt
- func OptObjectAlignment(n int) DescriptorInputOpt
- func OptObjectName(name string) DescriptorInputOpt
- func OptObjectTime(t time.Time) DescriptorInputOpt
- func OptPartitionMetadata(fs FSType, pt PartType, arch string) DescriptorInputOpt
- func OptSignatureMetadata(ht crypto.Hash, fp []byte) DescriptorInputOpt
- type DescriptorSelectorFunc
- func WithDataType(dt DataType) DescriptorSelectorFunc
- func WithGroupID(groupID uint32) DescriptorSelectorFunc
- func WithID(id uint32) DescriptorSelectorFunc
- func WithLinkedGroupID(groupID uint32) DescriptorSelectorFunc
- func WithLinkedID(id uint32) DescriptorSelectorFunc
- func WithNoGroup() DescriptorSelectorFunc
- func WithPartitionType(pt PartType) DescriptorSelectorFunc
- type FSType
- type FileImage
- func CreateContainer(rw ReadWriter, opts ...CreateOpt) (*FileImage, error)
- func CreateContainerAtPath(path string, opts ...CreateOpt) (*FileImage, error)
- func LoadContainer(rw ReadWriter, opts ...LoadOpt) (*FileImage, error)
- func LoadContainerFromPath(path string, opts ...LoadOpt) (*FileImage, error)
- func (f *FileImage) AddObject(di DescriptorInput, opts ...AddOpt) error
- func (f *FileImage) CreatedAt() time.Time
- func (f *FileImage) DataOffset() int64
- func (f *FileImage) DataSize() int64
- func (f *FileImage) DeleteObject(id uint32, opts ...DeleteOpt) error
- func (f *FileImage) DescriptorsFree() int64
- func (f *FileImage) DescriptorsOffset() int64
- func (f *FileImage) DescriptorsSize() int64
- func (f *FileImage) DescriptorsTotal() int64
- func (f *FileImage) GetDescriptor(fns ...DescriptorSelectorFunc) (Descriptor, error)
- func (f *FileImage) GetDescriptors(fns ...DescriptorSelectorFunc) ([]Descriptor, error)
- func (f *FileImage) GetHeaderIntegrityReader() io.Reader
- func (f *FileImage) ID() string
- func (f *FileImage) LaunchScript() string
- func (f *FileImage) ModifiedAt() time.Time
- func (f *FileImage) PrimaryArch() string
- func (f *FileImage) SetPrimPart(id uint32, opts ...SetOpt) error
- func (f *FileImage) UnloadContainer() error
- func (f *FileImage) Version() string
- func (f *FileImage) WithDescriptors(fn func(d Descriptor) bool)
- type FormatType
- type LoadOpt
- type MessageType
- type PartType
- type ReadWriter
- type SetOpt
- type SpecVersion
Constants ¶
const CurrentVersion = version01
CurrentVersion specifies the current SIF specification version.
const DefaultObjectGroup = 1
DefaultObjectGroup is the default group that data objects are placed in.
Variables ¶
var ErrInvalidGroupID = errors.New("invalid group ID")
ErrInvalidGroupID is the error returned when an invalid group ID is supplied.
var ErrInvalidObjectID = errors.New("invalid object ID")
ErrInvalidObjectID is the error returned when an invalid object ID is supplied.
var ErrMultipleObjectsFound = errors.New("multiple objects found")
ErrMultipleObjectsFound is the error returned when multiple data objects are found.
var ErrNoObjects = errors.New("no objects in image")
ErrNoObjects is the error returned when an image contains no data objects.
var ErrObjectNotFound = errors.New("object not found")
ErrObjectNotFound is the error returned when a data object is not found.
Functions ¶
This section is empty.
Types ¶
type AddOpt ¶
type AddOpt func(*addOpts) error
AddOpt are used to specify object add options.
func OptAddWithTime ¶
OptAddWithTime specifies t as the image modification time.
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
A Buffer is a variable-sized buffer of bytes that implements the sif.ReadWriter interface. The zero value for Buffer is an empty buffer ready to use.
func (*Buffer) Bytes ¶
Bytes returns the contents of the buffer. The slice is valid for use only until the next buffer modification (that is, only until the next call to a method like ReadAt, Write, or Truncate).
type CreateOpt ¶
type CreateOpt func(*createOpts) error
CreateOpt are used to specify container creation options.
func OptCreateWithCloseOnUnload ¶
OptCreateWithCloseOnUnload specifies whether the ReadWriter should be closed by UnloadContainer. By default, the ReadWriter will be closed if it implements the io.Closer interface.
func OptCreateWithDescriptorCapacity ¶ added in v2.1.1
OptCreateWithDescriptorCapacity specifies that the created image should have the capacity for a maximum of n descriptors.
func OptCreateWithDescriptors ¶
func OptCreateWithDescriptors(dis ...DescriptorInput) CreateOpt
OptCreateWithDescriptors appends dis to the list of descriptors.
func OptCreateWithID ¶
OptCreateWithID specifies id as the unique ID.
func OptCreateWithLaunchScript ¶ added in v2.1.1
OptCreateWithLaunchScript specifies s as the launch script.
func OptCreateWithTime ¶
OptCreateWithTime specifies t as the image creation time.
type DataType ¶
type DataType int32
DataType represents the different SIF data object types stored in the image.
const ( DataDeffile DataType = iota + 0x4001 // definition file data object DataEnvVar // environment variables data object DataLabels // JSON labels data object DataPartition // file system data object DataSignature // signing/verification data object DataGenericJSON // generic JSON meta-data DataGeneric // generic / raw data DataCryptoMessage // cryptographic message data object )
List of supported SIF data types.
type DeleteOpt ¶
type DeleteOpt func(*deleteOpts) error
DeleteOpt are used to specify object deletion options.
func OptDeleteCompact ¶
OptDeleteCompact specifies whether the image should be compacted following object deletion.
func OptDeleteWithTime ¶
OptDeleteWithTime specifies t as the image modification time.
func OptDeleteZero ¶
OptDeleteZero specifies whether the deleted object should be zeroed.
type Descriptor ¶
type Descriptor struct {
// contains filtered or unexported fields
}
Descriptor represents the SIF descriptor type.
func (Descriptor) CreatedAt ¶
func (d Descriptor) CreatedAt() time.Time
CreatedAt returns the creation time of the data object.
func (Descriptor) CryptoMessageMetadata ¶
func (d Descriptor) CryptoMessageMetadata() (FormatType, MessageType, error)
CryptoMessageMetadata gets metadata for a crypto message data object.
func (Descriptor) DataType ¶
func (d Descriptor) DataType() DataType
DataType returns the type of data object.
func (Descriptor) GetData ¶
func (d Descriptor) GetData() ([]byte, error)
GetData returns the data object associated with descriptor d.
func (Descriptor) GetIntegrityReader ¶
func (d Descriptor) GetIntegrityReader() io.Reader
GetIntegrityReader returns an io.Reader that reads the integrity-protected fields from d.
func (Descriptor) GetReader ¶
func (d Descriptor) GetReader() io.Reader
GetReader returns a io.Reader that reads the data object associated with descriptor d.
func (Descriptor) GroupID ¶
func (d Descriptor) GroupID() uint32
GroupID returns the data object group ID of d, or zero if d is not part of a data object group.
func (Descriptor) LinkedID ¶
func (d Descriptor) LinkedID() (id uint32, isGroup bool)
LinkedID returns the object/group ID d is linked to, or zero if d does not contain a linked ID. If isGroup is true, the returned id is an object group ID. Otherwise, the returned id is a data object ID.
func (Descriptor) ModifiedAt ¶
func (d Descriptor) ModifiedAt() time.Time
ModifiedAt returns the modification time of the data object.
func (Descriptor) Name ¶
func (d Descriptor) Name() string
Name returns the name of the data object.
func (Descriptor) Offset ¶
func (d Descriptor) Offset() int64
Offset returns the offset of the data object.
func (Descriptor) PartitionMetadata ¶
func (d Descriptor) PartitionMetadata() (fs FSType, pt PartType, arch string, err error)
PartitionMetadata gets metadata for a partition data object.
func (Descriptor) SignatureMetadata ¶
func (d Descriptor) SignatureMetadata() (ht crypto.Hash, fp []byte, err error)
SignatureMetadata gets metadata for a signature data object.
type DescriptorInput ¶
type DescriptorInput struct {
// contains filtered or unexported fields
}
DescriptorInput describes a new data object.
func NewDescriptorInput ¶
func NewDescriptorInput(t DataType, r io.Reader, opts ...DescriptorInputOpt) (DescriptorInput, error)
NewDescriptorInput returns a DescriptorInput representing a data object of type t, with contents read from r, configured according to opts.
It is possible (and often necessary) to store additional metadata related to certain types of data objects. Consider supplying options such as OptCryptoMessageMetadata, OptPartitionMetadata, and OptSignatureMetadata for this purpose.
By default, the data object will be placed in the default data object group (1). To override this behavior, use OptNoGroup or OptGroupID. To link this data object, use OptLinkedID or OptLinkedGroupID.
By default, the data object will be aligned according to the system's memory page size. To override this behavior, consider using OptObjectAlignment.
By default, no name is set for data object. To set a name, use OptObjectName.
type DescriptorInputOpt ¶
DescriptorInputOpt are used to specify data object options.
func OptCryptoMessageMetadata ¶
func OptCryptoMessageMetadata(ft FormatType, mt MessageType) DescriptorInputOpt
OptCryptoMessageMetadata sets metadata for a crypto message data object. The format type is set to ft, and the message type is set to mt.
If this option is applied to a data object with an incompatible type, an error is returned.
func OptGroupID ¶
func OptGroupID(groupID uint32) DescriptorInputOpt
OptGroupID specifies groupID as data object group ID.
func OptLinkedGroupID ¶
func OptLinkedGroupID(groupID uint32) DescriptorInputOpt
OptLinkedGroupID specifies that the data object is linked to the data object group with the specified groupID.
func OptLinkedID ¶
func OptLinkedID(id uint32) DescriptorInputOpt
OptLinkedID specifies that the data object is linked to the data object with the specified ID.
func OptNoGroup ¶
func OptNoGroup() DescriptorInputOpt
OptNoGroup specifies the data object is not contained within a data object group.
func OptObjectAlignment ¶
func OptObjectAlignment(n int) DescriptorInputOpt
OptObjectAlignment specifies n as the data alignment requirement.
func OptObjectName ¶
func OptObjectName(name string) DescriptorInputOpt
OptObjectName specifies name as the data object name.
func OptObjectTime ¶
func OptObjectTime(t time.Time) DescriptorInputOpt
OptObjectTime specifies t as the dat object creation time.
func OptPartitionMetadata ¶
func OptPartitionMetadata(fs FSType, pt PartType, arch string) DescriptorInputOpt
OptPartitionMetadata sets metadata for a partition data object. The filesystem type is set to fs, the partition type is set to pt, and the CPU architecture is set to arch. The value of arch should be the architecture as represented by the Go runtime.
If this option is applied to a data object with an incompatible type, an error is returned.
func OptSignatureMetadata ¶
func OptSignatureMetadata(ht crypto.Hash, fp []byte) DescriptorInputOpt
OptSignatureMetadata sets metadata for a signature data object. The hash type is set to ht, and the signing entity fingerprint is set to fp.
If this option is applied to a data object with an incompatible type, an error is returned.
type DescriptorSelectorFunc ¶
type DescriptorSelectorFunc func(d Descriptor) (bool, error)
DescriptorSelectorFunc returns true if d matches, and false otherwise.
func WithDataType ¶
func WithDataType(dt DataType) DescriptorSelectorFunc
WithDataType selects descriptors that have data type dt.
func WithGroupID ¶
func WithGroupID(groupID uint32) DescriptorSelectorFunc
WithGroupID returns a selector func that selects descriptors with a matching groupID.
func WithID ¶
func WithID(id uint32) DescriptorSelectorFunc
WithID selects descriptors with a matching ID.
func WithLinkedGroupID ¶
func WithLinkedGroupID(groupID uint32) DescriptorSelectorFunc
WithLinkedGroupID selects descriptors that are linked to the data object group with specified ID.
func WithLinkedID ¶
func WithLinkedID(id uint32) DescriptorSelectorFunc
WithLinkedID selects descriptors that are linked to the data object with specified ID.
func WithNoGroup ¶
func WithNoGroup() DescriptorSelectorFunc
WithNoGroup selects descriptors that are not contained within an object group.
func WithPartitionType ¶
func WithPartitionType(pt PartType) DescriptorSelectorFunc
WithPartitionType selects descriptors containing a partition of type pt.
type FSType ¶
type FSType int32
FSType represents the different SIF file system types found in partition data objects.
type FileImage ¶
type FileImage struct {
// contains filtered or unexported fields
}
FileImage describes the representation of a SIF file in memory.
func CreateContainer ¶
func CreateContainer(rw ReadWriter, opts ...CreateOpt) (*FileImage, error)
CreateContainer creates a new SIF container in rw, according to opts.
On success, a FileImage is returned. The caller must call UnloadContainer to ensure resources are released. By default, UnloadContainer will close rw if it implements the io.Closer interface. To change this behavior, consider using OptCreateWithCloseOnUnload.
By default, the image will support a maximum of 48 descriptors. To change this, consider using OptCreateWithDescriptorCapacity.
A launch script can optionally be set using OptCreateWithLaunchScript.
func CreateContainerAtPath ¶
CreateContainerAtPath creates a new SIF container file at path, according to opts.
On success, a FileImage is returned. The caller must call UnloadContainer to ensure resources are released.
By default, the image will support a maximum of 48 descriptors. To change this, consider using OptCreateWithDescriptorCapacity.
A launch script can optionally be set using OptCreateWithLaunchScript.
func LoadContainer ¶
func LoadContainer(rw ReadWriter, opts ...LoadOpt) (*FileImage, error)
LoadContainer loads a new SIF container from rw, according to opts.
On success, a FileImage is returned. The caller must call UnloadContainer to ensure resources are released. By default, UnloadContainer will close rw if it implements the io.Closer interface. To change this behavior, consider using OptLoadWithCloseOnUnload.
func LoadContainerFromPath ¶
LoadContainerFromPath loads a new SIF container from path, according to opts.
On success, a FileImage is returned. The caller must call UnloadContainer to ensure resources are released.
By default, the file is opened for read and write access. To change this behavior, consider using OptLoadWithFlag.
func (*FileImage) AddObject ¶
func (f *FileImage) AddObject(di DescriptorInput, opts ...AddOpt) error
AddObject add a new data object and its descriptor into the specified SIF file.
By default, the image modification time is set to the data object creation time. To override this, use OptAddWithTime.
func (*FileImage) DataOffset ¶
DataOffset returns the offset (in bytes) of the data section in the image.
func (*FileImage) DeleteObject ¶
DeleteObject deletes the data object with id, according to opts.
To zero the data region of the deleted object, use OptDeleteZero. To compact the file following object deletion, use OptDeleteCompact.
By default, the image modification time is set to time.Now(). To override this, use OptDeleteWithTime.
func (*FileImage) DescriptorsFree ¶
DescriptorsFree returns the number of free descriptors in the image.
func (*FileImage) DescriptorsOffset ¶
DescriptorsOffset returns the offset (in bytes) of the descriptors section in the image.
func (*FileImage) DescriptorsSize ¶
DescriptorsSize returns the size (in bytes) of the descriptors section in the image.
func (*FileImage) DescriptorsTotal ¶
DescriptorsTotal returns the total number of descriptors in the image.
func (*FileImage) GetDescriptor ¶
func (f *FileImage) GetDescriptor(fns ...DescriptorSelectorFunc) (Descriptor, error)
GetDescriptor returns the in-use descriptor selected by fns. If the image contains no data objects, an error wrapping ErrNoObjects is returned. If no descriptor is selected by fns, an error wrapping ErrObjectNotFound is returned. If multiple descriptors are selected by fns, an error wrapping ErrMultipleObjectsFound is returned.
func (*FileImage) GetDescriptors ¶
func (f *FileImage) GetDescriptors(fns ...DescriptorSelectorFunc) ([]Descriptor, error)
GetDescriptors returns a slice of in-use descriptors for which all selector funcs return true. If the image contains no data objects, an error wrapping ErrNoObjects is returned.
func (*FileImage) GetHeaderIntegrityReader ¶
GetHeaderIntegrityReader returns an io.Reader that reads the integrity-protected fields from the header of the image.
func (*FileImage) LaunchScript ¶
LaunchScript returns the image launch script.
func (*FileImage) ModifiedAt ¶
ModifiedAt returns the last modification time of the image.
func (*FileImage) PrimaryArch ¶
PrimaryArch returns the primary CPU architecture of the image.
func (*FileImage) SetPrimPart ¶
SetPrimPart sets the specified system partition to be the primary one.
By default, the image/object modification time is set to time.Now(). To override this, use OptSetWithTime.
func (*FileImage) UnloadContainer ¶
UnloadContainer unloads f, releasing associated resources.
func (*FileImage) WithDescriptors ¶
func (f *FileImage) WithDescriptors(fn func(d Descriptor) bool)
WithDescriptors calls fn with each in-use descriptor in f, until fn returns true.
type FormatType ¶
type FormatType int32
FormatType represents the different formats used to store cryptographic message objects.
const ( FormatOpenPGP FormatType = iota + 1 FormatPEM )
List of supported cryptographic message formats.
func (FormatType) String ¶
func (t FormatType) String() string
String returns a human-readable representation of t.
type LoadOpt ¶
type LoadOpt func(*loadOpts) error
LoadOpt are used to specify container loading options.
func OptLoadWithCloseOnUnload ¶
OptLoadWithCloseOnUnload specifies whether the ReadWriter should be closed by UnloadContainer. By default, the ReadWriter will be closed if it implements the io.Closer interface.
func OptLoadWithFlag ¶
OptLoadWithFlag specifies flag (os.O_RDONLY etc.) to be used when opening the container file.
type MessageType ¶
type MessageType int32
MessageType represents the different messages stored within cryptographic message objects.
const ( // openPGP formatted messages. MessageClearSignature MessageType = 0x100 // PEM formatted messages. MessageRSAOAEP MessageType = 0x200 )
List of supported cryptographic message formats.
func (MessageType) String ¶
func (t MessageType) String() string
String returns a human-readable representation of t.
type PartType ¶
type PartType int32
PartType represents the different SIF container partition types (system and data).
type ReadWriter ¶
ReadWriter describes the interface required to read and write SIF images.
type SetOpt ¶
type SetOpt func(*setOpts) error
SetOpt are used to specify object set options.
func OptSetWithTime ¶
OptSetWithTime specifies t as the image/object modification time.
type SpecVersion ¶
type SpecVersion uint8
SpecVersion specifies a SIF specification version.
func (SpecVersion) String ¶
func (v SpecVersion) String() string