Ik heb zairyu-card-reader uitgebracht, een open-source Windows-applicatie waarmee informatie op Japanse verblijfskaarten kan worden uitgelezen met een geschikte USB NFC-lezer.
Het is een relatief kleine applicatie, maar het project brengt verschillende onderwerpen samen die belangrijk zijn in mijn werk: praktische administratieve problemen oplossen, persoonsgegevens beschermen, complexe techniek bruikbaar maken voor niet-technische medewerkers en beperkingen eerlijk documenteren.
In dit artikel leg ik uit waarom ik de applicatie heb gebouwd, waarom alles volledig lokaal op de computer gebeurt en wat ik heb geleerd tijdens de voorbereiding van de publieke release.
Een praktisch probleem in de schooladministratie
Ik werk met internationale studenten op een Japanse taalschool.
Informatie op een verblijfskaart is voor mij daarom geen abstract gegevensformaat. Het maakt deel uit van dagelijkse administratieve werkzaamheden.
Scholen moeten onder andere de verblijfsstatus, verblijfsduur, het kaartnummer, adres en eventuele toestemming voor activiteiten buiten de verblijfsstatus controleren.
Op nieuwe verblijfskaarten die vanaf 14 juni 2026 zijn uitgegeven, wordt de verblijfsduur niet meer op de fysieke kaart afgedrukt.
Toen ik deze applicatie ontwikkelde, liet ook de officiële Residence Card Reader-applicatie deze informatie niet zien. De Japanse immigratiedienst had aangekondigd dat er rond september 2026 een bijgewerkte officiële applicatie zou verschijnen.
Hierdoor ontstond onmiddellijk een praktisch probleem.
De verblijfsduur is nog steeds opgeslagen in de IC-chip, maar medewerkers hebben niet altijd een eenvoudige manier om deze informatie te controleren. De verblijfsduur kan ook nodig zijn bij het invullen van immigratiegerelateerde online procedures.
Ik begon de technische structuur van de kaart te onderzoeken om te begrijpen of de ontbrekende informatie veilig en betrouwbaar kon worden uitgelezen.
Dat onderzoek groeide geleidelijk uit tot een werkende applicatie.
Waarom ik geen cloudoplossing wilde
Een verblijfskaart bevat zeer gevoelige persoonsgegevens.
Bij het ontwerpen van een hulpmiddel voor dit soort gegevens zou de eerste vraag niet moeten zijn:
> Hoeveel informatie kan de applicatie verzamelen?
Een betere vraag is:
> Wat moet de applicatie minimaal doen, en hoe voorkomen we onnodige blootstelling van de gegevens?
Daarom is zairyu-card-reader bewust ontworpen als een volledig lokale applicatie.
Tijdens het uitlezen van een kaart:
- worden geen kaartgegevens naar een server verzonden;
- wordt geen cloudservice gebruikt;
- is geen gebruikersaccount nodig;
- worden geen telemetrie of analytische gegevens verzameld;
- wordt geen database met kaartinformatie gebruikt;
- worden geen kaartgegevens naar de schijf geschreven;
- worden geen gezichtsfoto's of volledige kaartafbeeldingen weergegeven of opgeslagen;
- worden geen My Number- of JPKI-gegevens benaderd.
De applicatie draait alleen op de Windows-computer waarop de NFC-lezer is aangesloten.
De lokale server die intern wordt gebruikt, accepteert uitsluitend loopbackverbindingen vanaf dezelfde computer. De applicatie weigert te binden aan een LAN-adres of openbaar netwerkadres.
Het resultaat is bewust beperkt.
Eén bevoegde gebruiker kan op één computer één kaart controleren die fysiek voor hem of haar ligt.
Die beperking is geen ontbrekende functie, maar een onderdeel van het privacyontwerp.
Het kleinste hulpmiddel bouwen dat het probleem oplost
De applicatie detecteert geschikte PC/SC-kaartlezers die met de computer zijn verbonden en controleert of er een kaart op de lezer ligt.
De gebruiker voert het verblijfskaartnummer in dat op de voorkant van de kaart staat.
De applicatie communiceert vervolgens met de IC-chip en toont 17 velden die door een medewerker moeten worden gecontroleerd.
Afhankelijk van de generatie van de kaart worden sommige waarden als gestructureerde tekst opgeslagen. Andere gegevens, met name namen en adressen, kunnen als afbeeldingen zijn opgeslagen.
Wanneer dat nodig is, gebruikt de applicatie een lokaal OCR-model om deze afbeeldingen te lezen. De afbeelding wordt niet naar een externe OCR-service geüpload.
De applicatie controleert ook de cryptografische relatie tussen de uitgelezen gegevens en de ondersteunde certificaten die bij de applicatie zijn verpakt.
Deze digitale-handtekeningcontrole is nuttig, maar heeft een belangrijke beperking.
Een geslaagde controle bewijst op zichzelf niet dat de kaart op dit moment nog geldig is of dat deze niet later ongeldig is verklaard.
De applicatie helpt een bevoegde gebruiker om informatie te bekijken en controleren. Zij neemt geen administratieve of juridische beslissingen.
OCR moet altijd handmatig worden gecontroleerd
Lokale OCR was een van de moeilijkere onderdelen van het project.
Namen op verblijfskaarten kunnen ongebruikelijke spaties, lange geromaniseerde namen, meerdere schriftsystemen of tekens bevatten die niet altijd goed door OCR-modellen worden herkend.
Ook adressen bevatten complexe plaatsnamen, kanji en lay-outs die moeilijk correct te segmenteren zijn.
Tijdens het testen kwam ik onder andere de volgende problemen tegen:
- spaties op de verkeerde plaats in een naam;
- ontbrekende delen van lange namen;
- ontbrekende of verkeerd herkende tekens;
- onjuiste segmentatie van adressen;
- verkeerd herkende kanji in complexe plaatsnamen;
- een onvolledige of incorrecte laatste adresregel.
Daarom moet ieder veld dat door OCR is geproduceerd worden vergeleken met de fysieke kaart.
De interface doet niet alsof OCR perfect is.
Wanneer een waarde niet kan worden uitgelezen, toont de applicatie dat het veld niet kon worden gelezen. Er wordt geen waarde geraden.
Onzekerheid moet zichtbaar blijven voor de gebruiker.
Dat was een belangrijk ontwerpprincipe tijdens het hele project.
Testen zonder persoonsgegevens te publiceren
De geautomatiseerde tests gebruiken uitsluitend synthetische gegevens.
Echte namen, adressen, kaartnummers, foto's, chipdumps, certificaten en handtekeningen horen niet thuis in een openbare repository of issue tracker.
Naast de synthetische tests heb ik de applicatie in de praktijk getest met meer dan 60 nieuwere echte Japanse verblijfskaarten en ongeveer 10 kaarten van een oudere generatie.
Deze tests zijn uitgevoerd met een Sony FeliCa RC-S300-lezer op Windows 10, Windows 11 en Windows Server 2016.
De gestructureerde gegevens uit de IC-chip en de digitale-handtekeningcontrole werkten tijdens deze tests correct.
Dat betekent niet dat iedere combinatie van kaart, kaartlezer, stuurprogramma, Windows-installatie en OCR-omgeving gegarandeerd werkt.
Hardware en stuurprogramma's kunnen zich anders gedragen en praktijktests kunnen nooit alle mogelijke omgevingen afdekken.
De openbare documentatie beschrijft daarom zowel wat is getest als wat onzeker blijft.
Van een intern hulpmiddel naar een openbaar project
Een hulpmiddel dat privé binnen één organisatie wordt gebruikt, is niet hetzelfde als een verantwoord uitgebracht open-sourceproject.
Voor een publieke release was meer nodig dan alleen de broncode naar GitHub uploaden.
Ik heb onder andere het volgende toegevoegd:
- Engelse en Japanse documentatie;
- installatie- en probleemoplossingsgidsen;
- privacy- en beveiligingsdocumentatie;
- een proces om kwetsbaarheden privé te melden;
- een releasechecklist;
- informatie over afhankelijkheden en licenties van derden;
- documentatie over de certificaten voor offline verificatie;
- reproduceerbare afhankelijkheidsbestanden;
- geautomatiseerde tests en releasecontroles;
- een Windows-pakket waarvoor Python niet hoeft te worden geïnstalleerd.
Ik heb ook functies verwijderd die niet meer pasten binnen de privacygrenzen van het project.
De applicatie heeft bijvoorbeeld geen algemene functie om alle gegevens naar het klembord te kopiëren.
Het doel is informatie ter controle weer te geven, niet een nieuwe en onbeheerde manier te creëren om gevoelige gegevens naar andere programma's te kopiëren.
Deze keuzes maken de applicatie minder uitgebreid, maar wel duidelijker en consistenter.
Waarom ik het project als open source uitbracht
Er zijn verschillende redenen waarom ik besloot het project te publiceren.
Ten eerste is het administratieve probleem niet uniek voor één school.
Taalscholen, andere onderwijsinstellingen, werkgevers, ondersteuningsorganisaties en inwoners zelf kunnen tegen hetzelfde probleem aanlopen.
Ten tweede is transparantie belangrijk bij software die gevoelige informatie verwerkt.
Openbare broncode maakt het mogelijk voor andere ontwikkelaars om te bekijken hoe gegevens worden verwerkt en om mogelijke problemen te melden.
Ten derde wilde ik ook de beperkingen van het project openbaar maken.
Open source betekent niet dat overdreven claims moeten worden gedaan. Gebruikers moeten net zo duidelijk kunnen begrijpen wat een hulpmiddel niet ondersteunt als wat het wel kan.
De applicatie is onafhankelijk ontwikkeld en is niet verbonden aan, goedgekeurd door, aanbevolen door of gecertificeerd door de Immigration Services Agency of Japan of het Japanse Ministerie van Justitie.
Een kaart mag alleen worden uitgelezen wanneer de kaarthouder toestemming heeft gegeven of wanneer de gebruiker op een andere manier bevoegd is om de kaart te controleren.
Wat ik van dit project heb geleerd
Het interessantste onderdeel van dit project was niet alleen de NFC-communicatie.
Het was vooral de combinatie van uiteenlopende onderwerpen:
- een werkelijk administratief proces begrijpen;
- de technische structuur van de kaart onderzoeken;
- met fysieke hardware communiceren;
- digitale handtekeningen verifiëren;
- OCR volledig lokaal uitvoeren;
- een Python-applicatie verpakken voor gewone Windows-gebruikers;
- gevoelige persoonsgegevens beschermen;
- documentatie schrijven voor gebruikers en ontwikkelaars;
- beslissen welke functies bewust niet moeten bestaan.
Het project bevestigde opnieuw iets dat ik vaker heb geleerd bij het ontwikkelen van hulpmiddelen voor scholen.
Een nuttige applicatie hoeft niet alles te automatiseren.
Soms is een klein, begrijpelijk hulpmiddel beter. Een hulpmiddel dat mensen de informatie geeft die ze nodig hebben, terwijl de technische en privacygrenzen duidelijk blijven.
Bekijk het project
De broncode, documentatie, installatie-instructies en Windows-releases zijn beschikbaar op GitHub:
Meldingen van fouten en compatibiliteitsproblemen zijn welkom, maar gebruik in openbare meldingen uitsluitend synthetische gegevens. Plaats nooit echte verblijfskaartgegevens in een GitHub-issue.