======
releng
======

This repository is used to create release artifacts for Arch Linux.

Artifacts
=========

Releases of this repository provide artifacts, that are in either of the following two categories: *build artifacts* and
*promotion artifacts*. For `archweb <https://github.com/archlinux/archweb/>`_ only releases with *both* artifact types
are considered.

Build Artifacts
---------------

These artifacts are the output of the build script in this repository (e.g. by running `make` as root, locally). It
gathers artifacts by:

- running ``mkarchiso`` (`archiso <https://gitlab.archlinux.org/archlinux/archiso>`_) using the `releng profile
  <https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng>`_ in all available build modes
  (``bootstrap``, ``iso``, ``netboot``)
- copying relevant binaries from the `ipxe package <https://archlinux.org/packages/community/x86_64/ipxe/>`_
- creating a codesigned iPXE target script (see `#9 <https://gitlab.archlinux.org/archlinux/releng/-/issues/9>`_)
- creating zsync files for large artifacts
- creating checksums

The artifacts are assembled in a directory structure, that reflects the artifact type (``bootstrap``, ``ipxe``, ``iso``,
``netboot``) per-release (i.e. ``<type>/<type>-<version>``).

Promotion Artifacts
-------------------

These artifacts are added to a release by a developer, after it has been created to "promote" the release to become one
that is used on the mirrors. Promotion artifacts encompass:

- detached PGP signatures for the ``iso`` and ``bootstrap`` build artifacts (see `#1
  <https://gitlab.archlinux.org/archlinux/releng/-/issues/1>`_)
- base64-encoded torrent files for the ``iso`` and ``bootstrap`` build artifacts (which include the detached PGP
  signatures) (see `#5 <https://gitlab.archlinux.org/archlinux/releng/-/issues/5>`_)
- a JSON file with required metadata for the release (see `#3
  <https://gitlab.archlinux.org/archlinux/releng/-/issues/3>`_)

Code Signing
============

``mkarchiso`` (`archiso <https://gitlab.archlinux.org/archlinux/archiso>`_) offers the export of server-side artifacts,
that allow for `iPXE <https://ipxe.org>`_ to use them. The artifacts can optionally be codesigned which can establish a
trust path between a client and the server-side files.

How to establish a code signing authority is explained in the `iPXE upstream documentation <https://ipxe.org/crypto>`_.
The server-side artifacts are signed using a codesigning certificate and key pair. The codesigning certificate is then
embedded in the iPXE binary and is used during boot to validate the codesigning signature when downloading the file.

Additionally, CA certificates are embedded in the iPXE binary to validate the TLS connection over which the data is
transmitted.

.. code:: sh

           iPXE binary                                   Server
   xxxxxxxxxxxxxxxxxxxxxxxxxxx               xxxxxxxxxxxxxxxxxxxxxxxxxxxx
   x       CA cert(s)        x    =====>     x Transport Layer Security x
   xxxxxxxxxxxxxxxxxxxxxxxxxxx               xxxxxxxxxxxxxxxxxxxxxxxxxxxx
   x Codesigning Certificate x    =====>     x   Codesigning Signature  x
   xxxxxxxxxxxxxxxxxxxxxxxxxxx               xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create a new Code Signing Key Pair
----------------------------------

1. Create a new code signing key pair using ``codesigning/create_codesigning_key_pair.sh``.
2. Embed the codesigning certificate in the binaries generated by `the ipxe
   package <https://archlinux.org/packages/community/x86_64/ipxe/>`_ and release a new version of the package.
3. Add the codesigning certificate and key as `variables of type File
   <https://docs.gitlab.com/ee/ci/variables/#project-cicd-variables>`_ to this repository
   (``SECRET_CODESIGNING_CERT_FILE`` and ``SECRET_CODESIGNING_KEY_FILE``, respectively), so that they can be accessed
   during build.
4. Build a new release with the respective artifacts being signed with the new codesigning key and make sure that the
   release contains the iPXE binaries from the updated package (embedding the new codesigning certificate)
5. Once all official releases using the previous codesigning key pair have been removed, the previous codesigning
   certificate can be removed from the ipxe package.

License
=======

Releng is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).