CRABTools - Vlaanderen Interncrab.beta.agiv.be/Manuals/Handleiding_CRABTools_v0.1.pdf · Agentschap...

Agentschap voor Geografische Informatie Vlaanderen

Gebroeders Van Eyckstraat 16 T +32 9 261 52 00 [email protected]

BE-9000 Gent F +32 9 261 52 99 www.agiv.be

Handleiding

CRABTools

Webservice met utilitaire methodes

voor het gebruik van CRAB

0.1


2 / 21 Handleiding CRABTools • 0.1 • Handleiding_CRABTools.docx • 20/04/2009 7:31

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


Handleiding CRABTools • 0.1 • Handleiding_CRABTools.docx • 20/04/2009 7:31 3 / 21

Inhoud

Inhoud 3

1 Inleiding 4

1.1 Wat kan u met deze dienst doen? 4

1.2 Waar komen de gegevens vandaan? 4

1.3 Hoe kan u gebruik maken van deze dienst? 4

1.3.1 juridisch 4

1.3.2 administratief 4

1.3.3 technisch 4

2 Webservice interfaces 5

2.1 SOAP Header 5

2.2 SOAP Body 6

2.3 SOAP Fault 7

2.4 Security 7

3 Operaties en datatypes 15

3.1 Overzicht 15

3.2 GetCRABMatch 15

3.2.1 request 15

3.2.2 response 16

3.2.3 Toelichting bij de interpretatie 16

3.2.4 Fouten 17

3.3 GetAddressLocation 17

3.3.1 request 17

3.3.2 response 17

3.3.3 Kwaliteit van de positiebepaling 18

4 Client implementatie 19

4.1 Microsoft .Net Framework 19

4.1.1 Stap 1: Genereren client proxy en datatypes 19

4.1.2 Stap 2: Implementeren webservice client op basis van proxy class 20

4.2 Java en WSIT 21

4.2.1 Stap 1: Genereren client proxy en datatypes 21

4.2.2 Stap 2: Implementeren webservice client op basis van proxy class 21

5 Verwante informatie Error! Bookmark not defined.



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 83.000 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 140 000 straten en 2,5 miljoen adressen.

1.3 Hoe kan u gebruik maken van deze dienst?

1.3.1 juridisch

1.3.2 administratief

Indien dat nog niet is gebeurd (bv. in het kader van een andere AGIV toepassing) dan dient u zich eerst te registeren op http://login.agiv.be/registreer.aspx. Na validatie van uw registratie ontvangt u

een e-mail met uw gebruikersnaam en wachtwoord.

Rol kiezen, validatie, gemeente kiezen, start.

1.3.3 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.



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="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>

...

...

</soap:Header>

<soap:Body>

...

...

<soap:Fault>

...

...

</soap:Fault>

</soap:Body>

</soap:Envelope>

Figuur 1: Basisskelet van een SOAP bericht

2.1 SOAP Header

De SOAP header bevat volgende elementen:

• 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.



<s:Header> <a:Action s:mustUnderstand="1"

u:Id="_4"

xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-�

ssecurity-utility-1.0.xsd" xmlns:a="http://www.w3.org/2005/08/addressing">

http://ws.agiv.be/crabtools/GetCRABMatch

</a:Action>

<a:MessageID u:Id="_5"


wssecurity-utility-1.0.xsd" xmlns:a="http://www.w3.org/2005/08/addressing">

urn:uuid:a81da8ba-8adc-4461-b77b-d7c4127eb3e1

</a:MessageID>

<a:ReplyTo u:Id="_6"

xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-� wssecurity-utility-1.0.xsd"

xmlns:a="http://www.w3.org/2005/08/addressing">

<a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>

</a:ReplyTo>

<a:To s:mustUnderstand="1" u:Id="_7"


wssecurity-utility-1.0.xsd"

xmlns:a="http://www.w3.org/2005/08/addressing">

http://ws.agiv.be/crabtools/CRABTools.svc

</a:To> <o:Security s:mustUnderstand="1"

xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-�

wssecurity-secext-1.0.xsd">

...

</o:Security>

</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="http://ws.agiv.be/crabtools/"> <houseNumberId>32100540</houseNumberId>

</GetAddressLocation>

</soap:Body>

Figuur 3: Voorbeeld van een SOAP Body in een request message



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 BESCHRIJVING

Technisch Een onvoorziene fout door (tijdelijke) onbeschikbaarheid van een benodigde bron

(server, databank,...).

Request validatie Een fout tijdens het valideren tegen het XML schema van de request (ontbreken

van een verplicht header element, onjuiste opbouw van het body element).

Authenticatie Een fout tijdens het controleren van de identiteit van de aanvrager (ongeldige

gebruikersnaam, ongeldig wachtwoord, time-out security semantics verstreken).

Autorisatie Een fout door het ontbreken van machtiging voor de dienst of de gevraagde

operatie.

Inhoudelijk 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.



STANDAARD LINK

WS-Security 1.1 http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-

os-SOAPMessageSecurity.pdf

XML Signature http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/

XML Encryption http://www.w3.org/TR/xmlenc-core/

WS-SecureConversation

1.3

http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/ws-

secureconversation-1.3-os.pdf

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="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-�

wssecurity-secext-1.0.xsd"> ...

</o:Security>

</s:Header>

Figuur 5: stap 1 van de SOAP beveiliging

Stap 2

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="http://docs.oasis-open.org/wss/2004/01/oasis-200401-� wss-wssecurity-utility-1.0.xsd">

<u:Created>2008-12-02T10:57:41Z</u:Created>



<u:Expires>2008-12-02T11:02:41.153Z</u:Expires>

</u:Timestamp>

</o:Security>


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="http://www.w3.org/2001/04/xmlenc#"> <e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">

<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"

xmlns="http://www.w3.org/2000/09/xmldsig#">

</DigestMethod>

</e:EncryptionMethod>

<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <o:SecurityTokenReference>

<o:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-�

wss-soap-message-security-1.1#ThumbprintSHA1"

EncodingType="http://docs.oasis- open.org/wss/2004/�

01/oasis-200401- 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>

</o:Security>


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="http://docs.oasis-open.org/wss/2004/01/�

oasis-200401-wss-wssecurity-secext-1.0.xsd"

xmlns:u="http://docs.oasis-open.org/wss/2004/01/�

oasis-200401-wss-wssecurity-utility-1.0.xsd">

<o:Username>myUserName</o:Username>

<o:Password> myClearTextPassword</o:Password>

</o:UsernameToken>

</o:Security>




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="http://schemas.xmlsoap.org/ws/2005/02/sc" xmlns:u="http://docs.oasis-open.org/wss/2004/01/�


<o:SecurityTokenReference>

<o:Reference ValueType="http://docs.oasis-open.org/wss/�

oasis-wss-soap-message-security-1.1#EncryptedKey" URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-1">

</o:Reference>


<c:Offset>0</c:Offset>

<c:Length>24</c:Length>

<c:Nonce>ygSK7aIqSFEMfSq9oU8cnA==</c:Nonce>

</c:DerivedKeyToken>

</o:Security>




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="http://www.w3.org/2000/09/xmldsig#">

<SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">

</CanonicalizationMethod>

<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">

</SignatureMethod>

<Reference URI="#_2"> <Transforms>

<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">

</Transform>

</Transforms>

<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">

</DigestMethod> <DigestValue>SY5NsDjjUkOdFOoboaGGrHDiFoE=</DigestValue>

</Reference>

<Reference URI="#_4">

<Transforms>

<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> </Transform>

</Transforms>


</DigestMethod>

<DigestValue>qHWK5XqrTqGNK0c+9c1sn9L52uA=</DigestValue>

</Reference> <Reference URI="#_5">

<Transforms>


</Transform>

</Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">

</DigestMethod>

<DigestValue>E0NkLEjKilpGe/Ia5rdr9g69x/o=</DigestValue>

</Reference>


<Transforms> <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">

</Transform>

</Transforms>


</DigestMethod> <DigestValue>CuNmjfm/U6y2+ZScFHyVRRpkyKQ=</DigestValue>

</Reference>


<Transforms>


</Transform> </Transforms>




</DigestMethod> <DigestValue>mC43VpmQjV2ZrU37W6nEhCLjv94=</DigestValue>

</Reference>

<Reference URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-2">

<Transforms> <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">

</Transform>

</Transforms>


</DigestMethod>

<DigestValue>FdJT/b/r7TVnS1LwhQHanOaHs1w=</DigestValue> </Reference>

<Reference URI="#uuid-1937dc4a-f830-4ad1-9b42-01bfd7ab0227-1">

<Transforms>


</Transform> </Transforms>


</DigestMethod>

<DigestValue>sO5k6ae4E2DPSGLApuLNxsUFr0o=</DigestValue>

</Reference> </SignedInfo>

<SignatureValue>eI1P+RTs2C8H88LWYS/M37J5QKM=</SignatureValue>

<KeyInfo>

<o:SecurityTokenReference xmlns:o="http://docs.oasis-open.org/wss/2004/01/�

oasis-200401-wss-wssecurity-secext-1.0.xsd">

<o:Reference URI="#_0"></o:Reference> </o:SecurityTokenReference>

</KeyInfo>

</Signature>

</o:Security>


Stap 7

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="http://schemas.xmlsoap.org/ws/2005/02/sc"

xmlns:u="http://docs.oasis-open.org/wss/2004/01/�



<o:Reference ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-�

message-security-1.1#EncryptedKey" URI="#uuid-f02b27a1-25a7-450e-b61c-ec8a3b70dd28-1

</o:Reference>


<c:Nonce>JcJzVaE+CZIlJryhYUVADw==</c:Nonce>

</c:DerivedKeyToken>

</o:Security>




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="http://www.w3.org/2001/04/xmlenc#Content" xmlns:e="http://www.w3.org/2001/04/xmlenc#">

<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc">


<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">

<o:SecurityTokenReference xmlns:o="http://docs.oasis-open.org/wss/� 2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

<o:Reference URI="#_1"></o:Reference>


</KeyInfo>

<e:CipherData>

<e:CipherValue> 0n07yYDO562qcP3rS74P0fsfX8PbEGnqTNPcUGPru3ndjz40UpGe+d/CdQGRapMckhJ0rEgrWk3vwfgci9dmuHem

oyIBmESvwg3TAPCj0qE=

</e:CipherValue>

</e:CipherData>

</e:EncryptedData>

</s:Body>


Stap 9 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="http://www.w3.org/2001/04/xmlenc#Element"

xmlns:e="http://www.w3.org/2001/04/xmlenc#">

<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"> </e:EncryptionMethod>



<o:Reference URI="#_1"></o:Reference>

</o:SecurityTokenReference> </KeyInfo>

<e:CipherData>

<e:CipherValue>

hURVXUCdchyRrxNG+Z8RkbBOUxDiMhkan2Ziv1gDGoKfYfeh30FPdj2BR1Mp6y0bjsLM1cGNFgeocq7/Lz7FwORg

ClRFeWdw9IhbTWQ+sFMPKwisOydybeniPA5rE2XBx1br/Q3bU1kbMEj56jrJ2x6fAy3VUgfXOq7HIc0SRkBlNgVx

vlwzeVxUYSPZbDonO8uRWFqRt/o+MsFvrjk5R1UXjWCQ1k30WJUG5n01tLdiXPIG3K0SyRdo3SGknwYz/ZGos8Km8EUMDIcG8vGvrk9+2Gb9oRiY69TiVznA9xo/Mrki5F77WOYOTvkce5KME93yLm+RTw4zlSSvJqpy2tkpT6esNQux

34rWcch35EBwo/Dl1sdXN1REbx63FXM49zZ63rFOvoRW5lEhKvTNdQdDBabJ2Oq+6mDtlxI7ekYGy8J0ry0yq2CF

wy717/GiGtg9rM6YfObY8X5bRqi01CQ90eiS9ectRSk2Z7Ch3/

...

</e:CipherValue> </e:CipherData>

</e:EncryptedData>

</o:Security>




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="http://www.w3.org/2001/04/xmlenc#Element" xmlns:e="http://www.w3.org/2001/04/xmlenc#">

<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc">



<o:SecurityTokenReference> <o:Reference URI="#_1"></o:Reference>


</KeyInfo>

<e:CipherData>

<e:CipherValue>

4Hpq5zK0Lg0FZtLbWTwZ1v3pJWTGfw96v+oI/4tdTsFCyW1s7nr6GxA2lOSkgbMyHULWFletcb0DbNWFqiHYlKQ0kD2Dprc8hYnnuIVfQxZieed7NxBNcSYNlutpCKDoPN6XsN8Q++r/7WAs8QzTtW0zyy1nJkSj6rXCHSw2xi/T6GTi

6O/lZs0zU8hRKtNgVsuVDvN+EhtCleEkzos4LHCFbBeAzolss+5ioQNROQzJGgto0p4961q84gn3drF21TUTjPOH

oxwo4DBdvBSTAdFutr5r1AGLoWg5LnGA6EwhKKyvE0345w2Vg5JkJtlBQb50FqlR6WEi0gmpW4e666z9znjO0grB

3FrRyIQF7u8R5HW/gDYE5KIOhs9TQMPXEmr7k4OR5c8A19tntktpt8ZNS17/GDmOaBJ7/n/eRdVslLRSuQRsSFz8

CG17sBjhMYEpnl/cm9TyzHK2IzalhdzolzZwAnTPmuydnQBdcergUmnDGg8KiVU+oXyhJiO9ZBn0gKBJbJnwXfd6HqEixvoXDavKOE3mvUTRA+zJ4Lyj+Wxvx9vEZPZRknGmzLRECsLSHi1czIEWeFgr1jMPyHdyRemrwIiFhkZwB8ol

SZ8=

</e:CipherValue>

</e:CipherData>

</e:EncryptedData>

</o:Security>


Stap 11 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="http://www.w3.org/2001/04/xmlenc#"> <e:DataReference URI="#_3"></e:DataReference>

<e:DataReference URI="#_8"></e:DataReference>

<e:DataReference URI="#_9"></e:DataReference>

</e:ReferenceList>

</o:Security>




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

3.2.1 request Aan de operatie GetCRABMatch wordt een <FormattedAddress> meegegeven als parameter.

Figuur 16:het <FormattedAddress> element

ELEMENT OMSCHRIJVING

BoxNumber Bevat het huisnummertoevoegsel. In rijksregistertermen is dit het busnummer.

CityName Bevat de naam van de gemeente.

HouseNumber Bevat het huisnummer.

NisCityCode Bevat de NIS code van de gemeente.

PostalCode Bevat de postcode van het adres.




RrStreetCode Bevat de straatcode zoals toegekend door het rijksregister.

Streetname 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.

3.2.2 response De operatie GetCRABMatch geeft een <MatchResponse> element terug.

Figuur 17: het <MatchResponse> element


MatchFound Duidt aan of er minimaal één overeenkomstig CRAB adres is gevonden.

Faults Bevat een lijst van fouten die gevonden werden in de request.

HouseNumberId Bevat het CRAB huisnummerid van het gevonden CRAB adres (indien tot dit

niveau opgelost).

StreetnameId Bevat de CRAB straatcode van het gevonden CRAB adres.

SubAddressId Bevat het CRAB subadresid van het gevonden CRAB adres (indien tot dit

niveau opgelost).

3.2.3 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



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.

3.2.4 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

11 Bisnummer niet in huisnummer maar in toevoegsel: niet-numeriek bisnummer in

<BoxNumber>

12 Adrescomplement niet interpreteerbaar: <BoxNumber> niet leeg, maar niet

interpreteerbaar

13 Geen overeenkomst tussen postcode en gemeentenaam: verwijzen niet naar eenzelfde

gemeente

14 Geen overeenkomst tussen postcode en NIS gemeentecode: verwijzen niet naar

eenzelfde gemeente

3.3 GetAddressLocation

3.3.1 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.

3.3.2 response De operatie GetAddressLocation geeft een <LocationResponse> element terug.



Figuur 18: het <LocationResponse> element


Bbox Bevat de omschrijvende rechthoek van het (de) geografische object(en) waarnaar

de locatie verwijst.

Centroid Bevat het zwaartepunt van het (de) geografische object(en) waarnaar de locatie

verwijst.

HouseNumberIdExists Duidt aan of het opgegeven huisnummerid al dan niet bestaat.

Merk op dat indien het niet bestaat, er ook geen locatie wordt teruggegeven.

Quality Bevat een indicatie van het kwaliteitsniveau van de positiebepaling.

3.3.3 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



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


5 Positie bepaald op basis van koppeling aan kadastraal perceel.

6 Positie bepaald op basis van koppeling aan meerdere kadastrale percelen. De positie is de


7 Positie bepaald op basis van interpolatie tussen de centroïdes van twee GRB gebouwen

gekoppeld aan nevenliggende huisnummers.

8 Positie bepaald op basis van interpolatie tussen de centroïdes van twee GRB percelen


9 Positie bepaald op basis van interpolatie tussen de centroïdes van twee kadastrale percelen


10 Positie bepaald op basis van interpolatie tussen begin- en eindknoop van een gekoppeld

wegsegment met aanwezige nummeringsinformatie.

11 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 2008.

4.1.1 Stap 1: Genereren client proxy en datatypes

4.1.1.1 svcutil.exe command-line tool

1. Open een Command Prompt venster

2. Tik het volgende commando in: svcutil http://ws.agiv.be/crabtools/crabtools.svc?wsdl

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

4.1.1.2 Visual Studio 2008

1. start een nieuw client project



2. rechtsklik op de projectnaam en selecteer ‘Add Service Reference’

3. vul het adres in van de service (http://ws.agiv.be/crabtools/crabtools.svc)

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

4.1.2 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



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: http://java.sun.com/webservices/reference/tutorials/wsit/doc/index.html

4.2.1 Stap 1: Genereren client proxy en datatypes

4.2.1.1 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 http://ws.agiv.be/crabtools/crabtools.svc?wsdl

3. De tool genereert dan een bestand CRABToolsStub.java met daarin de domeinspecifieke

types en de proxy.

4.2.1.2 NetBeans 6.1

1. 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 (http://ws.agiv.be/crabtools/crabtools.svc?wsdl) en klik op

Finish

4.2.2 Stap 2: Implementeren webservice client op basis van proxy class

Hieronder volgt een beschrijving van het gebruiken van de web service proxy in NetBeans 6.1.

1. 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

CRABTools - Vlaanderen Interncrab.beta.agiv.be/Manuals/Handleiding_CRABTools_v0.1.pdf · Agentschap...

Documents

Transcript of CRABTools - Vlaanderen Interncrab.beta.agiv.be/Manuals/Handleiding_CRABTools_v0.1.pdf · Agentschap...