Dit is een werkversie die op elk moment kan worden gewijzigd, verwijderd of vervangen door andere documenten. Het is geen door het TO goedgekeurde consultatieversie.
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.
De trefwoorden MOET en MOETEN in dit
document moeten worden geïnterpreteerd als in
BCP 14
[RFC2119] [RFC8174]
als, en alleen als deze in hoofdletters zijn weergegeven, zoals hier
getoond.
Abstract
Dit document is onderdeel van een standaard voor het loggen van dataverwerkingen in de Nederlandse publieke sector. De governance van deze standaard wordt beschreven in het API-Standaarden beheermodel, gepubliceerd door Logius.
Context bij de standaard
De overheid wil voor burgers en bedrijven zo transparant mogelijk zijn in de omgang met hun data. Daarom is het bij de informatieverwerking in datasets belangrijk om voor elke mutatie of raadpleging vast te leggen wie deze actie wanneer uitvoert, en waarom. Voor een optimale samenwerking over organisaties en bronnen heen is voor deze logging een algemene standaard nodig.
Transparantie en verantwoording naar burgers is één van de drijfveren voor ontwikkeling van deze logging standaard, maar geen onderdeel van de standaard. De standaard richt zich op vastlegging van de logging en deze eenduidige vastlegging maakt het mogelijk om, via een extensie, inzage mogelijk te maken.
Verwijzingen
De Logboek Dataverwerkingen (LDV) standaard bestaat uit de volgende vier documenten:
We moedigen gebruikers aan om meldingen of suggesties aan te maken via
GitHub. Mocht dit niet mogelijk zijn, dan kunt u ook een e-mail sturen naar
api@logius.nl.
2. Naam en beschrijving
Het project Logboek Dataverwerkingen (voorheen: Verwerkingenlogging) maakt deel uit van het actieplan Data bij de Bron en onderzoekt met Digilab in samenwerking met diverse overheidspartijen (ministeries, uitvoeringsorganisaties en gemeentes) of we op basis van de tot nu toe opgedane inzichten een overheidsbrede standaard kunnen vaststellen. Na het succesvol beproeven van de standaard wordt deze voorgesteld voor opname in de ‘Pas toe of leg uit’-lijst van het Forum voor Standaardisatie.
Hier gaat het om de extensie lezen op de standaard logboek dataverwerkingen: Een algemeen toepasbare standaard voor het lezen van gelogde overheidsdata. Deze standaard zal interoperabel kunnen werken met meerdere logging standaarden; Tenminste zal de standaard werken met de Logboek Dataverwerkingen standaard. De beschrijving van standaard zal gebeuren in de vorm van een extensie op de Logboek Dataverwerkingen standaard.
2.1 Doel en nut
De standaard Logboek Dataverwerkingen beschrijft een manier om technisch interoperabele functionaliteit voor het loggen van dataverwerkingen te implementeren, door voor de volgende functionaliteit de interface en het gedrag voor te schrijven:
het wegschrijven van logs van dataverwerkingen
het aan elkaar relateren van logs van dataverwerkingen
het aan elkaar relateren van dataverwerkingen over de grenzen van systemen
De extensie lezen breid deze uit met de mogelijkheid te kunnen lezen:
De logs van een (interne) bron te lezen
Logs lezen bij de(externe) bron(loggende organisatie)
Gerelateerde logs bij meerdere bronnen op te vragen
3. Technische specificatie
3.1 Architectuur
Per logboek MOET er één lezen API beschikbaar zijn.
Deze geeft toegang tot alle dataverwerkingen die in dit logboek zijn opgeslagen.
Indien de verwerkingsactiviteit over meerdere applicaties (met eigen logboeken) gaat, dienen alle lezen APIs bevraagd te worden om een compleet beeld van de verwerkingsactiviteit te krijgen.
Wanneer er binnen één organisatie meerdere logboeken zijn dan MOETEN deze vanuit oogpunt van de extensie lezen gezien worden als aparte applicaties en voor elk logboek de lezen API implementeren.
De extensie voegt een extra attribuut toe aan dataverwerkingen bovenop de core standaard waarmee een aangeroepen externe organisatie (en bijbehorende lezen API) geidentificeerd kan worden.
Het bevragen van de lezen APIs begint altijd bij de applicatie waar de verwerkingsactiviteit gestart is.
Vanuit de daar opgevraagde dataverwerkingen zijn dan de URLs van APIs te vinden die als volgende bevraagd moeten worden om een compleet beeld van de verwerkingsactiviteit te krijgen.
Op deze manier kan iteratief een compleet beeld opgebouwd worden.
3.2 Werking lezen API
De lezen API kent één type resource Dataverwerkingen volgens de core standaard logboek dataverwerkingen oftewel ProcessingActivities in opentelemetry.
Voor het bevragen van deze resource MOET tenminste een van de volgende parameters meegegeven worden:
Wanneer dit bij een request aan de server niet gebeurd, MOET de server antwoorden met een HTTP 400 Bad Request, die aangeeft dat hieraan niet voldaan is.
Noot
Wanneer geen query paramaters worden meegegeven, dan zou de server alle dataverwerkingen terug moeten geven. Het risico is dan groot dat zowel client als server dit niet aankunnen, alsmede dat er teveel gegevens worden gedeeld.
aanbeveling: Het is verstandig als de server ook bij het toepassen van query parameters een maximum stelt aan het aantal terug te geven dataverwerkingen.
3.3 Toevoeging bij schrijven Logs
De extensie lezen voegt één attribuut toe ten opzichte van de Core standaard.
Het stelt in staat te verwijzen naar de volgende partij of applicatie in de keten waar verdere logging over een ketenproces te vinden is.
Registreer bij iedere verwerking die een externe partij aanroept de URL van de lezen API waar je de verwerkingen van die partij kan opzoeken.
Indien er geen sprake is van het aanroepen van een andere API, dan MOET dit attribuut niet toegevoegd worden.
Wanneer er wel een volgende partij is maar deze de extensie lezen (nog) niet implementeert kan je in dit attribuut een URL die verwijst naar een pagina met contactgegevens opnemen.
Dit attribuut MOET een specifieke waarde hebben ongeacht het gebruikte detailniveau.
Veld
Type
Beschrijving
dpl.read.externalReadAPI_id
String
verwijzing naar de lezen API van de aan te roepen externe applicatie of partij. uri naar uniek identificeerbare API volgens extensie lezen
3.3.1 Query op basis van traceID
De TraceID wordt voor organisatie overstijgende processen gevuld met de W3C TracecontextID en anders met een interne ID waarmee alle logging die bij één instantie van een proces hoort aan elkaar gerelateerd wordt.
Deze usecase gaat ervanuit dat de TraceID bekend is en dat je alle bijbehorende logging op wil vragen.
3.3.2 Query op basis van processingActivityID
De processingActivityID wordt gevuld met een verwijzing naar de verwerkingsactiviteit (verwerkingsregister bij core standaard of algoritmeregister i.h.g.v. objecten extensie) die uitgevoerd wordt.
Je wil dan alle traceIDs terugkrijgen die voor deze verwerkingsactiviteit bekend zijn.
3.3.3 Query op basis van dataSubjectId
De dataSubjectId gevuld met een verwijzing naar de betrokkene van verwerkingen.
Je wil dan alle traceIDs terugkrijgen die voor deze betrokkene bekend zijn.
Het is hierbij aan te bevelen het gebruik van BSN en andere gevoelige personsgegevens in de logging te vermijden.
Het waar mogelijk toepassen van pseudoniemen verminderd de kans op datalekken.
3.3.4 Query op starttijd/eindtijd
Hierbij wil je filters kunnen toepassen tenminste op start_time en/of end_time einde van de dataverwerkingen.
We kiezen ervoor om in de interface de REST API Designrules te volgen voor het aangeven van tijd.
Deze kent andere conventies dan Open Telemetry waarin tijdstippen volgens de core standaard van logboek dataverwerkingen wordt vastgelegd.
De implementatie van de lezen API zal dus een vertaling moeten maken van het OTLP formaat naar het ADR formaat.
In de OAS specificatie staat geen authenticatie voor de lezen API gespecificeerd.
Dit is bewust niet normatief neergezet om per implementatie de vrijheid te hebben dit binnen het domein waarin de standaard wordt geimplementeerd open te laten.
Het is echter wel belangrijk om het endpoint goed te beveiligen.
Dus zorg tenminste voor authenticatie van de client die de lezen API bevraagd en richt autorisatie regels in zodat een client alleen toegang krijgt tot loggingregels waar deze recht op heeft.
In zijn algemeenheid biedt de module access control van het kennisplatform APIs hier goede handvaten voor.
De referentie-implementatie van logboek dataverwerkingen geeft één specifiek voorbeeld voor hoe dit gedaan kan worden.
3.5 Todo
Pagination toevoegen
Na publicatie logboek dataverwerkingen core, verwijzingen naar begrippen in json schema aanpassen
Batch bevragingen mogelijk maken voor meerdere processingActivityIds/TraceIds/dataSubjectIds volgens Batching module ADR
Uitwerken hoe lezen uit te breiden voor objecten. Is dit een uitbreiding op de extensie lezen of op de extensie objecten?
Foutmelding definieren voor wanneer het maximum aantal terug te geven dataverwerkingen van de server door een request overschreden wordt
Aanbeveling wat te doen als niet alle organisaties de lezen API implementeren
Verwijzen naar beleidsjuridischkader voor inrichting samenwerking tussen organisaties
4. Gebruiksscenario's
4.1 Query voorbeelden
4.1.1 Voorbeeld query op basis van traceID
4.1.2 Voorbeeld query op basis van processingActivityID
4.1.3 Voorbeeld query op basis van dataSubjectId
4.1.4 Voorbeeld query op basis van start_time/end_time
4.2 voorbeeld loggen url lezen API externe partij
4.3 voorbeeld compleet beeld verwerkingsactiviteit krijgen door meerdere lezen APIs aan te roepen
5. Versiebeheer
A. Structuur van een extensie
Elke extensie moet de volgende structuur hebben:
Naam en beschrijving
Hierin wordt de naam van de extensie beschreven en wat het inhoudt.
Doel en nut
Hierin moet beschreven worden wat het doel is van deze extensie. Waar dient de extensie voor? Wie is het doelgroep hiervoor en welke toepassingsgebieden zijn er voor deze extensie?
Technische specificatie
Beschrijf hierin de aanvullende technische specificaties op de core standaard.
Gebruiksscenario's
In dit kopstuk worden de verschillende use cases van de extensie beschreven
Versiebeheer
Hierin wordt de versiebeheer beschreven.
