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/hpcng/sif/v2/pkg/sif.
This package is frozen and no new functionality will be added.
Index ¶
- Constants
- Variables
- func GetGoArch(sifarch string) (goarch string)
- func GetSIFArch(goarch string) (sifarch string)
- type CreateInfo
- type CryptoMessage
- type Datatype
- type Deffile
- type Descriptor
- func (d *Descriptor) GetArch() ([HdrArchLen]byte, error)
- func (d *Descriptor) GetData(fimg *FileImage) []byte
- func (d *Descriptor) GetEntity() ([]byte, error)
- func (d *Descriptor) GetEntityString() (string, error)
- func (d *Descriptor) GetFormatType() (Formattype, error)
- func (d *Descriptor) GetFsType() (Fstype, error)
- func (d *Descriptor) GetHashType() (Hashtype, error)
- func (d *Descriptor) GetMessageType() (Messagetype, error)
- func (d *Descriptor) GetName() string
- func (d *Descriptor) GetPartType() (Parttype, error)
- func (d *Descriptor) GetReadSeeker(fimg *FileImage) io.ReadSeekerdeprecated
- func (d *Descriptor) GetReader(fimg *FileImage) io.Reader
- func (d *Descriptor) SetExtra(extra []byte)
- func (d *Descriptor) SetName(name string)
- type DescriptorInput
- type Envvar
- type FileImage
- func (fimg *FileImage) AddObject(input DescriptorInput) error
- func (fimg *FileImage) DeleteObject(id uint32, flags int) error
- func (fimg *FileImage) FmtDescrInfo(id uint32) stringdeprecated
- func (fimg *FileImage) FmtDescrList() stringdeprecated
- func (fimg *FileImage) FmtHeader() stringdeprecated
- func (fimg *FileImage) GetFromDescr(descr Descriptor) ([]*Descriptor, []int, error)
- func (fimg *FileImage) GetFromDescrID(id uint32) (*Descriptor, int, error)
- func (fimg *FileImage) GetFromLinkedDescr(id uint32) ([]*Descriptor, []int, error)
- func (fimg *FileImage) GetHeader() *Header
- func (fimg *FileImage) GetLinkedDescrsByType(id uint32, dataType Datatype) ([]*Descriptor, []int, error)
- func (fimg *FileImage) GetPartFromGroup(groupid uint32) ([]*Descriptor, []int, error)
- func (fimg *FileImage) GetPartPrimSys() (*Descriptor, int, error)
- func (fimg *FileImage) GetSignFromGroup(groupid uint32) ([]*Descriptor, []int, error)
- func (fimg *FileImage) SetPrimPart(id uint32) error
- func (fimg *FileImage) UnloadContainer() (err error)
- type Formattype
- type Fstype
- type Generic
- type GenericJSON
- type Hashtype
- type Header
- type Labels
- type Messagetype
- type Partition
- type Parttype
- type ReadWriter
- type Signature
Constants ¶
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.
const ( DelZero = iota + 1 // zero the data object bytes DelCompact // free the space used by data object )
SIF data object deletion strategies.
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 ¶
var ErrMultValues = errors.New("lookup would return more than one match")
ErrMultValues is the code for when search key is not unique.
var ErrNotFound = errors.New("no match found")
ErrNotFound is the code for when no search key is not found.
Functions ¶
func GetSIFArch ¶
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.2.2
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.
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.2.2
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.2.2
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.2.2
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.5.1
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.2.2
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 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 ¶
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 ¶
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 ¶
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 (*FileImage) FmtDescrList
deprecated
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) GetLinkedDescrsByType ¶ added in v1.2.2
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.2.2
SetPrimPart sets the specified system partition to be the primary one.
func (*FileImage) UnloadContainer ¶
UnloadContainer closes the SIF container file and free associated resources if needed.
type Formattype ¶ added in v1.2.2
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.5.1
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.
type Generic ¶ added in v1.2.2
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.
List of supported hash functions.
type Header ¶
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 Messagetype ¶ added in v1.2.2
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.5.1
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).
type ReadWriter ¶ added in v1.2.2
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.