ansible-koji/docs/technical/reference/siguldry_pkcs11.rst

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:

   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:

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

  System Message: ERROR/3 (<stdin>, line 63)

  Unexpected indentation.

  Standard environment variable pointing to the module.

  System Message: WARNING/2 (<stdin>, line 64)

  Block quote ends without a blank line; unexpected unindent.

  • ``SQ_PKCS11_MODULE`` Sequoia-specific fallback module path variable.

  Example:

  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:

%_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:

%_openpgp_sign gpg
%_openpgp_sign_id <YOUR_GPG_KEY_ID>

Ensure the %__gpg macro resolves to the GnuPG binary:

%__gpg /usr/bin/gpg

During execution, gpg-agent will delegate token operations to gnupg-pkcs11-scd, which will sign using libsiguldry_pkcs11.so.