Zum Inhalt

Siegel einrichten

Ein Siegel belegt dem Empfänger eines Kalibrierscheins, dass das Dokument aus diesem Labor stammt und seit der Freigabe unverändert ist. Diese Seite beschreibt, wie ein Labor zu einem Siegel kommt, was die vier Wege dorthin unterscheidet und wie sich der Aufbau prüfen lässt.

Die Verwaltung liegt unter Administration → Siegel und verlangt die Operation seal_edit.

Die vier Wege im Vergleich

Alle vier führen zu einem Eintrag in derselben Liste. Sie unterscheiden sich darin, wo der private Schlüssel liegt und was ein Empfänger dem Siegel entnehmen kann.

Weg Schlüssel entsteht Nachweis beim Empfänger Wann
Selbst erzeugen Im Siegel-Dienst „Gültigkeit unbekannt" — belegt Unverändertheit, nicht die Herkunft Intern, Test, sofort
Von einer CA ausstellen lassen Im Siegel-Dienst, verlässt ihn nie Herkunft belegt, Aussteller sichtbar Regelfall, auch fürs Akkreditierungssiegel
Vorhandene .p12 einlesen Ausserhalb, wandert als Datei Wie das gekaufte Zertifikat hergibt Zertifikat ist schon gekauft
Fernsignatur eintragen Beim Vertrauensdiensteanbieter Einzige Konstellation für ein qualifiziertes Siegel Beschaffung läuft oder ist abgeschlossen

Ein selbstsigniertes Siegel ist kein Herkunftsnachweis

Es ist in Sekunden erzeugt und sieht in der Liste wie ein Siegel aus. Jeder PDF-Betrachter zeigt dafür „Gültigkeit unbekannt", weil niemand ausser dem Labor selbst für das Zertifikat bürgt. Für den internen Gebrauch und zum Ausprobieren richtig, für einen Schein beim Kunden nicht.

Voraussetzungen

  1. Eigener Siegel-Dienst. In der Host-.env muss SEAL_SERVICE_URL=http://calserver-seal:8091 stehen. Der abgekündigte report-runner kann keine Credentials verwalten; ohne die Zeile lehnt die Einrichtung mit genau diesem Hinweis ab. deploy.sh setzt sie bei neuen Anlagen selbst.

  2. Keystore-Passwort. PDF_SIGNING_PASSWORD schützt die Schlüsseldateien. Ohne diesen Wert kann kein Credential angelegt und keines geöffnet werden. deploy.sh erzeugt ihn, wenn die .env die Zeile noch nicht kennt.

    Gehört in den Passwort-Manager

    Ohne dieses Passwort sind vorhandene Siegel-Credentials verloren — auch aus einem Backup. Vaultwarden-Item „calServer Siegel-Keystore" je Installation.

  3. Beschreibbares Schlüsselverzeichnis — siehe Schlüsselverzeichnis. Prüfen:

    docker compose exec calserver-seal wget -qO- http://127.0.0.1:8091/ready

    Erwartet wird "provisioning":"enabled". Bei "directory-read-only" nennt das Feld provisioningDetail in derselben Antwort den Pfad und beide möglichen Gründe.

  4. Laborangaben gepflegt. Unter Administration → Berichte → Laborangaben stehen Laborname, Laborkennung (Akkreditierungsnummer), Anschrift und Kontakt. Der Einrichtungsdialog belegt den Zertifikatsinhaber daraus vor — damit Briefkopf, DCC-Export und Siegel dieselbe Identität nennen.

Firmensiegel selbst erzeugen

  1. Administration → Siegel → Siegel einrichten
  2. Weg „Selbst erzeugen" wählen
  3. Angaben prüfen — sie kommen aus den Laborangaben
  4. Einrichten

Das Credential erscheint in der Liste mit dem Nachweis „Selbstauskunft" und der Stufe PAdES-B-B. Es ist sofort verwendbar.

Akkreditierungssiegel über eine Zertifizierungsstelle

Der Weg, bei dem kein Schlüsselmaterial die Anlage verlässt. Er läuft über mehrere Tage, weil die Zertifizierungsstelle dazwischen arbeitet.

Schritt 1: Credential anlegen und Antrag holen

  1. Siegel einrichten → „Von einer Zertifizierungsstelle ausstellen lassen"
  2. Art auf Akkreditierungssiegel, Akkreditierungsnummer prüfen (z. B. D-K-12345-01-00)
  3. Einrichten — der Dialog zeigt danach den nächsten Schritt
  4. Zertifikatsantrag herunterladen (<referenz>.csr)

Wo die Akkreditierungsnummer landet

Im Zertifikat als organizationIdentifier (OID 2.5.4.97, EN 319 412-1) — dort suchen die Werkzeuge einer Begutachtung sie. In der Betreffzeile des Credentials steht sie ausgeschrieben (organizationIdentifier=D-K-12345-01-00).

Bei Siegeln, die vor Version 1.3.0 des Siegel-Dienstes entstanden sind, steht dort noch 2.5.4.97=#0c0f…. Ein Abgleich zieht die Credential-Liste nach; die Betreffzeile im Nachweis eines bereits gesiegelten Dokuments bleibt, wie sie war — ein Nachweis wird nicht nachträglich umgeschrieben.

Schritt 2: Antrag einreichen

Die .csr-Datei bei der Zertifizierungsstelle einreichen. Verlangt wird ein Zertifikat für digitale Signatur (digitalSignature, nonRepudiation); die Erweiterungen stehen im Antrag.

Schritt 3: Zertifikat einsetzen

  1. In der Liste beim Credential das Symbol Zertifikat einsetzen wählen
  2. Zertifikatsdatei hochladen (.cer, .crt, .pem, .p7b) oder den PEM-Text einfügen
  3. Zertifikat einsetzen

Der Schlüssel bleibt derselbe, der Nachweis wechselt auf „Von einer CA ausgestellt". Gehört das Zertifikat zu einem anderen Schlüssel, wird es abgewiesen.

Zwischenzertifikate mitgeben

Für die Stufe PAdES-B-LT müssen Kette und Sperrauskunft im Dokument liegen. Wenn die CA ein Bündel anbietet (Zertifikat plus Zwischenzertifikate), dieses hochladen — nicht nur das Blatt.

Das vorherige Keystore bleibt als <referenz>.p12.replaced-<zeitstempel> neben dem neuen liegen. Es wird nicht mehr als Credential geführt, aber der Schlüssel ist bei einem Fehlgriff nicht verloren.

Vorhandene Schlüsseldatei einlesen

Für ein Zertifikat, das schon gekauft ist.

  1. Siegel einrichten → „Vorhandene Schlüsseldatei einlesen"
  2. .p12/.pfx wählen, Dateipasswort eingeben
  3. Einrichten

Der Siegel-Dienst verpackt die Datei mit dem Betriebspasswort neu. Das Dateipasswort wird einmal zum Öffnen gebraucht und nirgends gespeichert.

Der einzige Weg, auf dem der Schlüssel reist

Die Datei läuft vom Browser über die API zum Siegel-Dienst. Gespeichert wird sie dort und nur dort — nicht in der Datenbank, nicht im Log. Wer auch das vermeiden will, nimmt den Zertifikatsantrag oder legt die Datei weiter von Hand ab (siehe unten).

Fernsignatur eintragen

Ein Credential bei einem Vertrauensdiensteanbieter ist die einzige Konstellation, in der ein Siegel qualifiziert sein kann: der Schlüssel liegt auf einer qualifizierten Signaturerstellungseinheit des Anbieters und nicht als Datei auf dem Server.

  1. Siegel einrichten → „Fernsignatur … eintragen"
  2. Anbieter, Protokoll, Dienst- und Token-Adresse (nur https://), Client-ID, Client-Secret, Credential-ID
  3. Das Zertifikat des Anbieters als PEM einfügen
  4. Einrichten
  5. In der Liste über das Netzwerk-Symbol prüfen, ob der Anbieter erreichbar ist

Welche Anbieter gehen

Unterstützt wird die CSC-Schnittstelle (Cloud Signature Consortium API v2) — Protokollwert csc-v2. Das ist der Standard, den die meisten europäischen Anbieter sprechen. Ein Anbieter mit eigenem Protokoll (Swisscom AIS, GlobalSign DSS) lässt sich eintragen, und die Liste sagt dann, dass für dieses Protokoll kein Adapter vorliegt — der Eintrag bleibt trotzdem sinnvoll, weil die Beschaffung Wochen dauert.

Die Zugangsdaten liegen beim Siegel-Dienst und nicht in der Datenbank.

Kein Anbieter wurde echt getestet

Der Adapter ist gegen die Spezifikation gebaut und gegen einen Testserver geprüft, der sie nachspielt. Beim ersten echten Anbieter ist mit Abweichungen zu rechnen — die Spezifikation legt weder den OAuth-Grant für unbeaufsichtigtes Siegeln fest noch eindeutig, welche OID in signAlgo gehört. Genau diese Werte sind deshalb pro Credential einstellbar (Felder OAuth-Grant und signAlgo-OID), damit eine Abweichung konfiguriert und nicht gepatcht werden muss.

Drei Felder entscheiden über den Ablauf:

Feld Vorgabe Wann ändern
OAuth-Grant client_credentials Wenn der Anbieter einen anderen Grant für automatisches Siegeln verlangt
Signatur je Vorgang freischalten an Aus nur, wenn der Anbieter ein Token ausgibt, das schon für das Credential gilt
signAlgo-OID leer (abgeleitet) Nur wenn der Anbieter die abgeleitete OID ablehnt

Die Erreichbarkeitsprüfung sagt bewusst nichts über die Gültigkeit der Zugangsdaten — das liesse sich nur durch eine Signatur feststellen, und die kostet bei den meisten Anbietern Geld. Sie schliesst den Fall aus, der in der Praxis stört: ein Container ohne Netz nach draussen.

Wenn beim Siegeln etwas schiefgeht

Beim Fernsiegel gibt es einen Ausgang, den ein lokaler Schlüssel nicht kennt: unbestimmt. Antwortet der Anbieter nicht, kann er trotzdem signiert, den Vorgang vermerkt und abgerechnet haben — nur die Antwort fehlt. calServer protokolliert das dann als „nicht feststellbar" und nicht als Fehlschlag.

Bei „nicht feststellbar" erst beim Anbieter nachsehen

Ein blinder Wiederholungslauf erzeugt sonst eine zweite Signatur über dasselbe Dokument — und eine zweite Rechnung. Ist die Meldung dagegen eindeutig („nichts wurde signiert"), kann sofort wiederholt werden.

Weiterhin möglich: Datei von Hand ablegen

Der Weg aus ADR-042 funktioniert unverändert und ist für viele Credentials auf einmal der bessere:

# Schlüsseldatei in das Verzeichnis aus SEAL_KEYSTORE_PATH legen
# (Default: ./pdf-signing, relativ zum docker/-Verzeichnis).
# Der Dateiname ohne .p12 ist die Referenz: acme-company.p12 -> acme-company
cp acme-company.p12 ./pdf-signing/

# Passwort je Credential, falls es nicht PDF_SIGNING_PASSWORD entspricht:
#   PDF_SIGNING_PASSWORD_ACME_COMPANY=...
# (Referenz gross, alles Nicht-Alphanumerische zu _; dann Container neu erstellen)

# Danach in der Oberfläche: Administration -> Siegel -> Mit Siegel-Dienst abgleichen

Eine nachgelegte Datei wirkt ohne Neustart — das Verzeichnis wird bei jedem Aufruf gelesen. Eine geänderte Umgebungsvariable braucht docker compose up -d calserver-seal.

Von Hand kopierte Dateien brauchen den richtigen Besitzer

Eine als root hereinkopierte .p12 kann der Dienst nicht öffnen — er läuft als uid 10001. Nach dem Kopieren:

docker compose exec -u 0 calserver-seal chown 10001:10001 /keystores/acme-company.p12

Schlüsselverzeichnis

Hier liegen die Schlüsseldateien. Es ist das einzige Stück Betrieb, das die Einrichtung aus der Oberfläche voraussetzt — und es gibt genau zwei Zustände, in denen sie scheitert.

Der Dienst läuft als uid 10001 (nicht als root, damit ein Einbruch in den Container nicht die Schlüssel gehören). Das Verzeichnis muss ihm gehören:

# Zustand ansehen (Pfad im Container ist immer /keystores)
docker compose exec calserver-seal wget -qO- http://127.0.0.1:8091/ready

# Besitzer korrigieren, falls provisioning nicht "enabled" meldet
docker compose exec -u 0 calserver-seal chown -R 10001:10001 /keystores

Der Besitzerwechsel wirkt sofort — kein Neustart, kein erneutes Deployment. Der nächste Versuch in der Oberfläche gelingt.

provisioning Bedeutung Behebung
enabled Alles in Ordnung —
directory-read-only Verzeichnis ist da, der Dienst darf nicht schreiben Besitzer setzen (oben), oder :ro am Keystore-Mount in docker-compose.v2.yml entfernen
read-only Der Dienst wurde ohne Schlüsselverzeichnis gestartet Mount in docker-compose.v2.yml prüfen

Zwei Gründe, ein Zustandsname

directory-read-only deckt beides ab: einen :ro-Mount und ein Verzeichnis mit falschem Besitzer. Das Feld provisioningDetail derselben Antwort nennt den Pfad und beide Möglichkeiten. Der zweite Fall ist der häufigere: legt Docker den Bind-Mount-Quellpfad selbst an, weil er noch nicht existiert, gehört er root — ganz ohne :ro.

deploy.sh legt das Verzeichnis an und setzt den Besitzer bei jedem Lauf. Von Hand ist das nur nötig, wenn das Deployment nicht über deploy.sh läuft oder der Besitzer nachträglich geändert wurde.

Ein Siegel zum Testen erzeugen

Der schnellste vollständige Durchlauf auf einer Testanlage:

  1. Laborangaben ausfüllen (mindestens Laborname)
  2. Siegel einrichten → Selbst erzeugen → Einrichten
  3. Einen Kalibrierschein freigeben und siegeln
  4. Das Dokument im Adobe Reader öffnen: die Signatur ist vorhanden, der Inhaber wird angezeigt, die Gültigkeit ist unbekannt — genau das ist bei einem selbstsignierten Zertifikat richtig

Für einen Durchlauf mit echtem Nachweis braucht es Schritt 2 über den Zertifikatsantrag und eine CA, die ihn signiert; eine eigene Test-CA genügt dafür.

Der Siegel-Dienst prüft keine Signaturen

Er erzeugt sie. Ob ein Siegel gültig ist, entscheidet der Betrachter des Dokuments — zum Prüfen also einen PDF-Betrachter verwenden, nicht calServer.

Fehlersuche

Meldung Ursache Abhilfe
„Diese Anlage siegelt noch über den kombinierten report-runner" SEAL_SERVICE_URL fehlt Zeile in die Host-.env, Container neu erstellen
„Der Siegel-Dienst verwaltet keine Credentials" Verzeichnis gehört nicht uid 10001, oder Mount ist :ro Schlüsselverzeichnis
„the service may not write /keystores/…" (uid 10001) Dasselbe, vom Dienst selbst benannt Schlüsselverzeichnis
„No keystore password configured" PDF_SIGNING_PASSWORD fehlt Setzen und docker compose up -d calserver-seal
„Die Referenz ist schon vergeben" Name doppelt Andere Referenz wählen; Credentials werden nicht überschrieben
„None of the certificates … belongs to the key" Zertifikat gehört zu einem anderen Antrag Zertifikat zum passenden Credential hochladen
Liste bleibt nach dem Ablegen einer Datei leer Datei liegt im falschen Verzeichnis, oder gehört root SEAL_KEYSTORE_PATH prüfen — zuständig ist calserver-seal, nicht der report-runner; danach Besitzer prüfen

Zustand des Dienstes:

docker compose exec calserver-seal wget -qO- http://127.0.0.1:8091/ready

Meldet Version, Authentifizierung, erzeugbare Stufen und provisioning: enabled | read-only | directory-read-only.