smgw-pki/docs/development.md

Development Setup

Lokales Setup für die Lab-Umgebung. Ziel: Tool gegen einen SoftHSM2-Container und eine Test-Sub-CA betreiben, ohne echte SMGW-Hardware.

Voraussetzungen

• Rust ≥ 1.80 (rustup)
• Docker / Podman
• xmlsec1 CLI (für die XML-DSig in iconfig.sig)
• OpenSSL CLI (für Testzertifikate)

Auf Debian/Ubuntu:

sudo apt install xmlsec1 libxmlsec1-dev openssl pkg-config

Build & Run

cargo check
cargo run

Logs via RUST_LOG:

RUST_LOG=smgw_pki_automator=debug,info cargo run

SoftHSMv2 als Container

SoftHSMv2 per Docker laufen lassen. Beispiel (Pseudo-Compose, anpassen an euer Setup):

services:
  softhsm:
    image: ghcr.io/example/softhsm2:latest
    volumes:
      - ./tokens:/var/lib/softhsm/tokens
    environment:
      SOFTHSM2_CONF: /etc/softhsm2.conf

Token einmalig initialisieren:

softhsm2-util --init-token --slot 0 \
  --label "smgw-lab" \
  --pin 1234 --so-pin 5678

Im app.rs-Boot-Pfad wird der Adapter konstruiert mit:

SoftHsmAdapter::new("/usr/lib/softhsm/libsofthsm2.so", "1234")

Pfad zur PKCS#11-Lib hängt vom Container/OS ab.

mTLS-Testzertifikate

Für die Kommunikation mit der Test-Sub-CA brauchen wir:

• Client-Cert (EMT) — wird im reqwest-Client als Identity geladen.
• Server-Cert der CA — wird als Trust-Root im Client geladen.
• Eigenes Server-Cert für den Axum-Callback-Endpunkt (mTLS-Server).
• CA-Trust für eingehende CA-Calls, damit das Client-Cert der CA gegen diesen Trust verifiziert werden kann.

Test-PKI mit OpenSSL aufsetzen (vereinfacht):

mkdir -p certs && cd certs

# Test-Root
openssl req -x509 -newkey rsa:4096 -days 3650 -nodes \
  -keyout test-root.key -out test-root.crt \
  -subj "/CN=smgw-lab-root"

# Client (EMT)
openssl req -newkey rsa:4096 -nodes -keyout emt.key -out emt.csr \
  -subj "/CN=emt-client"
openssl x509 -req -in emt.csr -CA test-root.crt -CAkey test-root.key \
  -CAcreateserial -out emt.crt -days 825

# Server (CA-Mock + Axum-Callback)
openssl req -newkey rsa:4096 -nodes -keyout server.key -out server.csr \
  -subj "/CN=ca.test.local"
openssl x509 -req -in server.csr -CA test-root.crt -CAkey test-root.key \
  -CAcreateserial -out server.crt -days 825

PEM-Bundle für reqwest::Identity::from_pem:

cat emt.crt emt.key > emt-bundle.pem

Datenbank

SQLite, default sqlite::memory: im Stub-Boot. Für Persistenz Pfad setzen:

DATABASE_URL=sqlite://./data/smgw.db cargo run

Migrationen (sobald angelegt) via sqlx:

cargo install sqlx-cli --no-default-features --features sqlite,rustls
sqlx migrate run

SMTP

Für lokales Testing MailHog oder Mailpit:

docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit

SmtpAdapter::new("localhost", 1025).

Test-Sub-CA

Optionen:

1. Mock-Server mit wiremock für Integrationstests — antwortet auf RequestCertificate mit ok_syntax und triggert anschließend einen HTTP-Call gegen den eigenen Callback-Endpunkt. Kein BSI-Compliance-Ersatz, aber gut für CI.
2. Echte Test-Sub-CA-Instanz (sofern verfügbar) — Adresse + Test-EMT- Zertifikate aus eurem Lab-Bestand einsetzen.

Tests

cargo test                    # Unit + In-Memory-Integration
cargo test --features it      # Integration mit SoftHSM-Container (folgt)

Konvention: Tests liegen neben dem Code (#[cfg(test)] mod tests). Adapter- Tests, die externe Dienste brauchen, hinter Cargo-Feature it gaten.

Code-Style

• cargo fmt vor jedem Commit.
• cargo clippy --all-targets -- -D warnings muss grün sein.
• Keine Result<_, String> in Produktionscode. Strukturierte Fehler via thiserror.