Rénich Bon Ćirić
96c7d426e5
- Configure mxos-packages DNF repository to allow siguldry-pkcs11 package resolution. - Verify if rsvg-convert exists on localhost to bypass become/dnf installation check when passwordless sudo is unavailable. - Align PKCS#11 module path to /usr/lib64/pkcs11/libsiguldry_pkcs11.so in spooler and docs. Co-developed-by: Gemini AI <renich+gemini@woralelandia.com> Signed-off-by: Rénich Bon Ćirić <renich@woralelandia.com>
106 lines
5.1 KiB
ReStructuredText
106 lines
5.1 KiB
ReStructuredText
============================
|
|
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/pkcs11/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/pkcs11/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``.
|