e7d931347a
README.rst: Add documentation on iPXE code signing and how to generate a new codesigning key pair.
49 lines
2.4 KiB
ReStructuredText
49 lines
2.4 KiB
ReStructuredText
======
|
|
releng
|
|
======
|
|
|
|
This repository is used to create release artifacts for Arch Linux.
|
|
|
|
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>`_).
|