.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "apk-v2" "5" "2025-12-12"
.PP
.SH NAME
.PP
apk v2 - overview of apk v2 format
.PP
.SH DESCRIPTION
.PP
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.\&
.PP
.SH THE SIGNATURES
.PP
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:
.PP
.RS 4
\fB.\&SIGN.\&<algorithm>.\&<keyid>\fR
.PP
.RE
where <algorithm> must be one of \fBDSA\fR, \fBRSA\fR, \fBRSA256\fR, and \fBRSA512\fR
and <keyid> must be the name of the key'\&s file in /etc/apk/keys (see
\fBapk-keys\fR(5)).\&
.PP
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).\&
.PP
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.\&
.PP
.SH THE CONTROL SECTION
.PP
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 \fBabuild\fR(1) is the best reference.\&
.PP
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.\&
.PP
The control section is also where pre/post hook scripts for install, deinstall,
and upgrade live, and where triggers live.\&
.PP
.SH THE DATA SECTION
.PP
The data section is simply a tar archive of the package'\&s contents, as
produced by the build process.\& These files are postprocessed by
\fBabuild-tar\fR(1) and use pax extended headers to include per-file
checksums in a header named APK-TOOLS.\&checksum.\&\fB<hash>\fR.\&
.PP
.SH EXAMPLE
.PP
As an example, the v2 apk for \fBscdoc\fR(1) itself contains these files in
this order:
.PP
.nf
.RS 4
\&.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
.fi
.RE
.PP
Since v2 apk files are simply tarballs (broken into multiple gzip
streams), they can be inspected and unpacked with \fBtar\fR(1), although
care must be taken when changing them not to reorder the sections or
invalidate the signature.\& It is better to use \fBabuild\fR(1) to modify
them.\& If you want to take them apart into their constituent gzip
streams, you can use \fBabuild-gzsplit\fR(1).\&
.PP
.SH NOTES
.PP
Only the "RSA" (meaning RSA + SHA1) signature scheme is currently used
by \fBabuild\fR(1).\&
.PP
.SH SEE ALSO
.PP
\fBabuild\fR(1), \fBapk\fR(8), \fBapk-package\fR(5), \fBapk-v3\fR(5)