A-Trust REGISTRIERKASSE mobile Developer Manual

Transkript

1 A-Trust Gesellschaft für Sicherheitssysteme im elektronischen Datenverkehr GmbH Landstraÿer Hauptstraÿe 5 A-1030 Wien oce@a-trust.at A-Trust REGISTRIERKASSE mobile Developer Manual Version: 0.4 Datum: 30. Oktober 2015

2 im elektr. Datenverkehr GmbH Inhaltsverzeichnis Inhaltsverzeichnis 1. Überblick Zusammenfassung Schnittstelle Übersicht Signatur erstellen Anfrage Antwort Zertikatsinformationen abfragen Anfrage Antwort ZDA-Informationen abfragen Anfrage Antwort Ausstellen einer A-Trust REGISTRIERKASSE mobile (Kundenkonto) Anfrage Antwort Testsystem Implementierung des Aufrufs Aufruf mit curl (Windows) Aufruf mit C-Sharp Aufruf mit Java Anhang A. ReturnCode der Schnittstelle 14 A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 2 von 14

3 im elektr. Datenverkehr GmbH Inhaltsverzeichnis Datum Rev Autor Änderungen Patrick Hagelkruys Erste Version Patrick Hagelkruys Update Fehlercodes Patrick Hagelkruys Erweiterung der Schnittstelle Patrick Hagelkruys Überarbeitung Tabelle 1: Dokumentenhistorie A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 3 von 14

4 im elektr. Datenverkehr GmbH 1. Überblick 1.1. Zusammenfassung Ziel dieses Dokumentes ist die Beschreibung der Schnittstelle zur A-Trust REGISTRIER- KASSE mobile. A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 4 von 14

5 im elektr. Datenverkehr GmbH 2. Schnittstelle 2.1. Übersicht Als Schnittstelle zur A-Trust REGISTRIERKASSE mobile wird eine REST Schnittstelle (HTTP POST und HTTP GET) verwendet. In der URL muss ein Benutzername angegeben werden Signatur erstellen Der Signatur Aufruf besteht aus einem POST, dessen Inhalt ein JSON mit Passwort und zu signierende Daten ist. Die Antwort enthält die Signatur sowie den verwendeten Signaturalgorithmus Anfrage POST / R e g i s t r i e r k a s s e M o b i l e /v1/ Benutzername / Sign HTTP/ 1.1 Content Type: a p p l i c a t i o n / j s o n Host:... Content Length: 152 "password" : " ", " to_be_signed" : " c2ftcgxlihrlehqgz... WNl" Listing 1: Signatur Request A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 5 von 14

6 im elektr. Datenverkehr GmbH 2.3 Zertikatsinformationen abfragen Antwort HTTP/ OK Content Length: 130 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" : "BC4jJ\/ fdavbbln+y6h... egc7u=", "algo" : "ES256" Listing 2: Signatur Response 2.3. Zertikatsinformationen abfragen Die Abfrage der Zertikatsinformationen ist über einen GET Request realisiert Anfrage GET / R e g i s t r i e r k a s s e M o b i l e /v1/ Benutzername / C e r t i f i c a t e HTTP/1.1 Host:... Listing 3: Zertikatsinformation Request A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 6 von 14

7 im elektr. Datenverkehr GmbH 2.4 ZDA-Informationen abfragen Antwort HTTP/ OK Content Length: 1540 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 "Signaturzertifikat" : "MIIE... QA6o=", "Zertifizierungsstellen" : [ "MII...WSF" ], " Zertifikatsseriennummer" : " " Listing 4: Zertikatsinformation Response Die ersten beiden Zeilen der Antwort sind im geforderten Format für die Beleg Gruppe (siehe RKSV - Anlage Detailspezikation - Z6) ZDA-Informationen abfragen Die Abfrage der ZDA-Informationen ist über einen GET Request realisiert Anfrage GET / R e g i s t r i e r k a s s e M o b i l e /v1/ Benutzername /ZDA HTTP/ 1.1 Host:... Listing 5: ZDA-Informationen Request A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 7 von 14

8 im elektr. Datenverkehr GmbH2.5 Ausstellen einer A-Trust REGISTRIERKASSE mobile (Kundenkonto) Antwort HTTP/ OK Content Length: 15 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 "zdaid" : "AT1" Listing 6: ZDA-Informationen Response 2.5. Ausstellen einer A-Trust REGISTRIERKASSE mobile (Kundenkonto) Für das Erstellen eines Kundenkontos wird ein POST Request gesendet. Dieser beinhaltet das Passwort des Partners (partner_password) und Daten für den Ordnungsbegri. Die Antwort enthält die Zugangsdaten für das ausgestellte A-Trust REGISTRIERKASSE mobile Zertikat. Der Ordnungsbegri (u.b.: UID-Nummer) wird in zwei Werten angegeben. Als Unterscheidung der drei möglichen Kategorien wird ein Integer angegeben, sowie der Wert selbst. classication_key_type=0; UID-Nummer; z.b.: classication_key=atu classication_key_type=1; Global Location Number (GLN); z.b.: classication_key= classication_key_type=2; Finanzamt- und Steuernummer; z.b.: classication_key=12345/ Anfrage POST / R e g i s t r i e r k a s s e M o b i l e /v1/ partner_benutzername / Account HTTP/ 1.1 Content Type: a p p l i c a t i o n / j s o n Host:... Content Length: 261 " partner_password" : " partnerpwd", " classification_key_type" : 0, " classification_key" : " ATU ", " " : "test@test.com" Listing 7: Konto erstellen Request A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 8 von 14

9 im elektr. Datenverkehr GmbH2.5 Ausstellen einer A-Trust REGISTRIERKASSE mobile (Kundenkonto) Antwort HTTP/ OK Content Length: 130 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 "username" : "u ", "password" : " " Listing 8: Konto erstellen Response A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 9 von 14

10 im elektr. Datenverkehr GmbH 3. Testsystem Zu Testzwecken können folgende Parameter verwendet werden: URL: Benutzername: u Passwort: Partner Benutzername: partner4711 Partner Passwort: partnerpwd A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 10 von 14

11 im elektr. Datenverkehr GmbH 4. Implementierung des Aufrufs 4.1. Aufruf mit curl (Windows) c u r l. exe o outputsign. txt c a c e r t cas. pem X POST H "Content -Type: application/json" j s o n h t t p s : / /... / v1/ u / Sign Listing 9: Kommandozeilenaufruf Signatur "password" : " ", " to_be_signed" : " c2ftcgxlihrlehqgz... WNl" "signature" : "GkXDFLK3C... fejhpwaa ==", "algo" : "ES256" Listing 10: requestsign.json Listing 11: outputsign.txt c u r l. exe o outputcert. txt c a c e r t cas. pem X GET h t t p s : / /... / v1/ u / C e r t i f i c a t e Listing 12: Kommandozeilenaufruf Zertikatsinformationen "Signaturzertifikat" : "MIIE... QA6o=", "Zertifizierungsstellen" : [ "MII...WSF" ], " Zertifikatsseriennummer" : " " c u r l. exe o outputzda. txt c a c e r t h t t p s : / /... / v1/ u /ZDA Listing 13: outputcert.txt cas. pem X GET Listing 14: Kommandozeilenaufruf Zertikatsinformationen "zdaid" : "AT1" Listing 15: outputzda.txt A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 11 von 14

12 im elektr. Datenverkehr GmbH 4.2 Aufruf mit C-Sharp 4.2. Aufruf mit C-Sharp s t r i n g URL = "https: //.../v1/u /sign" ; s t r i n g r e q u e s t ""password"":"" "", ""to_be_signed"":""c2ftc... SBzZXJ2aWNl"" " ; byte [ ] data = System. Text. UTF8Encoding.UTF8. GetBytes ( r e q u e s t ) ; HttpWebRequest webrequest = ( HttpWebRequest ) WebRequest. C r e a t e (URL) ; webrequest. Method = " POST" ; webrequest. ContentType = " application/ json" ; webrequest. ContentLength = data. Length ; webrequest. GetRequestStream ( ). Write ( data, 0, data. Length ) ; HttpWebResponse webresponse = ( HttpWebResponse ) webrequest. GetResponse ( ) ; StreamReader r e a d e r = new StreamReader ( webresponse. GetResponseStream ( ), System. Text. UTF8Encoding.UTF8) ; s t r i n g ResponseText = reader. ReadToEnd ( ) ; Listing 16: C# Beispiel 4.3. Aufruf mit Java S t r i n g u r l S t r = "https ://.../ v1/u /sign" ; S t r i n g r e q u e s t = "\" password \":\" \", \" to_be_signed \":\" c2ftcgxl... XJ2aWNl \"" ; URL u r l = new URL( u r l S t r ) ; HttpURLConnection conn = ( HttpURLConnection ) u r l. openconnection ( ) ; conn. setrequestmethod ( "POST" ) ; conn. setdooutput ( true ) ; conn. setdoinput ( true ) ; conn. setusecaches ( f a l s e ) ; conn. s e t A l l o w U s e r I n t e r a c t i o n ( f a l s e ) ; conn. setrequestproperty ( "Content -Type", "application/json" ) ; OutputStream out = conn. getoutputstream ( ) ; Writer w r i t e r = new OutputStreamWriter ( out, "UTF -8" ) ; w r i t e r. w r i t e ( r e q u e s t ) ; w r i t e r. c l o s e ( ) ; out. c l o s e ( ) ; i f ( conn. getresponsecode ( )!= 200) throw new IOException ( conn. getresponsemessage ( ) ) ; A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 12 von 14

13 im elektr. Datenverkehr GmbH 4.3 Aufruf mit Java BufferedReader rd = new BufferedReader (new InputStreamReader ( conn. getinputstream ( ) ) ) ; S t r i n g B u i l d e r sb = new S t r i n g B u i l d e r ( ) ; S t r i n g l i n e ; while ( ( l i n e = rd. readline ( ) )!= null ) sb. append ( l i n e ) ; rd. c l o s e ( ) ; conn. d i s c o n n e c t ( ) ; S t r i n g r e s p o n s e S t r = sb. t o S t r i n g ( ) ; Listing 17: Java Beispiel A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 13 von 14

14 im elektr. Datenverkehr GmbH A. ReturnCode der Schnittstelle HTTP 200 Erfolgreich HTTP 400 (invalid bas64) Base64 der Inputdaten konnte nicht konvertiert werden HTTP 401 (invalid username or password) Benutzername oder Passwort falsch HTTP 403 (username blocked) Benutzer gesperrt HTTP 403 (username expired) Benutzer abgelaufen HTTP 403 (username not supplied) Benutzername nicht ausgefüllt oder zu kurz HTTP 403 (password not supplied) Passwort nicht ausgefüllt oder zu kurz HTTP 500 Allgemeiner Fehler HTTP 500 (error loading signing key) Signaturschlüssel konnte nicht geladen werden A-Trust REGISTRIERKASSE mobile Version: 0.4 Seite 14 von 14