Dit document beschrijft de functionele specificaties voor de Digikoppeling Koppelvlakstandaard REST-API.
Het document is bestemd voor architecten en ontwikkelaars die op basis van REST-API's gegevens willen uitwisselen via Digikoppeling.
Dit is een door het TO goedgekeurde consultatieversie. Commentaar over dit document kan gestuurd worden naar digikoppeling@logius.nl
1. Conformiteit
Naast onderdelen die als niet normatief gemarkeerd zijn, zijn ook alle diagrammen, voorbeelden, en noten in dit document niet normatief. Verder is alles in dit document normatief.
2. Context voor ontwikkeling van het Digikoppeling REST API profiel
Het Digikoppeling Rest API profiel is gericht op Machine-to-Machine (M2M) en Government-to-Government (G2G) interacties conform de algemene uitgangspunten van de Digikoppeling standaard en het toepassingsgebied van Digikoppeling op de Pas-toe-of-leg-uit lijst (PTLU) van het Forum Standaardisatie;
3. Toelichting bij de scope van het Digikoppeling REST API profiel
Figuur 2Digikoppeling voor Closed Data G2G Uitwisseling
In de figuur wordt onderscheid gemaakt tussen open en gesloten diensten:
Open Diensten: Diensten zonder toegangsbeperking bv open data.
Gesloten Diensten: Diensten met toegangsbeperking bv persoonsgegevens en vertrouwelijke gegevens of diensten voor specifieke partijen.
Het Digikoppeling REST API profiel richt zich op Machine-to-Machine (M2M) gegevensuitwisseling via een gesloten dienst tussen overheidspartijen.
Buiten scope van het profiel zijn:
REST API's voor open diensten van een overheidspartij.
REST API's voor gesloten diensten van een overheidspartij (direct) aan burgers of bedrijven.
Het Digikoppeling REST API profiel is wat betreft functionele toepassing vergelijkbaar met het Digikoppeling WUS profiel.
De client van de dienstafnemer die gebruik maakt van het Digikoppeling REST API profiel is in deze context een systeem (applicatie) en geen internetbrowser.
Invulling Digikoppeling
DK REST API profiel
DK WUS profiel
DK ebMS2 profiel
Bevragingen / Meldingen
best-effort
1.0
2W-be
osb-be
best-effort signed
2W-be-S
osb-be-s
best-effort signed/encrypted
2W-be-SE
osb-be-e
reliable
osb-rm
reliable signed
osb-rm-s
reliable signed en encrypted
osb-rm-e
In versie 1.0 van het Digikoppeling REST API profiel wordt signing en encryptie nog niet ondersteund. In de volgende versies van het profiel wordt hier wel invulling aan gegeven. Modules voor signing en encryptie zijn al ontwikkeld en worden na vaststelling toegevoegd. (Zie ook 4.6 Signing & Encryptie (in HTTP REST Context))
4. Digikoppeling Restful API profiel
4.1 Historie
Vanuit het TO Digikoppeling zijn al langere tijd de ontwikkelingen rond Restful API's gevolgd. Binnen het Kennisplatform API zijn de REST-API Design Rules (REST ADR) ontwikkeld en de REST ADR standaard is ook opgenomen op de Pas-toe-of-leg-uit lijst van het Forum Standaardisatie. De REST ADR standaard is dan ook als basis genomen voor dit Digikoppeling REST API Profiel dat zich specifiek richt op G2G (Government-to-Government) interactie en M2M (Machine-to-Machine verkeer).
4.2 Toepassingsgebied
Het toepassingsgebied is voor Digikoppeling:
Digikoppeling moet worden toegepast bij digitale gegevensuitwisseling die plaatsvindt met voorzieningen die onderdeel zijn van de GDI, waaronder de basisregistraties, of die sectoroverstijgend is. De verplichting geldt voor gegevensuitwisseling tussen systemen waarbij er noodzaak is voor tweezijdige authenticatie.
Dit profiel is toe te passen bij het aanbieden van REST API's ten behoeve van het ontsluiten van overheidsinformatie en/of functionaliteit.
4.3 Algemeen
Het Digikoppeling REST-API profiel is gebaseerd op de REST-API Design Rules standaard zoals ontwikkeld door het Kennisplatform API's en in beheer gebracht bij Logius Stelsels & Standaarden: [ADR]
Het Digikoppeling REST-API profiel conformeert zich volledig aan het normatieve deel van de REST-API Design Rules.
4.4 Koppelvlak Generiek
4.4.1 Vertrouwelijkheid
De Digikoppeling Beveiligingsstandaarden en voorschriften gaan specifiek in op het verplichte gebruik van PKIO certificaten [PKIO-PvE] en 2-zijdig TLS.
Digikoppeling maakt gebruik van het OIN (Organisatie Identificatie Nummer) voor de identificatie van organisaties.
Binnen dit DK REST-API profielprofiel zijn er alleen voorschriften m.b.t. het verplicht gebruik van het OIN binnen PKIO certificaten. Voor OIN gebruik binnen payloads (bv JSON) of resource-pad gelden geen specifieke voorschriften.
Het Digikoppeling REST-API profiel conformeert zich volledig aan het normatieve deel van de API Design Rules (Nederlandse API Strategie IIa). Het is verplicht te voldoen aan alle (normatieve) eisen van de REST-API Design Rules:
Extensies op de API Design Rules (Nederlandse API Strategie IIa) zijn geschreven in modules. Hieronder wordt aangegeven welke regels uit de API Design Rules modules in dit profiel verplicht zijn of worden aanbevolen.
* Wat betreft TLS zijn de Digikoppeling beveiligingsvoorschriften leidend (zie Digikoppeling Beveiligingsstandaarden en voorschriften).
** Alleen verplicht indien er sprake is van logging in systemen die niet onder controle van de betrokken client- en serverorganisatie staan.
4.5.3 Toelichting aanduidingen
Voorschriften zijn aangeduid met 'Verplicht', 'Aanbevolen' en 'Niet van Toepassing' waarvoor de volgende definities gelden (gebaseerd op [rfc2119]):
Categorie
Codering RFC2119
Voorschrift
Verplicht
MUST
De eisen moeten gevolgd worden. Hier kan niet van afgeweken worden.
Aanbevolen
SHOULD
Aanbevolen is om de eisen conform conform voorschrift te implementeren. Wanneer hier van afgeweken wordt dient een zorgvuldige afweging plaats te vinden
Niet van Toepassing
-
De eisen zijn niet van toepassing
4.6 Signing & Encryptie (in HTTP REST Context)
4.6.1 Signing
Signing van HTTP body en/of header kan gebruikt worden voor authenticatie, om de integriteit van de request/response berichten te controleren en signing realiseert ook onweerlegbaarheid.
(Onweerlegbaarheid in de zin van: de verzender van de request/response kan niet ontkennen het bericht verzonden te hebben wanneer deze voorzien is van de digitale handtekening van de afzender).
De berichten kunnen ook samen met de digitale handtekeningen worden bewaard zodat deze bij audits of juridische bewijsvoering gebruikt kunnen worden.
Een HTTP requestbericht is opgebouwd uit de volgende onderdelen:
Header
HTTP operatie (GET, POST etc)
Pad / URL resource
Protocol
Header velden
Body
data
Door naast de body data ook onderdelen uit de header digitaal te ondertekenen kan worden gecontroleerd dat bv ook de HTTP operatie en resource specificatie in de request echt van de afzender afkomstig zijn en niet onderweg gemanipuleerd.
Encryptie van HTTP request/response kan gebruikt worden om de vertrouwelijkheid van gegevens te beschermen.
Indien encryptie van HTTP request/response wordt toegepast is het Verplicht om dit te doen volgens de regels van de ADR Module ADR-HTTP Payload encryption
A. HTTP Message Signing & Encryptie in het Digikoppeling REST API profiel
A.1 Inleiding
Door een HTTP-Request/Response te voorzien van een digitale handtekening kan identiteit van de afzender worden gecontroleerd en het HTTP verkeer beschermd worden tegen manipulatie van buitenaf, ook kan met de digitale handtekening onweerlegbaarheid worden gerealiseerd in de zin dat de ontvanger niet kan ontkennen het bericht te hebben ontvangen en de verzender niet kan ontkennen het bericht te hebben
verzonden.
Bij HTTP verkeer wordt voor authenticatie, integriteits bescherming (en bescherming van de vertrouwelijkheid) TLS (Transport Level Security) breed toegepast. In Digikoppeling wordt specifiek 2-zijdig TLS toegepast. Echter TLS beschermt alleen via één TLS-verbinding en het pad tussen de client en de server kan bestaan uit meerdere onafhankelijke TLS-verbindingen (bijvoorbeeld als de applicatie wordt gehost achter een TLS-beëindigende gateway of als de client zich achter een TLS Inspection-apparaat bevindt). In dergelijke gevallen kan TLS geen end-to-end berichtintegriteit of authenticiteit tussen de client en de server garanderen.
HTTP Message signing kan dit geval gebruikt worden om end-to-end bescherming tegen manipulatie te realiseren voor het volledige pad Client naar Server.
HTTP Payload encryptie kan dit geval gebruikt worden om end-to-end vertrouwelijkheid te realiseren voor het volledige pad Client naar Server.
Figuur 3Bescherming voor het volledige pad Client naar Server
A.2 Wanneer is HTTP Message Signing/Encryptie te gebruiken
Wanneer Client en Server middels 2-zijdig TLS verbonden zijn over 1 connectie (bijvoorbeeld direct of als de gateway d.m.v. 'pass-through' verkeer doorgeeft aan de Server) dan is er al sprake van end-to-end bescherming van het verkeer en is voor bescherming HTTP Message Signing niet nodig. (Voor vastlegging van audit logs of om rekening te houden met toekomstige infrastuktuur wijzigingen die end-to-end 2-zijdig TLS onderbreken zou signing ook in dit geval bruikbaar kunnen zijn ).
Wanneer de 2-zijdig TLS connectie bij de Gateway wordt beindigd en de gateway het verkeer ontsleuteld en doorstuurd naar de server is er geen end-to-end beveiliging via TLS. In dit geval kan met behulp van HTTP Message Signing wel end-to-end bescherming geboden worden.
De Client kan HTTP header informatie zoals bv de HTTP Operatie (GET/POST/DELETE/etc) en het resource pad samen met de body van het bericht voorzien van een handtekening, De Gateway kan deze ondertekening doorsturen naar de Server en de Server kan dmv de handtekening afzender en integriteit van het bericht controleren en vaststellen.
NB Of HTTP Signing en Encryptie nodig/wenselijk zijn is afhankelijk van de opzet van de infrastruktuur en het gewenste beschermingsniveau. Signing , en ook Encryptie toepassen zorgt voor meer complexiteit in de uitwisselingen. Ook zijn Signing en Encryptie relatief zware operaties die ook beslag op resources opleveren dus het is belangrijk om dit alleen toe te passen in use cases waar HTTP Signing en Encryptie toegevoegde waarde hebben
