Dit document beschrijft de functionele specificaties voor de Digikoppeling koppelvlak standaard WUS

Het document is bestemd voor architecten en ontwikkelaars die op basis van WUS gegevens willen uitwisselen via Digikoppeling.

Alle Digikoppeling webservices die op WUS gebaseerd zijn, moeten conformeren aan de koppelvlakstandaard WUS. Deze wordt tot in detail in dit document gespecificeerd. Doel van dit document is ontwikkelaars te informeren wat deze koppelvlakstandaard nu precies inhoudt en waar zij zich aan moeten conformeren. Het document is bestemd voor architecten en ontwikkelaars die op basis van WUS gegevens willen uitwisselen via Digikoppeling. Het gaat hierbij om zowel service providers als service requesters (clients).

Digikoppeling is beschreven in een set van documenten. Deze set is als volgt opgebouwd:

Dit document beschrijft de WUS-variant van de koppelvlakstandaarden. Naast de Koppelvlakstandaard WUS zijn er ook de ebMS2- en REST-API-standaarden. Deze worden in een aparte documenten beschreven.

Een koppelvlak is een interface die volgens standaarden de gegevensuitwisseling vastlegt. Het werken met vaste standaarden is essentieel voor een koppelvlak. Hierdoor wordt implementatie vergemakkelijkt. Ook wordt het mogelijk diverse soorten berichten door te sturen met een grote mate van interoperabiliteit, omdat via de standaard afspraken over hun inhoud gemaakt is.

Eén van de belangrijkste eisen die door de overheid gesteld worden bij de inrichting van generieke voorzieningen, is dat er niet veel maatwerk ontwikkeld hoeft te worden, maar dat er van “off the shelf” commercieel of Open source geleverde software gebruik gemaakt kan worden. Voor Digikoppeling, dus voor de logistieke laag, betreft dat het niet willen ontwikkelen van software voor de adapters.

Dit doel kan bereikt (benaderd) worden doordat gekozen wordt voor internationale (de jure of de facto) vastgelegde standaarden, die door “alle” leveranciers interoperabel zijn geïmplementeerd.

Een andere eis is dat met name afnemers gebruik kunnen maken van één “stekker” (één logistiek koppelpunt). Aanbieders dienen hiervoor de nodige voorzieningen te treffen.

Een koppelvlakspecificatie beschrijft de eisen die gesteld worden aan de adapters om interoperabel met elkaar te kunnen communiceren. Digikoppeling gaat over logistiek, dus over de envelop en niet over de inhoud. De hele set informatie die tezamen nodig is voor een complete generieke Digikoppeling koppelvlakdefinitie bestaat uit:

• Interfacedefinitie “on the wire”, (voorbeeld)listing van SOAP headers en informatie over velden en hun specifieke inhoud.

De voor Digikoppeling vereiste interoperabiliteit van de WUS standaarden van OASIS en W3C wordt gebaseerd op de profielen (en tests) van OASIS WS-BRSP (voorheen WS-I).

Hoofdstuk 1 bevat een aantal algemene inleidende onderwerpen.

Hoofdstuk 2 bevat de kern van de standaard. Deze is onderverdeeld naar onderwerpen/gebieden: WSDL, WS-Addressing, naamgeving, beveiliging, betrouwbaarheid en binaire data. Het identificeert de gekozen internationale (WS-I) profielen die dienen als fundament voor de Digikoppeling Koppelvlakstandaard WUS. Die keuzes, de nadere invullingen voor Digikoppeling binnen de ruimte van die standaarden/profielen en specifieke aandachtspunten bij de keuzes, vormen tezamen de “voorschriften” per onderwerp.

Hoofdstuk 3 definieert de resulterende Digikoppeling WUS profielen.

Gehanteerde terminologie: Glossary

Voor de definities die binnen het Digikoppeling project gehanteerd worden, zie de ‘Digikoppeling Glossary’ via de onderstaande website.

Website

Dit document en andere documentatie is beschikbaar op www.logius.nl/digikoppeling.

WUS is een acroniem voor WSDL, UDDI en SOAP: WUS dus. Daarmee wordt een familie van internationale standaarden van OASIS en W3C bedoeld; deze worden ook vaak met WS-* aangeduid. Deze standaarden gaan over application-to-application webservices.

Alle Digikoppeling webservices die op WUS gebaseerd zijn, moeten aan deze koppelvlakstandaard conformeren. Doel van de Koppelvlakstandaard WUS is het eenduidig en bruikbaar definiëren van het koppelvlak voor WUS. Er zijn daarvoor de volgende onderwerpen relevant: WSDL met adressering en naamgeving, beveiliging, betrouwbaarheid, binaire data, resulterende berichtheaders, profielen van Digikoppeling en compliancevoorzieningen. Deze standaard wordt verder aangevuld met “Best Practices” en adviezen, beschreven in een apart document. Alle documentatie over Digikoppeling is te vinden op [Logius].

Om redenen van interoperabiliteit, eenvoud en overzichtelijkheid onderscheidt deze Digikoppeling Koppelvlakstandaard een tweetal varianten van uitwisselingen. Elke variant veronderstelt bepaalde voorgedefinieerde keuzes voor parameters als beveiliging en betrouwbaarheid en is daarmee een “profiel” voor WUS.

Elke uitwisseling op basis van de WUS-protocollen over Digikoppeling zal moeten voldoen aan één of een combinatie van de volgende Digikoppeling WUS-varianten:

• Best Effort: dit zijn synchrone uitwisselingen die geen faciliteiten voor betrouwbaarheid (ontvangstbevestigingen, duplicaateliminatie etc.) vereisen. Voorbeelden zijn toepassingen waar het eventueel verloren raken van sommige berichten niet problematisch is en waar snelle verwerking gewenst is.

• End-to-End Security: een bericht wordt beveiligd tussen de uiteindelijke consumer en de uiteindelijke provider, ook wanneer er zich intermediairs bevinden in het pad tussen die twee. Het betreft hier authenticatie van de consumerorganisatie, conform het Digikoppeling authenticatiemodel, waarbij alleen de identiteit van de consumerorganisatie relevant is(signing), en encryptie van het bericht (payload inclusief attachments) onderweg. Voor de authenticatie en encryptie wordt gebruikgemaakt van WS-Security.

• Attachments: één of meerdere bijlagen, naast natuurlijk het reeds bestaande (xml) bericht zelf. Dit kan, maar hoeft niet, toegepast te worden in combinatie de bovengenoemde profielen: het is dus optioneel.

• Vertrouwelijkheid en authenticatie van zender en ontvanger wordt als volgt gerealiseerd:

  • voor Point-to-Point Security, door middel van twee-zijdig TLS op

transport-niveau (in het HTTP kanaal). (De toepassing ervan is verplicht op alle Digikoppeling versies.)

• voor End-to-End Security, door middel van signing (ondertekening) en (optioneel) encryptie (versleuteling) op berichtniveau (payload inclusief de attachments, ook wel 'bijlagen' genoemd) in combinatie met (point-to-point) twee-zijdig TLS in het HTTP kanaal.

De onderstaande tabel geeft in essentie de eigenschappen van de verschillende Digikoppeling profielen weer. Voor alle profielen wordt tweezijdig TLS gebruikt op transportniveau (HTTPS).

Voor de Digikoppeling Koppelvlakstandaard WUS is een compliancevoorzieningen beschikbaar gesteld, waarmee een ontwikkelaar of beheerder kan testen “of het berichtenverkeer werkt”. Deze compliancevoorziening is gedefinieerd aan de hand van de WSDL’s die opvraagbaar zijn op [Compliance].

De volgende interacties zijn beschikbaar:

• Digikoppeling service requester: wordt gebruikt om een ontwikkelde servicere requester (client) te testen.

• Digikoppeling service provider: wordt gebruikt om een ontwikkelde service provider (service) te testen.

De documenten over de compliancevoorzieningen zijn te vinden op [Logius]. De Digikoppeling Compliancevoorziening zelf is beschikbaar op [Compliance]

In dit hoofdstuk worden de verschillende versies van de onderliggende internationale standaarden vermeld.

De inhoud van de Digikoppeling standaard vloeit voort uit bovengenoemde standaarden, of vormt een nadere invulling daarvan (een keuze uit toegestane mogelijkheden in die standaarden).

In de paragrafen hierna worden die onderdelen achtereenvolgens behandeld:

• WSDL,

• WS-Addressing,

• Binaire data,

• Beveiliging,

• Betrouwbaarheid,

• Namespace.

<element name="TradePriceRequest">
<complextype\>
<all>
<element name="tickerSymbol" type="string"></element>
</all>
</complextype\>
</element>
…
<message name="GetLastTradePriceInput">
<part name="body" elements="xsd1:TradePriceRequest"></part>
</message>

Er worden momenteel nog geen eisen gesteld aan de foutafhandeling, anders dan in de onderliggende specificaties vermeld worden, zoals WS-I Basic Profile 1.2. In het document ” Digikoppeling Best Practices WUS” is een aantal adviezen opgenomen.

Aanvullende standaarden die gebruikt worden in combinatie met Digikoppeling kunnen overigens wel eisen stellen aan de fouthandeling.

Beveiliging

Dit profiel maakt voor de beveiliging alleen gebruik van tweezijdig TLS.

Headerblocks

Alleen de verplichte WS-Addressing headers zijn hier van toepassing (zie soapenv:Header in Digikoppeling WUS voorbeelden (zip)).

MTOM

De geoptimaliseerde (MTOM) voorbeeldberichten worden weergegeven in Digikoppeling WUS voorbeelden (zip).

Beveiliging

Dit profiel maakt voor de beveiliging gebruik van tweezijdig TLS en tevens worden de berichtonderdelen ondertekend zoals vermeld in hoofdstuk 2, paragraaf End-to-End beveiliging.

Headerblocks

In dit profiel zijn de WS-Addressing en WS-Security 1.0 ondertekening (wsse:Security) headers van toepassing (zie Digikoppeling WUS voorbeelden (zip)).

MTOM

De geoptimaliseerde (MTOM) voorbeeldberichten voor profiel Digikoppeling 2W-be-S worden weergegeven in Digikoppeling WUS voorbeelden (zip).

Beveiliging

Dit profiel maakt voor de beveiliging gebruik van tweezijdig TLS en tevens worden de berichtonderdelen ondertekend en versleuteld zoals vermeld in hoofdstuk 2, paragraaf End-to-End beveiliging.

Headerblocks

In dit profiel zijn de WS-Addressing en WS-Security 1.0 ondertekening (wsse:Security) headers van toepassing. Ook wordt hierbij de payload van het bericht versleuteld (xenc:EncryptedData) (zie Digikoppeling WUS voorbeelden (zip)).

MTOM

De geoptimaliseerde (MTOM) voorbeeldberichten voor profiel Digikoppeling 2W-be-SE worden weergegeven in Digikoppeling WUS voorbeelden (zip).