TNO Geologische Dienst Nederland

Transcriptie

1 TNO Geologische Dienst Nederland BRO Handleiding CPT Voorbeeldclient Versie 1.0

2 Documenthistorie Datum Versie Beschrijving Auteur Initiële versie F. Waardenburg Aanpassingen na review F.Waardenburg Naam Tim van Dijk x Wilfred Visser x Reviewers Pagina 2 van 19

3 Inhoudsopgave 1. Inleiding Doel Samenhang met andere documenten Referenties 4 2. Installatie Java JDK Aanpassing t.b.v. het werken met 256 bit AES encryptie Toevoegen server certificaat Eclipse IDE Eclipse configuratie Plugin installatie CPT Voorbeeldclient Client certificaat Client configuratie 7 3. Gebruik van de applicatie User interface Verzoek Panel Operatie panel Respons panel Fouten panel XML panel Werking Opzet Genereren van JAXB classes De CPT Referenceclient Opzet Interactie 14 Appendix A. Toevoegen van server certificaten 19 A.1 Verkrijgen van server certificaten 19 A.2 Toevoegen van certificaten aan een keystore 19 Pagina 3 van 19

4 1. Inleiding 1.1 Doel Dit document beschrijft de installatie, het gebruik en de werking van de CPT Voorbeeldclient. 1.2 Samenhang met andere documenten CPT Gegevensdefinitie CPT Koppelvlak beschrijving 1.3 Referenties Titel Versie Datum Vindplaats [1] Catalogus voor Geotechnisch Sondeeronderzoek [2] Koppelvlakbeschrijving CPT Innameservice [3] Koppelvlakbeschrijving CPT Uitgifteservice [4] <verkrijgen client certificaat> nov november 2015 Formele documentatie januari 2016 Formele documentatie januari 2016 Formele documentatie Pagina 4 van 19

5 2. Installatie De CPT Voorbeeldclient wordt opgeleverd in de vorm van een Eclipse project. Hiervoor zijn de volgende componenten benodigd: Java JDK Eclipse IDE CPT Voorbeeldclient project De installatie van deze componenten in een Windows omgeving wordt in dit hoofdstuk beschreven. 2.1 Java JDK Voor de CPT Voorbeeldclient is minimaal Java7 vereist. Deze kan van worden gedownload. De meest recente versie van Java JDK kan worden gedownload van De installer installeert Java default in folder C:\Program Files\Java. Er wordt zowel een JRE als JDK geïnstalleerd Aanpassing t.b.v. het werken met 256 bit AES encryptie De bestanden local_policy.jar en US_export_policy.jar in de %jdk%/jre/lib/security folder van de JAVA installatie moeten worden vervangen door een versie die 256 bit AES encryptie ondersteunt folder (%jdk% staat voor de JDK installatie folder). De hiervoor benodigde bestanden kunnen als UnlimitedJCEPolicyJDK7.zip (Java7) of jce_policy- 8.zip (Java8) worden gedownload van Hernoem de bestaande local_policy.jar en US_export_policy.jar in de ${jdk}/jre/lib/security folder naar b.v. local_policy.org en US_export_policy.org Download het benodigde bestand Pak dit uit op een willekeurige plek en kopieer de bestanden local_policy.jar en US_export_policy.jar naar de %jdk%/jre/lib/security Toevoegen server certificaat Om een SSL connectie met een BRO server te kunnen maken moet deze vertrouwd ( trusted ) zijn. Dit kan worden gerealiseerd door de server certificaten aan de keystore van de Java installatie (%jdk%/jre/lib/security/cacerts ) toe te voegen of door ze toe te voegen aan een willekeurige keystore. In het eerste geval hoeft de locatie van de keystore niet gespecificeerd te worden in de client configuratie. In het tweede geval moet de locatie van de keystore wel worden gespecificeerd ( zie par ). Het toevoegen van certificaten aan een keystore wordt beschreven in appendix A. 2.2 Eclipse IDE De Eclipse IDE kan van worden gedownload. Minimaal versie is Luna. Download het benodigde bestand, b.v. eclipse-jee-luna-sr2-win32-x86_64.zip Extract de inhoud naar C:\Program Files Open het bestand C:\Program Files\eclipse\eclipse.ini en voeg voor de regel vmargs de volgende regels toe (%jdk% staat voor de JDK installatie folder): -vm %jdk%\bin\javaw.exe Pagina 5 van 19

6 2.2.1 Eclipse configuratie Eclipse IDE kan nu worden gestart door te dubbel klikken op C:\Program Files\eclipse\eclipse.exe. Eclipse slaat projecten op in een workspace folder. Default is dit de folder workspace in de user directory. Behalve de workspace moet ook de Installed JRE s worden aangepast, zodat de actuele JRE wijst naar een JDK i.p.v. JRE: Start Eclipse Accepteer de default workspace Ga naar Window Preferences en kies Java Installed JRE s Voeg %jdk% toe en verwijder JRE(default) (%jdk% staat voor de JDK installatie folder) Plugin installatie Om met maven en jaxws te kunnen werken moeten nog enige plugins geïnstalleerd worden: Ga naar Help Install New Software Vul bij Work with in en selecteer m2e connector for the Maven Dependency Plugin Kies twee keer Next> en accepter de license agreement Ga naar Help Install New Software Vul bij Work with : in en selecteer CoderPlus M2E Connectors Kies Next> en Finish Herstart Eclipse 2.3 CPT Voorbeeldclient De CPT Voorbeeldclient kan uit GitHub worden gedownload: Ga in een browser naar: Download de Voorbeeldclient m.b.v. de Download ZIP button. Hiervoor is een geldig GDN LDAP account benodigd. Pak de gedownloade file cpt_javavoorbeeldclient.zip uit in de Eclipse workspace. De CPT Voorbeeldclient moet nu in de workspace worden geïmporteerd door: Ga naar File Import Kies Maven Existing Maven Projects en Next > Vul bij Root Directory de folder in waar de CPT Voorbeeldclient is uitgepakt (%Eclipse Workspace%\cpt_referentieclient-master) Selecteer bij Projects beide pom s Kies Finish De workspace wordt nu automatisch gebuild en kan in de Project Explorer geopend worden De CPT Voorbeeldclient kan nu worden uitgevoerd, maar moet nog wel worden geconfigureerd Client certificaat Om met een BRO service te kunnen communiceren moet de client in de meeste aantal gevallen over een PKCS12 client certificaat beschikken. In [4] wordt beschreven hoe een PKCS12 certificaat kan worden verkregen. Pagina 6 van 19

7 2.3.2 Client configuratie De voor de CPT Voorbeeldclient benodigde instellingen worden gedefinieerd m.b.v. het bestand client.properties in de folder src/main/resources van het client project (cpt_rc_client): parameter nl.broclients.cpt.client.endpoint.iscpt nl.broclients.cpt.client.endpoint.dscpt nl.broclients.cpt.client.authentication.basic.username nl.broclients.cpt.client.authentication.basic.password nl.broclients.cpt.client.authentication.pkcs12.store beschrijving endpoint en authenticatie optie (none, basic of certificate, zie par ) voor de inname (intake) service, van elkaar gescheiden door een spatie endpoint en authenticatie optie (none, basic of certificate, zie par ) voor de uitgifte (dispatch) service, van elkaar gescheiden door een spatie gebruikersnaam die aan de service wordt doorgegeven wanneer basic authentication wordt toegepast password dat aan de service wordt doorgegeven wanneer basic authentication wordt toegepast locatie van de PKCS12 keystore die gebruikt wordt om de SSL key manager te configureren; de PKCS12 keystore wordt alleen gebruikt wanneer certificate authentication wordt toegepast nl.broclients.cpt.client.authentication.pkcs12.password password van de gespecificeerde PKCS12 keystore nl.broclients.cpt.client.authentication.jks.store nl.broclients.cpt.client.authentication.jks.password nl.broclients.cpt.client.authentication.debug locatie van het JKS truststore (waaraan de server certificaten zijn toegevoegd, zie par ) die gebruikt wordt om de SSL trust manager te configureren; wanneer geen truststore wordt gespecificeerd wordt de keystore van de JDK installatie gebruikt password van de gespecificeerde JKS truststore specificeert een debug optie voor SSL socket communicatie: all ssl:handshake ssl:record Opmerkingen: Debug informatie wordt weergeven in de console en kan behulpzaam zijn bij het oplossen van SSL problemen Paden moeten in het configuratiebestand ook in een Windows omgeving worden gedefinieerd met forward slashes Pagina 7 van 19

8 Voorbeeld configuratie: nl.broclients.cpt.client.endpoint.iscpt= certificate nl.broclients.cpt.client.endpoint.dscpt= certificate nl.broclients.cpt.client.authentication.pkcs12.store=c:/certificates/bro-ac-testclient.gdnnet.nl.p12 nl.broclients.cpt.client.authentication.pkcs12.password=****** nl.broclients.cpt.client.authentication.jks.store= nl.broclients.cpt.client.authentication.jks.password= nl.broclients.cpt.client.authentication.debug=ssl:handshake Pagina 8 van 19

9 3. Gebruik van de applicatie De CPT Voorbeeldclient kan in de Eclipse omgeving worden uitgevoerd m.b.v. de optie: Run As Java Application m.b.t. het bestand CptReferenceClient.java in de folder cpt_rc_client/src/main/java/nl.broclients.cpt.client. Dit commando genereert een Run Configuratie die later m.b.v. de button geactiveerd kan worden. Tijdens het build proces (Run As Maven Install m.b.t. de pom van het cpt_rc_client project) wordt een executable jar gegenereerd in de target folder van het cpt_rc_client project. Deze kan op de command line worden uitgevoerd d.m.v.: java jar <target folder>/cpt_rc-jar-with-dependencies.jar 3.1 User interface De user interface bestaat uit vijf onderdelen: Verzoek panel - toont de parameters die relevant zijn voor het geselecteerde (type) request Operatie panel - toont de service url en authenticatie optie (zoals gedefinieerd in de properties), de verwerkingsduur en de status van de applicatie tijdens de uitvoering van een verzoek Respons panel - toont de (generieke) parameters die door de service geretourneerd worden Fouten panel - toont de fout(en) die door de service geretourneerd worden XML panel toont de XML weergave van het verzoek en de respons Pagina 9 van 19

10 3.1.1 Verzoek Panel M.b.v. het verzoek panel kan door de gebruiker worden gespecificeerd welk verzoek naar de service wordt verzonden. Een verzoek bestaat over het algemeen uit transactiegegevens en een brondocument. In de onderstaande tabel is weergegeven welke verzoek parameters relevant zijn voor welk type request: request type request transactiegegevens bron verzoek kenmerk kwaliteitsregime corrective rede BRO id criteria document Inname RegisterCPT CorrectCPT Uitgifte DispatchCPTObject DispatchCPTCharacteristics Het brondocument dat naar de BRO wordt opgestuurd kan door de CPT Voorbeeldclient worden gegenereerd (Intern optie) of door de gebruiker worden aangeleverd (Extern optie). In het eerste geval wordt steeds hetzelfde document (voor het geselecteerde kwaliteitsregime) opgestuurd. Het door de CPT Voorbeeldclient gegenereerde registratie of correctie brondocument kan naar een extern bestand worden geschreven m.b.v. de button. Dit bestand kan vervolgens worden aangepast en m.b.v. de extern optie worden opgestuurd, nadat het m.b.v. de button is geopend. De button toont informatie m.b.t. de gebruiksrechten van de CPT Voorbeeldclient Operatie panel Het Operatie panel toont het endpoint en de authenticatie optie van de service waarnaar het verzoek verstuurd wordt (zoals geconfigureerd in het client.properties bestand). Tijdens de verwerking wordt de status van de applicatie weergegeven. De verwerkingsduur geeft aan hoeveel tijd de service nodig had om het verzoek te verwerken. De CPT Voorbeeldclient ondersteunt drie vormen van authenticatie: None de client verstuurt het verzoek zonder eigenschappen aan de header toe te voegen of een PKCS12 keymanager te definiëren Basic door de client worden de in het bestand client.properties gedefinieerde eigenschappen username en password aan de header van het verzoek toegevoegd; er wordt geen PKCS12 keymanager gedefinieerd Certificate door de client wordt een PKCS12 keymanager gedefinieerd op basis van de geconfigureerde eigenschappen pkcs12.store en pkcsd12.password Een JKS trustmanager wordt gedefinieerd wanneer van SSL gebruik wordt gemaakt. De trustmanager wordt gedefinieerd op basis van de geconfigureerde eigenschappen jks.store en jks.password. Pagina 10 van 19

11 De buttons tonen informatie m.b.t. de service waarnaar het (inname of uitgifte) verzoek wordt gestuurd: WSDL: beschrijving van de interface van de (inname of uitgifte) service XSD: de door de BRO gedefinieerde schema s waarvan de client en service gebruik maken en informatie m.b.t. de authenticatie: Respons panel Het Respons panel toont (een deel van) de informatie die na de verwerking van een verzoek door de server geretourneerd wordt. Het betreft m.n. de attributen die gemeenschappelijk zijn voor alle type responses: request type request verzoek kenmerk respons type verwerking acceptatie levering afwijzing transactie id BRO id Inname RegisterCPT Pagina 11 van 19

12 CorrectCPT Uitgifte DispatchCPTObject DispatchCPTCharacteristics De response datum heeft betrekking op het tijdstip van verwerking (bij registratie), acceptatie (bij correctie), levering of afwijzing. Wanneer een Kenmerkenverzameling wordt geretourneerd wordt tevens aangegeven uit hoeveel elementen deze bestaat Fouten panel Het Fouten panel toont foutmeldingen die worden gegenereerd in de CPT Voorbeeldclient of door de service tijdens de verwerking van het request. Hierbij wordt onderscheid gemaakt tussen systeemfouten, software fouten en gebruiksfouten. Systeem- en softwarefouten worden als uitzondering (exception) door de service geretourneerd, gebruiksfouten als response van het type Afwijzing. Software- en gebruiksfouten kunnen behalve de melding ook een of meer detail meldingen bevatten: type fout type melding detail melding(en) Uiitzondering Systeemfout Er is een fout opgetreden in het BRO systeem - Softwarefout Het verzoek voldoet niet aan het schema XML validatiefout(en) Afwijzing respons Gebruiksfout een van gebruiksfouten die voor de service gedefinieerd zijn - Er zijn 1 of meer fouten geconstateerd in het brondocument Brondocument validatiefout(en) Er zijn 1 of meer fouten geconstateerd in de kenmerkenverzameling Kenmerk validatiefout(en) Client fout een van de fouten die in de referentiecliënt kunnen optreden XML panel Het XML panel toont zowel het door de client verstuurde verzoek als de door de server geretourneerde respons in XML formaat met syntax highlighting. Pagina 12 van 19

13 4. Werking 4.1 Opzet Het CPT Voorbeeldclient (cpt_rc) project bestaat uit twee subprojecten: cpt_rc_ws en cpt_rc_client. Het eerstgenoemde (sub)project is bedoeld om op basis van de WSDL en XSD s JAXB classes te genereren. Het tweede project definieert de client en maakt gebruik van de gegenereerde JAXB classes. 4.2 Genereren van JAXB classes Het cpt_rc_ws (sub)project bevat in de resource folder de voor de inname en uitgifte service benodigde wsdl en xsd bestanden: schema/brocommon.xsd schema/cptcommon.xsd schema/dscpt-messages.xsd schema/iscpt-messages.xsd wsdl/dscpt.wsdl wsdl/iscpt.wsdl De versies van deze bestanden moeten overeenkomen met de versies die door de inname resp. uitgifte service gebruikt wordt. Eventueel kunnen wsdl s worden opgevraagd van de server. Naaste de genoemde xsd en wsdl bestanden spelen een aantal andere bestanden een rol bij het genereren van JAXB classes door de jaxws plugin: src/main/resources/meta-inf/binding.xjb bevat een aantal aanvullende/afwijkende regels voor het genereren van XLINK, GML, SWE en CPT classes src/main/resources/meta-inf/catalog.xml definieert de fysieke locatie van wsdl s en xsd s door system id s te mappen naar projectfolders src/main/java/nl/broservices/xsd/iscpt._1/package-info.java en src/main/java/nl/broservices/xsd/dscpt._1/package-info.java definieren prefixes voor de in de inname resp. uitgifte service gebruikte namespaces De JAXB classes worden gegenereerd m.b.v. de optie Run As Maven Install m.b.t. de pom van het cpt_rc_ws project. De gegenereerde classes komen terecht in de folder target/generatedsources/xjc: net.opengis.gml.v_3_2_1 net.opengis.om._2 net.opengis.sampling._2 net.opengis.swe._2 nl.broservices.wsdl.iscpt._1 nl.broservices.wsdl.dscpt._1 nl.broservices.xsd.brocommon._2 nl.broservices.xsd.cptcommon._1 nl.broservices.xsd.iscpt._1 nl.broservices.xsd.dscpt._1 4.3 De CPT Referenceclient Opzet De client is opgezet volgens het MVC patroon. De view presenteert het model aan de gebruiker. Gebruikersinvoer wordt via ActionEvents door de controller gebruikt om de state van het RequestModel aan te passen. State veranderingen worden m.b.v. PropertyChange events doorgegeven aan de view. Pagina 13 van 19

14 Voor het versturen van een request is de Service verantwoordelijk. Aan de hand van de state van het RequestModel, ClientProperties en een SourceDocument (bij inname) of Criteria (bij uitgifte) wordt door de ServiceRequest klasse een request samengesteld dat naar de inname- of uitgifteservice (IsCpt resp. DsCpt) wordt gestuurd. De respons en eventuele excepties worden door de ServiceResponse klasse verwerkt door de state van het ResponseModel aan te passen, hetgeen via PropertyChange events lijdt tot aanpassing van de view. class Entities ClientProperties ViewController Serv ice «WebService» IsCpt «WebService» DsCpt View actionevent update «JAXB» SourceDocument «JAXB» Criteria Serv icerequest RequestPanel OperationPanel notify RequestModel ResponsePanel ErrorPanel notify ResponseModel update Serv iceresponse XmlPanel Interactie In de volgende sequence diagrammen is voor een aantal processen weergegeven hoe en in welke volgorde objecten met elkaar interacteren. Pagina 14 van 19

15 Initializatie van de applicatie sd Init CptReferenceClient Locale setdefault(language) MainFrame setvisible(true) RequestModel ResponseModel new(mainframe, requestmodel, responsemodel) ViewController ClientProperties new(controller) addpropertychangelistener(requestpanel) «JPanel» RequestPanel load() new(controller) addpropertychangelistener(operationpanel) «JPanel» OperationPanel addpropertychangelistener(operationpanel) addpropertychangelistener(responsepanel) «JPanel» ResponsePanel addpropertychangelistener(responsepanel) addpropertychangelistener(errorpanel) «JPanel» ErrorPanel addpropertychangelistener(requestxmlpanel) «JPanel» RequestXMLPanel ResponseXMLPanel addpropertychangelistener(responsexmlpanel) initialize() setendpoints() setauthentications() setrequestreference() setrequesttype() Pagina 15 van 19

16 Het versturen van een request sd Send ViewController RequestModel ResponseModel ServiceRequest ServiceResponse SourceDocument Marshaller actionperformed() Send dosend() setrequestxml(null) clear() validate() new(requestmodel, responsemodel, clientproperties) Service setstate(creating_request) Thread start() run() getrequest(requestmodel) getwraprdcpt() setrequestxml() setrequestxml() marshal(request) setstate(waiting_for_response) :request getintakeservice() «JAXWS» Iscpt/Dscpt setcontext() registercpt(request) :response setstate(processing_response) processresponse(response, responsemodel) processintakeresponse() set<parameter>() setresponsexml() setresponsexml() marshal(response) setstate(idle) Pagina 16 van 19

17 Intern vs. extern brondocument sd SourceDocument ServiceRequest «ObjectFact... ISCPT_OF RequestModel SourceDocument JaxbUtil getregistercptrequest(requestmodel) start createregistercptrequesttype() :registercptrequesttype getrequestreference(): String getqualityregime(): String alt source [source = internal] getwraprdcpt(qualityregime) [source = external] createwraprdcpttype() :wraprdcpttype getsourcefile(): File unmarshal(sourcefile) :RDCPTType Pagina 17 van 19

18 Verwerken van response sd ResponseProcessing ServiceResponse ResponseModel ServiceError IntakeResponseType ParseFaultType SOAPFaultException Detail Marshaller processregistercptresponse(response, responsemodel) start processintakeresponse(response, responsemodel) setresponsetype(responsetype) setrequestreference(requestreference) settransactionid(transactionid) setbroid(broid) setresponsetime(responsetime) alt rejected [rejected] new(use, SOURCE_DOCUMENT, rejectionreason) adddetailspecification() seterror() setresponsexml(responsemodel) setresponsexml(xml) marshal(): xml setstate(idle) processparsefault(parsefault, responsemodel) setresponsetype(exception) setrequestreference() getrequestreference(): String gettransactionid(): String settransactionid(transactionid) setresponsetime(responsetime) new(software, PARSE, rejectionreason) adddetailspecification() seterror() setstate(idle) processsoapfault(soapfaultexception, responsemodel) setresponsetype(exception) getfault().getdetail: Detail getattribute("requestreference") getattribute("transactionid") setrequestreference() settransactionid() new(system, rejectionreason) seterror() setstate(idle) Pagina 18 van 19

19 Appendix A. Toevoegen van server certificaten A.1 Verkrijgen van server certificaten De BRO webservers maken gebruik van Quo Vadis certificaten. Voor de productie- en inregelomgeving zijn verschillende certificaten benodigd: productieomgeving bestandsnaam download URL QuoVadis PKI Overheid RootCA PKIo_QuoVadis_CA_G2.cer Staat der Nederlanden Root CA - G2 RootCA-G2.cer Staat der Nederlanden Organisatie CA - G2 DomOrganisatieCA-G2.cer inregelomgeving bestandsnaam download URL TRIAL QuoVadis CSP - PKI Overheid TEST CA - G2 PKIo_QuoVadis_TRIALCA_G2.cer TRIAL PKIoverheid TEST Root CA - G2 PKIo_TRIALRootCA.cer TRIAL PKIoverheid Organisatie TEST CA - G2 PKIo_TRIALOrgCA.cer A.2 Toevoegen van certificaten aan een keystore Server certificaten kunnen met de standaard Java command line tool keytool aan een keystore worden toegevoegd. In dit voorbeeld wordt de standaard Java CACerts keystore (met default password: changit) gebruikt om de certificaten voor de inregelomgeving op te slaan. Dit script moet als administrator uitgevoerd worden. set JAVA_JDK_HOME=%jdk% set CERTPATH=%crt% set KEYTOOL=%JAVA_JDK_HOME%\jre\bin\keytool.exe set KEYSTORE_FILE=%JAVA_JDK_HOME%\jre\lib\security\cacerts set KEYSTORE_PASS=changeit set CERT="%CERTPATH%\PKIo_QuoVadis_TRIALCA_G2.cer" %KEYTOOL% -importcert -noprompt -trustcacerts -alias %CERT% -keystore %KEYSTORE_FILE% -storepass %KEYSTORE_PASS% -file %CERT% set CERT="%CERTPATH%\PKIo_TRIALOrgCA.cer" %KEYTOOL% -importcert -noprompt -trustcacerts -alias %CERT% -keystore %KEYSTORE_FILE% -storepass %KEYSTORE_PASS% -file %CERT% set CERT="%CERTPATH%\PKIo_TRIALRootCA.cer" %KEYTOOL% -importcert -noprompt -trustcacerts -alias %CERT% -keystore %KEYSTORE_FILE% -storepass %KEYSTORE_PASS% -file %CERT% %jdk% staat voor de JDK installatie folder, %crt% voor de folder waarin de certificaten zijn opgeslagen Pagina 19 van 19