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 actual calculation of this checksum is done as follows:

• For every file that is not a --PACKAGE-* meta-data file, 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 following UTF-8 encoded string is added to the digst: "D/0/<directory path>" (e.g. the directory foo/images would generate D/0/foo/images)

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

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.

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.appkg ./--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'