Handleiding. CRABTools. Webservice met utilitaire methodes voor het gebruik van CRAB 0.1. Agentschap voor Geografische Informatie Vlaanderen

Transcriptie

1 Handleiding CRABTools Webservice met utilitaire methodes voor het gebruik van CRAB 0.1 Agentschap voor Geografische Informatie Vlaanderen Gebroeders Van Eyckstraat 16 T info@agiv.be BE-9000 Gent F

2 Versie 0.1 Auteur Sammy Dalewyn Datum aanmaak 9 september 2008 Datum afdruk 20 april 2009 Interne bestandsnaam Handleiding_CRABTools.docx Documenthistoriek 0.1: initiële versie 2 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

3 Inhoud Inhoud 3 1 Inleiding Wat kan u met deze dienst doen? Waar komen de gegevens vandaan? Hoe kan u gebruik maken van deze dienst? juridisch administratief technisch 4 2 Webservice interfaces SOAP Header SOAP Body SOAP Fault Security 7 3 Operaties en datatypes Overzicht GetCRABMatch request response Toelichting bij de interpretatie Fouten GetAddressLocation request response Kwaliteit van de positiebepaling 18 4 Client implementatie Microsoft.Net Framework Stap 1: Genereren client proxy en datatypes Stap 2: Implementeren webservice client op basis van proxy class Java en WSIT Stap 1: Genereren client proxy en datatypes Stap 2: Implementeren webservice client op basis van proxy class 21 5 Verwante informatie Error! Bookmark not defined. Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 3 / 21

4 1 Inleiding 1.1 Wat kan u met deze dienst doen? Met de CRABTools service kan u aan geocoding doen. Een eerste operatie laat toe om uw eigen adressen (mogelijks in rijksregisternotatie) om te zetten naar bestaande CRAB adressen. Als u een match hebt gevonden, kan u daarmee verder om met behulp van de tweede operatie de positie van het adres op te vragen. 1.2 Waar komen de gegevens vandaan? Voor de oorspronkelijke aanmaak van het CRAB werd een hele batterij aan bronbestanden stap voor stap gecontroleerd en ingeladen. Als bronbestanden gebruikte men het Rijksregister voor de straatnamen, een subset van de kadastrale legger voor de huisnummers en de koppeling met de percelen (in samenwerking met AAPD), een wegenbestand voor de straatkanten en de koppeling met de wegen en het kadastraal percelenplan voor de adresposities. Centraal in het CRAB staan de ongeveer 2,5 miljoen huisnummers en straatnamen die Vlaanderen rijk is. Het aanmaken van een databank met deze bronbestanden vormde geen gemakkelijke klus omdat de gegevens zich niet zomaar in een CRAB-kleedje laten steken. Dat heeft te maken met de strikte objectdefinities in het CRAB, definities waaraan een deel van de brongegevens niet voldoet. Voeg daar nog de incompatibiliteit van de coderingssystemen aan toe (waardoor men bv. een straat in het Rijksregister niet zomaar kan koppelen aan een straat in de kadastrale legger) en de vele fouten (huisnummers met twee straatnamen, wegen met onbekende Rijksregister-straatcodes, enzovoort) en men kan begrijpen waarom de aanmaak van het CRAB een werk van lange adem vormde. Het Centraal Referentie Adressen Bestand (CRAB) is een centrale gegevensbank met adresgegevens in Vlaanderen. Ze is ontstaan uit een integratie van volgende bestaande bronbestanden: straatnamen van het rijksregister, straatnamen, huisnummers en de koppeling met percelen van het kadaster, straatnamen en hun ligging van NavTeq, huisnummers en subadressen van VKBO (Verrijkte Kruispuntbank Ondernemingen) en eigen gegevens van het AGIV (vnl. GRB). Centraal in de databank staan straten en 2,5 miljoen adressen. 1.3 Hoe kan u gebruik maken van deze dienst? juridisch administratief Indien dat nog niet is gebeurd (bv. in het kader van een andere AGIV toepassing) dan dient u zich eerst te registeren op Na validatie van uw registratie ontvangt u een met uw gebruikersnaam en wachtwoord. Rol kiezen, validatie, gemeente kiezen, start technisch U dient te beschikken over een client toepassing die gepaste SOAP berichten kan uitwisselen. U dient over een gebruikersnaam en wachtwoord te beschikken. U kan alle entiteiten bevragen. U kan enkel die entiteiten bewerken die binnen de eigen gemeentegrenzen liggen. Alle bewerkingen worden nog gevalideerd alvorens ze in de operationele databank worden doorgedrukt. 4 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

5 2 Webservice interfaces Services worden beschreven met behulp van WSDL (Web Services Definition Language). Een WSDL-document is een XML-document bestaande uit een verzameling definities die de ontwikkelaar toelaten een client implementatie te bouwen. De WSDL kan verwijzen naar externe schema s die informatie bevatten over de elementen nodig voor de beveiliging op message level of over domeintypes die in de service gebruikt worden. Verschillende frameworks ondersteunen de ontwikkelaar door een deel van de client code automatisch te genereren. Deze dienst maakt gebruik van de W3C standaard SOAP 1.2 over HTTP en volgt verder de WS-I Basic Profile 1.1 richtlijn om interoperabiliteit te verzekeren. Elk SOAP bericht bevat een SOAP Envelope die op haar beurt bestaat uit een SOAP Header en een SOAP Body. Een SOAP response kan ook een SOAP fault bevatten wanneer bij het verwerken van de SOAP request iets verkeerd gaat. <?xml version="1.0"?> <soap:envelope xmlns:soap=" soap:encodingstyle=" <soap:header> </soap:header> <soap:body> <soap:fault> </soap:fault> </soap:body> </soap:envelope> 2.1 SOAP Header De SOAP header bevat volgende elementen: Figuur 1: Basisskelet van een SOAP bericht het <Action> element dat de gevraagde operatie van de service aanduidt: een <MessageID> element dat een door de gebruiker toegekende unieke waarde bevat om het request bericht te identificeren; in het response bericht wordt diezelfde waarde in het <RelatesTo> element terug gegeven zodat request en response aan elkaar kunnen gekoppeld worden; het <ReplyTo> element dat het adres bevat waarnaar de response moet worden gestuurd (indien verschillend van het adres van afzending); het <To> element dat het end point aanduidt van de service; het <Security> element bevat elementen die de integriteit en de vertrouwelijkheid van een bericht garanderen; de gebruikte mechanismen worden beschreven in 2.4. Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 5 / 21

6 <s:header> <a:action s:mustunderstand="1" u:id="_4" xmlns:u=" ssecurity-utility-1.0.xsd" xmlns:a=" </a:action> <a:messageid u:id="_5" xmlns:u=" wssecurity-utility-1.0.xsd" xmlns:a=" urn:uuid:a81da8ba-8adc-4461-b77b-d7c4127eb3e1 </a:messageid> <a:replyto u:id="_6" xmlns:u=" wssecurity-utility-1.0.xsd" xmlns:a=" <a:address> </a:replyto> <a:to s:mustunderstand="1" u:id="_7" xmlns:u=" wssecurity-utility-1.0.xsd" xmlns:a=" </a:to> <o:security s:mustunderstand="1" xmlns:o=" wssecurity-secext-1.0.xsd">... </s:header> Figuur 2: Voorbeeld van een SOAP Header 2.2 SOAP Body In het request bericht bevat de SOAP body de parameters nodig om de in het header element <Action> vermelde operatie uit te voeren. In het geval van een parameterloze operatie blijft de SOAP body dus leeg. Een succesvol response bericht zal steeds een niet lege SOAP body bevatten met het resultaat van de gevraagde operatie. Voor de inhoud van de SOAP body wordt verder verwezen naar hoofdstuk 3 waar alle operaties in detail worden beschreven. Merk op dat de body van een request ook versleuteld wordt zoals dat in 2.4 beschreven wordt. <soap:body> <GetAddressLocation xmlns=" <housenumberid> </housenumberid> </GetAddressLocation> </soap:body> Figuur 3: Voorbeeld van een SOAP Body in een request message 6 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

7 2.3 SOAP Fault Indien er zich tijdens het verwerken van het request bericht fouten mochten voordoen, dan worden deze via SOAP fault in de request gemeld. <soap:body> <soap:fault> <faultcode>soap:server</faultcode> <faultstring>insufficient rights</faultstring> <detail /> </soap:fault> </soap:body> Figuur 4: Voorbeeld van een SOAP Fault Het element <faultcode> bevat een indicatie van de oorzaak van de uitzondering (client of server). Een beschrijving van de uitzondering wordt meegegeven in het element <faultstring>. Volgende uitzonderingen kunnen zich voordoen: TYPE Technisch Request validatie Authenticatie Autorisatie Inhoudelijk BESCHRIJVING Een onvoorziene fout door (tijdelijke) onbeschikbaarheid van een benodigde bron (server, databank,...). Een fout tijdens het valideren tegen het XML schema van de request (ontbreken van een verplicht header element, onjuiste opbouw van het body element). Een fout tijdens het controleren van de identiteit van de aanvrager (ongeldige gebruikersnaam, ongeldig wachtwoord, time-out security semantics verstreken). Een fout door het ontbreken van machtiging voor de dienst of de gevraagde operatie. Een fout in de request parameters (zoeken op een onbestaand veld, ongeldige waarde,...). 2.4 Security De service maakt gebruik van de SOAP Message Security 1.1 (WS-Security 2004) specificaties. Dit omvat volgende aspecten: Er wordt een User Name Token gebruikt voor de authenticatie van de eindgebruiker; deze bevat de gebruikersnaam en het wachtwoord van de gebruiker die zich bij AGIV heeft geregistreerd voor de service; op basis van deze gebruikersnaam wordt bepaald welke operaties door de gebruiker mogen uitgevoerd worden en eventueel voor welke gemeente de gebruiker editeerrechten heeft; Er wordt een Binary Security Token (met name een X.509 certificaat) gebruikt voor zowel de integriteit als de vertrouwelijkheid van de berichtenuitwisseling; Er wordt gebruik gemaakt van een XML Signature om de integriteit van het bericht te garanderen; Er wordt gebruik gemaakt van XML Encryption om de vertrouwelijkheid van het berichtenverkeer te garanderen. In onderstaande tabel is een overzicht opgenomen van de verschillende standaarden die worden gebruikt. Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 7 / 21

8 STANDAARD WS-Security 1.1 XML Signature XML Encryption WS-SecureConversation 1.3 LINK De stappen die dienen genomen te worden om een SOAP bericht om te vormen naar een bericht dat aan de gebruikte beveilingsvoorschriften voldoet zijn de volgende: 1. Voeg een <Security> element toe aan de SOAP header 2. Voeg een <TimeStamp> element toe aan het <Security> element 3. Voeg een <EncryptedKey> element toe aan het <Security> element (deze bevat een versleutelde vorm van de Binary Security Token) 4. Voeg een <UserNameToken> element toe aan het <Security> element 5. Voeg een <DerivedKeyToken> element toe aan het <Security> element (deze wordt berekend op basis van de Binary Security Token en wordt gebruikt voor het creëren van de Signature) 6. Voeg een <Signature> element toe aan het <Security> element 7. Voeg een tweede <DerivedKeyToken> element toe aan het <Security> element (deze wordt gebruikt voor de encryptie van de SOAP body, de UserNameToken en de Signature) 8. Vervang de inhoud van de SOAP body door een <EncryptedData> element 9. Vervang het <Signature> element door een <EncryptedData> element 10. Vervang het <UserNameToken> element door een <EncryptedData> element 11. Voeg een <ReferenceList> element toe aan het <Security> element (deze bevat verwijzingen naar de versleutelde delen van het bericht) In bijlage Error! Reference source not found. is het request bericht voor en na encryptie te zien (dus voor stap 7 en na stap 11). Stap 1 <s:header>... <o:security s:mustunderstand="1" xmlns:o=" wssecurity-secext-1.0.xsd">... </s:header> Stap 2 Figuur 5: stap 1 van de SOAP beveiliging De TimeStamp dient om de versheid van de security semantics na te gaan. Het wordt gebruikt bij de berekening van de Signature. De waardes dienen opgegeven te worden als een xsd:datetime type en moeten in UTC tijd zijn. <o:security> <u:timestamp u:id="uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-2" xmlns:u=" wss-wssecurity-utility-1.0.xsd"> <u:created> t10:57:41z</u:created> 8 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

9 <u:expires> t11:02:41.153z</u:expires> </u:timestamp> Figuur 6: stap 2 van de SOAP beveiliging Stap 3 Het <KeyIdentifier> element bevat de base64 encoded thumbprint van het X.509 certificaat. Het <CipherValue> element bevat de versleutelde sessiesleutel. Het algoritme dat gebruikt wordt voor de versleuteling is RSA-OAEP-MGF1P met een SHA1 digest. Dit asymmetrisch algoritme gebruikt daarvoor de publieke sleutel van het X.509 certificaat. De sessiesleutel wordt random gekozen door de client en is 40 tot 2000 bytes groot. <o:security> <e:encryptedkey Id="uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-1" xmlns:e=" <e:encryptionmethod Algorithm=" <DigestMethod Algorithm=" xmlns=" </DigestMethod> </e:encryptionmethod> <KeyInfo xmlns=" <o:securitytokenreference> <o:keyidentifier ValueType=" wss-soap-message-security-1.1#thumbprintsha1" EncodingType=" open.org/wss/2004/ 01/oasis wss-soap-message-security- 1.0#Base64Binary"> robybgufsrc0j7frn6zfs63egwk= </o:keyidentifier> </o:securitytokenreference> </KeyInfo> <e:cipherdata> <e:ciphervalue> WQKlnQ1YqU0KlT1kP2ljz9x/G6xi3Ypn8QIdnS+Gac/JhzNndPzEPpVqnTNjRWP7ajC0fE5I/AbCvKa7t9cu5r7 M+9zJBX/KNsYUC0y+JXFqU98tRQBGIh2x9WI6UkPblKAtHW6ePVIBrYO79Xrp6dODkbOmispODbeMjqrY6YI= </e:ciphervalue> </e:cipherdata> </e:encryptedkey> Figuur 7: stap 3 van de SOAP beveiliging Stap 4 Het <UserNameToken> element bevat de gebruikersnaam en het wachtwoord zoals ingegeven tijdens de registratie bij AGIV. Merk op dat het wachtwoord niet wordt versleuteld. Dit gebeurt in een latere stap. <o:security> <o:usernametoken u:id="uuid-1937dc4a-f830-4ad1-9b42-01bfd7ab0227-1" xmlns:o=" oasis wss-wssecurity-secext-1.0.xsd" xmlns:u=" oasis wss-wssecurity-utility-1.0.xsd"> <o:username>myusername</o:username> <o:password> mycleartextpassword</o:password> </o:usernametoken> Figuur 8: stap 4 van de SOAP beveiliging Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 9 / 21

10 Stap 5 Het <Reference> element verwijst naar het in stap 3 gecreëerde <EncryptedKey> element. Het <Offset> element en het <Length> element bepalen waar in de byte stream de gegenereerde sleutel is te vinden. Het <Nonce> element bevat een random base64 encoded seed value voor de berekening van de gegenereerde sleutel. De berekening van de gegenereerde sleutel gebeurt met het PSHA1 algoritme op volgende wijze: key = PSHA1(secret, label + seed) Secret staat daarbij voor de sessiesleutel. Indien niet anders gespecifieerd is label de waarde WS- SecureConversationWS-SecureConversation. <o:security> <c:derivedkeytoken u:id="_0" xmlns:c=" xmlns:u=" oasis wss-wssecurity-utility-1.0.xsd"> <o:securitytokenreference> <o:reference ValueType=" oasis-wss-soap-message-security-1.1#encryptedkey" URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-1"> </o:reference> </o:securitytokenreference> <c:offset>0</c:offset> <c:length>24</c:length> <c:nonce>ygsk7aiqsfemfsq9ou8cna==</c:nonce> </c:derivedkeytoken> Figuur 9: stap 5 van de SOAP beveiliging 10 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

11 Stap 6 De signature wordt berekend voor alle reeds aanwezige elementen (behalve de keys): <Body>, <Action>, <MessageId>, <ReplyTo>, <To>, <TimeStamp> en <UserNameToken>. Elk van die elementen wordt gecanonaliseerd met de C14N methode en de output daarvan wordt gevoed aan een HMAC-SHA1 algoritme waarop de digest van de individuele elementen in de respectievelijke <DigestValue> elementen terecht komt (de bookmark in <Reference>@URI verwijst naar de respectievelijke elementen). Ook het geheel van de genoemde elementen wordt gecanonaliseerd waarop de HMAC-SHA1 digest vervolgens in het <SignatureValue> element wordt geplaatst. Het algoritme gebruikt de in stap 5 gegenereerde sleutel zoals dat wordt aangegeven in het <KeyInfo> element. <o:security> <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" </CanonicalizationMethod> <SignatureMethod Algorithm=" </SignatureMethod> <Reference URI="#_2"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>SY5NsDjjUkOdFOoboaGGrHDiFoE=</DigestValue> </Reference> <Reference URI="#_4"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>qHWK5XqrTqGNK0c+9c1sn9L52uA=</DigestValue> </Reference> <Reference URI="#_5"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>E0NkLEjKilpGe/Ia5rdr9g69x/o=</DigestValue> </Reference> <Reference URI="#_6"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>CuNmjfm/U6y2+ZScFHyVRRpkyKQ=</DigestValue> </Reference> <Reference URI="#_7"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 11 / 21

12 </DigestMethod> <DigestValue>mC43VpmQjV2ZrU37W6nEhCLjv94=</DigestValue> </Reference> <Reference URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-2"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>FdJT/b/r7TVnS1LwhQHanOaHs1w=</DigestValue> </Reference> <Reference URI="#uuid-1937dc4a-f830-4ad1-9b42-01bfd7ab0227-1"> <Transforms> <Transform Algorithm=" </Transform> </Transforms> <DigestMethod Algorithm=" </DigestMethod> <DigestValue>sO5k6ae4E2DPSGLApuLNxsUFr0o=</DigestValue> </Reference> </SignedInfo> <SignatureValue>eI1P+RTs2C8H88LWYS/M37J5QKM=</SignatureValue> <KeyInfo> <o:securitytokenreference xmlns:o=" oasis wss-wssecurity-secext-1.0.xsd"> <o:reference URI="#_0"></o:Reference> </o:securitytokenreference> </KeyInfo> </Signature> Stap 7 Figuur 10: stap 6 van de SOAP beveiliging Deze stap is gelijkaardig aan stap 5. In ieder geval moet hier een andere random nonce waarde worden gebruikt. Merk op dat de elementen <Offset> en <Length> ontbreken en dat dus de respectievelijke default waarden 0 en 32 worden verondersteld. <o:security> <c:derivedkeytoken u:id="_1" xmlns:c=" xmlns:u=" oasis wss-wssecurity-utility-1.0.xsd"> <o:securitytokenreference> <o:reference ValueType=" message-security-1.1#encryptedkey" URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-1 </o:reference> </o:securitytokenreference> <c:nonce>jcjzvae+cziljryhyuvadw==</c:nonce> </c:derivedkeytoken> Figuur 11: stap 7 van de SOAP beveiliging 12 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

13 Stap 8 De inhoud van de SOAP body wordt volledig versleuteld. In het voorbeeld van 2.2 is dat dus het volledige <objectrequest> element. De versleuteling gebeurt met het AES256 algoritme in Cipher Block Chaining modus met de in stap 7 gecreëerde sleutel. De verwijzing naar die sleutel wordt geplaatst in <KeyInfo> <SecurityTokenReference><Reference>@URI. <s:body u:id="_2"> <e:encrypteddata Id="_3" Type=" xmlns:e=" <e:encryptionmethod Algorithm=" </e:encryptionmethod> <KeyInfo xmlns=" <o:securitytokenreference xmlns:o=" 2004/01/oasis wss-wssecurity-secext-1.0.xsd"> <o:reference URI="#_1"></o:Reference> </o:securitytokenreference> </KeyInfo> <e:cipherdata> <e:ciphervalue> 0n07yYDO562qcP3rS74P0fsfX8PbEGnqTNPcUGPru3ndjz40UpGe+d/CdQGRapMckhJ0rEgrWk3vwfgci9dmuHem oyibmesvwg3tapcj0qe= </e:ciphervalue> </e:cipherdata> </e:encrypteddata> </s:body> Stap 9 Figuur 12: stap 8 van de SOAP beveiliging Het in stap 6 gecreëerde <Signature> element wordt vervangen door zijn geëncrypteerde vorm. De versleuteling gebeurt wederom met het AES256-CBC algoritme en de in stap 7 gecreëerde sleutel. <o:security> <e:encrypteddata Id="_8" Type=" xmlns:e=" <e:encryptionmethod Algorithm=" </e:encryptionmethod> <KeyInfo xmlns=" <o:securitytokenreference> <o:reference URI="#_1"></o:Reference> </o:securitytokenreference> </KeyInfo> <e:cipherdata> <e:ciphervalue> hurvxucdchyrrxng+z8rkbbouxdimhkan2ziv1gdgokfyfeh30fpdj2br1mp6y0bjslm1cgnfgeocq7/lz7fworg ClRFeWdw9IhbTWQ+sFMPKwisOydybeniPA5rE2XBx1br/Q3bU1kbMEj56jrJ2x6fAy3VUgfXOq7HIc0SRkBlNgVx vlwzevxuyspzbdono8urwfqrt/o+msfvrjk5r1uxjwcq1k30wjug5n01tldixpig3k0syrdo3sgknwyz/zgos8km 8EUMDIcG8vGvrk9+2Gb9oRiY69TiVznA9xo/Mrki5F77WOYOTvkce5KME93yLm+RTw4zlSSvJqpy2tkpT6esNQux 34rWcch35EBwo/Dl1sdXN1REbx63FXM49zZ63rFOvoRW5lEhKvTNdQdDBabJ2Oq+6mDtlxI7ekYGy8J0ry0yq2CF wy717/gigtg9rm6yfoby8x5brqi01cq90eis9ectrsk2z7ch3/... </e:ciphervalue> </e:cipherdata> </e:encrypteddata> Figuur 13: stap 9 van de SOAP beveiliging Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 13 / 21

14 Stap 10 Het in stap 4 gecreëerde <UsernameToken> element wordt vervangen door zijn geëncrypteerde vorm. De versleuteling gebeurt opnieuw met het AES256-CBC algoritme en de in stap 7 gecreëerde sleutel. <o:security> <e:encrypteddata Id="_9" Type=" xmlns:e=" <e:encryptionmethod Algorithm=" </e:encryptionmethod> <KeyInfo xmlns=" <o:securitytokenreference> <o:reference URI="#_1"></o:Reference> </o:securitytokenreference> </KeyInfo> <e:cipherdata> <e:ciphervalue> 4Hpq5zK0Lg0FZtLbWTwZ1v3pJWTGfw96v+oI/4tdTsFCyW1s7nr6GxA2lOSkgbMyHULWFletcb0DbNWFqiHYlKQ0 kd2dprc8hynnuivfqxzieed7nxbncsynlutpckdopn6xsn8q++r/7was8qzttw0zyy1njksj6rxchsw2xi/t6gti 6O/lZs0zU8hRKtNgVsuVDvN+EhtCleEkzos4LHCFbBeAzolss+5ioQNROQzJGgto0p4961q84gn3drF21TUTjPOH oxwo4dbdvbstadfutr5r1aglowg5lnga6ewhkkyve0345w2vg5jkjtlbqb50fqlr6wei0gmpw4e666z9znjo0grb 3FrRyIQF7u8R5HW/gDYE5KIOhs9TQMPXEmr7k4OR5c8A19tntktpt8ZNS17/GDmOaBJ7/n/eRdVslLRSuQRsSFz8 CG17sBjhMYEpnl/cm9TyzHK2IzalhdzolzZwAnTPmuydnQBdcergUmnDGg8KiVU+oXyhJiO9ZBn0gKBJbJnwXfd6 HqEixvoXDavKOE3mvUTRA+zJ4Lyj+Wxvx9vEZPZRknGmzLRECsLSHi1czIEWeFgr1jMPyHdyRemrwIiFhkZwB8ol SZ8= </e:ciphervalue> </e:cipherdata> </e:encrypteddata> Stap 11 Figuur 14: stap 10 van de SOAP beveiliging Als laatste stap wordt aan het <Security> element een <ReferenceList> element toegevoegd met verwijzingen naar de geëncrypteerde delen van de SOAP request die in de vorige drie stappen zijn gecreëerd. <o:security> <e:referencelist xmlns:e=" <e:datareference URI="#_3"></e:DataReference> <e:datareference URI="#_8"></e:DataReference> <e:datareference URI="#_9"></e:DataReference> </e:referencelist> Figuur 15: stap 11 van de SOAP beveiliging 14 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

15 3 Operaties en datatypes 3.1 Overzicht Er zijn momenteel twee operaties: GetCRABMatch: met deze operatie kan men voor een gegeven adres het overeenkomstige CRAB adres opzoeken; deze operatie is in eerste instantie bedoeld voor de omzetting van adressen in rijksregisternotatie naar CRAB adressen, maar kan uiteraard ook voor andere formaten worden aangewend; GetAddressLocation: met deze operatie kan men de (gekende of berekende) terreinpositie voor een gegeven adres bekomen. Door beide operaties sequentieel te gebruiken kan men aan geocoding doen. Mogelijks worden in de toekomst nog extra operaties toegevoegd. In wat volgt worden de operaties en hun response en request parameters nader toegelicht. 3.2 GetCRABMatch request Aan de operatie GetCRABMatch wordt een <FormattedAddress> meegegeven als parameter. Figuur 16:het <FormattedAddress> element ELEMENT BoxNumber CityName HouseNumber NisCityCode PostalCode OMSCHRIJVING Bevat het huisnummertoevoegsel. In rijksregistertermen is dit het busnummer. Bevat de naam van de gemeente. Bevat het huisnummer. Bevat de NIS code van de gemeente. Bevat de postcode van het adres. Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 15 / 21

16 ELEMENT RrStreetCode Streetname OMSCHRIJVING Bevat de straatcode zoals toegekend door het rijksregister. Bevat de straatnaam. Geen enkele van de invoervelden is verplicht. Uiteraard is het vinden van een overeenkomstig CRAB adres makkelijker indien de invoer gedegen informatie bevat response De operatie GetCRABMatch geeft een <MatchResponse> element terug. Figuur 17: het <MatchResponse> element ELEMENT MatchFound Faults HouseNumberId StreetnameId SubAddressId OMSCHRIJVING Duidt aan of er minimaal één overeenkomstig CRAB adres is gevonden. Bevat een lijst van fouten die gevonden werden in de request. Bevat het CRAB huisnummerid van het gevonden CRAB adres (indien tot dit niveau opgelost). Bevat de CRAB straatcode van het gevonden CRAB adres. Bevat het CRAB subadresid van het gevonden CRAB adres (indien tot dit niveau opgelost) Toelichting bij de interpretatie In een eerste stap wordt getracht de overeenkomstige straatnaam terug te vinden in CRAB. Pas als dat gelukt is, wordt er gekeken naar huisnummers en eventuele busnummers. Het kan zijn dat een gevonden CRAB adres enkel bestaat uit een straatnaamid indien bijvoorbeeld geen huisnummerinformatie in de request werd meegegeven, of indien er geen overeenkomstig huisnummer werd gevonden in CRAB. Het antwoord kan nul, een of meerdere overeenkomstige CRAB adressen bevatten. Deze multipliciteit kan twee oorzaken hebben. Ofwel werd tijdens het zoeken naar de straatnaam geen 16 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

17 exacte overeenstemming gevonden, maar wel een aantal gelijkende straatnamen. Het is dan aan de aanroeper om verder te bepalen welke de juiste is. Ofwel bevatte de request een zogenaamd huisnummerbereik en werd dat omgezet naar individuele huisnummers Fouten Tijdens de interpretatie worden een aantal controles uitgevoerd die de aanroeper van de operatie kunnen bijstaan in het opschonen van diens gegevens. Het voorkomen van een of meerdere fouten in de response betekent niet noodzakelijkerwijs dat er geen overeenkomstig CRAB adres is gevonden. FOUTCODE OMSCHRIJVING 1 Ongeldige NIS gemeentecode: niet numeriek 2 Onbekende NIS gemeentecode: komt niet voor in CRAB 3 Onbekende gemeentenaam: komt niet voor in CRAB 4 Geen overeenkomst tussen NIS gemeentecode en gemeentenaam: verwijzen naar verschillende gemeentes 5 Ongeldige postcode: niet numeriek 6 Onbekende postcode: komt niet voor in CRAB 7 Ongeldige rijksregisterstraatcode: niet numeriek en geen wachtcode 8 Ongeldig huisnummer: bevat de waarde 0 9 Huisnummer in straatnaam: [0-9]+ als prefix in de straatnaam 10 Huisnummer met bisnummer in straatnaam: [0-9]+[A-Z] als prefix in de straatnaam Bisnummer niet in huisnummer maar in toevoegsel: niet-numeriek bisnummer in <BoxNumber> Adrescomplement niet interpreteerbaar: <BoxNumber> niet leeg, maar niet interpreteerbaar Geen overeenkomst tussen postcode en gemeentenaam: verwijzen niet naar eenzelfde gemeente Geen overeenkomst tussen postcode en NIS gemeentecode: verwijzen niet naar eenzelfde gemeente 3.3 GetAddressLocation request Aan de operatie GetAddressLocation wordt een <housenumberid> meegegeven als parameter. Dit is de code die binnen CRAB wordt gehanteerd voor de entiteit huisnummer. Bijgevolg kunnen enkel posities worden gegeven voor ons bekende huisnummer response De operatie GetAddressLocation geeft een <LocationResponse> element terug. Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 17 / 21

18 Figuur 18: het <LocationResponse> element ELEMENT Bbox Centroid HouseNumberIdExists Quality OMSCHRIJVING Bevat de omschrijvende rechthoek van het (de) geografische object(en) waarnaar de locatie verwijst. Bevat het zwaartepunt van het (de) geografische object(en) waarnaar de locatie verwijst. Duidt aan of het opgegeven huisnummerid al dan niet bestaat. Merk op dat indien het niet bestaat, er ook geen locatie wordt teruggegeven. Bevat een indicatie van het kwaliteitsniveau van de positiebepaling Kwaliteit van de positiebepaling Er wordt getracht een zo nauwkeurig mogelijke positie te bepalen voor het gegeven huisnummer. Daarvoor zijn een aantal niveau s gedefinieerd, waarbij steeds gestart wordt op het hoogste niveau. Wordt op dat niveau geen positionele informatie gevonden, dan wordt naar een niveau lager afgezakt. Wordt ook daar geen positionele informatie gevonden, dan wordt er opnieuw gezakt. Dit gaat zo verder tot het laagste niveau is bereikt. NIVEAU KWALITEIT 18 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

19 1 Positie bepaald op basis van koppeling aan een enkel GRB gebouw. 2 Positie bepaald op basis van koppeling aan meerdere GRB gebouwen. De positie is de interpolatie tussen de respectievelijke centroïdes. 3 Positie bepaald op basis van koppeling aan een enkel GRB perceel. 4 Positie bepaald op basis van koppeling aan meerdere GRB percelen. De positie is de interpolatie tussen de respectievelijke centroïdes. 5 Positie bepaald op basis van koppeling aan kadastraal perceel Positie bepaald op basis van koppeling aan meerdere kadastrale percelen. De positie is de interpolatie tussen de respectievelijke centroïdes. Positie bepaald op basis van interpolatie tussen de centroïdes van twee GRB gebouwen gekoppeld aan nevenliggende huisnummers. Positie bepaald op basis van interpolatie tussen de centroïdes van twee GRB percelen gekoppeld aan nevenliggende huisnummers. Positie bepaald op basis van interpolatie tussen de centroïdes van twee kadastrale percelen gekoppeld aan nevenliggende huisnummers. Positie bepaald op basis van interpolatie tussen begin- en eindknoop van een gekoppeld wegsegment met aanwezige nummeringsinformatie. Positie bepaald op basis van de centroïde van alle wegsegmenten behorend tot gekoppelde straat. 12 Positie bepaald op basis van de centroïde van de gekoppelde gemeente. 4 Client implementatie 4.1 Microsoft.Net Framework Het implementeren van een webservice client met het Microsoft.Net framework verloopt in twee stappen: Genereren client proxy class en datatypes Implementeren webservice client op basis van proxy class De eerste stap kan geheel automatisch verlopen met behulp van de tool svcutil.exe of met Visual Studio Stap 1: Genereren client proxy en datatypes svcutil.exe command-line tool 1. Open een Command Prompt venster 2. Tik het volgende commando in: svcutil 3. De tool genereert dan standaard twee bestanden: a. CRABTools.cs: bevat de domeinspecifieke datatypes en de eigenlijke proxy (standaard CRABToolsClient geheten) b. output.config: bevat een beschrijving van het end point en de specifieke binding Merk op dat de tool te vinden is in de folder %Program Files%\Microsoft WSE\v3.0\Tools Visual Studio start een nieuw client project Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 19 / 21

20 2. rechtsklik op de projectnaam en selecteer Add Service Reference 3. vul het adres in van de service ( 4. wijzig de namespace in CRABTools en klik op OK 5. het project bevat dan een referentie naar de service met ondermeer een kopij van de WSDL en de gerelateerde schema s, informatie over de binding en een broncodebestand met de domeinspecifieke datatypes en de eigenlijke proxy (standaard CRABToolsClient geheten); in het config bestand zijn een beschrijving van het end point en de specifieke binding opgenomen Stap 2: Implementeren webservice client op basis van proxy class Het aanroepen van de webservice kan op volgende manier gebeuren: //by supplying the endpointconfigurationname one does not have to set //the url, the binding and the service certificate reference by hand CRABToolsClient proxy = new CRAB_WSTClient("WSHttpBinding_ICRABTools"); proxy.clientcredentials.username.username = "myusername"; proxy.clientcredentials.username.password = "mypassword"; int housenumberid = 1234; LocationResponse location = proxy.getaddressposition(housenumberid); Figuur 19: gebruik van de webservice proxy 20 / 21 Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31

21 4.2 Java en WSIT Het implementeren van een webservice client met Web Services Interoperability Technologies (WSIT) verloopt in twee stappen: Genereren client proxy class en datatypes Implementeren webservice client op basis van proxy class Uitgebreide informatie over het gebruik van WSIT vindt u in de WSIT Tutorial: Stap 1: Genereren client proxy en datatypes fromwsdl tool De tool is te vinden in de library webservices-tools.jar en kan ofwel aangesproken worden vanuit een build task (vb. Ant) of bijvoorbeeld vanuit een batch bestand. Deze laatste mogelijkheid wordt hier beschreven. 1. Open een Command Prompt venster 2. Tik het volgende command in: wsimport 3. De tool genereert dan een bestand CRABToolsStub.java met daarin de domeinspecifieke types en de proxy NetBeans start een nieuw client project 2. rechtsklik op de projectnaam en selecteer New -> Web Service Client 3. selecteer de WSDL URL optie 4. vul het adres in van de service ( en klik op Finish Stap 2: Implementeren webservice client op basis van proxy class Hieronder volgt een beschrijving van het gebruiken van de web service proxy in NetBeans Ga in een methode waar de web service moet aangeroepen worden op een lege lijn staan 2. Rechstklik op die lege lijn en selecteer Web Service Client Resources -> Call Web Service Operation 3. Selecteer de gewenste operatie en klik op OK 4. De IDE voegt automatisch code toe Handleiding CRABTools 0.1 Handleiding_CRABTools.docx 20/04/2009 7:31 21 / 21