digiseal OASIS-DSS verification service

Transkript

1 Seite 1 von 10 digiseal OASIS-DSS verification service Anwenderhandbuch ab Softwareversion v Markenhinweis: Unter OASIS wird in diesem Dokument die Organization for the Advancement of Structured Information Standards ( verstanden. Mit DSS ist deren Standard Digital Signature Service gemeint. Erstellt von: secrypt GmbH Kontakt: Fon: +49 (0) mail@secrypt.de Revisionshistorie: Datum Version Bemerkung(en) Autor(en) Erstellt / zur Freigabe EmJa Freigegeben MaSc secrypt GmbH Bessemerstraße 82 D Berlin Fon: +49 (0) Fax: +49 (0) Ergänzung ERS-Verifikation EmJa Ergänzung der Namespaces in XML-Listings EmJa Verifikation von XML-DSig/XAdES Signaturen EmJa mail@secrypt.de Dok.-Version 1.1

2 Seite 2 von 10 Inhaltsverzeichnis 1. Einführung Ablauf einer Verifikation und Funktionsübersicht Durchführung der Verifikation Übersicht über die Funktionen des Webservice Hinweise zur Implementierung eines Clients Erstellen eines Client gegen die WSDL Erstellen eines Clients gegen vorkompilierte Klassen Aufbau eines VerifyRequest Einbetten der Signaturdaten in das XML-Element <SignatureObject> Signaturformate PDF, CMS (Cryptographic Message Syntax) und XML Zeitstempelsignatur gemäß RFC Archivierungsnachweisen gemäß RFC4998 (Evidence Record Syntax) Bereitstellen der signierten Daten bei abgesetzten (detached) Signaturen Übertragung der signierten Daten im verify-aufruf Verwenden einer Datei-URI zur Referenzieren der signierten Daten Übergabe der Hashwerte für eine ERS-Verifikation ohne Übertragung der signierten Daten Aufbau der Antwort VerifyResponse Interpretation des Ergebnis aus der Response Wichtiger Hinweis zur Ergebnisinterpretation Anhang Unterstützte Signaturformate Verwendete URI Verwendete Spezifikationen Unterstützungstiefe von XAdES Signaturen... 10

3 Seite 3 von Einführung Der digiseal OASIS-DSS verification service ist eine Webanwendung für Java-Servlet-kompatible Webserver (z.b. Apache Tomcat) zur Verifikation von elektronischen Signaturen unterschiedlicher Formate. Die Schnittstelle ist gemäß dem OASIS Standard DSS (Digital Signature Service) ([DSS_CORE], [DSS_VR]) implementiert. In diesem Dokument ist beschrieben, wie ein Anwender die Funktionen des Webservice zur Verifikation von elektronischen Signaturen nutzen kann. Die Schwerpunkte dieser Anleitung sind: Prinzipieller Ablauf einer Verifikation mit dem Webservice Dokumentation der verfügbaren Funktionen Aufbau eines Request für eine Verifikation Interpretation einer Response Hinweise zur Installation und den Betrieb finden sich in einem gesonderten Dokument Betreiberhandbuch. 2. Ablauf einer Verifikation und Funktionsübersicht 2.1. Durchführung der Verifikation Zum Auslösen der Verifikation wird ein VerifyRequest ([DSS_CORE]) aufgebaut und im verify-aufruf an den Webservice übermittelt. Im VerifyRequest werden die Signaturdaten in Abhängigkeit des vorliegenden Signaturaustauschformats eingebunden (siehe Absatz 4.1). Bei einer abgesetzten Signatur werden die eigentliche Signatur und die signierten Daten in zwei getrennten Dateien gespeichert. Die signierten Daten müssen für die Verifikation ebenfalls zur Verfügung stehen und daher an den Webserver übertragen werden. Die Möglichkeiten zur Übertragung dieser Daten sind in Abschnitt 4.2 Bereitstellen der signierten Daten bei abgesetzten (detached) Signaturen erläutert Übersicht über die Funktionen des Webservice In diesem Abschnitt werden die einzelnen Funktionen des Webservice beschrieben. verify Zweck: Startet die Verifikation einer Signatur. Aktionen: Prüft den VerifyRequest und extrahiert die Signatur. In Abhängigkeit des Signaturformats wird die Signatur gegen die signierten Daten verifiziert. Der OASIS-DSS Prüfbericht wird erstellt und in der Response zurückgegeben. Eingangsdaten: <VerifyRequest> enthält die Signatur und bei abgesetzten Signaturen die signierten Daten (ggf. eine Referenz auf diese). Ausgangsdaten: <VerifyResponse> enthält den Prüfbericht gemäß OASIS-DSS. Fehlermeldungen:

4 Seite 4 von 10 upload Zweck: Dient dem Hochladen von Dateien auf dem Webserver. Die Daten können später referenziert werden, indem die URI aus dem Rückgabewert dieser Funktion genutzt wird. Aktionen: Binäre Dateien werden unter einem temporären Namen im konfigurierten Verzeichnis abgespeichert. Der Dateiname wird als URI in der Response zurückgegeben. Eingangsdaten: <FileUploadRequest> enthält die base64codiert Bytes der Daten Ausgangsdaten: <FileUploadResponse> enthält die URI der Datei auf dem Webserver Fehlermeldungen: Achtung: Da die Daten technisch in einem http POST übertragen werden, ist die Größe entsprechend der Konfiguration des Webservice beschränkt. delete Zweck: Veranlasst die Löschung einer hochgeladenen Datei. Aktionen: Es wird geprüft, ob die in der URI angegebene Datei existiert und den angegebenen Hashwert hat. Ist dies der Fall, wird die Datei vom Webserver gelöscht. Eingangsdaten: <FileRemoveRequest> mit der URI der Datei und dem Hashwert Ausgangsdaten: Keine Rückgabe Fehlermeldungen: 3. Hinweise zur Implementierung eines Clients 3.1. Erstellen eines Client gegen die WSDL Die Schnittstelle des Webservice ist durch eine WSDL-Datei vollständig spezifiziert. Die URL zu dieser WSDL wird durch den Betreiber des Webservice bekannt gegeben. Der Betreiber kann die WSDL-Datei und die referenzierten XSD-Dateien ggf. auch direkt bereitstellen. Aufgabe des Anwenders ist es dann, diese WSDL in Programmcode zu überführen. Der generierte Code enthält alle Funktionen, um die notwendigen Datenobjekte zu handhaben und die Funktionen des Webservice aufzurufen Erstellen eines Clients gegen vorkompilierte Klassen Alternativ dazu können Java-Programmierer die vorgenerierten Klassen verwenden, welche durch den Hersteller zur Verfügung gestellt werden. Diese Klassen wurden mit Hilfe des Apache CXF generiert, welche das JAXB- Databinding und das JAX-WS-Webservice-Framework umsetzten. 4. Aufbau eines VerifyRequest Zum Ausführen eines Verifikationsauftrags durch den Webservice wird eine Datenstruktur vom Typ <VerifyRequest> erstellt. Diese beschreibt den Verifikationsauftrag. Die Struktur des XML-Elements ist in Listing 1 gezeigt. Es enthält drei wesentliche Elemente: die Signatur im Knoten <SignatureObject>

5 Seite 5 von 10 bei abgesetzten Signaturen: o eine URI-Referenz auf die signierten Daten im Element <InputDocuments> oder o Base64-kodiert im Element <InputDocuments> und weitere Parameter zur Detaillierung der Verifikation im Element <OptionalInputs><ReturnVerificationReport> Listing 1: Struktur des XML-Elements <VerifyRequest> <?xml version="1.0" encoding="utf-8" standalone="yes"?> <VerifyRequest xmlns="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:vr="urn:oasis:names:tc:dss-x:1.0:profiles:verificationreport:schema#" RequestID=" T153133" Profile="urn:oasis:names:tc:dssx:1.0:profiles:verificationreport"> <OptionalInputs> <vr:returnverificationreport>... <!-- Parametrisierung der Verifikation --> </vr:returnverificationreport> </OptionalInputs> <InputDocuments>... <!-- Bei abgesetzten Signaturen werden hier die signierten Daten base64 kodiert hinterlegt bzw. per URI referenziert --> </InputDocuments> <SignatureObject>... <!-- Die Signatur entsprechend des Signaturformats --> </SignatureObject> </VerifyRequest> Das Element <VerifyReport> muss ein Attribut Profile mit dem Wert urn:oasis:names:tc:dssx:1.0:profiles:verificationreport enthält. Das Einbetten der Signatur und ggf. der signierten Daten erfolgt in Abhängigkeit des Signaturformats und wird in den folgenden Abschnitten beschrieben Einbetten der Signaturdaten in das XML-Element <SignatureObject> Die Signatur bzw. der gesamte Signaturträger wird in das XML-Element <SignatureObject> eingebettet. Die nächsten Abschnitte erläutern, wie dies in Abhängigkeit des Signaturformats geschehen muss Signaturformate PDF, CMS (Cryptographic Message Syntax) und XML CMS-Signaturdateien, signierte PDFs und XML-Signaturen werden base64-codiert in den Knoten <Base64Signatur> eingebettet (Listing 2). Das Attribut Type gibt an, um welches Format es sich bei diesen handelt. Unterstützt werden: urn:ietf:rfc:3369 für CMS (*.p7s oder *.pk7) für PDF-Dateien urn:ietf:rfc:3275 für XML Dateien Listing 2 zeigt ein entsprechendes Element. Im Fall einer detached Signatur werden die signierten Daten wie in Abschnitt 4.2 beschrieben auf den Webserver übertragen.

6 Seite 6 von 10 Listing 2: Beispiel für eine CMS-Signatur im Element <SignatureObject> <SignatureObject xmlns="urn:oasis:names:tc:dss:1.0:core:schema"> <Base64Signature Type="urn:ietf:rfc:3369"> JVBERi0[...]xL0YNCg== </Base64Signature> </SignatureObject> Zeitstempelsignatur gemäß RFC3161 Soll ein RFC3161-Zeitstempel verifiziert werden, wird dieser im Element <TimeStamp> eingebettet. Listing 3 zeigt ein beispielhaftes SignaturObject-Element für einen Zeitstempel. Die gezeitstempelten Daten befinden sich in einer gesonderten Datei und werden wie in Abschnitt 4.2 beschrieben angegeben. Listing 3: Beispiel für einen Zeitstempel im Element <SignatureObject> <SignatureObject xmlns="urn:oasis:names:tc:dss:1.0:core:schema"> <Timestamp> <RFC3161TimeStampToken>MIINo[...]QYJKo==</RFC3161TimeStampToken> </Timestamp> </SignatureObject> Archivierungsnachweisen gemäß RFC4998 (Evidence Record Syntax) Der Webservice kann Archivierungsnachweise verifizieren, welche im Format RFC4998-EvidenceRecordSyntax vorliegen. Diese Daten werden gemäß der Struktur in Listing 4 in das <SignatureObject> eingebettet. Die ERS- Daten werden Base64-kodiert im Element <asn1evidencerecord> angegeben. Listing 4: Beispiel für einen Zeitstempel im Element <SignatureObject> <SignatureObject xmlns="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:ecard=" > <Other> <ecard:evidencerecord> <ecard:asn1evidencerecord>miinxq[...]acw5ksq==</ecard:asn1evidencerecord> </ecard:evidencerecord> </Other> </SignatureObject> Sollte für die Hashwertberechnung über die archivierten Daten ein spezielles Verfahren erforderlich sein, können die Hashwerte direkt in den VerifyRequest-Aufruf eingebettet werden (siehe Absatz 4.2.3) Bereitstellen der signierten Daten bei abgesetzten (detached) Signaturen Bei abgesetzten (detached) Signaturen werden die Signatur und die signierten Daten in zwei getrennten Dateien gespeichert. Die Signaturdatei wird wie oben beschrieben in das Element <SignatureObject> eingebettet. Zur Verifikation müssen aber auch die signierten Daten übermittelt werden. Die dazu vorgesehenen Möglichkeiten werden in den folgenden Abschnitten beschrieben Übertragung der signierten Daten im verify-aufruf Die abgesetzten Daten können direkt base64-kodiert im Element <InputDocuments><Document> eingebettet werden. Dazu stehen folgende XML-Elemente zur Verfügung: <Base64XML> für XML-Daten <Base64Data> für sonstige Daten Beide Elemente unterscheiden sich hinsichtlich ihrer Nutzung nicht. Das Element <Base64XML> weist lediglich darauf hin, dass es sich bei den kodierten Daten um ein XML-Dokument handelt. Listing 5 zeigt ein entsprechendes Beispiel.

7 Seite 7 von 10 Listing 5: Einbetten von signierten Daten in das Element <InputDocuments> <InputDocuments xmlns="urn:oasis:names:tc:dss:1.0:core:schema" > <Document> <Base64Data>MIINxQ[...]ACW5ksQ==</Base64Data> </Document> </InputDocuments> Das Einbetten der abgesetzten Daten in den Aufruf hat zur Folge, dass der VerifyRequest keine weiteren Abhängigkeiten hat. Dies kann z.b. für die Ansprache eines im Cluster betriebenen Verifikationsdienstes notwendig sein. Genauere Vorgaben hierzu veröffentlicht der Betreiber des Verifikationsdienstes. Achtung: Entsprechend der Einstellungen des Webservers ist die maximale Größe des VerifyRequest beschränkt. Soll die Signatur über großen Daten verifiziert werden, müssen diese dem Verifikationsdienst in geeigneter Form übermittelt und per URI im VerifyRequest adressiert werden. Genauere Vorgaben hierzu veröffentlicht der Betreiber des Verifikationsdienstes Verwenden einer Datei-URI zur Referenzieren der signierten Daten Die abgesetzten Daten können ebenfalls per URI referenziert und müssen dann nicht mehr in den Aufruf eingebettet werden. Die Datei muss dazu in einer Freigabe abgelegt werden, welche der Verifikationsdienst über die angegebene URI erreichen kann, z.b: Einrichten einer Netzwerkfreigabe und übertragen der Daten z.b. per FTP unabhängig vom Verifikationsdienst. Übertragen der Daten auf den Verifikationsserver mithilfe der Webservicefunktion upload bzw. delete. Als Ergebnis der Übertragung steht die file:/-uri der Datei auf dem Webserver zur Verfügung. Diese URI wird im Element <InputDocuments> hinterlegt. Listing 6 zeigt ein entsprechendes Beispielelement. Listing 6: Beispiel für einen Verweis auf eine Datei im Element <InputDocuments> <InputDocuments xmlns="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xmldsig=" <Document> <AttachmentReference AttRefURI="file:/c:/uploaded_data/tempFileWS dat"> <xmldsig:digestmethod Algorithm=" <xmldsig:digestvalue>fb3fwhrjid4dmbhpl3fmuuan5r3lmozmx2kih2zqrvq=</ns2:digestvalue> </AttachmentReference> </Document> </InputDocuments> Die File-URI wird im Attribute AttRefURI des Knoten <AttachmentReference> angegeben. Über <DigestMethod> und <DigestValue> wird der Hashwert über die Daten transportiert, damit der Webservice die Daten zweifelsfrei identifizieren kann. Tabelle 9 (Absatz 6.2) listet die unterstützen Hashalgorithmen und ihre URIs auf Übergabe der Hashwerte für eine ERS-Verifikation ohne Übertragung der signierten Daten Im speziellen Fall der ERS-Verifikation können auch direkt die Hashwerte im VerifyRequest angegeben werden, welche in den ERS-Daten verarbeitet werden. Dies ist dann sinnvoll, wenn die Daten in speziellen Archivformaten vorliegen und die Hashwertberechnung durch ein spezielles Verfahren erfolgen muss. In diesem Fall können im Element <InputDocuments> mehrere Elemente <DocumentHash> angegeben werden, welche für jeden erforderlichen Hashalgorithmus den jeweiligen Wert beinhalten. Listing 7 zeigt ein entsprechendes <InputDocuments>-Element.

8 Seite 8 von 10 Listing 7: Beispiel für die Übergabe von Hashwerten im Element <InputDocuments> bei ERS-Verifikation <InputDocuments xmlns="urn:oasis:names:tc:dss:1.0:core:schema" xmlns:xmldsig=" <DocumentHash> <xmldsig:digestmethod Algorithm=" <xmldsig:digestvalue>a7qt8zqgfatwqfl95axbx5x7gbi=</ns2:digestvalue> </DocumentHash> <DocumentHash> <xmldsig:digestmethod Algorithm=" <xmldsig:digestvalue>ciwy3tjsjooef9od6mclnornzcsg+yqizryknq==</ns2:digestvalue> </DocumentHash> <DocumentHash> <xmldsig:digestmethod Algorithm=" <xmldsig:digestvalue>k3xfxbddi6zcv0i9vv3iojgnf7zn/nwdj6ee/ugkfac=</ns2:digestvalue> </DocumentHash> </InputDocuments> 5. Aufbau der Antwort VerifyResponse 5.1. Interpretation des Ergebnis aus der Response Die Rückgabe des verify-aufruf des Webservice ist ein XML-Element <VerifyResponse>, welches alle Ergebnisse und Daten über die Verifikation enthält. Dieser Verifikationsbericht unterteilt sich in mehrere, teilweise wiederkehrende Elemente, welche Teilprüfschritte der Verifikation repräsentieren z.b.: die lokale mathematische Prüfung einer Signatur im Element <SignatureOK> die Verifikation der Zertifikatsketten im Element <CertificatePathValidity> eine Onlinestatusprüfung im Element <CertificateStatus> Viele dieser Elemente enthalten wiederum ein Element vom Typ <Result>, in dem das Ergebnis des jeweiligen Prüfschritts festgehalten wird. Der ResultMajor-String des <Result>-Typs kann folgende Werte annehmen: urn:oasis:names:tc:dss:1.0:detail:valid urn:oasis:names:tc:dss:1.0:detail:invalid urn:oasis:names:tc:dss:1.0:detail:indetermined Eine Besonderheit stellt das erste <Result>-Element in der VerifyResponse dar. Hier wird das Gesamtergebnis über alle durchgeführten Teilschritte angegeben. Die möglichen Ergebnisse sind im OASIS DSS Core spezifiziert: Eine erfolgreiche Durchführung der Verifikation wird im Element <ResultMajor> durch den Wert urn:oasis:names:tc:dss:1.0:resultmajor:success angezeigt. Dies bedeute aber nur, dass keine Fehler in der Bearbeitung aufgetreten sind und die notwendigen Informationen verfügbar waren. Erst der Wert im Element <ResultMinor> läßt erkennen, ob die Signatur positiv oder negativ verifiziert wurde. Hier zeigt der Wert urn:oasis:names:tc:dss:1.0:resultminor:valid:signature:onalldocuments an, dass alle Signaturen und Zeitstempel gültig sind und alle Eingangsdokumente umfassen Wichtiger Hinweis zur Ergebnisinterpretation Beachten Sie, dass der Wert urn:oasis:names:tc:dss:1.0:resultmajor:success im Element <ResultMajor> eine erfolgreiche technische Durchführung des Verifikationprozesses signalisiert. Ob die Signatur positiv oder negativ verifiziert wurde, ist geht erst aus dem Inhalt des Elements <ResultMinor> hervor (siehe Absatz 5.1).

9 Seite 9 von Anhang 6.1. Unterstützte Signaturformate Die folgende Tabelle listet die Signaturaustauschformate auf, welche durch die Webanwendung digiseal OASIS-DSS verification service verifiziert werden können. Tabelle 8: Unterstützte Signaturaustauschformate Bezeichnung CMS (PKCS#7 signed data) PDF Signaturen XML-Signatur Beschreibung Signaturdatei (typischerweise als *.p7s oder *.pk7) gemäß Cryptographic Message Syntax (CMS) RFC 5652 PDF-Signatur gemäß Adobe PDF References 1.6 (*.pdf) Gemäß XMLDSig und XAdES-BES / -EPES / -T gemäß ETSI TS V1.4.1 Die Prüftiefe für XAdES-Signaturen ist in Abschnitt 6.4 beschrieben. Zeitstempel ASN.1 Evidence Record gemäß RFC3161 gemäß RFC4998 (Evidence Record Syntax) 6.2. Verwendete URI Tabelle 9: URI der Hashalgorithmen Bezeichnung HASH_SHA1 HASH_SHA224 HASH_SHA256 HASH_SHA384 HASH_SHA512 HASH_RIPMD160 HASH_MD5 URI Verwendete Spezifikationen [DSS_VR] OASIS DSS v1.0 Profile for Comprehensive Multi-Signature Verification Reports Version [DSS_CORE] OASIS DSS v1.0 Profile for Comprehensive Multi-Signature Verification Reports Version [DSS_GERMAN] OASIS DSS v1.0 Profile for Comprehensive Multi-Signature Verification Reports Version [XAdES] [XMLDSig] ETSI TS V XML Signature Syntax and Processing

10 Seite 10 von Unterstützungstiefe von XAdES Signaturen XAdES-Signaturen werden in der Tiefe BES (Basic Electronic Signature), -EPES (Explicit policy electronic signatures) und T (with Timestamp) unterstützt. Weiterführende Elemente in der XML-XAdES-Signatur werden nicht interpretiert. Die Abbildung 1 illustriert die unterstützte Verifikation von XAdES-Signaturen. Zusätzlich gibt es folgende Einschränkungen: Der Zeitstempel muss als XML Element <EncapsulatedPKIDataType> eingebettet werden Abbildung 1: Unterstützte Validierung von XAdES-Signaturen (gemäß Abb. G.2 aus ([XAdES])