Package Format

Introduction

The application manager uses a very simple package format: a standard UNIX gzip-compressed TAR archive. Metadata is embedded as normal files, but using the reserved name prefix --PACKAGE-. Even though USTAR tar archives support a lot of features, the application manager only supports standard files and directories with relative paths only (using ../ in a path is not allowed). Modes, except the owner's x bit, are ignored.

This makes it very easy to write custom packagers as well as custom app-store server backends, since TAR archive handling is available as a utility library in any programming language.

These are the important files in a package:

In short, here is what is NOT allowed inside a package:

• You are not allowed to have file names that start with --PACKAGE-
• You are not allowed to have absolute paths
• You are not allowed to have ../ in relative paths
• You are not allowed to have sym-links, hard-links, device files, sockets, etc.
• File modes except the owner's x bit are ignored.

The Checksum Algorithm

All of package data, as well as important meta-data is protected by a SHA256 digest. This checksum has two purposes: it protects against transmission errors, and the package signing is done by encrypting this checksum.

The algorithm is selected by the formatVersion field of the --PACKAGE-HEADER--: version 3 uses the algorithm described in the first section below, versions 1 and 2 use the legacy algorithm described in the second section.

The generated digest is put into the --PACKAGE-FOOTER-- as a 32-byte hex-encoded string.

Format version 3

The digest input is a single byte stream that is unambiguous to parse from left to right: every variable-length field is preceded by its length, and every other field has a fixed width. Different packages therefore can never produce the same byte stream. All values are written with QDataStream, using the stream version Qt_6_7 (big endian). The stream consists of the following parts, in this order:

stream  := TAG header entry*
TAG     := "AM" 0x00 "PKG3" 0x00
header  := 'H' QVariant(QVariantMap)
entry   := 'E' type QString(path) quint64(size) ('X' bytes(name) bytes(value))* [ 'C' <size bytes> ]
type    := 'F' | 'D'
bytes   := quint32(length) <length bytes>

• TAG is the 8 bytes 41 4D 00 50 4B 47 33 00. It is the first thing hashed.
• 'H', 'E', 'X', 'C' and type are single quint8 values.
• header is a QVariantMap with the following four entries: formatVersion (the integer 3), packageId (string), extendedAttributes (bool; false if absent in the header) and extraSigned (map; empty if absent in the header). All other header fields (e.g. extra and diskSpaceUsed) are not part of the digest.
• There is one entry for every file and directory, in the order they appear in the archive (excluding the --PACKAGE-* meta-data files). type is 'F' for files and 'D' for directories, path is the path (normalized to Unicode normalization form C, without a trailing slash) and size is the size of the file content in bytes (always 0 for directories).
• If extended attributes are included in the package (extendedAttributes in the header), then every attribute of the entry is added as 'X', name and value in the order they appear in the archive.
• The 'C' section, containing exactly size bytes of the file's content, is only present for files.

Format versions 1 and 2 (legacy)

• If the extraSigned field is present in the header, it is converted to a QVariantMap and serialized with QDataStream (using the Qt 6.7 data stream version), and the result is added to the digest.
• For every file that is not a --PACKAGE-* meta-data file, the extended attributes (if included in the package) are added to the digest, each as the UTF-8 encoded string "XATTR/<name>/<value>". Then the complete content is added to the digest. Afterwards the following UTF-8 encoded string is also added to the digest: "F/<file size in bytes>/<file path>" (e.g. the file foo/test.qml with a size of 250 bytes would generate F/250/foo/test.qml)
• For every directory, the extended attributes (if included in the package) and then the following UTF-8 encoded string is added to the digest: "D/0/<directory path>" (e.g. the directory foo/images would generate D/0/foo/images)

The Signing Algorithm

The package format currently supports two signatures: a developer signature (generated by the developer before uploading to an appstore-server) and a store signature (generated by the appstore-server before the client actually downloads a package).

Both signatures are calculated the same way and are appended to the package's meta-data the same way: The binary digest is used as an input to create a detached PKCS7 signature. This PKCS7 signature is then BASE64 encoded and stored in --PACKAGE-FOOTER-- - either in the developerSignature or storeSignature field.

There is also a separate page documenting the required Public Key Infrastructure.

If you want to implement this signing algorithm yourself, then please look at these four existing implementations:

• C++ OpenSSL based in src/crypto-lib/signature_openssl.cpp
• C++ WinCrypt based in src/crypto-lib/signature_win.cpp (Windows only)
• C++ SecurityFramework based in src/crypto-lib/signature_macos.cpp (macOS only)
• Python m2crypt based in the appstore-server reference implementation.

The Header and Footer file format

The fields within the --PACKAGE-FOOTER-- and --PACKAGE-HEADER-- file headers (first YAML document) are as follows:

The fields within the --PACKAGE-FOOTER-- and --PACKAGE-HEADER-- data (second YAML document) are as follows:

Example Package

This is an example of a minimal QML application package. The actual package can be created by tar'ing all these files up with

tar cvzf qmlapp.ampkg ./--PACKAGE-HEADER-- info.yaml icon.png main.qml ./--PACKAGE-FOOTER--

%YAML 1.1
---
formatType: am-package-header
formatVersion: 2
---
packageId: com.pelagicore.minimal
diskSpaceUsed: 1000

%YAML 1.1
---
formatType: am-package
formatVersion: 1
---
id: 'com.pelagicore.minimal'
icon: 'icon.png'
name:
  en: 'Minimal App'
applications:
- id: com.pelagicore.minimalapp
  code: 'main.qml'
  runtime: 'qml'

%YAML 1.1
---
formatType: am-package-footer
formatVersion: 2
---
# SHA256 digest in 32 char hex representation
digest: '9df5635bb50e93846954c6377468c07835119e2835475ec90b3e9a9f7261cf27'