feat: Integración de Siguldry PKCS#11 y spooler de firmas
* Implementación del rol de Ansible 'siguldry' para CentOS Stream 10 * Migración del plugin de firmas de Koji Hub a un spooler asíncrono * Modificación de roles para utilizar empaquetamiento RPM nativo de siguldry-pkcs11 * Documentación de decisiones (ADRs) y roadmap en docs/technical/ * Limpieza de binarios locales pesados de PKCS#11 en Ansible Co-developed-by: Gemini AI <renich+gemini@woralelandia.com> Signed-off-by: Rénich Bon Ćirić <renich@woralelandia.com>
This commit is contained in:
parent
d1203ba555
commit
89d6f66be8
GPG key ID:
AB2A9F49384FE324
32 changed files with 1453 additions and 321 deletions
106
docs/technical/reference/siguldry_pkcs11.rst
Normal file
106
docs/technical/reference/siguldry_pkcs11.rst
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
============================
|
||||
Siguldry PKCS#11 Integration
|
||||
============================
|
||||
|
||||
Context and Overview
|
||||
--------------------
|
||||
|
||||
Siguldry is a Rust-based, modern replacement for the legacy Sigul software signing service, designed to manage and isolate cryptographic keys. In CentOS Stream 10 (EL10) / EPEL 10 environments, the legacy python-based Sigul client is blocked due to compilation issues with the ``python-nss`` dependency. Siguldry resolves this by utilizing a modern Rust architecture, providing a PKCS#11 dynamic module (``libsiguldry_pkcs11.so``) to integrate with client-side signing utilities like ``rpmsign`` and Sequoia PGP.
|
||||
|
||||
This document outlines the architecture, configuration files, systemd credentials, and RPM macro configurations required to sign RPM packages using keys held securely on a Siguldry server.
|
||||
|
||||
Siguldry Architecture and Components
|
||||
------------------------------------
|
||||
|
||||
The Siguldry architecture separates components into three distinct services:
|
||||
|
||||
* **Siguldry Server**: The secure backend node housing GPG signing keys (encrypted at rest). It does not listen on any network interfaces directly; instead, it establishes outgoing TLS connections to the bridge.
|
||||
* **Siguldry Bridge**: The intermediary daemon acting as a secure proxy. It manages mutual TLS (mTLS) authenticated connections from both the server and client components, ferrying traffic between them.
|
||||
* **Siguldry Client**: The client application (or its PKCS#11 module) that requests signatures from the bridge. The PKCS#11 module (``libsiguldry_pkcs11.so``) allows PKCS#11-compatible tools to leverage keys on the server.
|
||||
|
||||
Configuration Files
|
||||
-------------------
|
||||
|
||||
Client-side signing setups require configuration of the connection settings and authentication backends:
|
||||
|
||||
1. **Client Configuration (``/etc/siguldry/client.toml``)**
|
||||
Defines the connection parameters to reach the Siguldry Bridge, including:
|
||||
* The host and port of the bridge.
|
||||
* Paths to the client TLS certificate, private key, and the CA certificate used for mTLS authentication.
|
||||
* The default key name to be used for signing requests.
|
||||
|
||||
2. **GnuPG Smartcard Daemon Override (``~/.gnupg/gpg-agent.conf``)**
|
||||
If using the GnuPG backend for signing, the agent must load ``gnupg-pkcs11-scd`` instead of the standard ``scdaemon``:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
scdaemon-program /usr/bin/gnupg-pkcs11-scd
|
||||
|
||||
3. **GnuPG PKCS#11 Daemon Configuration (``~/.gnupg/gnupg-pkcs11-scd.conf``)**
|
||||
Defines the PKCS#11 provider details to load the Siguldry module:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
providers siguldry
|
||||
provider-siguldry-library /usr/lib64/libsiguldry_pkcs11.so
|
||||
|
||||
Environment Variables and Credentials
|
||||
-------------------------------------
|
||||
|
||||
Siguldry leverages the modern systemd credentials mechanism to securely pass sensitive configuration files and passphrases into its services at runtime.
|
||||
|
||||
* **``CREDENTIALS_DIRECTORY``**
|
||||
An environment variable pointing to the system-managed directory containing decrypted credentials. In manual testing or non-systemd wrappers, this environment variable can be set manually.
|
||||
|
||||
* **Decrypted Credentials Files**
|
||||
Under the credentials directory, the following file targets are read by Siguldry:
|
||||
* ``sigul-client-config``: Contains the TOML configuration payload matching client connection configurations.
|
||||
* ``sigul-signing-key-passphrase``: Contains the plaintext passphrase used to unlock the GPG keys stored on the server.
|
||||
|
||||
* **PKCS#11 Module Environment Variables**
|
||||
When using Sequoia PGP or related wrappers, specify the location of the PKCS#11 driver:
|
||||
* **``PKCS11_MODULE_PATH``**
|
||||
Standard environment variable pointing to the module.
|
||||
* **``SQ_PKCS11_MODULE``**
|
||||
Sequoia-specific fallback module path variable.
|
||||
|
||||
*Example:*
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export PKCS11_MODULE_PATH=/usr/lib64/libsiguldry_pkcs11.so
|
||||
|
||||
RPM Macro Configuration for rpmsign
|
||||
-----------------------------------
|
||||
|
||||
RPM signing backends have transitioned to be implementation-agnostic in modern RPM versions (6.0+). The legacy `%__gpg_sign_cmd` macro is deprecated and ignored. Instead, implementation-independent macros must be used.
|
||||
|
||||
Sequoia PGP Backend (EL10 Default)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
CentOS Stream 10 uses Sequoia PGP (via ``rpm-sequoia``) as the default OpenPGP engine. Configure the signing macros in ``~/.config/rpm/macros``:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
%_openpgp_sign sq
|
||||
%_openpgp_sign_id <YOUR_KEY_FINGERPRINT>
|
||||
|
||||
When running ``rpmsign --addsign``, the Sequoia engine interacts with the keystore daemon (``sequoia-keystore-server``) which accesses the Siguldry PKCS#11 module loaded via ``PKCS11_MODULE_PATH``.
|
||||
|
||||
GnuPG Backend with gnupg-pkcs11-scd
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To explicitly enforce the traditional GnuPG engine, configure ``~/.config/rpm/macros``:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
%_openpgp_sign gpg
|
||||
%_openpgp_sign_id <YOUR_GPG_KEY_ID>
|
||||
|
||||
Ensure the ``%__gpg`` macro resolves to the GnuPG binary:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
%__gpg /usr/bin/gpg
|
||||
|
||||
During execution, ``gpg-agent`` will delegate token operations to ``gnupg-pkcs11-scd``, which will sign using ``libsiguldry_pkcs11.so``.
|
||||
105
docs/technical/reference/svg_conversion.rst
Normal file
105
docs/technical/reference/svg_conversion.rst
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
==================================
|
||||
SVG to PNG Conversion on EL10/CS10
|
||||
==================================
|
||||
|
||||
Context and Tooling Selection
|
||||
-----------------------------
|
||||
|
||||
Personalizing Koji Web branding for MxOS requires converting corporate vector assets (specifically ``mxos.svg`` and ``mxos-reducido.svg``) into high-resolution PNG format (e.g. to be placed in ``images/koji.png`` within the custom theme).
|
||||
|
||||
Because enterprise servers require lightweight and reliable packages, CentOS Stream 10 (EL10) / RHEL 10 AppStream repositories provide native utilities for graphic conversion. Additional modern utilities can be pulled from EPEL 10 or installed via the Python ecosystem.
|
||||
|
||||
Conversion Tools and Usage
|
||||
--------------------------
|
||||
|
||||
Three primary methods are available on CentOS Stream 10 to perform SVG to PNG conversion:
|
||||
|
||||
rsvg-convert (librsvg2-tools)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the recommended, native tool for server environments. It is extremely lightweight, fast, and does not require a graphical display server (X11/Wayland).
|
||||
|
||||
* **Package installation**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install librsvg2-tools
|
||||
|
||||
* **Command usage**:
|
||||
To perform a simple conversion, use the output flag (``-o``):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rsvg-convert -o koji.png mxos.svg
|
||||
|
||||
* **Sizing and aspect ratio preservation**:
|
||||
Specify target dimensions directly. Use the ``--keep-aspect-ratio`` flag to prevent stretching:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rsvg-convert -w 250 --keep-aspect-ratio -o koji.png mxos.svg
|
||||
|
||||
Inkscape CLI
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Inkscape is a powerful editor, but is heavier than ``rsvg-convert``. It is useful if complex SVG features (like certain embedded filters or text styling) do not render correctly in ``rsvg-convert``.
|
||||
|
||||
* **Package installation**:
|
||||
Depending on EPEL 10 availability, install via DNF or use Flatpak as an isolated container:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install inkscape
|
||||
|
||||
* **Command usage**:
|
||||
The modern Inkscape command-line structure uses the ``-o`` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
inkscape -o koji.png mxos.svg
|
||||
|
||||
* **Sizing**:
|
||||
Resize the export using the ``-w`` (width) or ``-h`` (height) options:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
inkscape -w 250 -o koji.png mxos.svg
|
||||
|
||||
CairoSVG (Python Library)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
CairoSVG is a Python-based SVG-to-PDF/PNG converter. It is not packaged as a native RPM in base EL10 repositories, but is useful for scripted configurations.
|
||||
|
||||
* **Installation**:
|
||||
Install using Python's package manager within a virtual environment or on the user-level path:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip3 install --user cairosvg
|
||||
|
||||
* **Command usage**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cairosvg mxos.svg -o koji.png
|
||||
|
||||
* **Python Code integration**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import cairosvg
|
||||
cairosvg.svg2png(url='mxos.svg', write_to='koji.png', output_width=250)
|
||||
|
||||
Application for Koji Web Branding
|
||||
---------------------------------
|
||||
|
||||
To personalize the Koji Web theme for MxOS:
|
||||
|
||||
1. Convert the logo vector to the required logo size (standard Koji logos are usually around 100-250px wide):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rsvg-convert -w 250 --keep-aspect-ratio -o koji.png mxos.svg
|
||||
rsvg-convert -w 64 --keep-aspect-ratio -o koji-reducido.png mxos-reducido.svg
|
||||
|
||||
2. Copy the resulting PNG assets into the custom Koji Web static theme directory (e.g. ``/usr/share/koji-web/static/themes/mxos/images/koji.png``).
|
||||
Loading…
Reference in a new issue