01/03/2011 - 17:40 (GMT+1) SafeJDBC Quick Start -------------------- This file describes the protocol for a quick setup & test of SafeJDBC without any programming. It uses a default application example database and default Java examples that call SafeJDBC. This Quick Start requires 20 to 40 minutes. This quick start is written for Windows testing, but it can be done on Unix/Linux with the same procedure. Just change the directories in accordance with Unix naming. You should read the User Documentation in PDF format before doing this quick start: safejdbc_userdoc_v102_en.pdf 1) Install a Java 6 JVM ----------------------- - Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html - Follow instructions to Download and install Java 6. 2) Unzip safejdbc archive ------------------------- Unzip the safejdbc_XXX.zip in c:\, it will create the c:\safelogic directory. 3) SQL Setup ------------ - Create a SQL database with "safejdbc_catalog" name. - Execute in SQL the c:\safelogic\safejdbc\sql\safejdbc_create_tables.sql script. This will create the SafeJDBC meta database. - Create a SQL database with "sj_clients" name. - Execute in SQL the c:\safelogic\safejdbc\sql\sj_clients_create_tables.sql script. This will create the example database with Clients, Sales and Large Objects (Blob/Clob). Note : the DROP table orders may produce warnings on SQL console. 4) JDBC Drivers configuration ----------------------------- First step is to setup JDBC access for the SafeJDBC meta-database: - Edit the c:\safelogic\safejdbc\conf\con_safejdbc.ini file. - Change the DRIVER value with your native JDBC driver. - Change the DB_URI_ROOT value with the Database URI for safejdbc_catalog. Note that name must ends with "?". - Do NOT change the USER & PASSWORD values. Second step is to setup JDBC access for the application/demo database: - Edit the C:\safelogic\safejdbc\conf\con_application.ini file. - Change the DRIVER value with your native JDBC driver. - Change the DB_URI_ROOT value with the Database URI for sj_clients. Note that name must ends with "?". - Do NOT change the USER & PASSWORD values. 5) SafeJDBC catalog initialization ---------------------------------- - Open a MS-DOS session. - cd c:\safelogic\safejdbc\bin - Create a CLASSPATH variable and add to it the classpath to your native JDBC driver JAR. - Launch the c:\safelogic\safejdbc\bin\set_classpath.bat This will add to your CLASSPATH the libraries of SafeJDBC and the demo files. - java com.safejdbc.bat.ColumnsCipherMain encrypt This will init the SafeJDBC catalog and store informations about the columns to be encrypted. The list of encrypted columns is contained in the file c:\safelogic\safejdbc\conf\con_application.ini 6) Using the Java demo classes ------------------------------ We are now ready to use the demo classes stored with source code in c:\safelogic\safejdbc\examples : - java com.safejdbc.demo.Insert secure This will insert and cipher a row in Clients and Sales tables. It will display a resulting select on screen. If you pass a "SELECT * FROM CLIENTS" in SQL, you'll see that somme columns are encrypted in the database. - java com.safejdbc.demo.SelectWithJoins secure This will display a SELECT with JOINs. Please see source code SelectWithJoins.java to read the query. - java com.safejdbc.demo.Update secure This will update and cipher a row in Clients and Sales tables. It will display a resulting select on screen - java com.safejdbc.demo.Delete secure This will delete the Clients & Sales rows. The source code of demo examples are written so that all the methods can be re-used easely in your own classes. 7) "Reverse" sj_clients database -------------------------------- SafeJDBC includes methods to change or "reverse" the database so that all columns are deciphered and stored in clear. See User Documentation for full explanation and details. Following batch will decrypt the sj_clients database : - java com.safejdbc.bat.ColumnsCipherMain decrypt 8) Other infos in con_safejdbc.ini file & iSQL Viewer infos ----------------------------------------------------------- If you want to test safeJDBC with a SQL Editor, you can use iSQL Viewer http://www.isqlviewer.com/ con_safejdbc.ini contains: # SafeJDBC Crypto Provider SAFEJDBC_PROVIDER = SunJCE SAFEJDBC_PROVIDER may be set to "Cryptix", which is faster than Sun JCE, *but* use SunJCE with ISQL Viewer because there is a bug/feature in iSQL which prevent using Cryptix (old) Policies system. Because ISQL Viewer "erases" the CLASSPATH of the called application (SafeJDBC), the con_safejdbc.ini file must be placed in directory java.getProperty("user.home"). Note : when logging is activated, location is displayed on console. Java settings in iSQL: Please see enclosed the "isql_setting_1.gif" & "isql_setting_2.gif" snapsots for defining a connection. Resume : - the classpath must be set for each SafeJDBC connection. - The Driver name is com.safejdbc.api.Driver - The URL syntax is "jdbc:mysql://localhost:3306/sj_clients". - Please check "User Authentication prompt" Logging facilities: con_safejdbc.ini contains the line : SAFEJDBC_LOGFILE = safejdbc.log wich defines logging in safejdbc.log. comment the line with # if you want to deactivate logging. 9) Using IngrianProvider ------------------------ You *must* re-create the sj_clients application database example with the C:\safelogic\safejdbc\sql_sj_clients_create_tables.sql because: - VARCHAR is longer for text columns. - For Mysql, CLOB_FILES.FILE_CLOB_CONTAINER column is now MEDIUMTEXT. SafeJDBC supports now the IngrianProvider which works with dedicated encryption hardrware. (Please see http://www.ingrian.com/) 9.a) setting the Provider name: Provider name is "IngrianProvider" and mau bet set using SafeJdbcSetter.SetProvider() or ini value in con_safejdbc.ini: SAFEJDBC_PROVIDER = IngrianProvider 9.b) setting the key: To set the Key with SafeJdbcSetter : SafeJdbcSetter sjSetter = SafeJdbcSetter.getInstance(); sjSetter.SetProvider("IngrianProvider); IngrianDESedeKey key = new IngrianDESedeKey(sKey); sjSetter.setKey(DefaultParms.DEFAULT_USERID, key); To set the key using con_safejdbc.ini file with a key name: SAFEJDBC_KEY = CSencrypt 9.c) Limitations with IngrianProvider - INTEGER encryption is not supported, because Ingrian DES-EDE increases byte[] size after encryption 9.d) Toubleshootings with IngrianProvider Trying to decrypt an encrypted column value that has been truncated when INSERT because of limited column size may cause hang up when decrypting. This is normal and due to IngrianProvider behavior. Example with CSencrypt with SampleApp: 1) Encrypt "Test" 2) Copy the Ingrian NAE result 01FCA6CCF56C87AC8C00000040C841C098142D6EE64255140279933887D09D 93AA731C2915FA5E17060BEC6F5E into the "Text" box. 3) Truncate the Text Box to CA6CCF56C87AC8C00000040C841C098142 4) Click Execute 5) SampleApp hangs up. **end**