Mdule Secure-Cnnect Manual fr installatin and usage f the mdule Secure-Cnnect Page 1 / 1 5
Table f Cntents 1)Cntents f the package...3 2)Features f the mdule...4 3)Installatin f the mdule...5 Step 1: Installatin f the mdule-file...5 Step 2: Generate the certificates and key-stres...5 Step 3: Preparing the MySQL-Server fr SSL-functinality...8 Step 4: Preparing Labmatica LIMS fr SSL-functinality...9 Step 5: Create a directry fr string the user-data...9 Step 6: Edit the Labmatica-cnfiguratin file...9 Step 7: First start f the system...10 Step 8: Managing ther users f Labmatica LIMS...11 Step 9: Every fllwing start f the system...11 Installatin Remark...12 4)Messages f the mdule...13 5)Cnfiguratin f the mdule...15 Page 2 / 1 5
1) Cntents f the package The package cnsists f a Zip-file cntaining the fllwing files: 1 labmatica_secure_cnnect.jar The mdule Labmatica-Secure-Cnnect 2 create_cert.bat The batch-file t generate the certificates n Windws 3 create_cert.sh The shell-script t generate the certificates n Linux 4 Secure-Cnnect-Manual.pdf A cpy f this guide as PDF 2) Features f the mdule The features f the mdule Labmatica-Secure-Cnnect are the fllwing: - Prtectin f the database-cnnectin-data against unauthrized access - Securing the transfer f data thrugh SSL-encryptin - Changing the database-cnnectin-data in Labmatica LIMS - Prtectin against unauthrized remval f the mdule - Limitatin t maximum 3 attempts f lgin during a system-start - Demand the user t change his passwrd after 365 days Page 3 / 1 5
3) Installatin f the mdule Step 1: Installatin f the mdule-file T install the mdule Labmatica-Secure-Cnnect, yu first have t perfrm the fllwing steps: 1. Unzip the file that was shipped with the package 2. Cpy the file labmatica_secure_cnnect.jar int the Lib-flder f yur Labmaticainstallatin Step 2: Generate the certificates and key-stres Nw, yu have t generate the certificate-authrity (CA), the certificates and the key-stres. This is necessary t enable the SSL-ability between the MySQL-Server and Labmatica LIMS. S, first f all, yu have t install the Sftware OpenSSL. A versin accrding t yur perating system can be fund at and dwnladed frm http://www.penssl.rg. Nte: Yu may have t set an envirnment-variable t the Bin-flder f yur OpenSSLinstallatin, in rder t be able t d next steps. Nte: The SSL-functinality nly wrks with MySQL 4.0.4 r higher. Yu may als require JDK 1.4.1 r newer. Once yu have installed OpenSSL, yu can cntinue t create the certificate authrity by running the batch-file create_cert.bat n Windws r the shell-script create_cert.sh n Linux. T d s, pen a prmpt/terminal, change int the apprpriate directry and type in: On Windws: create_cert.bat On Linux:./create_cert.sh Nte: On Linux yur may have t set the permissin t execute the file with the cmmand: chmd 777 create_cert.sh 1. After the first 3 autmatic steps, which d sme preparatins, in step 4 f the script, the previusly created Certificate Authrity s private key will be self signed by the administratr. The data entered shuld accrd t yur situatin and may lk like this: Page 4 / 1 5
Nte: The Cmmn Name must be different in all fllwing infrmatin requests f this frm. 2. The fllwing step 5 is als an autmatic step. It autmatically creates the server-key. After that, yu have t create the server s signing request in step 6. Here, remember, that the cmmn name has t be different t the name previusly entered. In step 7, the request is then signed by the lcal CA: Page 5 / 1 5
Nte: Alternatively, yu can use a SSL-prvider, just like Verisign, t sign the server s signing request. 3. In step 8, the client key will be created. Nte that the first entered infrmatin crrespnds t the cmmn name and must be different t all previusly entered names. At the end f this step, yu will be asked, if yu trust the certificate. Here, please type in the wrd fr yes, accrding t yur language: English: Yes Deutsch: Ja Français: Oui After step 8, in steps 9 and 10, the client s signing request is created and autmatically signed by the lcal CA. Nte: Again, yu can use a SSL-prvider, just like Verisign, t sign the client s signing request. Page 6 / 1 5
4. In the fllwing steps 11 and 12, the certificates created are imprted in the keystres fr the client side. Here, yu first have t enter a passwrd fr the truststre and the keystre. It is imprtant that yu remember these tw passwrds! Then yu have t cnfirm that yu trust the certificates with the wrd fr yes, accrding t yur language: English: Yes Deutsch: Ja Français: Oui Page 7 / 1 5
5. The last steps 13 t 15 are autmatic steps again and finish up the setup f the SSLcertificates: 6. After these steps, there are tw flders in the wrking directry, server_files and client_files. The server_files-flder cntains the fllwing files: - ca-cert.pem - server-cert.pem - server-key.pem - my.txt The client_files-flder cntains the fllwing files: - truststre - keystre Step 3: Preparing the MySQL-Server fr SSL-functinality T prepare the MySQL-Server fr the SSL-functinality, d the fllwing steps: - On the MySQL-Server-machine, create a new directry - Cpy all the files f the server_files-flder int this directry - Nw, yu have t cnfigure the server fr SSL-functinality: Page 8 / 1 5
1. Open the created cnfiguratin-files-entries file, my.txt in the server_files-flder and cpy all its cntents 2. Open the cnfiguratin-file f the MySQL-server in an editr and navigate t the sectin called [mysqld]. The cnfiguratin-files is lcated at: - /etc/my.cnf n Linux - my.ini in the Installatin-path n Windws Nw paste the cpied cntents int a free space in this sectin. - Start/Restart the server in the manner yu did it s far Step 4: Preparing Labmatica LIMS fr SSL-functinality T prepare Labmatica LIMS fr SSL-functinality, yu have t d the fllwing: - In the Labmatica-flder, create a new directry - Cpy the files.truststre and.keystre f the client_files-flder int this directry Step 5: Create a directry fr string the user-data Nw it s time t create a directry fr the later string f the encrypted user-files. These files are used t stre the encrypted database-cnnectin-data. Fr example, this directry can be created in the installatin-flder f Labmatica LIMS and shuld als be prtected by apprpriate OS-privileges. Step 6: Edit the Labmatica-cnfiguratin file In this step, yu have t edit the cnfiguratin-file f Labmatica LIMS. Fr nw, this file is called cnnect.xml and shuld be lcated in the rt-directry f the Labmatica-installatin. S, t edit the file, please d the fllwing: 1. Open the file with an editr 2. Edit the fllwing tags: <userid> </userid> <passwrd> </passwrd> Replace the cntaining values by #### 3. Edit the fllwing tags: <!-- Where shuld the keystre- and user-files be stred? --> <userdirectry>xxxx</userdirectry> Page 9 / 1 5
Please set here the path t the directry, where the user-files shuld be stred. This is the directry created in step3. <!-- What is the default-language fr the Secure-Cnnect-Mdule? English, Francais r Deutsch --> <default_language>xxxx</default_language> Please set here yur preferred language fr the Secure-Cnnect-Mdule. This will be the language, used in the lgin masks. Step 7: First start f the system Nw, the system is ready t use the mdule and yu can start the system. When yu d s, after the start-prgress the fllwing windw will appear: This is the lgin-windw fr the administratr, which is used t initialize the Secure-Cnnect- Mdule. Here, please enter the fllwing infrmatin: - Labmatica LIMS: User: YOUR username r admin Page 1 0 / 1 5
Passwrd: YOUR passwrd r admin - Database: User: The database-user Passwrd: The passwrd f this user - Secure-Cnnectin: Truststre-Lcatin: The path f the trust-stre file.truststre previusly created Truststre-Passwrd: The passwrd f the trust-stre previusly created Keystre-Lcatin: The path f the key-stre file.keystre previusly created Keystre-Passwrd: The passwrd f the key-stre previusly created Step 8: Managing ther users f Labmatica LIMS After lgging in as administratr, yu have t create the files fr all ther users. This can be made by the fllwing prcedure: 1. Call the Users-tab f Labmatica LIMS 2. Fr every user d the fllwing: a. Assign a new passwrd b. Save the settings 3. Let the user knw the new passwrd. The next time the user starts the system he has t change it Step 9: Every fllwing start f the system Nw, the system is cmpletely initialized and all needed data has been created. Each user can nw use the system as usual. That means that frm nw n the lgin-windw will lk as fllws: Installatin Remark Remving the mdule frm the Lib-flder after installatin will cause an inability f starting the system. T uninstall the mdule yu will first have t uncheck the specified checkbx in Page 1 1 / 1 5
the Mdules-panel f the cnfiguratin and save the settings. Only then yu will be able t remve the mdule and cntinue wrking with the system. 4) Messages f the mdule After installatin, the functinality f the mdule runs cmpletely in backgrund. Hwever, there may cme up sme messages, when the prper functinality cannt be assured. Here are the explanatins f these messages and their pssible slutin: Explanatin: This errr-message ccurs during the start f the system. The reasn is that the value f the tag <userdirectry> in the cnfiguratin file cnnect.xml is either nt valid r references a directry that desn t exist. Slutin: T slute this prblem try the fllwing: 1. Open the file cnnect.xml in an editr 2. Check the value f the tag <userdirectry> Explanatin: This errr-message ccurs during the first administratr-lgin frm step 7. The Appearance Page 1 2 / 1 5
can have three reasns: 1. The entered credentials fr the database-accunt are incrrect 2. The additinal database-cnnectin-data in the cnfiguratin-file cnnect.xml is incrrect 3. The database-server is nt running r nt reachable Slutin: T slute this prblem try the fllwing: 1. Check and re-enter the accunt-data fr the database 2. Open the file cnnect.xml in an editr and check the tags <databasetype> and <URL> fr crrect values 3. Make sure, that the database-server is running and reachable: a. Yu can test this by trying t cnnect t the database with the MySQL-Query- Brwser b. Make sure that the firewall is prperly cnfigured Explanatin: This errr-message appears in bth, the first administratr lgin and every fllwing lgin, in the case that the database-server is running, but the SSL-functinality is nt enabled. Slutin: T slute this prblem, yu have t start the MySQL-Server with the prper cmmand-line ptins. Yu can use the batch-file start_mysql_w_ssl.bat fr this. Page 1 3 / 1 5
Explanatin: This message appears, every time an administratr lgs int the system in the case, that there is still database-accunt-data in the cnfiguratin-file cnnect.xml. Slutin: T slute this prblem, d the fllwing: 1. Open the file cnnect.xml in an editr 2. Set the values f the fllwing tags t #### <userid>xxxx</userid> <passwrd>xxxx</passwrd> Page 1 4 / 1 5
5) Cnfiguratin f the mdule The cnfiguratin-tab f this mdule is reachable ver the main-cnfiguratin-tab f the system in the main-windw. There is a tab called FDA-Secure-Cnnect. As yu can see in the picture belw, here yu can change the database-cnnectin-data. This can be used in the case, that the currently used accunt has t be changed r that new certificates had t be created. When yu change the accunt-data and save the cnfiguratin by the buttn in the upper left, then every users file will be changed, in rder t be available at the next start f the system. Page 1 5 / 1 5