xar

README

This package implements reading and writing of XAR archives.

Documentation

Overview

Package xar provides for reading and writing XAR archives.

Index

• Variables
• type File
  • func (f *File) Open() (rc io.ReadCloser, err error)
  • func (f *File) OpenRaw() (rc io.ReadCloser, err error)
  • func (f *File) VerifyChecksum() bool
• type FileChecksum
• type FileChecksumKind
• type FileInfo
• type FileType
• type Reader
  • func NewReader(r ReaderAtCloser, size int64) (*Reader, error)
  • func OpenReader(name string) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) HasSignature() bool
  • func (r *Reader) ValidSignature() bool
  • func (r *Reader) VerifyApplePkg() error
• type ReaderAtCloser

Variables

var (
	ErrBadMagic      = errors.New("xar: bad magic")
	ErrBadVersion    = errors.New("xar: bad version")
	ErrBadHeaderSize = errors.New("xar: bad header size")

	ErrNoTOCChecksum        = errors.New("xar: no TOC checksum info in TOC")
	ErrChecksumUnsupported  = errors.New("xar: unsupported checksum type")
	ErrChecksumTypeMismatch = errors.New("xar: header and toc checksum type mismatch")
	ErrChecksumMismatch     = errors.New("xar: checksum mismatch")

	ErrNoCertificates             = errors.New("xar: no certificates stored in xar")
	ErrCertificateTypeMismatch    = errors.New("xar: certificate type and public key type mismatch")
	ErrCertificateTypeUnsupported = errors.New("xar: unsupported certificate type")

	ErrFileEncodingUnsupported = errors.New("xar: unsupported file encoding")
)

Types

type File

type File struct {
	Type FileType
	Info FileInfo
	Id   uint64
	Name string

	EncodingMimetype   string
	CompressedChecksum FileChecksum
	ExtractedChecksum  FileChecksum
	// The size of the archived file (the size of the file after decompressing)
	Size int64
	// contains filtered or unexported fields
}

func (*File) Open

func (f *File) Open() (rc io.ReadCloser, err error)

Open returns a ReadCloser that provides access to the file's uncompressed content.

func (*File) OpenRaw

func (f *File) OpenRaw() (rc io.ReadCloser, err error)

OpenRaw returns a ReadCloser that provides access to the file's raw content. The encoding of the raw content is specified in the File's EncodingMimetype field.

func (*File) VerifyChecksum

func (f *File) VerifyChecksum() bool

Verify that the compressed content of the File in the archive matches the stored checksum.

type FileChecksum

type FileChecksum struct {
	Kind FileChecksumKind
	Sum  []byte
}

type FileChecksumKind

type FileChecksumKind int

const (
	FileChecksumKindSHA1 FileChecksumKind = iota
	FileChecksumKindMD5
)

type FileInfo

type FileInfo struct {
	DeviceNo uint64
	Mode     uint32
	Inode    uint64
	Uid      int
	User     string
	Gid      int
	Group    string
	Atime    int64
	Mtime    int64
	Ctime    int64
}

type FileType

type FileType int

const (
	FileTypeFile FileType = iota
	FileTypeDirectory
	FileTypeSymlink
	FileTypeFifo
	FileTypeCharDevice
	FileTypeBlockDevice
	FileTypeSocket
)

type Reader

type Reader struct {
	File map[uint64]*File

	ChecksumHash crypto.Hash
	Checksum     []byte

	SignatureCreationTime int64

	Certificates   []*x509.Certificate
	Signature      []byte
	SignatureError error

	XCertificates   []*x509.Certificate
	XSignature      []byte
	XSignatureError error
	// contains filtered or unexported fields
}

func NewReader

func NewReader(r ReaderAtCloser, size int64) (*Reader, error)

NewReader returns a new reader reading from r, which is assumed to have the given size in bytes.

func OpenReader

func OpenReader(name string) (*Reader, error)

OpenReader will open the XAR file specified by name and return a Reader.

func (*Reader) Close

func (r *Reader) Close() error

Close closes the opened XAR file.

func (*Reader) HasSignature

func (r *Reader) HasSignature() bool

This is a convenience method that returns true if the opened XAR archive has a signature. Internally, it checks whether the SignatureCreationTime field of the Reader is > 0.

func (*Reader) ValidSignature

func (r *Reader) ValidSignature() bool

This is a convenience method that returns true of the signature if the opened XAR archive was successfully verified.

For a signature to be valid, it must have been signed by the leaf certificate in the certificate chain of the archive.

If there is more than one certificate in the chain, each certificate must come before the one that has issued it. This is verified by checking whether the signature of each certificate can be verified against the public key of the certificate following it.

The Reader does not do anything to check whether the leaf certificate and/or any intermediate certificates are trusted. It is up to users of this package to determine whether they wish to trust a given certificate chain. If an archive has a signature, the certificate chain of the archive can be accessed through the Certificates field of the Reader.

Internally, this method checks whether the SignatureError field is non-nil, and whether the SignatureCreationTime is > 0.

If the signature is not valid, and the XAR file has a signature, the SignatureError field of the Reader can be used to determine a possible cause.

func (*Reader) VerifyApplePkg

func (r *Reader) VerifyApplePkg() error

VerifyApplePkg verifies the xar like Apple's `pkgutil --check-signature`. Particularly, Apple uses a custom PKCS7 signature (x-signature element in the xar TOC) to sign and verify xar (pkg) files. VerifyApplePkg follows pkgutil's verification method: if x-signature is present, it will be used to verify the pkg (even if the standard xar signature is invalid). If x-signature is not present, verify the pkg like a standard xar (using signature element in the xar TOC).

type ReaderAtCloser

type ReaderAtCloser interface {
	io.ReaderAt
	io.Closer
}