Darts web authenticatie

Transcriptie

1 Darts web authenticatie Handleiding Versie mei 2011 Reinier Vos Communications Security Net BV Brugweg 56 Postbus AG Waddinxveen Copyright Communications Security Net B.V.

2 Titel : Darts web authenticatie Handleiding Auteur : Reinier Vos Versie : 1.3 Datum : 19 mei 2011 Uitgegeven door : Communications Security Net BV Copyright 2010, Communications Security Net B.V., Waddinxveen Niets uit dit document mag vermenigvuldigd en/of openbaar gemaakt worden door middel van druk, fotokopie microfilm, geluidsband, elektronisch of op andere wijze dan ook en evenmin in een retrieval systeem worden opgeslagen zonder voorafgaande schriftelijke toestemming van de bovengenoemde uitgever. Copyright Communications Security Net B.V. 2

3 Inhoud HOOFDSTUK 1 INLEIDING OP HET ONTWERP HET DOEL VAN DIT DOCUMENT DOELGROEP VAN DIT DOCUMENT REIKWIJDTE... 4 HOOFDSTUK 2 ALGEMENE BESCHRIJVING INLEIDING... 5 HOOFDSTUK 3 DE WEBSERVER INLEIDING WEBSERVER CONFIGURATIE Certificaten formaten HDN Root certificaat... 8 HOOFDSTUK 4 WEBSERVICE AANROEP INLEIDING WEBSERVICE OPERATIES XML REQUEST XML Request voorbeeld applicatie WSDL REQUEST WSDL Request voorbeeld applicatie WSDL functies authcertificateforgroup en authaansluitnummerforgroup getgroupsforaansluitnummer getallparamsforservice doaccounting ACCOUNTING APPENDIX A XML REQUEST XSD APPENDIX B XML REQUEST VOORBEELD APPENDIX C VOORBEELD WSDL SCRIPT Copyright Communications Security Net B.V. 3

4 Hoofdstuk 1 Inleiding op het ontwerp 1.1 Het doel van dit document Dit document heeft tot doel de implementie van het authenticeren/autoriseren met behulp van HDN certificaten te beschrijven. 1.2 Doelgroep van dit document De doelgroep bestaat uit ontwikkelaars van websites die bezoekers willen laten authenticeren met behulp van HDN certificaten. Een basiskennis van implementaties van webservices met behulp van SOAP/WSDL en of HTTP/XML (XSD) wordt verondersteld. Tevens wordt globale kennis verondersteld met betrekking tot het configureren van webservers. 1.3 Reikwijdte De scriptvoorbeelden in dit document worden gepresenteerd in PHP. Van de lezer wordt verwacht dat deze de PHP scripts eventueel kan vertalen naar een voor hem of haar beschikbaar alternatief. Verder wordt de webserver configuratie aan de hand van Apache gedemonstreerd. Indien de ontwikkelaar voor een andere webserver kiest wordt verwacht dat deze zelf de vertaalslag kan maken. Copyright Communications Security Net B.V. 4

5 Hoofdstuk 2 Algemene beschrijving 2.1 Inleiding DARTS is een uitbreiding van het Hypotheken Data Netwerk. Met DARTS kunnen dienstaanbieders diensten voor HDN aansluitnummers publiceren. Tevens definieert en implementeert DARTS de structuur en accounting betreffende de autorisatie en authenticatie voor het gebruik tot de diensten. Binnen het HDN netwerk wordt de authenticatie gedaan op basis van HDN certificaten. Certificaten zijn aan een aansluitnummer gekoppeld. De aansluitnummers kunnen in groepen geplaatst worden. Groepen kunnen op hun beurt aan een dienst gekoppeld worden. Hiermee kan worden gedefinieerd welke groepen en dus welke aansluitnummers, toegang tot een dienst hebben. Tevens kunnen aan een dienst-groep combinatie parameters gekoppeld worden. Het configuren van DARTS gebeurt via een webapplicatie Dartsbeheer. Verdere informatie over DARTS en Dartsbeheer is te vinden in de handleiding DARTS. Indien een gebruiker een website bezoekt kan de webserver zo geconfigureerd worden dat deze de browser om een HDN certificaat vraagt. Dit document beschrijft de implementatie om bezoekers van websites the authenticeren en autoriseren met behulp van HDN certificaten. Copyright Communications Security Net B.V. 5

6 Hoofdstuk 3 De Webserver 3.1 Inleiding Alle authenticatie via DARTS geschiedt op basis van certificaten. Aan een browser kan door de webserver om een cliënt certificaat gevraagd worden. Hiervoor dient de webserver dan geconfigureerd te worden. Nadat de webserver het cliënt certificaat ontvangen heeft dient de webserver zichzelf ook met een eigen certificaat bij de CSNET server te authenticeren. In onderstaand figuur is schematisch weergeven welke stappen doorlopen worden. De cliënt maakt via een web-browser verbinding met de webserver. Hiervoor wordt een SSL verbinding opgezet (1). De webserver is zo geconfigureerd dat deze om een cliënt certificaat vraagt. Indien de cliënt een certificaat heeft en deze selecteert wordt het certificaat naar de webserver verzonden (2). Met dit certificaat weet de webserver alleen dat het een geldig HDN certificaat is. Om te autoriseren dient de webserver een webrequest naar de CSNET server te maken (3). Dit verloopt ook over een SSL verbinding. De CSNET server accepteert alleen een authorisatie-request van aansluitnummers die beheerder zijn van de betreffende dienst. De webserver dient dus ook geauthenticeerd en geauthoriseerd te worden. Dit gebeurt ook met behulp van een HDN certificaat (4). Indien de dienstbeheerder toegang heeft zal de CSNET webservice het in (2) verkregen certificaat authenticeren en het resultaat in (5) terugsturen naar de webserver. De webserver kan nu met de verkregen rechten voor de gebruiker de webpagina tonen (6). 3.2 Webserver configuratie Het valt buiten de scope van dit document om voor alle webservers te beschrijven hoe gebruik gemaakt kan worden van cliëntcertificaat authenticatie. Als voorbeeld wordt hier rudimentair uiteen gezet hoe Apache geconfigureerd kan worden. Copyright Communications Security Net B.V. 6

7 De communicatie in (3),(4) wordt opgezet door de CSNET server. Hier hoeft dus op de webserver niets voor geconfigureerd te worden. Er wordt wel om een certificaat gevraagd. Dit wordt echter via een script gerealiseerd en wordt besproken in hoofdstuk 4. (1) en (2) verlopen over een beveiligde verbinding. Dit gebeurt m.b.v. een SSL verbinding. Hiervoor is dus een Server Certificaat benodigd. Dit certificaat is niet per se gerelateerd aan HDN certificaten (mag wel). Configureer een SSL verbinding op de webserver De server is op de volgende manier geconfigureerd voor port# 443 SSLEngine ON SSLCertificateFile [path]/server.pem SSLCertificateKeyFile [path]/server.key Server.pem/server.key zijn hier dus het server certificaat (en hoeft dus geen HDN certificaat te zijn). Nadat de SSL verbinding geconfigureerd is kan de webserver de cliënt om cliënt-certificaten vragen. Hiervoor dienen additionele instellingen toegevoegd te worden. Op webserver wordt optioneel om een cliënt certificaat gevraagd d.m.v. e.g.: SSLCACertificateFile [path]/ hdnca.pem SSLVerifyClient optional SSLOptions +ExportCertData +StdEnvVars SSLVerifyDepth 1 Indien de cliënt een certificaat heeft die dezelfde CN als het root CA certificaat hdnca.pem heeft zal de browser de cliënt vragen het certificaat te selecteren. Als de cliënt deze selecteert wordt deze naar de server verzonden. Indien dit certificaat ook daadwerkelijk door het root certificaat ondertekend is wordt de verbinding door de server geaccepteerd. Door de optie +ExportCertData kan in e.g. PHP het serienummer via $_SERVER['SSL_CLIENT_M_SERIAL'] uitgelezen worden Certificaten formaten HDN certificaten zijn standaard van binair (cer of p12) formaat. Apache vereist een BASE64 encoded DER certificaat. Op de volgende manier kan een p12 omgezet worden naar een.pem formaat: openssl pkcs12 -in cert.p12 -out cert.pem Copyright Communications Security Net B.V. 7

8 3.2.2 HDN Root certificaat Het HDN root certificaat kan via gedownload worden. Dit is het certificaat die de webserver gebruikt om de HDN cliënt certificaten te valideren. Met - openssl verify -CAfile hdnca.pem -verbose xxx.pem kan gecontroleerd worden of een cliënt HDN certificaat (xxx.pem) ook daadwerkelijk door dit CA certificaat ondertekend is. Copyright Communications Security Net B.V. 8

9 Hoofdstuk 4 Webservice aanroep 4.1 Inleiding In dit hoofdstuk wordt als voorbeeld m.b.v. een php script beschreven hoe een gebruiker m.b.v. een cliënt certificaat geautoriseerd kan worden. Door de webserver te configureren zoals in hoofdstuk 3 is beschreven kan e.g. een php script het serienummer van het cliënt certificaat lezen. Het serienummer en de dienst waartegen geautoriseerd dient te worden kan via een webservice naar CSNET verzonden worden. De webservice aanroep verloopt over een vergelijkbare verbinding als die van het cliënt certificaat. De CSNET server accepteert alleen een request indien deze ook een HDN certificaat gebruikt. De ontwikkelaar kan op basis van zijn/haar voorkeur een WSDL of XML request verzenden. Qua functionaliteit zijn deze identiek. De url s van de webservices zijn voor respectievelijk WSDL en XML: Webservice operaties De webservices die via een XML of WSDL request aangeroepen kunnen worden hebben de volgende basis functionaliteiten: - Een aansluitnummer of certificaatserienummer voor een dienst autoriseren - Een record toevoegen aan het centrale DARTS accounting systeem - Een overzicht van alle groepen waar een aansluitnummer in zit opvragen 4.3 XML Request De CSNET webserver verwacht een bericht en beantwoord met een bericht dat voldoet aan het in het in appendix A getoonde XSD schema. De CSNET webserver accepteert alleen een requests indien een geldig HDN certificaat gepresenteerd wordt. Deze dient dus geconfigureerd te worden. De berichtaanvraag dient Serial of Aansluitnr en LogDienstNaam te bevatten. Serial is het serienummer van het cliënt certificaat. LogDienstNaam is de unieke naam voor de dienst die via dartsbeheer geconfigureerd kan worden. Eventueel kunnen de elementen DoAccounting of GetAllgroups meegegeven worden. De CSNET webservice plaats het antwoord in BerichtAntwoord. Eventuele fouten worden in BerichtFout geplaats. Copyright Communications Security Net B.V. 9

10 <Bericht xsi:nonamespaceschemalocation="auth_info.xsd"> <BerichtAntwoord> <AansluitNummer>321319</AansluitNummer> <DienstNaam>man_info</DienstNaam> <GroepNaam>Openbaar/CSNET</GroepNaam> <AccessViagroep>Openbaar/CSNET</AccessViagroep> <Params> <Param> <Name>maatschappij nieuws ophalen</name> <Value>1</Value> </Param> <Param> <Name>param1</Name> <Value>2</Value> </Param> </Params> <Groups> <Group>Openbaar</Group> <Group>Openbaar/Maatschappij</Group> <Group>Openbaar/Maatschappij/sub groep</group> <Group>Openbaar/CSNET</Group> </Groups> </BerichtAntwoord> </Bericht> Bovenstaand bericht is een voorbeeld van een berichtantwoord. Het aansluitnummer van de gebruiker is en deze zit in de groep CSNET. Aan de groep CSNET zijn 2 parameters gekoppeld. Deze zijn onder Params geitereerd XML Request voorbeeld applicatie Apendix B bevat de source code van een voorbeeld script. Via CSNET kan de complete source code verkregen worden. Er wordt eerst een wrapper class gedefinieerd om de request te configureren. De construct van de class leest een aantal instellingen uit een ini file. In de ini file staat o.a. de locatie van de webservice en het cliënt certificaat (van de dienstbeheerder) waarmee het script zich bij de CSNET server authenticeert. Na de class definitie wordt eerst gecontroleerd of de cliënt een certificaat heeft aangeboden. Indien dit zo is staat het serienummer van het certificaat in de $_SERVER variabele. Hierna wordt met behulp van de wrapper class een XML document gecreerd. De aanvraag komt in het element BerichtAanvraag. Zoals in het XSD te zien is moeten hier de elementen Serial en LogDienstNaam in komen te staan. Dit wordt met de methode makerequest gedaan. Het antwoord van de webservice request komt in het object responsexml te staan. Copyright Communications Security Net B.V. 10

11 4.4 WSDL Request Het is ook mogelijk om een XML request volgens WSDL te maken. Het schema kan worden opgevraagd door?wsdl achter de webservice locatie te plaatsen. Het WSDL is volgens de rpc/encoded standaard. Een request waar de toegang wordt gevraagd voor het certificaat met serienummer 10CF00000C06 voor de dienst met de logische naam man_info kan als volgt: <?xml version="1.0" encoding="iso "?> <SOAP-ENV:Envelope> <SOAP-ENV:Body> <tns:authcertificateforgroup xmlns:tns="urn:darts"> <serial xsi:type="xsd:string">10cf00000c06</serial> <LogDienstNaam xsi:type="xsd:string">man_info</logdienstnaam> </tns:authcertificateforgroup> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Voor de WSDL request geldt ook dat deze met behulp van een cliënt certificaat gedaan moet worden WSDL Request voorbeeld applicatie Appendix C bevat de source code van een voorbeeld script. Via CSNET kan de complete source code verkregen worden WSDL functies authcertificateforgroup en authaansluitnummerforgroup Met deze 2 functies kan een gebruiker voor een dienst geautoriseerd worden. Beide functies hebben als input parameter de logische naam van een dienst en een serienummer van een certificaat of het aansluitnummer van de gebruiker. Indien de gebruiker toegang tot de dienst heeft wordt er een SOAP response geretourneerd die in de SOAP body het element aansluitnummer heeft. Hier kan dus op gecontroleerd worden. Als de gebruiker geen toegang heeft wordt er een SOAP fault geretourneerd getgroupsforaansluitnummer Deze functie heeft als input het aansluitnummer van de gebruiker en de logische dienstnaam. De response bevat een soap array met alle groepen waarmee het aansluitnummer toegang tot de dienst heeft (dus niet allen de groep die de hoogste prioriteit heeft en die via de in beschreven functies geretourneerd worden) getallparamsforservice Een aansluitnummer heeft via een groep toegang tot een dienst. Per groep die toegang heeft tot een dienst kunnen er andere parameters geretourneerd worden. De functie Copyright Communications Security Net B.V. 11

12 getallparamsforservice is een uitgebreide versie van getgroupsforaansluitnummer. Naast alle groepen worden ook per groep alle parameters geretourneerd doaccounting Met doaccounting kan voor een aansluitnummer in de centrale dartsdatabase vastgelegd worden op welk tijdstip welke dienst opgevraagd is. Zie verder Accounting Darts voorziet ook in een webservice operatie ten behoeve van accounting. Bij standaard autorisatie zoals eerder beschreven zal er geen accounting plaatsvinden. Voor de WSDL bestaat er de operatie doaccounting. Deze operatie authentiseert net zoals authcertificateforgroup maar verzorgt tevens de accounting binnen DARTS. Voor XML requests kan accounting worden verzorgd door DoAccouting de waarde true te geven (zie XSD in appendix). De operatie accounting legt het tijdstip, aansluitnummer, dienst en de groep waarmee het aansluitnummer toegang krijgt vast. Het is de verantwoording van de dienstaanbieder om accounting op een voor de dienst relevante wijze aan te roepen. Copyright Communications Security Net B.V. 12

13 Appendix A XML request XSD <?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns:xsd=" <xsd:element name="bericht"> <xsd:complextype> <xsd:choice> <xsd:sequence> <xsd:element name="berichtaanvraag" type="dienstauthaanvraagtype" /> <xsd:element name="berichtantwoord" type="dienstauthantwoordtype" inoccurs="0"/> <xsd:element name="berichtfout" type="berichtfouttype" minoccurs="0" maxoccurs="1"/> </xsd:sequence> <xsd:sequence> <xsd:element name="berichtantwoord" type="dienstauthantwoordtype"/> <xsd:element name="berichtfout" type="berichtfouttype" minoccurs="0" maxoccurs="1"/> </xsd:sequence> <xsd:element name="berichtfout" type="berichtfouttype" minoccurs="1" maxoccurs="1"/> </xsd:choice> </xsd:complextype> </xsd:element> <xsd:complextype name="dienstauthaanvraagtype"> <xsd:sequence> <xsd:choice> <xsd:element name="serial" type="hex12type"/> <xsd:element name="aansluitnr" type="n6type"/> </xsd:choice> <xsd:element name="logdienstnaam" type="an8_20type"/> <xsd:element name="doaccounting" minoccurs="0" maxoccurs="1" type="xsd:boolean"/> <xsd:element name="getallgroups" minoccurs="0" maxoccurs="1" type="xsd:boolean"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="dienstauthantwoordtype"> <xsd:sequence> <xsd:element name="aansluitnummer" type="xsd:string"/> <xsd:element name="dienstnaam" type="xsd:string"/> <xsd:element name="groepnaam" type="xsd:string"/> <xsd:element name="accessviagroep" type="xsd:string"/> <xsd:element name="params" minoccurs="0" maxoccurs="1" type="paramstype"/> <xsd:element name="groups" minoccurs="0" maxoccurs="1" type="groupstype"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="berichtfouttype"> <xsd:sequence> <xsd:element name="fout" type="xsd:string" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> <xsd:complextype name="paramstype"> <xsd:sequence minoccurs="1" maxoccurs="unbounded" > <xsd:element name="param" type="paramtype"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="paramtype"> <xsd:sequence> <xsd:element name="name" type="xsd:string"/> <xsd:element name="value" type="xsd:string"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="groupstype"> <xsd:sequence minoccurs="1" maxoccurs="unbounded" > <xsd:element name="group" type="xsd:string"/> </xsd:sequence> </xsd:complextype> <xsd:simpletype name="hex12type"> <xsd:restriction base="xsd:string"> Copyright Communications Security Net B.V. 13

14 </xsd:schema> <xsd:pattern value="[a-fa-f0-9]12" /> <xsd:maxlength value="12" /> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="an8_20type"> <xsd:restriction base="xsd:string"> <xsd:minlength value="8" /> <xsd:maxlength value="20" /> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="n6type"> <xsd:restriction base="xsd:nonnegativeinteger"> <xsd:pattern value="\d1,6" /> </xsd:restriction> </xsd:simpletype> Copyright Communications Security Net B.V. 14

15 Appendix B XML request voorbeeld <?php class CSNET_HTTPXML private $context; private $remote; private $host; private $path; public $requestxml; public $responsexml; function construct() $params = parse_ini_file('../dartsclient.ini'); $this->host = str_replace(' $this->remote = 'ssl://'.$this->host.":443"; $this->path = $params['path'].'ws2.php?xml'; $contect_params = array('ssl'=>array( 'local_cert'=>$params['clientcertificate'], 'passphrase'=>'1234', 'verify_peer'=>false, 'allow_self_signed'=>true, 'verify_depth'=>1, 'cafile'=>$params['cacertificate'])); $this->context = stream_context_create($contect_params); $this->requestxml = new DOMDocument(); $this->responsexml = new DOMDocument(); private function initxmldoc() $xmlstr = ' <Bericht xmlns:xsi= xsi:nonamespaceschemalocation="auth_info.xsd"> <BerichtAanvraag> </BerichtAanvraag> </Bericht>'; $this->requestxml->loadxml($xmlstr); private function sendrequest() $retvalue = false; //Create the socket with the context set in the construct $fp = stream_socket_cliënt($this->remote, $err, $errstr, 30, STREAM_CLIENT_CONNECT, $this->context); if ($fp ) $req=''; $req.="post $this->path HTTP/1.1\r\n"; $req.="host: $this->host\r\n"; $req.="content-type: application/xml\r\n"; $req.='content-length: '. strlen($this->requestxml->savehtml())."\r\n"; $req.="connection: close\r\n\r\n"; fputs($fp, $req); fputs($fp, $this->requestxml->savehtml()); $res = ''; while(!feof($fp)) $res.= fgets($fp, 128); $pos = strpos($res, '<?xml '); if ($pos >0) $res = substr($res,$pos); if (@$this->responsexml->loadxml($res)) Copyright Communications Security Net B.V. 15

16 else return $retvalue; $retvalue = true; echo "response is not a valid XML document:\n\r"; echo $res; /** * Send the request to the CSNET webservice array of elements to append to the request node the logical name of the service true on success */ public function makerequest($params) //create the basic layout of the XML request $this->initxmldoc(); $XML_XPATH = new DOMXpath($this->requestXml); if( is_array($params) && count($params)>0 ) $query="/bericht/berichtaanvraag"; $nodelist = $XML_XPATH->query($query); if($nodelist->length == 1 ) foreach($params as $element=>$value) $new_element = $this->requestxml->createelement($element,$value); $nodelist->item(0)->appendchild($new_element); return $this->sendrequest(); return false; if ( isset($_server['ssl_client_m_serial']) ) $new_req = new CSNET_HTTPXML(); if ($new_req->makerequest (array("serial"=>$_server['ssl_client_m_serial'],"logdienstnaam"=>'man_info',,"doaccounting"=>0,"getallgroups"=>1))) //validate the request with the XSD scheme if ) //set the header so the browser renders it as XML header("content-type: application/xml"); //dump the request on the screen for testing purposes echo $new_req->responsexml->savexml(); //Add logic to handle response and possible authorisation levels for the cliënt else //dump the server response for testing purposes echo $new_req->responsexml->savexml(); //Add logic to handle the response else echo 'No cliënt certificate found.';?> Copyright Communications Security Net B.V. 16

17 Appendix C Voorbeeld WSDL script <?php require_once('./libs/nusoap-0.9.5/lib/nusoap.php'); class CSNET_WSDL_Functions private $client; function construct() // De CSNET web service accepteert alleen requests waarbij een certificaat verzonden wordt. // Dit request wordt ondertekend met de private key die in het gecrypte.pem bestand staan // Om te crypten moet de private key uit het certificaat gehaald worden en hiervoor is het password van het certificaat nodig // Deze wordt uit een ini file gelezen $params = parse_ini_file('../dartsclient.ini'); $this->client = new nusoap_client($params['host'].$params['path'].'csnet_ws.php?wsdl', true); $this->client->authtype = 'certificate'; $this->client->certrequest['sslcertfile']=$params['clientcertificate']; $this->client->certrequest['passphrase']=$params['passphrase']; $this->client->certrequest['verifyhost']=1; $this->client->certrequest['verifyclient']=1; $this->client->certrequest['cainfofile']=$params['cacertificate']; function authorisecertuser($certserial,$servicenaam) //Vraag de rechten op voor het door de client verzonden certificate serienummer $paramrq = array('serial' => $certserial, 'LogDienstNaam' => $servicenaam); $response = $this->client->call('authcertificateforgroup', $paramrq); $clienterror = $this->client->geterror(); if ( $clienterror ) //plaats hier de logica voor het verwerken van een soap error, e.g. logging //informatie staat in de string $clienterror //print('<pre>'.print_r($clienterror,1).'</pre>'); return $response; //creer een instance van CSNET_WSDL_Functions //de instellingen worden via de construct uit de ini file gelezen $wsdlcon = new CSNET_WSDL_Functions(); //Vervolgens kunnen de clients voor de dienst geauthoriseerd worden //de authorisatiegegevens worden in $autharray opgeslagen $autharray = array(); //Controleer of de client een certificaat heeft aangeboden if ( isset($_server['ssl_client_m_serial']) ) $autharray = $wsdlcon->authorisecertuser ($_SERVER['SSL_CLIENT_M_SERIAL'],'man_info'); //print('<pre>'.print_r($_server,1).'</pre>'); //Voor testdoeleinden kan de array afgedrukt worden print('<pre>'.print_r($autharray,1).'</pre>');?> Copyright Communications Security Net B.V. 17