sif

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2021 License: BSD-3-Clause Imports: 14 Imported by: 23

Documentation

Overview

Package sif implements data structures and routines to create and access SIF files.

  • sif.go contains the data definition the file format.
  • create.go implements the core functionality for the creation of of new SIF files.
  • load.go implements the core functionality for the loading of existing SIF files.
  • lookup.go mostly implements search/lookup and printing routines and access to specific descriptor/data found in SIF container 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                       |
| .                                              |
| .                                              |
| .                                              |
`================================================'

Deprecated: this package is deprecated. Users should migrate applications to package github.com/sylabs/sif/v2/pkg/sif.

This package is frozen and no new functionality will be added.

Index

Constants

View Source 
const (
	HdrLaunch       = "#!/usr/bin/env run-singularity\n"
	HdrMagic        = "SIF_MAGIC" // SIF identification
	HdrVersion      = "01"        // SIF SPEC VERSION
	HdrArchUnknown  = "00"        // Undefined/Unsupported arch
	HdrArch386      = "01"        // 386 (i[3-6]86) arch code
	HdrArchAMD64    = "02"        // AMD64 arch code
	HdrArchARM      = "03"        // ARM arch code
	HdrArchARM64    = "04"        // AARCH64 arch code
	HdrArchPPC64    = "05"        // PowerPC 64 arch code
	HdrArchPPC64le  = "06"        // PowerPC 64 little-endian arch code
	HdrArchMIPS     = "07"        // MIPS arch code
	HdrArchMIPSle   = "08"        // MIPS little-endian arch code
	HdrArchMIPS64   = "09"        // MIPS64 arch code
	HdrArchMIPS64le = "10"        // MIPS64 little-endian arch code
	HdrArchS390x    = "11"        // IBM s390x arch code

	HdrLaunchLen  = 32 // len("#!/usr/bin/env... ")
	HdrMagicLen   = 10 // len("SIF_MAGIC")
	HdrVersionLen = 3  // len("99")
	HdrArchLen    = 3  // len("99")

	DescrNumEntries   = 48                 // the default total number of available descriptors
	DescrGroupMask    = 0xf0000000         // groups start at that offset
	DescrUnusedGroup  = DescrGroupMask     // descriptor without a group
	DescrDefaultGroup = DescrGroupMask | 1 // first groupid number created
	DescrUnusedLink   = 0                  // descriptor without link to other
	DescrEntityLen    = 256                // len("Joe Bloe <jbloe@gmail.com>...")
	DescrNameLen      = 128                // descriptor name (string identifier)
	DescrMaxPrivLen   = 384                // size reserved for descriptor specific data
	DescrStartOffset  = 4096               // where descriptors start after global header
)

SIF header constants and quantities.

View Source 
const (
	DelZero    = iota + 1 // zero the data object bytes
	DelCompact            // free the space used by data object
)

SIF data object deletion strategies.

View Source 
const DataStartOffset = 32768

DataStartOffset indicates where data object start after descriptors.

Deprecated: this value may not be accurate for all images. Use (Header).Dataoff from the image instead.

Variables

View Source 
var ErrMultValues = errors.New("lookup would return more than one match")

ErrMultValues is the code for when search key is not unique.

View Source 
var ErrNotFound = errors.New("no match found")

ErrNotFound is the code for when no search key is not found.

Functions

func GetGoArch 

func GetGoArch(sifarch string) (goarch string)

GetGoArch returns the go runtime arch code from the SIF arch code.

func GetSIFArch 

func GetSIFArch(goarch string) (sifarch string)

GetSIFArch returns the SIF arch code from go runtime arch code.

Types

type CreateInfo 

type CreateInfo struct {
	Pathname   string            // the end result output filename
	Launchstr  string            // the shell run command
	Sifversion string            // the SIF specification version used
	ID         uuid.UUID         // image unique identifier
	InputDescr []DescriptorInput // slice of input info for descriptor creation
}

CreateInfo wraps all SIF file creation info needed.

type CryptoMessage added in v1.0.8 

type CryptoMessage struct {
	Formattype  Formattype
	Messagetype Messagetype
}

CryptoMessage represents the SIF crypto message object descriptor.

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.

func (Datatype) String added in v1.0.9 

func (t Datatype) String() string

String returns a human-readable representation of t.

type Deffile 

type Deffile struct{}

Deffile represents the SIF definition-file data object descriptor.

type Descriptor 

type Descriptor struct {
	Datatype Datatype // informs of descriptor type
	Used     bool     // is the descriptor in use
	ID       uint32   // a unique id for this data object
	Groupid  uint32   // object group this data object is related to
	Link     uint32   // special link or relation to an id or group
	Fileoff  int64    // offset from start of image file
	Filelen  int64    // length of data in file
	Storelen int64    // length of data + alignment to store data in file

	Ctime int64                 // image creation time
	Mtime int64                 // last modification time
	UID   int64                 // Deprecated: UID exists for historical compatibility and should not be used.
	Gid   int64                 // Deprecated: Gid exists for historical compatibility and should not be used.
	Name  [DescrNameLen]byte    // descriptor name (string identifier)
	Extra [DescrMaxPrivLen]byte // big enough for extra data below
}

Descriptor represents the SIF descriptor type.

func (*Descriptor) GetArch 

func (d *Descriptor) GetArch() ([HdrArchLen]byte, error)

GetArch extracts the Arch field from the Extra field of a Partition Descriptor.

func (*Descriptor) GetData 

func (d *Descriptor) GetData(fimg *FileImage) []byte

GetData returns the data object associated with descriptor d from image fimg, or nil on error.

func (*Descriptor) GetEntity 

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

GetEntity extracts the signing entity field from the Extra field of a Signature Descriptor.

func (*Descriptor) GetEntityString 

func (d *Descriptor) GetEntityString() (string, error)

GetEntityString returns the string version of the stored entity.

func (*Descriptor) GetFormatType added in v1.0.8 

func (d *Descriptor) GetFormatType() (Formattype, error)

GetFormatType extracts the Formattype field from the Extra field of a Cryptographic Message Descriptor.

func (*Descriptor) GetFsType 

func (d *Descriptor) GetFsType() (Fstype, error)

GetFsType extracts the Fstype field from the Extra field of a Partition Descriptor.

func (*Descriptor) GetHashType 

func (d *Descriptor) GetHashType() (Hashtype, error)

GetHashType extracts the Hashtype field from the Extra field of a Signature Descriptor.

func (*Descriptor) GetMessageType added in v1.0.8 

func (d *Descriptor) GetMessageType() (Messagetype, error)

GetMessageType extracts the Messagetype field from the Extra field of a Cryptographic Message Descriptor.

func (*Descriptor) GetName 

func (d *Descriptor) GetName() string

GetName returns the name tag associated with the descriptor. Analogous to file name.

func (*Descriptor) GetPartType 

func (d *Descriptor) GetPartType() (Parttype, error)

GetPartType extracts the Parttype field from the Extra field of a Partition Descriptor.

func (*Descriptor) GetReadSeeker deprecated added in v1.1.0 

func (d *Descriptor) GetReadSeeker(fimg *FileImage) io.ReadSeeker

GetReadSeeker returns a io.ReadSeeker that reads the data object associated with descriptor d from image fimg.

Deprecated: GetReadSeeker will be removed in a future release. Use GetData or GetReader to read the data object.

func (*Descriptor) GetReader added in v1.3.0 

func (d *Descriptor) GetReader(fimg *FileImage) io.Reader

GetReader returns a io.Reader that reads the data object associated with descriptor d from image fimg.

func (*Descriptor) SetExtra 

func (d *Descriptor) SetExtra(extra []byte)

SetExtra sets the extra byte array to a provided byte array.

func (*Descriptor) SetName 

func (d *Descriptor) SetName(name string)

SetName sets the byte array field "Name" to the value of string "name".

type DescriptorInput 

type DescriptorInput struct {
	Datatype  Datatype // datatype being harvested for new descriptor
	Groupid   uint32   // group to be set for new descriptor
	Link      uint32   // link to be set for new descriptor
	Size      int64    // size of the data object for the new descriptor
	Alignment int      // Align requirement for data object

	Fname string    // file containing data associated with the new descriptor
	Fp    io.Reader // file pointer to opened 'fname'
	Data  []byte    // loaded data from file

	Image *FileImage  // loaded SIF file in memory
	Descr *Descriptor // created end result descriptor

	Extra bytes.Buffer // where specific input type store their data
}

DescriptorInput describes the common info needed to create a data object descriptor.

func (*DescriptorInput) SetCryptoMsgExtra added in v1.0.8 

func (di *DescriptorInput) SetCryptoMsgExtra(format Formattype, message Messagetype) error

SetCryptoMsgExtra serializes the message format and type info into a binary buffer.

func (*DescriptorInput) SetPartExtra 

func (di *DescriptorInput) SetPartExtra(fs Fstype, part Parttype, arch string) error

SetPartExtra serializes the partition and fs type info into a binary buffer.

func (*DescriptorInput) SetSignExtra 

func (di *DescriptorInput) SetSignExtra(hash Hashtype, entity string) error

SetSignExtra serializes the hash type and the entity info into a binary buffer.

type Envvar 

type Envvar struct{}

Envvar represents the SIF envvar data object descriptor.

type FileImage 

type FileImage struct {
	Header     Header        // the loaded SIF global header
	Fp         ReadWriter    // file pointer of opened SIF file
	Filesize   int64         // file size of the opened SIF file
	Filedata   []byte        // Deprecated: Filedata exists for historical compatibility and should not be used.
	Amodebuf   bool          // Deprecated: Amodebuf exists for historical compatibility and should not be used.
	Reader     *bytes.Reader // Deprecated: Reader exists for historical compatibility and should not be used.
	DescrArr   []Descriptor  // slice of loaded descriptors from SIF file
	PrimPartID uint32        // ID of primary system partition if present
}

FileImage describes the representation of a SIF file in memory.

func CreateContainer 

func CreateContainer(cinfo CreateInfo) (fimg *FileImage, err error)

CreateContainer is responsible for the creation of a new SIF container file. It takes the creation information specification as input and produces an output file as specified in the input data.

On success, a FileImage is returned. The caller must call UnloadContainer to ensure resources are released.

func LoadContainer 

func LoadContainer(filename string, rdonly bool) (FileImage, error)

LoadContainer is responsible for loading a SIF container file. It takes the container file name, and whether the file is opened as read-only as arguments.

func LoadContainerFp 

func LoadContainerFp(fp ReadWriter, rdonly bool) (fimg FileImage, err error)

LoadContainerFp is responsible for loading a SIF container file. It takes a ReadWriter pointing to an opened file, and whether the file is opened as read-only for arguments.

func LoadContainerReader 

func LoadContainerReader(b *bytes.Reader) (fimg FileImage, err error)

LoadContainerReader is responsible for processing SIF data from a byte stream and extract various components like the global header, descriptors and even perhaps data, depending on how much is read from the source.

func (*FileImage) AddObject 

func (fimg *FileImage) AddObject(input DescriptorInput) error

AddObject add a new data object and its descriptor into the specified SIF file.

func (*FileImage) DeleteObject 

func (fimg *FileImage) DeleteObject(id uint32, flags int) error

DeleteObject removes data from a SIF file referred to by id. The descriptor for the data object is free'd and can be reused later. There's currently 2 clean mode specified by flags: DelZero, to zero out the data region for security and DelCompact to remove and shink the file compacting the unused area.

func (*FileImage) FmtDescrInfo deprecated 

func (fimg *FileImage) FmtDescrInfo(id uint32) string

FmtDescrInfo formats the output of detailed info about a descriptor from a SIF file.

Deprecated: FmtDescrInfo will be removed in a future release.

func (*FileImage) FmtDescrList deprecated 

func (fimg *FileImage) FmtDescrList() string

FmtDescrList formats the output of a list of all active descriptors from a SIF file.

Deprecated: FmtDescrList will be removed in a future release.

func (*FileImage) FmtHeader deprecated 

func (fimg *FileImage) FmtHeader() string

FmtHeader formats the output of a SIF file global header.

Deprecated: FmtHeader will be removed in a future release.

func (*FileImage) GetFromDescr 

func (fimg *FileImage) GetFromDescr(descr Descriptor) ([]*Descriptor, []int, error)

GetFromDescr searches for descriptors comparing all non-nil fields of a provided descriptor.

func (*FileImage) GetFromDescrID 

func (fimg *FileImage) GetFromDescrID(id uint32) (*Descriptor, int, error)

GetFromDescrID searches for a descriptor with.

func (*FileImage) GetFromLinkedDescr 

func (fimg *FileImage) GetFromLinkedDescr(id uint32) ([]*Descriptor, []int, error)

GetFromLinkedDescr searches for descriptors that point to "id".

func (*FileImage) GetHeader 

func (fimg *FileImage) GetHeader() *Header

GetHeader returns the loaded SIF global header.

func (*FileImage) GetLinkedDescrsByType added in v1.0.7 

func (fimg *FileImage) GetLinkedDescrsByType(id uint32, dataType Datatype) ([]*Descriptor, []int, error)

GetLinkedDescrsByType searches for descriptors that point to "id", only returns the specified type.

func (*FileImage) GetPartFromGroup 

func (fimg *FileImage) GetPartFromGroup(groupid uint32) ([]*Descriptor, []int, error)

GetPartFromGroup searches for partition descriptors inside a specific group.

func (*FileImage) GetPartPrimSys 

func (fimg *FileImage) GetPartPrimSys() (*Descriptor, int, error)

GetPartPrimSys returns the primary system partition if present. There should be only one primary system partition in a SIF file.

func (*FileImage) GetSignFromGroup 

func (fimg *FileImage) GetSignFromGroup(groupid uint32) ([]*Descriptor, []int, error)

GetSignFromGroup searches for signature descriptors inside a specific group.

func (*FileImage) SetPrimPart added in v1.0.3 

func (fimg *FileImage) SetPrimPart(id uint32) error

SetPrimPart sets the specified system partition to be the primary one.

func (*FileImage) UnloadContainer 

func (fimg *FileImage) UnloadContainer() (err error)

UnloadContainer closes the SIF container file and free associated resources if needed.

type Formattype added in v1.0.8 

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 added in v1.4.0 

func (t Formattype) String() string

String returns a human-readable representation of t.

type Fstype 

type Fstype int32

Fstype represents the different SIF file system types found in partition data objects. 

const (
	FsSquash            Fstype = iota + 1 // Squashfs file system, RDONLY
	FsExt3                                // EXT3 file system, RDWR (deprecated)
	FsImmuObj                             // immutable data object archive
	FsRaw                                 // raw data
	FsEncryptedSquashfs                   // Encrypted Squashfs file system, RDONLY
)

List of supported file systems.

func (Fstype) String added in v1.4.0 

func (t Fstype) String() string

String returns a human-readable representation of t.

type Generic added in v1.0.3 

type Generic struct{}

Generic represents the SIF generic data object descriptor.

type GenericJSON 

type GenericJSON struct{}

GenericJSON represents the SIF generic JSON meta-data data object descriptor.

type Hashtype 

type Hashtype int32

Hashtype represents the different SIF hashing function types used to fingerprint data objects. 

const (
	HashSHA256 Hashtype = iota + 1
	HashSHA384
	HashSHA512
	HashBLAKE2S
	HashBLAKE2B
)

List of supported hash functions.

func (Hashtype) String added in v1.4.0 

func (t Hashtype) String() string

String returns a human-readable representation of t. 

type Header struct {
	Launch [HdrLaunchLen]byte // #! shell execution line

	Magic   [HdrMagicLen]byte   // look for "SIF_MAGIC"
	Version [HdrVersionLen]byte // SIF version
	Arch    [HdrArchLen]byte    // arch the primary partition is built for
	ID      uuid.UUID           // image unique identifier

	Ctime int64 // image creation time
	Mtime int64 // last modification time

	Dfree    int64 // # of unused data object descr.
	Dtotal   int64 // # of total available data object descr.
	Descroff int64 // bytes into file where descs start
	Descrlen int64 // bytes used by all current descriptors
	Dataoff  int64 // bytes into file where data starts
	Datalen  int64 // bytes used by all data objects
}

Header describes a loaded SIF file.

type Labels 

type Labels struct{}

Labels represents the SIF JSON-labels data object descriptor.

type Messagetype added in v1.0.8 

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 added in v1.4.0 

func (t Messagetype) String() string

String returns a human-readable representation of t.

type Partition 

type Partition struct {
	Fstype   Fstype
	Parttype Parttype
	Arch     [HdrArchLen]byte // arch the image is built for
}

Partition represents the SIF partition data object descriptor.

type Parttype 

type Parttype int32

Parttype represents the different SIF container partition types (system and data). 

const (
	PartSystem  Parttype = iota + 1 // partition hosts an operating system
	PartPrimSys                     // partition hosts the primary operating system
	PartData                        // partition hosts data only
	PartOverlay                     // partition hosts an overlay
)

List of supported partition types.

func (Parttype) String added in v1.4.0 

func (t Parttype) String() string

String returns a human-readable representation of t.

type ReadWriter added in v1.0.3 

type ReadWriter interface {
	io.ReadWriteSeeker
	io.ReaderAt
	io.Closer
	Name() string
	Fd() uintptr
	Stat() (os.FileInfo, error)
	Sync() error
	Truncate(size int64) error
}

ReadWriter describes the operations needed to support reading and writing SIF files.

type Signature 

type Signature struct {
	Hashtype Hashtype
	Entity   [DescrEntityLen]byte
}

Signature represents the SIF signature data object descriptor.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.