86 lines
4.3 KiB
ReStructuredText
86 lines
4.3 KiB
ReStructuredText
======
|
|
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>`_).
|