Apkindex format

From Alpine Linux
Revision as of 03:52, 23 December 2017 by Mcrute (talk | contribs)
Jump to navigation Jump to search

The APKINDEX.tar.gz format

From apk-tools-2.0_pre15 there was added support for package signing. The caused the index format to chage, as it needs to contain a signature for the repository. This document explains how the new index works and how it is created. This is intended to be a reference for abuild developers. Other developers should use the tools provided from abuild.

See the abuild source and abuild-sign source for more details about how this indexes and signatures are constructed behind the scenes.

Creating APKINDEX.tar.gz

The APKINDEX.tar.gz is created by concatenating 2 other tar.gz files, signature.tar.gz and APKINDEX.unsigned.tar.gz.

cat signature.tar.gz APKINDEX.unsigned.tar.gz > APKINDEX.tar.gz

Creating signature.tar.gz Manually

First we create a signature file for APKINDEX.unsigned.tar.gz, using our private key.

openssl dgst -sha1 -sign privatekeyfile -out .SIGN.RSA.nameofpublickey APKINDEX.unsigned.tar.gz

Then we put this in a tar file, without the end-of-tar record at the end of the file. This is because we will concatenate this tar archive with the index tar archive.

tar -c .SIGN.RSA.nameofpublickey | abuild-tar --cut | gzip -9 > signature.tar.gz

The name of public key should be the email address of the developer.

Creating APKINDEX.unsigned.tar.gz

The APKINDEX.unsigned.tar.gz is an old 1.9 style index file in a tar archive. This is created with:

apk index -o APKINDEX.unsigned.tar.gz *.apk

Signing APKINDEX.unsigned.tar.gz

Without a signature apk-tools will not trust the index file and will require the --allow-untrusted flag for all operations involving the index. To sign an index requires a key, if you don't already have a key the easiest way to generate one is to use the abuild-keygen command like so:

apk add abuild abuild-keygen -a -i

It will prompt you for a filename to save the keypair. Enter file in which to save the key. The standard practice for naming the key is to use your email address or the email address of a maintainer's mailing list as a prefix for the filename of the keypair followed by an alphanumeric suffix, which is generated by the abuild-keygen tool.

For this example, we will use alpine-devel@example.com-5629d7e6.rsa which will create the alpine-devel@example.com-5629d7e6.rsa and alpine-devel@example.com-5629d7e6.rsa.pub keypair and copy the public key to /etc/apk/keys/. Make sure you keep a copy of your private key somewhere safe because you will need it if you add any packages to the repo in the future since you will need to re-sign the updated index.

Finally, sign the index. Ensure that you provide the full path to the private key or abuild-sign will not be able to find it.

abuild-sign -k ~/alpine-devel@example.com-5629d7e6.rsa /repo/x86_64/APKINDEX.tar.gz

For hosts to trust this index ensure that the public component of the key you generated exists in their /etc/apk/keys directory.