Buiten het aanbieden van webservices biedt MAGDA ook bestandsuitwisseling aan. De uitwisseling van gegevens gebeurt dan via FTP. Deze worden beveiligd met FTPS waarbij alle informatie versleuteld over een TLS kanaal gestuurd wordt en een VO-DCBaaS-certificaat gebruikt wordt.

De uitwisseling van bestanden tussen afnemers van het MAGDA platform en MAGDA gebeurt via FTPS-servers. Dit wil zeggen dat de doeltoepassing van de afnemer via een zogenaamde FTP-client die FTPS ondersteunt bestanden klaar zet of ophaalt op één van de VIP FTP Servers.  MAGDA zelf plaatst geen bestanden op de servers van afnemers en pikt ook geen bestanden op bij de afnemers.

Het is de verantwoordelijkheid van de afnemer(doeltoepassing) om tijdig de bestanden van de VIP FTPS-server af te halen, hierbij rekening houdend met de richtlijnen rond onderhoud van die folders.

Open

Folderstructuur

Vooraleer een afnemer bestandstransferdiensten van MAGDA kan gebruiken en verbinding kan maken met het MAGDA-platform, moet de afnemer een toelatingsaanvraag doorlopen hebben op het MAGDA platform.. Tijdens de toelatingsprocedure zal de afnemer een eigen home-folder toegewezen krijgen. De home-folder van elke afnemer is standaard opgedeeld in volgende subfolders.

to_vip	Hierin zal de afnemer/doeltoepassing de vraagbestanden voor VIP klaarzetten. Na verwerking verwijdert VIP de bestanden uit deze folder (en plaatst ze in cache\to_vip).	Open
from_vip	Hierin plaatst VIP alle bestanden voor de afnemer/doeltoepassing, dus zowel de antwoordbestanden als de (niet-publieke) publicaties. De afnemer zal zelf het initiatief nemen om deze bestanden op te halen en is zelf verantwoordelijk voor de maintenance van deze folder; m.a.w. de afnemer/doeltoepassing zal de reeds opgehaalde bestanden zelf verwijderen. Eventueel kunnen de opgehaalde bestanden vóór verwijdering worden overgezet naar de cache\from_vip.
cache	De cache folder heeft op haar beurt 2 subfolders, to_vip en from_vip.
cache/to_vip	Bevat alle bestanden die door VIP opgepikt zijn. Dit laat toe, om binnen de retentietijd, selectieve bestanden terug in de verwerkingsketting te zetten.
cache/from_vip	Bevat alle bestanden die door de doeltoepassing opgepikt zijn en daarna in deze folder verplaatst.
publiek	Bevat alle publicaties die voor iedereen bestemd zijn, m.a.w. niet afnemer/doeltoepassing specifiek.

Bestandsuitwisseling

Naamgeving van de bestanden

Voor de naamgeving van zowel de aan te leveren bestanden als de bestanden door MAGDA aangeboden, wordt verwezen naar de diensthandleidingen: Handleidingen MAGDA-diensten per domein

Opkuis bestanden

Zoals eerder aangehaald rekent MAGDA erop dat de afnemers zelf hun folders (from_vip en cache\from_vip) onderhouden. De afnemers worden aangemoedigd om automatische scripts te voorzien waarbij direct na het ophalen van een bestand datzelfde bestand wordt gekopieerd naar de cache en dan wordt verwijderd uit de from_vip folder.

Toch houdt MAGDA er rekening mee dat niet alle afnemers altijd deze richtlijnen zullen volgen. Onder meer daarom zal MAGDA zelf de folders regelmatig opkuisen door het verwijderen van oude bestanden. Hieronder wordt een samenvatting gegeven van de verschillende folders die binnen een gebruikersaccount bestaan, met een korte beschrijving van het onderhoud.

Beveiliging

Algemeen

Zoals eerder beschreven moet een afnemer altijd een toelatingsprocedure doorlopen en een FTPS account krijgen om gegevens te kunnen uitwisselen met MAGDA. Omdat toegangscontrole op basis van account (met gebruikersnaam en wachtwoord) op zich weinig bescherming biedt tegen ongeoorloofd gebruik, vereist MAGDA dat de connectie versleuteld wordt en dat afnemers en hun toepassing aan de hand van een certificaat geïdentificeerd worden.

Om de MAGDA servers te beschermen tegen aanvallen van buiten af, dient elke FTPS-communicatie te gebeuren vanuit een vooraf aangeduide PC of server aan afnemer kant. De afnemer moet daarom tijdens het aansluitingsproces het IP-adres van de PC of server die zal gebruikt worden voor de FTP-communicatie doorgeven. Op firewall-niveau zal FTP-verkeer enkel toegestaan worden voor dat IP-adres.

Software en connectie-instellingen

De  FTPS servers hebben de volgende DNSnamen waar u hen kan bereiken:

Netwerkinstellingen

Voor FTPS-verbindingen zijn er twee poorten in gebruik: een commando-poort en een gegevensverbindingspoort.

Het FTP protocol gebruikt standaard het poort 21 voor commando. De FTPS versie op het MAGDA platform gebruikt dezelfde poort (FTPS Explicit).

De gegevensverbindingspoorten die vast bepaald worden, zitten in de reeks poorten van 40000-42000.

Dit betekent dat afnemers die achter een forward proxy zitten, moeten de poorten 21 OUTBOUND en 40000-42000 INBOUND whitelisten om aan de nieuwe FTPS server te kunnen.

Software instellingen voor Windows

In WinSCP, moet de volgende configuratie gebeuren:

Aanmaken van een nieuwe site:

• Fite Protocol:      FTP

• Encryption:         TLS/SSL Explicit encryption

• Hostname:          vipftps.vlaanderen.be voor productie, of vipftps-aip.vlaanderen.be voor test

• Port number       21 (Default niet aanpassen)

• Username           Moet overeen komen met CN van het certificaat dat gebruikt wordt

Dan in op het "Advanced" knop drukken om het certificaat en privaat sleutel in te stellen:

In "Advanced" - "TLS/SSL" tab:

• Minimum TLS/SSL version: op TLS 1.2 zetten

• Client certificate file:  wijzen naar de certificaten en private sleutels

Voor het certificaat en de private sleutels adviseren wij sterk om het PKCS12 formaat te gebruiken. De private sleutel wordt ook dan beveiligd door een wachtwoord die tijdens aanmaak van een PKCS12 keystore moet gegeven worden. Zie ook Certificaten: Aanmaak op deze gebruikersomgeving.

PKCS12 keystores kunnen aangemaakt worden door b.v. het gebruiken van de Java "keytool IUI" programma, of door het OpenSSL programma te gebruiken:

openssl pkcs12 -export -in certificate.pem -inkey key.pem -out cert_and_key.p12

Als het vorige commando gebruikt wordt, gaat er een wachtwoord aangevraagd worden voor de sleutel (als er een nodig is) en gaat er een ander wachtwoord aangevraagd worden voor het resultaat bestand.

Na het drukken op de "Login" knop, gaat er wachtwoord gevraagd worden voor de ".p12" bestand. Hier moet het wachtwoord dat gebruikt is voor het aanmaken van het .p12 bestand ingegeven worden.

Software instellingen voor andere besturingssystemen

Voor andere besturingssystemen (Linux, UNIX) kan je Curl of LFTP gebruiken om van FTPS 2 way gebruik te maken. Hieronder vindt je de nodige commando’s om de connecties te bewerkstelligen. Uiteraard moeten dezelfde poorten openstaan als hierboven beschreven (poort 21 als controle poort en alle poorten tussen 40.000 en 42.000 langs waar de data zal verzonden worden).

Curl
Via Curl is het mogelijk om een FTPS 2 way connectie te maken. Je dient Curl uiteraard te installeren op je server
Hieronder vindt je de syntax voor connectie naar onze TNI omgeving
curl -v --sessionid -u usernamevanhetcertificaat:blabla --ftp-ssl --cert locatievanjecertificaatfile/crt file van het certificaat
--key locatievandekeyfilevanjecertificaat/keyfilevanhetcertificaat --pass paswoordvanhetcertificaatinplaintext --cacert vipftps-aip_vlaanderen_be.crt -p -x ftp://vipftps-aip.vlaanderen.be/from_vip/* -l
Hieronder vindt je de syntax voor connectie naar onze PRD omgeving
curl -v -u usernamevanhetcertificaat:blabla --ftp-ssl --cert locatievanjecertificaatfile/crt file van het certificaat
--key locatievandekeyfilevanjecertificaat/keyfilevanhetcertificaat --cacert vipftps_vlaanderen_be.crt ftp://vipftps.vlaanderen.be/from_vip/* -l

Legende:
usernamevanhetcertificaat:blabla : je username is dezelfde als de CN van je certificaat. Het dubbele punt en blabla is omdat curl altijd een paswoord verwacht ook al wordt dit in dit geval niet gebruikt (je certificaat wordt als paswoord gebruikt). Je mag om het even welk paswoord gebruiken zolang je certificaat maar correct is
locatievanjecertificaatfile/crt file: hier moet je de locatie waar je je certificaat hebt opgeslagen alsook de crt file van je certificaat specifiëren
locatievandekeyfilevanjecertificaat/keyfilevanhetcertificaat: je dient eveneens de locatie van de key file van je certificaat alsook de key file zelf te specifiëren
vipftps-aip_vlaanderen_be.crt/vipftps_vlaanderen_be.crt : dit zijn de server certificaten die je specifiek moet trusten. Indien nodig kunnen we je die bezorgen.

LFTP
LFTP is een tool waarmee je oa. FTPS 2 way connectie kan maken. UIteraard moet dit geinstalleerd zijn op je server.
Je zal zien dat LFTP om een paswoord zal vragen (zelfs als je een certificaat specifieert). Je mag gewoon op Enter drukken en dan zal LFTP het certificaat als paswoord gebruiken. Indien het het juiste certificaat is zal de connectie lukken.

!!NOOT: wanneer
Hieronder vindt je de syntax voor connectie naar TNI
❯ lftp
lftp :~>
lftp :~> exit
❯ lftp
lftp :~> set ftp:passive-mode true
lftp :~> set ftp:ssl-force true
lftp :~> set ssl:cert-file jecrtfile
lftp :~> set ssl:key-file dekeyfilevanjecertificaat
lftp :~> set ftp:ssl-protect-data true
lftp :~> set ftp:use-site-utime2 false
lftp :~> set ssl:verify-certificate no
lftp :~> connect vipftps-aip.vlaanderen.be
lftp vipftps-aip.vlaanderen.be:~> login usernamevanhetcertificaat
Password:
lftp usernamevanhetcertificaat@vipftps-aip.vlaanderen.be:~> ls

Hieronder vindt je de syntax voor connectie naar PRD
❯ lftp
lftp :~>
lftp :~> exit
❯ lftp
lftp :~> set ftp:passive-mode true
lftp :~> set ftp:ssl-force true
lftp :~> set ssl:cert-file jecrtfile
lftp :~> set ssl:key-file dekeyfilevanjecertificaat
lftp :~> set ftp:ssl-protect-data true
lftp :~> set ftp:use-site-utime2 false
lftp :~> set ssl:verify-certificate no
lftp :~> connect vipftps.vlaanderen.be
lftp vipftps.vlaanderen.be:~> login usernamevanhetcertificaat
Password:
lftp usernamevanhetcertificaat@vipftps.vlaanderen.be:~> ls

Legende
jecrtfile : dit is het certificaat dat je gebruikt om aan te loggen.
dekeyfilevanjecertificaat: dit is de keyfile van je certificaat dat je dient te specifiëren
usernamevanhetcertificaat: je username is dezelfde als de CN van je certificaat.

NOOT:
LFTP verwacht een ongeencrypteerde key. Als je dus een paswoord op je key hebt staan dan moet je deze key eerst ontsleutelen met het volgende commando

openssl rsa -in ssl.key.encrypted -out ssl.key.decrypted (vervang ssl.key met de naam van dekeyfile van je certificaat)

Het commando zal dan het wachtwoord van de key vragen. Vul dit in en het commando zal dan een gedecrypteerde key aanmaken die je dan dient te gebruiken in de lftp commando’s hierboven.

!!!!CURL en LFTP VIA PROXY!!!!

Sommige afnemers zullen via een proxy connectie moeten maken met onze vipftps servers. Dit is een complex gegeven omdat niet alle proxy technologie FTPS 2 way ondersteunt. Als u zeker weet dat uw proxy FTPS 2 way ondersteunt vindt u hieronder de commando’s om met Curl of LFTP over een proxy connectie te maken.

CURL

Voor TNI

curl -v --sessionid -u usernamevanhetcertificaat:blabla --ftp-ssl --cert locatievanjecertificaatfile/crt file --key locatievandekeyfilevanjecertificaat/keyfilevanhetcertificaat --pass passwoordvanjecertificaatinplaintext --cacert vipftps-aip_vlaanderen_be.crt -p -x http://proxyserver:proxypoort ftp://vipftps-aip.vlaanderen.be/from_vip/* -l

Voor PRD
curl -v --sessionid -u usernamevanhetcertificaat:blabla --ftp-ssl --cert locatievanjecertificaatfile/crt file --key locatievandekeyfilevanjecertificaat/keyfilevanhetcertificaat --pass passwoordvanjecertificaatinplaintext --cacert vipftps_vlaanderen_be.crt -p -x http://proxyserver:proxypoort ftp://vipftps.vlaanderen.be/from_vip/* -l

Legende

locatievandekeyfilevanjecertificaatdekeyfilevanjecertificaat: dit is de locatie van en de keyfile zelf van je certificaat dat je dient te specifiëren
usernamevanhetcertificaat: je username is dezelfde als de CN van je certificaat.
passwoordvanjecertificaatinplaintext het paswoord dat je op je certificaat hebt staan. Dat dien je in plain text te typen

proxyserver:proxypoort: dit is de naam van je proxyserver gevolgd door een dubbel punt en de poort langs waar de requests zullen verlopen (standaard is dat 8080 maar dat kan een andere zijn. Vraag aan uw netwerkmensen welke er gebruikt wordt)

LFTP
Voor TNI

 set ftp:proxy http://proxyserver:proxypoort
set hftp:Proxy http://proxyserver:proxypoort
set hftp:use-type false
set ftp:use-hftp false
set ftp:ssl-auth TLS
set ftp:bind-data-socket true
set ftp:ssl-force true
set ftp:ssl-protect-data true
set ftp:ssl-protect-list true
set ftp:ssl-data-use-keys true
set ftp:ssl-copy-sid true
set ftps:initial-prot "P"
set ftp:use-allo false
set ssl:verify-certificate true
set ssl:cert-file jecrtfile
set ssl:key-file dekeyfilevanjecertificaat
set ssl:check-hostname true
set ftp:passive-mode true
set ftp:use-site-utime2 false

open -u usernamevanhetcertificaat,"" ftp://vipftps-aip.vlaanderen.be
Legende
jecrtfile : dit is het certificaat dat je gebruikt om aan te loggen.
dekeyfilevanjecertificaat: dit is de keyfile van je certificaat dat je dient te specifiëren
usernamevanhetcertificaat: je username is dezelfde als de CN van je certificaat.
Voor PRD

 set ftp:proxy http://proxyserver:proxypoort
set hftp:Proxy http://proxyserver:proxypoort
set hftp:use-type false
set ftp:use-hftp false
set ftp:ssl-auth TLS
set ftp:bind-data-socket true
set ftp:ssl-force true
set ftp:ssl-protect-data true
set ftp:ssl-protect-list true
set ftp:ssl-data-use-keys true
set ftp:ssl-copy-sid true
set ftps:initial-prot "P"
set ftp:use-allo false
set ssl:verify-certificate true
set ssl:cert-file jecrtfile
set ssl:key-file dekeyfilevanjecertificaat
set ssl:check-hostname true
set ftp:passive-mode true
set ftp:use-site-utime2 false

open -u usernamevanhetcertificaat,"" ftp://vipftps.vlaanderen.be
Legende
jecrtfile : dit is het certificaat dat je gebruikt om aan te loggen.
dekeyfilevanjecertificaat: dit is de keyfile van je certificaat dat je dient te specifiëren
usernamevanhetcertificaat: je username is dezelfde als de CN van je certificaat.

Connectie instellingen tussen servers

Afnemers die met een applicatie connectie willen leggen naar onze FTPSservers moeten ongeveer de zelfde stappen volgens als voor een UI client:

• Een FTP library gebruiken die FTPS client certificaat ondersteunt voor de programmeertaal die gebruikt wordt;

• Het aanmaken van een keystore met erin het client certificaat en de private sleutel;

• Optioneel, een trust store aanmaken, waarin het VO DCB Root CA certificaat zal staan;

• De nodige netwerk verbindingen (laten) opzetten.

Hier is een pagina die meer in detail beschrijft hoe de libraries moeten gebruikt worden: FTPS Library Technische Informatie

Vernieuwing van het certificaat van onze FTP Servers

Omdat we met FTPS 2 way werken (waarbij zowel uw certificaat als afnemer als het certificaat van onze FTP server wordt afgecheckt) wordt ons server certificaat om de zoveel tijd geupdate. U zal dan om de zoveel tijd ons server certificaat moeten vertrouwen in uw truststore. U zal hiervoor tijdig worden verwittigd zodat u de nodige stappen hiervoor kan uitvoeren.
Om dit server certificaat te vernieuwen zijn de te ondernemen stappen verschillend afhankelijk van de wijze waarop u ons server certificaat vertrouwd. U kan op het hoogste niveau ons server certificaat vertrouwen door de Root Certification Authority (RCA) en Intermediate Certification Authority (ICA) toe te voegen in uw truststore. De Certification Authorities kan u vinden op https://documenten.pki.vlaanderen.be . Het betreft de Certificaat Vlaamse overheid Root CA 2020 en Certificaat Vlaamse overheid Issuing CA 2 2020 (zie screenshot hieronder)

Daarnaast kan u op het laagste niveau ons server certificaat vertrouwen door het server certificaat via OpenSSL op te vragen.U dient hiervoor OpenSSL geinstalleerd te hebben. De commando’s om het server certificaat te verkrijgen vindt u hieronder.
Voor TNI

openssl s_client -connect vipftps-aip.vlaanderen.be:21 -starttls ftp
Voor PRD

openssl s_client -connect vipftps.vlaanderen.be:21 -starttls ftp

De output van beide commando’s zal het server certificaat tonen. Het begint met -----BEGIN CERTIFICATE----- en eindigt met -----END CERTIFICATE-----
DIt volledig stuk van de output (inclusief het eerste streepje tot het laatste streepje) moet opgeslagen worden als een .crt file en toegevoegd worden in een truststore of gebruikt worden in uw commando om verbinding te maken met vipftps-aip.vlaanderen.be of vipftps.vlaanderen.be (bv bij het stuk cacert van Curl zie hierboven)

!! Gekende problemen !!

We hebben gemerkt dat afnemers die al langer met FTPS 2 way een connectie maken en hun certificaat reeds lang hebben gedownload en upgraden naar een nieuwe OpenSSL een foutmelding kunnen krijgen die luidt als volgt:
digital envelope routines::unsupported

De oorzaak is dat de nieuwe OpenSSL engine het encryptiealgoritme dat het certificaat encrypteert niet (meer) ondersteund.
De oplossing bestaat erin om het certificaat opnieuw te downloaden vanop https://dcb.vlaanderen.be

Meer info over deze foutmelding bij het gebruik van Winscp vindt u hier
https://winscp.net/forum/viewtopic.php?t=34236

Meer info over deze foutmelding bij het gebruik van scripting van de connectie via oa cURL, JS en anderen vindt u hier
https://stackoverflow.com/questions/72598983/curl-openssl-error-error0308010cdigital-envelope-routinesunsupported

Op deze pagina

Verwante pagina’s