5f84463a34
This change adds two manpages: apk-v2(5) and apk-v3(5). These pages describe the v2 and v3 file formats respectively, as I currently understand them.
85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
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)
|