Functionele beschrijving van de One Fox edav module. Kenmerk: FO_EDAV_MVDB_50 Document: V1,2 / FO edav v2.2 Status: Publicatie: Definitief 28-2-2013
Documenthistorie Wanneer Versie Wie Wat en waarom 15-02-2010 0,1 Ron v. Oosterhout Initiële versie functioneel ontwerp 31-03-2010 1,0 Ron v. Oosterhout Toevoeging encryptie 16-04-2010 1,1 Ron v. Oosterhout Opmerkingen verwerkt (Michel Hummel) 04-07-2012 1,2 Matthijs van den Bovenkamp Uitbreiding naar tablets en nieuwe authenticatie modules toegevoegd. Dienstverlener One Fox www.onefox.nl Jens Peters Tel.: 030-2324 350
Inhoudsopgave 1 Inleiding... 4 2 Systeem vereisten... 5 2.1 SERVER... 5 2.2 CLIËNT... 5 3 Specificatie edav... 6 3.1 ERROR HANDLING EN LOGGING... 7 3.2 MONITOREN VAN HANDELINGEN... 7 4 Authenticatie Modules... 8 4.1 WINDOWS AUTHENTICATION... 8 4.2 BASIC AUTHENTICATION... 9 4.3 URLBASED AUTHENTICATION... 9 4.4 URLBASED AUTHENTICATION MET WACHTWOORD ENCRYPTIE... 10 4.5 URLBASED AUTHENTICATION MET URL ENCRYPTIE... 13 3 / 14
1 Inleiding Dit document is het functioneel ontwerp van de One Fox edav module. De edav module is een WebDAV adapter, waarmee documentatie uit OpenText edocs gehaald kan worden. Deze documentatie kan vervolgens met bijhorende client applicaties bekeken en bewerkt worden en dan via edav weer terug geüpload worden naar OpenText edocs. De edav module maakt gebruik van de WebDAV techniek, wat een uitbreiding is op het http protocol. Voor deze oplossing is geen cliënt software noodzakelijk, behalve de applicatie waarmee het document bewerkt kan worden. De edav module maakt gebruik van de DM API om de juiste documentatie uit edocs te halen. Er zijn verschillende authenticatie modules gemaakt voor het afhandelen van de authenticatie. Zo is er bijvoorbeeld een windows authenticatie module zodat via de windows credentials documenten uit EDOCS geopend kunnen worden. Deze module wordt onder andere gebruikt wanneer edav toegepast wordt via een ipad of windows verkenner. Ook is er een basic authenticatie module die onder andere gebruikt wordt wanneer edav wordt toegepast via een Android Tablet, en een url authenticatie module zodat via een webapplicatie via "Single-Sign On" documenten uit edocs geopend kunnen worden. Om een document te openen dient een request gestuurd te worden naar de edav module die afhankelijk van de gekozen authenticatie module anders opgebouwd wordt. Hoe dit verschilt per authenticatie module, vind je terug in hoofdstuk 4 Authenticatie Modules. 4 / 14
2 Systeem vereisten Om de edav module te installeren, dient uw systeem aan de volgende eisen te voldoen: 2.1 Server Hardware Verbinding kunnen maken met een DM server; Beschikbaar via http en/of https voor de cliënt; Software DM API; Internet Information Services (IIS) 7; Microsoft.NET Framework 3.5; Microsoft Windows 2008 R2 Server. 2.2 Cliënt Hardware op de cliënt is niet van toepassing. Software Tablet Besturingssysteem o IOS; o Android. Een applicatie met WebDAV ondersteuning o ReaddleDocs (ipad) o WebDAV Navigator (Android) Bijhorende cliënt applicaties om de edocs documenten mee te openen o Polaris Office o Open Office o Documents To Go o Office Suite Software werkstation Besturingssysteem o Windows XP; o Vista (incl. http://support.microsoft.com/kb/841215); o Windows 7 (incl. http://support.microsoft.com/kb/841215). Browser o Internet Explorer 7, of hoger. Bijhorende cliënt applicaties voor de ondersteunde bestanden, bijvoorbeeld: o Microsoft Office (Word, Excel, PowerPoint); Windows verkenner 5 / 14
3 Specificatie edav De edav module is een oplossing die het mogelijk maakt om documenten uit OpenText edocs direct te openen in bijhorende cliënt applicaties zonder het document eerst lokaal te downloaden en zonder dat hiervoor een installatie van een edocs cliënt noodzakelijk is. Het desbetreffende document dat is geopend in de cliënt applicatie wordt ook rechtstreeks weer opgeslagen in edocs. De edav module maakt dit mogelijk door gebruik te maken van WebDAV techniek wat een uitbreiding is van het http protocol. Dankzij de WebDAV is het mogelijk om naast normale acties als POST en GET ook andere acties zoals LOCK en UNLOCK uit voeren over http. Er zijn verschillende authenticatie modules gemaakt voor het afhandelen van de authenticatie. Om een document te openen dient een request gestuurd te worden naar de edav module die afhankelijk van de gekozen authenticatie module anders opgebouwd wordt. Hoe dit verschilt per authenticatie module, vind je terug in het volgende hoofdstuk. Afhankelijk van de waardes die in de request staan wordt het document via de DM API opgehaald uit edocs en geopend op de cliënt met behulp van de software die dit type document opent. Op dit moment zal het document vergrendeld zijn in edocs. Op de cliënt kan het document bewerkt worden en bij opslaan worden de wijzigingen op de server opgeslagen. Bij sluiten van de applicatie zal het document weer ontgrendeld worden in edocs. Op dit moment ondersteunt de edav module zowel tablets als werkstations Bovenstaand schema geeft de verschillende componenten weer die gebruikt worden bij de edav module.
3.1 Error Handling en logging Via het WebDAV protocol worden foutmeldingen naar de client applicatie gestuurd, het is echter aan de client applicatie om iets met deze foutmeldingen te doen. De meeste client applicaties zoals MS Office tonen in veel gevallen een generieke foutmelding, daarom houdt de edav module de foutmeldingen ook bij in log bestanden. Voor het loggen wordt Log4Net gebruikt. Hierdoor kan in de configuratie opgegeven worden hoe er gelogd moet worden. Default gebruikt de edav module een RollingFileAppender, deze slaat alles op in een LOG bestand. De naam en locatie van dit bestand kan ook in de configuratie aangepast worden. Verder kan er ook nog gekozen worden om bijvoorbeeld te loggen naar de event log of database. 3.2 Monitoren van handelingen Omdat de edav module via de DM API zijn gegevens uit edocs haalt, en ook via de DM API de bewerkingen uitvoert (inclusief vergrendelen en ontgrendelen) wordt er in edocs een audit trail bijgehouden. Dit maakt het mogelijk om via de standaard tooling van DM controles uit te voeren op de m.b.v. edav geopende/bewerkte documenten. 7 / 14
4 Authenticatie Modules Authenticatie in edav wordt geregeld in de zogeheten authenticatie modules. Welke gebruikt wordt, is configureerbaar in het configuratiebestand van de edav module. In het edav configuratiebestand staat een sectie genaamd httpmodules. In dit gedeelte van de configuratie kun je opgeven welke authenticatie module gebruikt wordt. Hieronder staat een voorbeeld waarin gekozen is voor gebruik van urlbased authenticatie met encryptie van het wachtwoord. <httpmodules>... <add name="authenticationmodule" type="onefox.edav.modules.customauthentication.encrypted.urlbasedauthentic ationmodule, OneFox.eDAV.Modules.CustomAuthentication.Encrypted" /> </httpmodules> Er zijn vijf modules die geconfigureerd kunnen worden: Basic Authentication Windows Authentication UrlBased Authentication UrlBased Authentication met wachtwoord encryptie UrlBased Authentication met url encryptie Als de authenticatie module geconfigureerd is, moeten er nog enkele configuratie instellingen aangepast worden in het DMConfiguration gedeelte <DMConfiguration VirtualDirectory="/eDAV/" RequestSyntax="\[([^\]]*)\]\[([^\]]*)\]\[([^\]]*)\]\[([^\]]*)\]\.\w*" LibraryIndex="1" UsernameIndex="2" PasswordIndex="3" DocnumberIndex="4">... </DMConfiguration> Per authenticatie module wordt hieronder uitgelegd hoe edav geconfigureerd moet worden en wat voor aanvraag van andere applicaties dan door edav verwacht wordt om de juiste documenten te retourneren. 4.1 Windows authentication Bij windows authentication wordt de windows login van de gebruiker gebruikt. De volgende module moet geladen worden om gebruik te maken van windows authentication. <add name="authenticationmodule" type="onefox.edav.modules.customauthentication.windowsauthenticationmodule" /> Voor windows authentication moet de DMConfiguration node als volgt ingesteld worden 8 / 14
<DMConfiguration ProfileHierarchieItemFormat="{0} [{1}]{5}" ProfileHierarchieItemRequestSyntax="^(.*?)\ \[([^\]]*)\](\..*$ $)" RequestSyntaxRegexGroupOffset="1"... </DMConfiguration> De aanvraag die wordt verwacht door edav voor een document is als volgt: http://<servername>/<virtual directory>/[<libraryname>][<docnumber>].<extensie> Een voorbeeld hiervan ziet er als volgt uit: http://dmserver/onefox.edav/[edms][5699877].doc 4.2 Basic authentication Bij basic authentication wordt aan de gebruiker gevraagd om zijn gebruikersnaam en wachtwoord van edocs. De volgende module moet geladen worden om gebruik te maken van basic authentication. <add name="authenticationmodule" type="onefox.edav.modules.basicauthentication.basicauthenticationmodule" /> Voor basic authentication moet de DMConfiguration node als volgt ingesteld worden <DMConfiguration ProfileHierarchieItemFormat="{0} [{1}]{5}" ProfileHierarchieItemRequestSyntax="^(.*?)\ \[([^\]]*)\](\..*$ $)" RequestSyntaxRegexGroupOffset="1"... </DMConfiguration> De aanvraag die wordt verwacht door edav voor een document is als volgt: http://<servername>/<virtual directory>/[<libraryname>][<docnumber>].<extensie> Een voorbeeld hiervan ziet er als volgt uit: http://dmserver/onefox.edav/[edms][5699877].doc 4.3 UrlBased authentication Bij urlbased authentication wordt de gebruikersnaam en wachtwoord meegegeven in de URL van de aanvraag. Hierdoor is single sign-on mogelijk vanuit applicaties die gebruik maken van de edav koppeling. De volgende module moet geladen worden om gebruik te maken van urlbased authentication. 9 / 14
<add name="authenticationmodule" type="onefox.edav.modules.customauthentication.urlbasedauthenticationmodule, OneFox.eDAV.Modules.CustomAuthentication " /> Voor urlbased authentication moet de DMConfiguration node als volgt ingesteld worden <DMConfiguration ProfileHierarchieItemFormat="[{1}][{2}][{3}][{4}][{5}]" ProfileHierarchieItemRequestSyntax="\[([^\]]*)\]\[([^\]]*)\]\[([^\]]*)\]\ [([^\]]*)\]\.\w*" RequestSyntaxRegexGroupOffset="0"... </DMConfiguration> De aanvraag die wordt verwacht door edav voor een document is als volgt: http://<servername>/<virtual directory>/[<docnumber>][<libraryname>][<username>] [<wachtwoord>].<extensie> Een voorbeeld hiervan ziet er als volgt uit: http://dmserver/onefox.edav/[5699877][edms][user][welkom-1].doc 4.4 UrlBased authentication met wachtwoord encryptie Bij urlbased authentication wordt de gebruikersnaam en wachtwoord meegegeven in de URL van de aanvraag. Het wachtwoord is hierbij versleuteld zodat deze niet herleidbaar is. Ook bij deze module is single sign-on mogelijk vanuit applicaties die gebruik maken van de edav koppeling. De volgende module moet geladen worden om gebruik te maken van urlbased authentication met encryptie. <add name="authenticationmodule" type="onefox.edav.modules.customauthentication.encrypted.urlbasedauthenticationmo dule, OneFox.eDAV.Modules.CustomAuthentication.Encrypted" /> Als gebruik wordt gemaakt van deze authenticatie module, dan verwacht de edav module dat er een timestamp verwerkt is in het versleutelde wachtwoord. Waarbij de samenstelling als volgt er uit moet zien. <wachtwoord>+yyyy-mm-dd HH:mm:ss Voorbeeld: welkom+2009-12-09 12:45:21 De "+" dat gebruikt wordt is een "carriage return teken" 10 / 14
De eerste stap die de authenticatie module uitvoert is het controleren van deze gegevens. Als deze ongeldig zijn, dan zal het document niet geopend worden. De timestamp die verwerkt is in het wachtwoord wordt gebruikt om te kijken of de aanvraag verlopen is. De periode van 8 uur begint vanaf het tijdstip dat het bestand geopend wordt. Deze wordt niet tussentijds verlengt. Hierdoor kan het zijn dat iemand die 8 uur lang zijn document aan het bewerken is, niet meer kan opslaan omdat zijn aanvraag verlopen is. Microsoft office zal afhankelijk van de versie een melding tonen die aangeeft dat het document niet opgeslagen kan worden, vervolgens kan er gekozen worden om het document op een andere locatie op te slaan (bijvoorbeeld lokaal). Mocht deze periode te kort zijn, dan kan veranderd worden hoe lang het duurt voor een time-out optreedt. Als de aanvraag verlopen is zal het bestand gelocked blijven in DM tot dezelfde gebruiker het bestand opnieuw geopend en weer gesloten heeft. Voor urlbased authentication met encryptie moet de DMConfiguration hetzelfde ingesteld worden als wanneer geen encryptie gebruikt wordt. Er komt echter een extra encryptie node in de DMConfiguration node. zie hieronder de gewenste instellingen. <DMConfiguration ProfileHierarchieItemFormat="[{1}][{2}][{3}][{4}][{5}]" ProfileHierarchieItemRequestSyntax="\[([^\]]*)\]\[([^\]]*)\]\[([^\]]*)\]\ [([^\]]*)\]\.\w*" RequestSyntaxRegexGroupOffset="0" <Encryption EncryptionKey="XCXCSDWEGBHYJUKILOPOQWER"/>... </DMConfiguration> De EncryptionKey is de sleutel die gebruikt wordt voor de encryptie en decryptie van het wachtwoord. Deze sleutel moet 24 karakters lang zijn. De aanvraag die wordt verwacht door edav voor een document is als volgt: http://<servername>/<virtual directory>/[<docnumber>][<libraryname>][<username>] [<wachtwoord>].<extensie> Een voorbeeld hiervan ziet er als volgt uit: http://dmserver/onefox.edav/[5699877][edms][user][whayioz+ecs/wu/fcs2xcw==].doc 4.4.1 Voorbeeld encryptie - C# using System.Security.Cryptography; ----------------------------------- private string EncryptPassword(string input) { string encryptionkey = ConfigurationManager.AppSettings["EncryptionKey"]; if (String.IsNullOrEmpty(encryptionkey)) return input; 11 / 14
//CultureInfo cultureinfo = new CultureInfo("nl-NL"); //string dt = DateTime.Now.ToString(cultureInfo.DateTimeFormat); string data = input + "+" + String.Format("{0:yyyy-MM-dd HH:mm:ss}", DateTime.Now); byte[] utfdata = UTF8Encoding.UTF8.GetBytes(data); byte[] saltbytes = UTF8Encoding.UTF8.GetBytes(encryptionkey); // Our symmetric encryption algorithm AesManaged aes = new AesManaged(); // We're using the PBKDF2 standard for password-based key generation Rfc2898DeriveBytes rfc = new Rfc2898DeriveBytes("thePassword", saltbytes); // Setting our parameters aes.blocksize = aes.legalblocksizes[0].maxsize; aes.keysize = aes.legalkeysizes[0].maxsize; aes.key = rfc.getbytes(aes.keysize / 8); aes.iv = rfc.getbytes(aes.blocksize / 8); // Encryption ICryptoTransform encrypttransf = aes.createencryptor(); // Output stream, can be also a FileStream MemoryStream encryptstream = new MemoryStream(); CryptoStream encryptor = new CryptoStream(encryptStream, encrypttransf, CryptoStreamMode.Write); encryptor.write(utfdata, 0, utfdata.length); encryptor.flush(); encryptor.close(); // Showing our encrypted content byte[] encryptbytes = encryptstream.toarray(); //string encryptedstring = UTF8Encoding.UTF8.GetString(encryptBytes, 0, encryptbytes.length); string encryptedstring = Convert.ToBase64String(encryptBytes); encryptedstring = encryptedstring.replace("/", "-"); encryptedstring = HttpUtility.UrlEncode(encryptedString); } return encryptedstring; 4.4.2 Voorbeeld encryptie - Java import java.util.calendar; import javax.crypto.*; import javax.crypto.spec.*; import sun.misc.base64decoder; import sun.misc.base64encoder; 12 / 14
String password = "welkom-1"; String encryptedpassword = null; String encryptionkey = "XCXCSDWEGBHYJUKILOPOQWER"; String algorithmcipher = "DESede/ECB/PKCS5Padding"; String algorithmkey = "DESede"; Calendar now = Calendar.getInstance(); String time = String.format("%tF", now) + "" + String.format("%tR", now); password = password +"+" + time; try{ DESedeKeySpec spec = new DESedeKeySpec(encryptionkey.getBytes()); SecretKey skey = SecretKeyFactory.getInstance(algorithmKey).generateSecret(spec); byte[] inpbytes = password.getbytes("utf-8"); Cipher cipher = Cipher.getInstance(algorithmCipher); cipher.init(cipher.encrypt_mode, skey); byte[] outbytes = cipher.dofinal(inpbytes); encryptedpassword = new BASE64Encoder().encode(outBytes); } catch(exception ex) { // Do something } 4.5 UrlBased authentication met url encryptie Bij urlbased authentication met url encryptie wordt de gebruikersnaam en wachtwoord meegegeven in de URL van de aanvraag. Dat gedeelte van de url is hierbij versleuteld en als virtuale map meegegeven. Hierdoor kan je het bestand een naam geven naar keuze. Ook bij deze module is single sign-on mogelijk vanuit applicaties die gebruik maken van de edav koppeling. De volgende module moet geladen worden om gebruik te maken van urlbased authentication met encryptie. <add name="authenticationmodule" type="onefox.edav.modules.customauthentication.encrypted.urlbasedauthenticationmo dulev2, OneFox.eDAV.Modules.CustomAuthentication.Encrypted" /> Als gebruik wordt gemaakt van deze authenticatie module, dan verwacht de edav module dat er een timestamp verwerkt is in het versleutelde gedeelte van de url. Waarbij de samenstelling als volgt er uit moet zien. <url virtuele map>+yyyy-mm-dd HH:mm:ss Url virtuele map: [<docnumber>][<libraryname>][<username>][<wachtwoord>] Voorbeeld: [5699877][EDMS][USER][welkom-1]+2009-12-09 12:45:21 13 / 14
De "+" dat gebruikt wordt is een "carriage return teken" De eerste stap die de authenticatie module uitvoert is het controleren van deze gegevens. Als deze ongeldig zijn, dan zal het document niet geopend worden. De timestamp die verwerkt is in het wachtwoord wordt gebruikt om te kijken of de aanvraag verlopen is. De periode van 8 uur begint vanaf het tijdstip dat het bestand geopend wordt. Deze wordt niet tussentijds verlengt. Hierdoor kan het zijn dat iemand die 8 uur lang zijn document aan het bewerken is, niet meer kan opslaan omdat zijn aanvraag verlopen is. Microsoft office zal afhankelijk van de versie een melding tonen die aangeeft dat het document niet opgeslagen kan worden, vervolgens kan er gekozen worden om het document op een andere locatie op te slaan (bijvoorbeeld lokaal). Mocht deze periode te kort zijn, dan kan veranderd worden hoe lang het duurt voor een time-out optreedt. Als de aanvraag verlopen is zal het bestand gelocked blijven in DM tot dezelfde gebruiker het bestand opnieuw geopend en weer gesloten heeft. Voor urlbased authentication met encryptie moet de DMConfiguration hetzelfde ingesteld worden als wanneer geen encryptie gebruikt wordt. Er komt echter een extra encryptie node in de DMConfiguration node. zie hieronder de gewenste instellingen. <DMConfiguration ProfileHierarchieItemFormat="[{1}][{2}][{3}][{4}][{5}]" ProfileHierarchieItemRequestSyntax="\[([^\]]*)\]\[([^\]]*)\]\[([^\]]*)\]\ [([^\]]*)\]\.\w*" RequestSyntaxRegexGroupOffset="0" <Encryption EncryptionKey="XCXCSDWEGBHYJUKILOPOQWER"/>... </DMConfiguration> De EncryptionKey is de sleutel die gebruikt wordt voor de encryptie en decryptie van het wachtwoord. Deze sleutel moet 24 karakters lang zijn. De aanvraag die wordt verwacht door edav voor een document is als volgt: http://<servername>/<virtual directory>/[<viruele map>]/<bestandsnaam>.<extensie> Waarbij de virtuele map de versleutelde gegevens bevat die edocs nodig heeft: [<docnumber>][<libraryname>][<username>][<wachtwoord>] Een voorbeeld hiervan ziet er als volgt uit: http://dmserver/onefox.edav/[whayioz+ecs/wu/fcs2xcw==]/fo_edav.docx De virtuele map wordt weer door edav gedecrypt en zal er dan als volgt uit zien: [5699877][EDMS][USER][welkom-1] 14 / 14