19 breaking releases
0.20.0 | Nov 29, 2024 |
---|---|
0.18.0 | Jan 17, 2024 |
0.17.0 | Nov 17, 2023 |
0.13.0 | Dec 21, 2022 |
0.2.0 | Mar 28, 2022 |
#200 in macOS and iOS APIs
21,262 downloads per month
Used in 18 crates
(via apple-codesign)
120KB
2.5K
SLoC
apple-flat-package
This crate implements an interface to Apple's flat package installer package
file format. This is the XAR-based installer package (.pkg
) format used since
macOS 10.5.
The interface is in pure Rust and doesn't require the use of Apple specific
tools or hardware to run. The functionality in this crate could be used to
reimplement Apple installer tools like pkgbuild
and productbuild
.
lib.rs
:
Apple flat packages.
Apple flat packages - often existing as .pkg
files - are an installer
file format used by macOS.
File Format
Flat packages are Apple-flavored XAR archives. XAR is a tar-like
file format consisting of file records/metadata and raw file data.
See the apple-xar
crate for more on this file format.
Flat packages come in 2 flavors: component packages and product
packages. Component packages contain a single component. Product
installers can contain multiple components as well as additional
metadata describing the installer. End-user .pkg
files are typically
product packages. Using Apple tooling, component packages are built
using pkgbuild
and product packages using productbuild
.
Components
A component defines an installable unit. Components are comprised of a set of well-known files:
Bom
A bill of materials describing the contents of the component.
PackageInfo
An XML file describing the component. See [PackageInfo] for the Rust
struct defining this file format.
Payload
A cpio archive containing files comprising the component. See the
cpio-archive
for more on this file format.
Scripts
A cpio archive containing scripts files that run as part of component
processing.
Products
A product flat package consists of 1 or more components and additional metadata.
A product flat package is identified by the presence of a Distribution
XML file in the root of the archive. See [Distribution] for the Rust type
defining this file format. See also
Apple's XML documentation.
Components within a product flat package exist in sub-directories which often
have the name *.pkg/
.
In addition, a product flat package may also have additional resource files
in the Resources/
directory.
Cryptographic Signing
Cryptographic message syntax (CMS) / RFC 5652 signatures can be embedded in the XAR archive's table of contents, which is a data structure at the beginning of the XAR defining the content within.
The cryptographic signature is over the checksum content digest, which is also captured in the XAR table of contents. This checksum effectively captures the content of all files within the XAR.
Nested Archive Formats
Flat packages contain multiple data structures that effectively enumerate lists of files. There are many layers to the onion and there is duplication of functionality to express file manifests.
- XAR archives contain a table of contents enumerating files within the XAR.
- Each component has
Payload
and/orScripts
files, which are cpio archives. These cpio archives are file manifests containing file metadata and content. - Each component may have a
Bom
, which is a binary data structure defining file metadata as well as other attributes.
There are also multiple layers that involve compression:
- The XAR table of contents is likely compressed with zlib.
- Individual files within XAR archives can be individually compressed with a compression format denoted by a MIME type.
- cpio archive files may also be compressed.
- Installed files in components may also be compressed (but this file content is treated as opaque by the flat package format).
Dependencies
~14–23MB
~414K SLoC