Hoofdinhoud
Wat is 2-zijdig TLS en hoe werkt het?
Met 2-zijdig TLS (ook wel 2-zijdig SSL genoemd) controleren zowel de client als server elkaar om er zeker van te zijn dat beide partijen een vertrouwde communicatie hebben. Dit gebeurt bij het opzetten van de HTTP-verbinding door middel van een certificaat uitwisseling. Indien de certificaten correct zijn, wordt de HTTP-verbinding beveiligd en is de verbinding dus een HTTPS-verbinding.
Waar moet 2-zijdig TLS gebruikt worden in de DigiD aansluitingen?
In de DigiD aansluitingen (alle typen koppelvlakken) wordt 2-zijdig TLS gebruikt in de verbinding met de DigiD applicatieservers die bereikbaar zijn op was.digid.nl. Afhankelijk van de inrichting van het koppelvlak moet dus bij het opzetten van de HTTP-verbinding met de server was.digid.nl 2-zijdig TLS gebruikt worden.
Indien er gebruik gemaakt wordt van een uitgaande proxyserver, wordt de verbinding waarschijnlijk op de proxyserver (opnieuw) opgezet. In een dergelijke configuratie zal dan mogelijk 2-zijdig TLS op de proxyserver toegepast moeten worden.
De daadwerkelijke toepassing van het certificaat in de applicatie hangt af van welke infrastructuur, platform en code gebruikt wordt. In samenwerking met de leverancier(s) van de code, het platform en/of de infrastructuur kan bepaald worden wat de beste oplossing is. DigiD kan daar geen inzicht in geven. Het advies is dus om dit op te nemen met de leverancier(s) van de applicatie.
Welk certificaat moet gebruikt worden voor 2-zijdig TLS in de DigiD aansluiting ?
Er moet een PKIo Private Root CA - G1 certificaat (met daarin het OIN van de organisatie) gebruikt worden.
Omdat dit certificaat, aan de hand van het OIN dat in het certificaat opgenomen is, alleen maar aangeeft welke organisatie het betreft, kan hetzelfde certificaat gebruikt worden voor zowel de productie-omgeving als de preproductie-omgeving van DigiD. Het zelfde certificaat kan dus gebruikt worden bij het opzetten van de verbinding met de server was-preprod1.digid.nl én met was.digid.nl. Ook kan hetzelfde certificaat gebruikt worden voor meerdere aansluitingen op DigiD.
Ook is het niet van belang op welk (sub)domein het certificaat uitgegeven is (de velden Common Name CN en Subject Alternative Name SAN). Voor 2-zijdig TLS in een koppelvlak met DigiD kan er dus gebruik gemaakt worden van een certificaat dat reeds aanwezig is voor een ander koppelvlak, zelfs als dat een koppelvlak niet met DigiD is. Er kan dus bijvoorbeeld een certificaat gebruikt worden met als CN het (sub)domein backoffice.organisatie.nl, en zelfs als dit domein niet is opgenomen in DNS (en dus niet vindbaar is op Internet). Wel moet er goed gekeken worden naar de risico's als een certificaat voor meerdere doeleinden wordt gebruikt: als het certificaat niet meer werkt (verlopen of ingetrokken), dan worden meerdere verbindingen getroffen.
Voor een leverancier van meerdere aansluitingen op DigiD, bijvoorbeeld een leverancier die voor meerdere organisaties de aansluitingen beheert, is het mogelijk om een certificaat op naam van de leverancier te gebruiken voor 2-zijdig TLS. Een certificaat met als CN het (sub)domein leverancier.nl is dus ook mogelijk, zolang het maar een PKIo Private Root CA - G1 certificaat is (met daarin het OIN van de leverancier). Hiermee kan in sommige gevallen een efficiëntere aansluiting op DigiD gemaakt worden.
Hoe kan ik de werking van 2-zijdig TLS vanuit de applicatie testen?
De werking van 2-zijdig TLS kan getest worden vanaf de server / omgeving waar de private sleutel van het certificaat beschikbaar is. Door gebruik te maken van een HTTP-client (commandline-software zoals cURL, in sommige gevallen ook een browser) kan de verbinding met was-preprod1.digid.nl getest worden en moet het certificaat meegegeven worden in de verbinding. Afhankelijk van de respons van de DigiD applicatieserver kan bepaald worden of het certificaat op de juiste wijze wordt gebruikt voor 2-zijdig TLS.
De verschillende testscenario's zijn hieronder als voorbeeld uitgewerkt bij gebruik van cURL vanaf de commandline. Testscenario 5 resulteert in een "geslaagde" verbinding met DigiD.
Update
- 22 september 2022: Factsheet generiek gemaakt voor alle DigiD aansluitingen
- 4 januari 2022: testscenario’s aangevuld.
| Nr | Testscenario | cURL commando | Output van cURL | Resultaat |
|---|---|---|---|---|
| 1 | Geen certificaat meegeven in de verbinding | curl -v https://was-preprod1.digid.nl/ | 302 Moved Temporarily | Redirect naar www.digid.nl |
| 2 | Verkeerde certificaat of private sleutel meegeven in de verbinding | curl --key verkeerde.key --cert verkeerde.crt -v https://was-preprod1.digid.nl/ | curl: (58) unable to set private key file: 'verkeerde.key' type PEM | Er wordt geen verbinding opgezet |
| 3 | Een niet PKIo certificaat meegeven in de verbinding | curl --key geenPKIo.key --cert geenPKIo.crt -v https://was-preprod1.digid.nl/ | curl: (56) OpenSSL SSL_read: connection reset by peer * Afhankelijk van het OS en de SSL library kan hier een andere melding komen. Het resultaat is dat de verbinding wordt afgebroken. |
Verbinding wordt afgebroken |
| 4 | Een PKIo certificaat meegeven in de verbinding dat niet geldig is | curl --key ongeldigePKIo.key --cert ongeldigePKIo.crt -v https://was-preprod1.digid.nl/ | curl: (56) OpenSSL SSL_read: connection reset by peer * Afhankelijk van het OS en de SSL library kan hier een andere melding komen. Het resultaat is dat de verbinding wordt afgebroken. |
Verbinding wordt afgebroken |
| 5 | Een PKIo certificaat meegeven in de verbinding dat wel geldig is. | curl --key goedePKIo.key --cert goedePKIo.crt -v https://was-preprod1.digid.nl/ | 404 Not Found | Foutpagina (omdat het domein zonder URI wordt geraadpleegd) |
Welke aspecten van het certificaat moeten gecontroleerd worden voor 2-zijdig TLS?
Het certificaat, zowel van de server als van de client, moet gecontroleerd worden op geldigheid. De volgende aspecten zijn hierbij van belang:
- De geldigheidsdatum: is het certificaat niet verlopen?
- De domeinnaam: klopt de domeinnaam met de CN of de SAN's in het certificaat?
- De vertrouwensketen (trustchain): zijn de bovenliggende certificaten tot aan de root ook geldig?
- De status: is het certificaat niet ingetrokken (staat het certificaat niet op de Certificate Revocation List CRL)?
De daadwerkelijk uitgevoerde controle van het certificaat hangt af van welke infrastructuur, platform en software gebruikt wordt. In principe voert goede HTTP- en TLS-client software (een browser, maar ook commandline-software zoals cURL) automatisch deze controles uit bij gebruik van het certificaat, en hoeft er niet extra gecontroleerd te worden op deze aspecten. In sommige gevallen moet er toch een "handmatige" controle plaatsvinden, door extra software of code te gebruiken. DigiD kan daar geen inzicht in geven. Het advies is dus om dit op te nemen met de leverancier(s) van de applicatie.
Daarnaast is er nog het aspect dat de organisatie die bij het certificaat hoort gecontroleerd moet worden. Binnen het PKIoverheid stelsel zijn diverse waarborgen opgenomen, waaronder de vastlegging van het OIN in het certificaat, om de organisatie die bij het certificaat hoort te kunnen controleren. De certificaten binnen het PKIoverheid stelsel die onder de Private Root CA - G1 vallen, zijn dan ook Organization Validated (OV) certificaten. Voor het gebruik van 2-zijdig TLS vindt DigiD het daarom voldoende om te controleren dat de root van het certificaat de PKIo Private Root CA - G1 is, door middel van de vertrouwensketen (trustchain) van het certificaat.
Hoe kan de vertrouwensketen (trustchain) van een PKIo Private Root CA - G1 certificaat gecontroleerd worden?
De controle van de trustchain vindt in principe plaats door de HTTP- en TLS-client software (een browser, maar ook commandline-software zoals cURL). Dit doet deze software meestal door de trustchain te vergelijken met de certificaten in de zogenoemde truststore. De truststore bevat een verzameling certificaten op het platform of in de infrastructuur die vertrouwd wordt. Als de trustchain van het te controleren certificaat voorkomt in de truststore, betekent dit dat de vertrouwensketen op orde is en dus het certificaat vertrouwd kan worden.
De PKIo Private Root CA - G1 staat meestal niet standaard in de truststore van het platform of de infrastructuur, omdat het een specifieke, niet-publieke root is van PKIoverheid. Om ervoor te zorgen dat certificaten onder deze root toch vertrouwd worden, dient de root eenmalig opgenomen te worden in de truststore. Hoe dit moet op het platform of in de infrastructuur, kan DigiD geen inzicht in geven. Het advies is dus om dit op te nemen met de leverancier(s) van de applicatie.
De root certificaten van PKIoverheid zijn te vinden op de website https://cert.pkioverheid.nl en kunnen daarvandaan gedownload worden om op te nemen in de truststore of te gebruiken bij de controle in de applicatie.
Op sommige platforms (zoals Azure) is het niet mogelijk een trustchain toe te voegen. In dat geval moet u een andere oplossing zoeken door midel van een uitgaande proxyserver of aanvullende TLS-software op de applicatieserver.
Moet het specifieke certificaat van was.digid.nl gecontroleerd worden?
Het is mogelijk een controle te doen van het specifieke certificaat dat gebruikt wordt door een server. Dit wordt ook wel certificate pinning genoemd. Bij dit mechanisme wordt het unieke kenmerk van het certificaat gecontroleerd, ook wel de pin genoemd. Dit maakt de verbinding mogelijk nog veiliger, maar dit leidt voor het gebruik van 2-zijdig TLS tot extra beheer: als het certificaat vervangen wordt, verandert ook de pin van het certificaat en moet meestal de software of applicatie hier ook op aangepast worden. Deze extra beheerlast vergroot ook de kans op (korte) verstoringen in de verbinding. DigiD adviseert dan ook om certificate pinning niet te gebruiken voor 2-zijdig TLS in het koppelvlak met was.digid.nl (en dus ook niet met was-preprod1.digid.nl).
Hoe kan het certificaat van was.digid.nl toch ingezien worden?
Een certificaat is per definitie bestemd voor publiek gebruik, alleen de private sleutel waarmee het certificaat gebruikt wordt, dient goed beveiligd te blijven. De meeste HTTP- en TLS-client software (een browser, maar ook commandline-software zoals cURL) kan het certificaat inzichtelijk maken, bijvoorbeeld in een browser door op het "slotje" of ander symbool in de browserbalk te klikken.
Voor de volledigheid worden bij een wijziging van het certificaat van was.digid.nl en was-preprod1.digid.nl deze als download (een certificaatbestand in een zip-file) aangeboden op de documentatie-pagina van DigiD.