A-Trust Qualizierte Handy-Signatur REST API

A-Trust Gesellschaft für Sicherheitssysteme im elektronischen Datenverkehr GmbH Landstraÿer Hauptstraÿe 1b The Mall E02 A-1030 Wien https://www.a-trust.at E-Mail: oce@a-trust.at A-Trust Qualizierte Handy-Signatur REST API Version: 1.1 Datum: 27. Juli 2017

im elektr. Datenverkehr GmbH Copyright c 2017 - Alle Rechte vorbehalten A-Trust Gesellschaft für Sicherheitssysteme im elektronischen Datenverkehr GmbH A-1030 Wien Die in dieser Dokumentation enthaltenen Informationen, Kenntnisse und Darstellungen sind geistiges Eigentum der A-Trust und dürfen ohne die vorherige schriftliche Zustimmung von A-Trust weder vollständig noch auszugsweise, direkt oder indirekt Dritten zugänglich gemacht, veröentlicht oder anderweitig verbreitet werden. Die Geltendmachung aller diesbezüglicher Rechte, bleiben der Firma A-Trust vorbehalten. Die Übergabe der Dokumentation begründet keinerlei Anspruch auf eine Lizenz oder Benutzung. Handy-Signatur REST API Version: 1.1 Seite 2 von 19

im elektr. Datenverkehr GmbH Inhaltsverzeichnis Inhaltsverzeichnis 1 Allgemein 5 2 Ablaufbeschreibung 6 3 REST Schnittstelle 8 3.1 Session Erzeugen................................. 8 3.2 Update Session.................................. 9 3.3 Session beenden.................................. 9 3.4 Session Informationen.............................. 10 3.5 Design Einstellungen............................... 10 3.6 Benutzer Login.................................. 11 3.7 Zertikat lesen.................................. 11 3.8 Signatur starten.................................. 13 3.9 Signaturdaten abholen.............................. 14 3.10 Signaturrequest XML............................... 15 3.11 Signaturresponse XML.............................. 16 3.12 Session Erzeugen und Login........................... 17 4 Berechtigungen - Client Zertikat 18 5 Server Zertikatsprüfung 18 6 Vergleichswert 18 7 Dokumentation 19 Handy-Signatur REST API Version: 1.1 Seite 3 von 19

im elektr. Datenverkehr GmbH Inhaltsverzeichnis Datum Rev Autor Änderungen 27.07.2017 1.1 Patrick Hagelkruys Adresse aktualisiert Adresse aktualisiert 06.06.2016 1.0 Patrick Hagelkruys Textanpassungen 06.06.2016 0.9 Patrick Hagelkruys Textanpassungen, Testsystem 16.03.2016 0.8 Ramin Sabet Client Authentizierung klarer Server Auth, Vergleichswert beschrieben 09.03.2016 0.7 Patrick Hagelkruys Funktion zum Erzeugen einer Session und Login 26.01.2016 0.6 Patrick Hagelkruys Funktion zum Setzen des Design der Handy- Signatur BKU 04.11.2015 0.5 Patrick Hagelkruys internal Review Ramin Sabet neues Kapitel Berechtigung neues Kapitel Dokumentation 03.11.2015 0.4 Patrick Hagelkruys Überarbeitung der Kapitel neues Kapitel Allgemein neues Kapitel Ablaufbeschreibung Formatierung der REST s Erweiterte Beschreibung REST Befehle Beschreibung XML und 19.02.2015 0.3 Patrick Hagelkruys Überarbeitung Interface Authentifzierung hinzugefügt vollständiges Beispiel pro 17.02.2015 0.2 Joel Chinnow Überarbeitung REST Interface Patrick Hagelkruys 17.02.2015 0.1 Patrick Hagelkruys Erste Version Tabelle 1: Dokumentenhistorie Handy-Signatur REST API Version: 1.1 Seite 4 von 19

im elektr. Datenverkehr GmbH 1 Allgemein 1 Allgemein Die Handy-Signatur REST API ist eine Schnittstelle um einzelne Befehle der Handy- Signatur über REST-Aufrufe auszuführen. Für Login- und Signaturaufrufe wird eine URL der Handy-Signatur zurückgeliefert, welche dem Benutzer im Browserfenster angezeigt werden muss. Die Schnittstelle ist durch ein HTTPS Client Zertikat gesichert Kapitel 2 beschreibt einen Ablauf einer Signaturauslösung. Kapitel 3 beschreibt die REST Aufrufe und deren Antworten. Handy-Signatur REST API Version: 1.1 Seite 5 von 19

im elektr. Datenverkehr GmbH 2 Ablaufbeschreibung 2 Ablaufbeschreibung Signator Online-Applikation Handy-Signatur Webseite Server a Erzeuge Session (siehe 3.1) Session anlegen b Login (siehe 3.6) Login vorbereiten URL aus REST an Webbrowser Aufruf www.handysignatur.at Überprüfung der Session Login-Fenster Eingabe Telefonnummer und Passwort Überprüfung der Eingaben Weiterleiten an NextUrl Weiterleiten an NextUrl c Zertikat Abfragen (siehe 3.7) Zertikat lesen d Signatur starten (siehe 3.8) URL aus REST an Webbrowser Aufruf signatur.at www.handy- Eingabe TAN Weiterleiten an NextUrl Signatur vorbereiten SMS versenden Rückmeldung Überprüfung der Session TAN-Fenster Überprüfung der Eingaben Weiterleiten an NextUrl e Signaturdaten abholen (siehe 3.9) Signaturdaten erstellen Rückmeldung f Session beenden (siehe 3.3) Session löschen Handy-Signatur REST API Version: 1.1 Seite 6 von 19

im elektr. Datenverkehr GmbH 2 Ablaufbeschreibung Bei jedem REST Aufruf wird das Client Zertikat geprüft. a: Im ersten Schritt wird von der Online-Applikation eine Session am Handy-Signatur Server erzeugt. b: Im zweiten Schritt wird ein Login (erster Faktor der Handy-Signatur, Handynummer und Signaturpasswort) durchgeführt. Dazu wird der Login Befehl an den Handy-Signatur Server gesendet. Dieser liefert eine URL zurück, welche dem Signator im Webbrowser angezeigt werden muss. Der Signator gibt seine Handynummer und sein Signaturpasswort auf der Handy-Signatur Seite ein. Nach erfolgreicher Anmeldung wird der Webbrowser des Signators auf die NextUrl weitergeleitet. c: Nach erfolgreichem Login kann das Zertikat des Signators ausgelesen werden. d: Nach erfolgreichem Login kann eine Signatur gestartet werden. Der Handy-Signatur Server überprüft die Signaturdaten und versendet die SMS an den Signatur. Weiters wird eine URL zurückgeliefert welche an den Signator weitergegeben werden muss. Der Signatur gibt den TAN auf der Handy-Signatur Seite ein. Nach erfolgreicher Überprüfung wird der Webbrowser des Signators auf die NextUrl weitergeleitet. e: Nach dem die Signatur gestartet wurde, kann über einen weiteren Befehl die Signaturdaten abgeholt werden. f: Im letzten Schritt wird die Session am Handy-Signatur Server beendet. Handy-Signatur REST API Version: 1.1 Seite 7 von 19

im elektr. Datenverkehr GmbH 3 REST Schnittstelle 3 REST Schnittstelle Basis URL für die REST-API der Handy-Signatur ist folgende: Livesystem: https://www.handy-signatur.at/mobile/rest/v1_0/ Testsystem: https://hs-abnahme.a-trust.at/mobile/rest/v1_0/ Der Zugri auf die einzelnen Funktionen wird über ein Client-Zertikat geprüft. 3.1 Session Erzeugen Dieser Befehl erzeugt eine neue Session am Handy-Signatur Server und liefert die SessionId zurück. Als Parameter können die Höhe und Breite des Handy-Signatur Fensters angegeben werden. POST / mobile / r e s t /v1_0/ S e s s i o n HTTP/1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 26 " width " : 1 4 9, " height " :149 HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 135 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " s e s s i o n i d " : "TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG", "HRef" : " https :\/\/www. handy s i g n a t u r. at \/ mobile \/ r e s t \/v1_0\/ TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG" Handy-Signatur REST API Version: 1.1 Seite 8 von 19

im elektr. Datenverkehr GmbH 3.2 Update Session 3.2 Update Session Aktualisiert das Timeout der Session PUT / mobile / r e s t /v1_0/ S e s s i o n /TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG HTTP/1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 0 HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 15 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " r e s u l t " : true 3.3 Session beenden Löscht bzw. beendet die Session. DELETE / mobile / r e s t /v1_0/ S e s s i o n /TR_WTFCWNFBFGWWMSZTAUMUUCFIXVCZ HTTP/1.1 Content Length : 0 HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 15 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " r e s u l t " : true Handy-Signatur REST API Version: 1.1 Seite 9 von 19

im elektr. Datenverkehr GmbH 3.4 Session Informationen 3.4 Session Informationen Informationen zur Session. Enthält z.b.: ob ein Benutzer bereits durch Login Authenti- ziert wurde GET / mobile / r e s t /v1_0/ S e s s i o n /TR_MLWLBAYWUKFMPUQPVRPXRCWEGIAD HTTP/1.1 HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 57 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " LoggedIn " : f a l s e, " height " : 1 4 9, " width " : 1 4 9, " l o c a l e " : "DE" 3.5 Design Einstellungen Änderung des Design der Handy-Signatur Webseite. PUT / mobile / r e s t /v1_0/ S e s s i o n / Design HTTP/1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 54 " width " : 0, " height " : 0, " l o c a l e " : "DE", " design " : "", " backgroundcolor " : "", " showcancelbutton " : true, " r e d i r e c t T a r g e t " : "_parent", Der enthält keine Daten, ein HTTP Statuscode 200 wird als Erfolgreich angesehen. Handy-Signatur REST API Version: 1.1 Seite 10 von 19

im elektr. Datenverkehr GmbH 3.6 Benutzer Login 3.6 Benutzer Login Login durch Benutzer, die Parameter ErrorUrl und NextUrl werden verwendet um dem Aufrufer ein Feedback nach der Anmeldung zukommen zu lassen. Nach einer erfolgreicher Anmeldung wird der Browser des Signators an die NextUrl weitergeleitet. Die Antwort enthält die URL der Handy-Signatur welche an den Webbrowser des Signators weitergeleitet werden muss. Dadurch kann der Signator seine Handynummer und sein Signaturpasswort auf der Handy-Signatur Seite eingeben. POST / mobile / r e s t /v1_0/ S e s s i o n /TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG/ Login HTTP /1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 75 " ErrorUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /ERROR", " NextUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /OK" HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 143 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " HandySignaturUrl " : " https :\/\/www. handy s i g n a t u r. at \/ mobile \/ https s e c u r i t y layer r e q u e s t \/ i d e n t i f i c a t i o n. aspx? s i d= TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG" 3.7 Zertikat lesen Nach erfolgreicher Anmeldung (siehe 3.6) kann über diesen Befehl das Zertikat des Signators gelesen werden. GET / mobile / r e s t /v1_0/ S e s s i o n /TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG/ C e r t i f i c a t e HTTP/1.1 Handy-Signatur REST API Version: 1.1 Seite 11 von 19

im elektr. Datenverkehr GmbH 3.7 Zertikat lesen HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 1914 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " C e r t i f i c a t e " : "MIIFg... wp" Handy-Signatur REST API Version: 1.1 Seite 12 von 19

im elektr. Datenverkehr GmbH 3.8 Signatur starten 3.8 Signatur starten Startet eine Signatur, als Antwort wird eine URL der Handy-Signatur zurückgegeben, welche im Browser des Benutzer angezeigt werden muss. Der Parameter Signatur ist in Kapitel 3.11 beschreiben. POST / mobile / r e s t /v1_0/ S e s s i o n /TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG/ Signature HTTP/1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 3450 " ErrorUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /ERROR", " NextUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /OK", " Signature " : "<?xml v e r s i o n = '1.0 ' encoding ='UTF 8'?><atex : CreatePlainSignature xmlns : atex =' http :\/\/www. a t r u s t. at \/ namespace \/ s e c u r i t y l a y e r \/ e x t e n s i o n \/1.2# ' >... </ atex : CreatePlainSignature >" HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 133 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " HandySignaturUrl " : " https :\/\/www. handy s i g n a t u r. at \/ mobile \/ https s e c u r i t y layer r e q u e s t \/main. aspx? s i d=tr_yugghduzachgrgggseffwehiizeg" Handy-Signatur REST API Version: 1.1 Seite 13 von 19

im elektr. Datenverkehr GmbH 3.9 Signaturdaten abholen 3.9 Signaturdaten abholen Nach erfolgreicher Signatur können über diesen Befehl die Signaturdaten abgeholt werden. GET / mobile / r e s t /v1_0/ S e s s i o n /TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG/ Signature HTTP/1.1 HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 3435 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " Signature " : "<?xml v e r s i o n =\"1.0\" encoding=\"utf 8\"?>< s l : CreatePlainSignature xmlns : s l =' http :\/\/www. a t r u s t. at \/ namespace \/ s e c u r i t y l a y e r \/ e x t e n s i o n \/1.2# ' >... <\/ s l : CreatePlainSignature >" Handy-Signatur REST API Version: 1.1 Seite 14 von 19

im elektr. Datenverkehr GmbH 3.10 Signaturrequest XML 3.10 Signaturrequest XML Im Nachfolgenden Listing ist der XML für den Start einer Signatur angegeben. Das Element DataObject (Zeile 4 bis 15) beschreibt ein Dokument. Der Base64Content (Zeile 6) beinhaltet den zu signierenden Hash (SHA-256). Das Element ShowObject (Zeile 8 bis 14) enthält die Daten, welche dem Signator bei der Eingabe der TAN angezeigt werden. Das Element Reference (Zeile 9) muss eine URL auf das Dokument enthalten, sodass diese vom Signator aufgelöst werden kann. Sowohl das Element DataObject (Zeile 4 bis 15), als auch das Element ShowObject (Zeile 8) können mehrmals vorkommen. Dabei ist jedoch zu beachten, dass die Attribute num jeweils eindeutig sind. Eine Stapelsignatur kann durch mehrfache Angabe des Element DataObject durchgeführt werden. 1 <?xml v e r s i o n=' 1. 0 ' encoding='utf 8 '?> 2 <s l : C r e a t e P l a i n S i g n a t u r e R e q u e s t x m l n s : s l=' h t t p : //www. a t r u s t. at /namespace/ s e c u r i t y l a y e r / e x t e n s i o n /1.2# ' > 3 <s l : K e y b o x I d e n t i f i e r>securesignaturekeypair</ s l : K e y b o x I d e n t i f i e r> 4 <sl:dataobject num=' 1 '> 5 <s l : C o n t e n t> 6 <sl:base64content>vevzdcbtdhjpbmc=</ sl:base64content> 7 </ s l : C o n t e n t> 8 <sl:showobject num=' 1 '> 9 <s l : R e f e r e n c e>h t t p s : //www. a t r u s t. at /...</ s l : R e f e r e n c e> 10 <s l : M e t a I n f o> 11 <sl:mimetype>a p p l i c a t i o n / octet stream</sl:mimetype> 12 <s l : D e s c r i p t i o n>name des Dokuments</ s l : D e s c r i p t i o n> 13 </ s l : M e t a I n f o> 14 </ sl:showobject> 15 </ sl:dataobject> 16 </ s l : C r e a t e P l a i n S i g n a t u r e R e q u e s t> Handy-Signatur REST API Version: 1.1 Seite 15 von 19

im elektr. Datenverkehr GmbH 3.11 Signaturresponse XML 3.11 Signaturresponse XML Im Nachfolgenden Listing ist der XML angegeben, wie von dem Signaturabholen Aufruf zurückgeliefert. Für jedes DataObject der Anfrage ein DataObject in der Antwort eingefügt mit dem selben Attributwert in num (Zeile 3 bis 5). Im Element PlainSignature (Zeile 4) ist der Signaturwert (PKCS#1) enthalten. 1 <?xml v e r s i o n=" 1. 0 " encoding="utf 8"?> 2 <s l : C r e a t e P l a i n S i g n a t u r e x m l n s : s l=' h t t p : //www. a t r u s t. at /namespace / s e c u r i t y l a y e r / e x t e n s i o n /1.2# '> 3 <sl:dataobject num=' 1 '> 4 <s l : P l a i n S i g n a t u r e>xiodfb... LwcirTlcaWQ==</ s l : P l a i n S i g n a t u r e> 5 </ sl:dataobject> 6 <s l : X 5 0 9 C e r t i f i c a t e>miifgtcc... kdgypqatdi+uqb</ s l : X 5 0 9 C e r t i f i c a t e> 7 </ s l : C r e a t e P l a i n S i g n a t u r e R e s p o n s e> Handy-Signatur REST API Version: 1.1 Seite 16 von 19

im elektr. Datenverkehr GmbH 3.12 Session Erzeugen und Login 3.12 Session Erzeugen und Login Dieser Befehl erzeugt eine neue Session am Handy-Signatur Server und führt gleichzeitig ein Login durch. POST / mobile / r e s t /v1_0/ S e s s i o n / Login HTTP/1.1 Content Type : a p p l i c a t i o n / j s o n Content Length : 236 " width " : 1 4 9, " height " : 1 4 9, " l o c a l e " : "DE", " design " : null, " backgroundcolor " : "", " showcancelbutton " : true, " r e d i r e c t T a r g e t " : "_parent", " NextUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /OK", " ErrorUrl " : " http : \ / \ / 1 2 7. 0. 0. 1 \ /ERROR", HTTP/1.1 200 OK S t r i c t Transport S e c u r i t y : max age =31536000; includesubdomains Content Length : 175 Cache Control : p r i v a t e Content Type : a p p l i c a t i o n / j s o n ; c h a r s e t=utf 8 " s e s s i o n i d " : "TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG", "HRef" : " https :\/\/www. handy s i g n a t u r. at \/ mobile \/ r e s t \/v1_0\/ TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG", " HandySignaturUrl " : " https :\/\/www. handy s i g n a t u r. at \/ mobile \/ https s e c u r i t y layer r e q u e s t \/ i d e n t i f i c a t i o n. aspx? s i d= TR_YUGGHDUZACHGRGGGSEFFWEHIIZEG" Handy-Signatur REST API Version: 1.1 Seite 17 von 19

im elektr. Datenverkehr GmbH 4 Berechtigungen - Client Zertikat 4 Berechtigungen - Client Zertikat Für jeden Kunden wird am Handy-Signatur Server ein Client-Zertikat berechtigt, gemäÿ ist das Zertikat zu widerrufen, wenn es nicht mehr in alleiniger Kontrolle der berechtigten Personen ist. Dieses Client-Zertikat wird vom Aufrufer für jeden REST-Aufruf zur Authentizierung verwendet. 5 Server Zertikatsprüfung Es ist wichtig das Server Zertikat zu prüfen, um einen Man-in-the-Middle Angrie zu verhindern. Von einem Zertikats-Pinning wird abgeraten, da das Zertikat in regelmäÿigen Abständen getauscht wird. Es wird empfohlen zu prüfen, dass das Zertikat von einer vertrauenswürdigen CA ausgestellt und die Domain www.handy-signatur.at enthält (Entweder im Subject Commonname oder in einem Subject Alternative Name). 6 Vergleichswert Aus dem übermittelten Hash wird der Vergleichswert berechnet. Dieser wird im Browser und der SMS/Tan-App angezeigt. Handy-Signatur REST API Version: 1.1 Seite 18 von 19

im elektr. Datenverkehr GmbH 7 Dokumentation 7 Dokumentation Für jeden Signaturablauf werden am Handy-Signatur Server folgende Daten dokumentiert: Monatszähler: Anzahl Signaturen die in diesem Monat durchgeführt wurden. Signaturaufruf: Aufruf der Signatur mit Datum Hash-Logs: Zu signierende Hashwerte mit den zugehörigen Referenz URLs Handy-Signatur REST API Version: 1.1 Seite 19 von 19