Open Source für das E-Government |
MOA: Serversignatur (SS) und Signaturprüfung (SP), V 1.2
Konfiguration
Dieses Handbuch beschreibt detailliert die Konfigurationsmöglichkeiten für MOA SP/SS. Wenn nicht anders angegeben, beziehen sich die Erläuterungen sowohl auf die Konfiguration des Webservices als auch auf die Konfiguration von MOA SP/SS für den Einsatz als Klassenbibliothek.
Die Konfiguration von MOA SP/SS erfolgt zentral über eine einzige Konfigurationsdatei. Das Format der Konfigurationsdatei ist XML und muss dem Schema MOA-SPSS-config-1.3.xsd entsprechen. Abschnitt 2 erläutert die Konfigurationsmöglichkeiten im Einzelnen.
Mit dem Wechsel auf Version 1.3 verwendet MOA SP/SS ein neues, übersichtlicheres Format für die XML-Konfigurationsdatei.
Wenn Sie von einer älteren Version von MOA SP/SS auf die Version 1.3 wechseln und Ihre bestehende Konfiguration beibehalten wollen, steht Ihnen ein einfaches Kommandozeilenwerkzeug zur Verfügung, mit dem Sie Ihre Konfigurationsdatei vom bisherigen auf das neue Format migrieren können.
Dieses Werkzeug können Sie durch Ausführen des Scripts configtool
aus dem Verzeichnis
tools
im MOA-Installationsverzeichnis verwenden:
configtool c:\pfad\zur\konfiguration\config.alt.xml c:\pfad\zur\konfiguration\config.neu.xml
Der erste Parameter für das Script gibt also Pfad und Dateiname der bestehenden, alten Konfigurationsdatei an, der zweite Parameter Pfad und Dateiname für die zu erzeugende Konfigurationsdatei im neuen Format (Hinweis: Die Beispielpfade beziehen sich auf Windows-Betriebssysteme; für Unix-Betriebssysteme wählen Sie bitte sinngemäße Pfade.).
Die zentrale Konfigurationsdatei von MOA SP/SS wird der Java Virtual Machine, in der MOA SP/SS läuft, durch eine System Property mitgeteilt (wird beim Starten der Java Virtual Machine in der Form -D<name>=<wert>
gemacht). Der Name der System Property lautet moa.spss.server.configuration
; als Wert der System Property ist der Pfad sowie der Name der Konfigurationsdatei im Dateisystem anzugeben, z.B.
moa.spss.server.configuration=C:/Programme/apache/tomcat-4.1.30/conf/moa-spss/moa-spss.config.xml
Weitere Informationen zum Bekanntmachen der zentralen Konfigurationsdatei für MOA SP/SS erhalten Sie in Abschnitt 2.1.2.3 des Installationshandbuchs.
Wird MOA SP/SS als Webservice eingesetzt, kann durch Aufrufen einer speziellen URL des Webservice ein erneutes Einlesen der Konfigurationsdatei erzwungen werden. Damit ist es möglich, Änderungen an der Konfigurationsdatei vorzunehmen, und diese Änderungen ohne Neustart des zu Grunde liegenden Servlet Containers in den Betrieb zu übernehmen.
Weitere Informationen zum erneuten Einlesen der Konfigurationsdatei im Webservice-Betrieb erhalten Sie in Abschnitt 2.1.2.5 des Installationshandbuchs.
MOA SP/SS verwendet als Framework für Logging-Information die Open Source Software log4j
. Die Konfiguration der Logging-Information erfolgt nicht direkt durch MOA SP/SS, sondern über eine eigene Konfigurationsdatei, die der Java Virtual Machine durch eine System Property mitgeteilt wird. Der Name der System Property lautet log4j.configuration
; als Wert der System Property ist eine URL anzugeben, die auf die log4j
-Konfigurationsdatei verweist, z.B.
log4j.configuration=file:/C:/Programme/apache/tomcat-4.1.30/conf/moa-spss/log4j.propertiesWeitere Informationen zur Konfiguration des Loggings erhalten Sie in Abschnitt 2.1.3 des Installationshandbuchs.
Nachfolgend werden die verfügbaren Konfigurationsparameter der zentralen Konfigurationsdatei im Detail erläutert. Die Reihenfolge der Abhandlung entspricht der Reihenfolge des vorgeschriebenen Auftretens in der Konfigurationsdatei. Für beispielhafte Konfigurationsdateien siehe Abschnitt 3.
Muss der Wert eines Konfigurationsparameters eine URL oder eine Pfadangabe sein, und wird als konkreter Wert eine relative URL bzw. ein relativer Pfad angegeben, so wird diese Angabe relativ zum Pfad jenes Verzeichnisses interpretiert, in dem die zentrale Konfigurationsdatei gespeichert ist.
Präfixe für Namenräume von XML-Elementen werden wie folgt verwendet:
Präfix | Namenraum |
---|---|
cfg |
http://reference.e-government.gv.at/namespace/moaconfig/20021122# |
dsig |
http://www.w3.org/2000/09/xmldsig# |
moa | http://reference.e-government.gv.at/namespace/moa/20020822# |
xs |
http://www.w3.org/2001/XMLSchema |
Name | cfg:CanonicalizationAlgorithm |
Relevanz | MOA SS |
Gebrauch | optional |
Erläuterung | Als Inhalt des Elements kann der Kanonisierungs-Algorithmus, der für das Erstellen von XML-Signaturen verwendet werden soll und in der Signatur als Inhalt von
http://www.w3.org/TR/2001/REC-xml-c14n-20010315 Wird das Element nicht angegeben, wird folgender Wert als Default-Wert verwendet: http://www.w3.org/TR/2001/REC-xml-c14n-20010315 Für die genaue Bedeutung der Werte siehe die Spezifikation für XML-Signaturen. |
Name | cfg:DigestAlgorithm |
Relevanz | MOA SS |
Gebrauch | optional |
Erläuterung | Als Inhalt des Elements kann der Digest-Algorithmus, der für das Erstellen von XML-Signaturen verwendet werden soll und in der Signatur als Inhalt von
http://www.w3.org/2000/09/xmldsig#sha1 Wird das Element nicht angegeben, wird folgender Wert als Default-Wert verwendet: http://www.w3.org/2000/09/xmldsig#sha1 Für die genaue Bedeutung der Werte siehe die Spezifikation für XML-Signaturen. |
Das Element cfg:GenericConfiguration
ermöglicht die Bekanntgabe eines Name/Wert-Paares mittels seiner Attribute name
und value
. Das Element kann beliebig oft verwendet werden. Nachfolgend findet sich eine Erläuterung jener Namen (Attribut name
), die MOA zu interpretieren weiß.
cfg:GenericConfiguration/@name |
autoAddCertificates |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt an, ob Zertifikate, die in einer zu prüfenden Signatur enthalten sind bzw. bei der Zertifikatspfaderstellung durch Auswertung der Zertifikatserweiterung Authority Information Access (siehe auch Parameter Zulässige Werte für diesen Parameter sind Der Default-Wert lautet |
cfg:GenericConfiguration/@name |
useAuthorityInfoAccess |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt an, ob die Zertifikatserweiterung Authority Information Access für die Zertifikatspfaderstellung verwendet werden soll. Wird der Wert auf Zulässige Werte für diesen Parameter sind Der Default-Wert lautet |
cfg:GenericConfiguration/@name |
DirectoryCertStoreParameters.RootDir |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt ein Verzeichnis im lokalen Dateisystem an, das von MOA als lokaler Zertifikatsspeicher verwendet werden soll. Zulässige Werte für diesen Parameter sind absolute oder relative Pfadangaben, z.B.:
C:/Programme/apache/tomcat-4.1.30/conf/moa-spss/certstore certstore Der Default-Wert lautet: certstore |
cfg:GenericConfiguration/@name |
checkRevocation |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt an, ob bei der Zertifikatsüberprüfung im Zuge einer Signaturprüfung auch der Zertifikatsstatus jedes einzelnen Zertifikats des gebildeten Zertifikatspfads überprüft werden soll. Bitte beachten Sie: Die Widerrufsprüfung ist ein sehr wichtiger Schritt der Zertifikatsüberprüfung und somit der Signaturprüfung. Eine Deaktivierung sollte nur in begründeten Ausnahmefällen in Erwägung gezogen werden, z.B. für Testsituationen. Zulässige Werte für diesen Parameter sind Der Default-Wert lautet |
cfg:GenericConfiguration/@name |
maxRevocationAge |
Relevanz | MOA SSP |
Gebrauch | optional |
Erläuterung | Gibt an, wie aktuell eine ggf. lokal gespeicherte Widerrufsinformation sein muss, damit sie von MOA SP als gültig angesehen wird. Ist die lokal gespeicherte Widerrufsinformation nicht aktuell genug, wird sie von MOA SP erneut aus dem Internet geladen. Dieser Parameter wird nur ausgewertet, wenn die Widerrufsprüfung aktiviert ist (siehe Parameter Zulässige Werte für diesen Parameter sind ganze Zahlen:
Der Default-Wert lautet |
cfg:GenericConfiguration/@name |
archiveRevocationInfo |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt an, ob mittlerweile ungültig gewordene (i.e. historische) Widerrufsinformationen von MOA SP archiviert werden soll. Dieser Parameter wird nur dann ausgewertet, wenn gleichzeitig auch der Parameter
Zulässige Werte für diesen Parameter sind Der Default-Wert lautet |
cfg:GenericConfiguration/@name |
DataBaseArchiveParameter.JDBCUrl |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Gibt eine JDBC-URL zu jener Datenbank an, in der MOA historische Widerrufsinformationen archivieren soll. Wird dieser Paramter gesetzt, muss gleichzeitig auch der Parameter Der genaue Aufbau der JDBC-URL ist abhängig von der verwendeten Datenbank. Im Fall von PostgreSQL kann folgende URL verwendet werden: jdbc:postgresql://<host>/<moadb>?user=<moauser>&password=<moapassword> Die Platzhalter Bitte beachten Sie: Die Kodierung des Zeichens "&" als "&" ist erforderlich, da es andernfalls zu einem Validierungsfehler beim Parsen der XML-Konfigurationsdatei durch MOA kommen würde. Bitte beachten Sie: MOA SP legt eigenständig eine passende Tabelle in der angegebenen Datenbank an und befüllt diese dann in weiterer Folge. Der in der JDBC-URL angegebene Benutzer muss mit den dazu passenden Rechten ausgestattet sein. Für diesen Parameter existiert kein Default-Wert. |
cfg:GenericConfiguration/@name |
DataBaseArchiveParameter.JDBCDriverClass |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Dieser Parameter kann verwendet werden, um MOA SP den Klassennamen des JDBC-Datenbanktreibers bekannt zu geben, der zur Ansprache der für die CRL-Archivierung zu verwendenden Datenbank benützt werden soll. Der Parameter wird nur dann ausgewertet, wenn der generische Konfigurationsparameter Der Wert des Parameters muss den vollständig qualifizierten Java-Klassennamen des JDBC-Treibers enthalten. Bitte beachten Sie: Wird im Parameter Bitte beachten Sie: Informationen zum Anlegen einer Datenbank in postgreSQL finden Sie in Abschnitt 2.2.2.1 des Installationshandbuchs. Für diesen Parameter existiert kein Default-Wert. |
Name | cfg:HardwareKeyModule |
Relevanz | MOA SS |
Gebrauch | optional (zumindest ein Hardware- oder Software-Schlüsselspeicher muss vorhanden sein) |
Erläuterung | Mit diesem Element wird MOA SS die Verfügbarkeit eines Hardware-Schlüsselspeichers mitgeteilt. Das Element weist bis zu vier Attribute auf:
Das Element hat keinen Element-Inhalt. |
Name | cfg:SoftwareKeyModule |
Relevanz | MOA SS |
Gebrauch | optional (zumindest ein Hardware- oder Software-Schlüsselspeicher muss vorhanden sein) |
Erläuterung | Mit diesem Element wird MOA SS die Verfügbarkeit eines Software-Schlüsselspeichers in Form einer PKCS#12-Datei mitgeteilt. Das Element weist drei obligatorische Attribute auf:
Das Element hat keinen Element-Inhalt. |
Name | cfg:KeyGroup |
Relevanz | MOA SS |
Gebrauch | obligatorisch (zumindest eine Schlüsselgruppe muss vorhanden sein) |
Erläuterung | Mit diesem Element wird in MOA SS eine Schlüsselgruppe definiert. Eine Schlüsselgruppe ist eine Zusammenfassung von einem oder mehreren privaten Schlüsseln, die in Hardware- bzw. Softwareschlüsselspeichern (vergleiche Abschnitte 2.4 bzw. 2.5) verwaltet werden. Die Schlüsselgruppe wird vom Kunden von MOA SS über einen eindeutigen Bezeichner im Request zur Signaturerstellung angesprochen. Sinn der Zusammenfassung von mehreren privaten Schlüsseln zu einer Schlüsselgruppe ist es, dass MOA SS selbst entscheidet, welcher konkrete Schlüssel aus der Schlüsselgruppe zur Erstellung der Signatur verwendet wird. Durch die somit mögliche Parallelisierung (mehrere private Schlüssel werden parallel für Anfragen, die auf die gleiche Schlüsselgruppe referenzieren) lässt sich der Durchsatz der erstellten Signaturen verbessern. Das Element
Das Element
Um auf einfache Weise für alle in Ihren Schlüsselspeichern enthaltenen privaten Schlüssel die jeweiligen Werte für
Wenn Ihnen für einen privaten Schlüssel, den Sie in eine Schlüsselgruppe aufnehmen wollen, das Zertifikat bekannt ist und es in Form einer DER-kodierten Datei vorliegt, können Sie alternativ das Script certtool -info <certfilename>
SubjectDN (RFC2253): CN=Test: Signaturdienst aller Kunden: ECDSA (P192v1),OU=Technik und Standards,O=Stabsstelle IKT-Strategie des Bundes,C=AT IssuerDN (RFC2253) : CN=Test CA - Signaturdienste,OU=Technik und Standards,O=Stabstelle IKT-Strategie des Bundes,C=AT Die Werte für |
Name | cfg:KeyGroupMapping |
Relevanz | MOA SS |
Gebrauch | obligatorisch (zumindest eine Zuordnung muss vorhanden sein) |
Erläuterung | Das Element Das Element weist keine Attribute auf und hat folgenden Element-Inhalt:
Bitte beachten Sie: Für maximal ein Konfigurationselement |
Name | cfg:ChainingModes |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Das Element Das Element
Das Element
Bitte beachten Sie: Für maximal ein Konfigurationselement |
Name | cfg:CRLArchive |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Das Element Das Element weist ein obligatorisches Attribut auf:
Das Element hat keinen Element-Inhalt |
Name | cfg:CRLDistributionPoint |
Relevanz | MOA SP |
Gebrauch | optional |
Erläuterung | Das Element Dies macht für veraltete Zertifikate Sinn, die nicht den aktuellen Vorgaben aus dem PKIX RFC 3280 entsprechen und im Zertifikat selbst keine Zertifikatserweiterung mit einem solchen Verteilungspunkt enthalten. Weiters kann diese manuelle Konfiguration verwendet werden, wenn die in einem Zertifikat enthaltenen Verteilungspunkte für eine bestimmte CA durch einen manuellen Eintrag überschrieben werden soll (etwa weil die im Zertifikat enthaltenen Verteilungspunkte in Form von ldap-URLs angegeben sind, MOA SP aber der Zugriff auf ldap-URLs per Firewall-Einstellungen untersagt ist; dann könnte man stattdessen manuell eine (lokale) http-URL als Verteilungspunkt angeben, die von MOA SP dann aufgelöst werden kann). Das Element weist keine Attribute auf und hat folgenden Element-Inhalt:
|
MOA SP/SS erlaubt die Hinterlegung von vordefinierten Profilen für folgende Bereiche, um die Angabe von ständig wiederkehrenden Informationen in Requests zur Erstellung bzw. Prüfung von Signaturen zu vermeiden:
cfg:CreateSignatureEnvironmentProfile
: Enthält für eine zu erstellende XML-Signatur, die in ein bereits bestehendes XML-Dokument integriert werden soll, die Stelle, an der die XML-Signatur eingefügt werden soll, sowie allenfalls für die Verarbeitung des bestehenden XML-Dokuments notwendige Ergänzungsobjekte (z.B. ein XML-Schema für das validierende Parsen des bestehenden XML-Dokuments).cfg:CreateTransformsInfoProfile
: Enthält für ein bestimmtes Datenobjekt für eine zu erstellende XML-Signatur die auf dieses Datenobjekt anzuwendenden Transformationen, sowie allenfalls für die Durchführung der Transformationen notwendige Ergänzungsobjekte (z.B. einen zu importierenden Stylesheet für eine XSL-Transformation).cfg:VerifyTransformsInfoProfile
: Enthält für ein bestimmtes Datenobjekt für eine zu prüfende XML-Signatur eine für dieses Datenobjekt erlaubte Transformationsfolge, bestehend aus den anzuwendenden Transformationen, sowie allenfalls für die Durchführung der Transformationen erlaubte implizite Transformationsparameter (z.B. einen zu importierenden Stylesheet für eine XSL-Transformation).cfg:SupplementProfile
: Enthält für ein Datenobjekt in der zu prüfenden XML-Signatur ein allenfalls für die Durchführung der vorgegebenen Transformationen notwendiges Ergänzungsobjekt (z.B. einen zu importierenden Stylesheet für eine XSL-Transformation).Jedes dieser Elemente kann dabei beliebig oft (auch gar nicht) vorkommen. Alle Elemente teilen den gleichen Aufbau; sie weisen zwei obligatorische Attribute auf und haben keinen Element-Inhalt:
id
: Dieses Attribut vom Typ xs:token
enthält einen frei wählbaren Identifikator für dieses Konfigurationselement, der innerhalb der XML-Konfigurationsdatei eindeutig sein muss. Dieser Identifikator wird im Request zur Erstellung bzw. zur Überprüfung der Signatur verwendet, um das hinterlegte Profil zu referenzieren (vergleiche die Elemente moa:CreateSignatureEnvironmentProfileID
, moa:CreateTransformsInfoProfileID
, moa:VerifyTransformsInfoProfileID
, moa:SupplementProfileID
). filename
: Dieses Attribut vom Typ xs:string
enthält den Namen der XML-Datei, die das hinterlegte Profil beinhaltet. Der Wert enthält einen Dateinamen mit absoluter oder relativer Pfadangabe. Eine relative Pfadangabe wird von MOA SS relativ zum Pfad jenes Verzeichnisses interpretiert, in dem die zentrale Konfigurationsdatei gespeichert ist. Die XML-Datei muss als Wurzelelement eines der Elemente moa:CreateSignatureEnvironmentProfile
, moa:CreateTransformsInfoProfile
, moa:VerifyTransformsInfoProfile
oder moa:SupplementProfile
enthalten.Name | cfg:TrustProfile |
Relevanz | MOA SP |
Gebrauch | obligatorisch (zumindest ein Vertrauensprofil muss vorhanden sein) |
Erläuterung | Das Element Ein Vertrauensanker ist ein CA-Zertifikat, das explizit als vertrauenswürdig eingestuft wird. MOA SP versucht bei der Konstruktion einer Zertifikatskette, einen Pfad vom Signatorzertifikat bis hin zu einem der konfigurierten Vertrauensanker zu finden. Gelingt dies, wird auch das Signatorzertifikat als vertrauenswürdig betrachtet, ansonsten nicht. Wird neben der Menge von Vertrauensankern auch noch eine Menge von explizit erlaubten Signatorzertifikaten angegeben, prüft MOA SP nicht nur, ob sich ein Pfad vom Signatorzertifikat zu einem konfigurierten Vertrauensanker konstruieren lässt, sondern darüber hinaus auch noch, ob das Signatorzertifikat aus der zu prüfenden Signatur in der Menge der explizit erlaubten Signatorzertifikate vorkommt. Explizit erlaubte Signatorzertifikate sollten Sie dann konfigurieren, wenn nicht allen von einer als Vertrauensanker konfigurierten CA ausgestellten Zertifikaten vertraut werden soll, sondern nur ganz bestimmten Zertifikaten dieser CA. In MOA SP können beliebig viele solcher Vertrauensprofile konfiguriert werden. Der Kunde von MOA SP gibt im Request zur Signaturprüfung an, gegen welches Vertrauensprofil MOA SP die Zertifikatsprüfung vornehmen soll. Das Element
|
Nachfolgend finden Sie eine zentrale Konfigurationsdatei mit den minimal notwendigen Einträgen für den alleinigen Betrieb von MOA SS. Darin enthalten sind folgende Konfigurationselemente:
cfg:SoftwareKeyModule
)cfg:KeyGroup
)cfg:KeyGroupMapping
) Minimale Konfiguration für MOA SS
Nachfolgend finden Sie eine zentrale Konfigurationsdatei mit den minimal notwendigen Einträgen für den alleinigen Betrieb von MOA SP. Darin enthalten sind folgende Konfigurationselemente:
cfg:TrustProfile
) Minimale Konfiguration für MOA SP
Nachfolgend finden Sie eine typische zentrale Konfigurationsdatei mit Einträgen für den kombinierten Betrieb von MOA SP und SS. Diese Datei wird auch als Konfiguration von MOA SP und SS verwendet, die für das Ausführen der Beispiele des Anwenderhandbuchs notwendig ist.
Typische Konfiguration für MOA SP/SS