============================
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``.