apk-v2(5)

# NAME

*apk v2* - overview of apk v2 format

# DESCRIPTION

A v2 .apk file contains a single package's contents, some metadata, and
some signatures. The .apk file contains three concatenated gzip streams,
which together form a single tar archive. The tar archive contains three
sections: the signatures, the control section, and the data section.

# THE SIGNATURES

The signatures are a sequence of files whose names start with ".SIGN.",
which must come before any other data in the tarball. These filenames
look like:

	*.SIGN.<algorithm>.<keyid>*

where <algorithm> must be one of *DSA*, *RSA*, *RSA256*, and *RSA512*
and <keyid> must be the name of the key's file in /etc/apk/keys (see
*apk-keys*(5)).

The signature can be computed over either the metadata (if the metadata
contains a data hash for the data), or over the metadata and data
together (if the metadata contains no data hash).

A single signature from a trusted key is sufficient, so an apk can be
signed by multiple different keys if need be, as long as clients trust
at least one of them.

# THE CONTROL SECTION

In a v2 apk file, the package metadata is stored in a single file called
.PKGINFO. That file uses a key-value format, in which keys and values
are separated by " = " and lines beginning with "#" are comments. There
are many allowed keys and there is no centralized list of known keys;
the source of *abuild*(1) is the best reference.

One key is important for understanding the v2 format because it affects
the interpretation of the signature: if there is a "datahash" key in
PKGINFO, its value is the sha256 hash of the data part of the apk.
Packages are supposed to have a datahash, but indexes do not.

The control section is also where pre/post hook scripts for install, deinstall,
and upgrade live, and where triggers live.

# THE DATA SECTION

The data section is simply a tar archive of the package's contents, as
produced by the build process. These files are postprocessed by
*abuild-tar*(1) and use pax extended headers to include per-file
checksums in a header named APK-TOOLS.checksum.*<hash>*.

# EXAMPLE

As an example, the v2 apk for *scdoc*(1) itself contains these files in
this order:

	.SIGN.RSA.alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub
	.PKGINFO
	usr/
	usr/bin/
	usr/bin/scdoc
	usr/share/
	usr/share/pkgconfig/
	usr/share/pkgconfig/scdoc.pc

Since v2 apk files are simply tarballs (broken into multiple gzip
streams), they can be inspected and unpacked with *tar*(1), although
care must be taken when changing them not to reorder the sections or
invalidate the signature. It is better to use *abuild*(1) to modify
them. If you want to take them apart into their constituent gzip
streams, you can use *abuild-gzsplit*(1).

# NOTES

Only the "RSA" (meaning RSA + SHA1) signature scheme is currently used
by *abuild*(1).

# SEE ALSO

*abuild*(1), *apk*(1), *apk-v3*(5)