|
|
|
This section provides a quick, step-by-step guide to using encryption with FairCom DB Standalone SQL Service in 4 phases.
Phase 1: Create Your Master Keys
To work with encrypted data, you need to have a c-tree master key and, optionally, you may want to have an encrypted store to avoid entering the password.
The encrypted store is not mandatory for the standalone application if the user can enter the master key. However, if you have an application that does not have a user interface, you will need to use the encrypted store to pass the master key in a safe way.
Because the FairCom DB Standalone SQL Service requires the encrypted store to be started properly, it is useful to have both.
To create both the master key and the encrypted store we can use the provided ctcpvf utility, found in the bin\ace\sql folder.
To create the master key, run the following command and then enter the master key:
ctcpfv
If you want to create both master key and the encrypted store, use the following and then enter the master key:
ctcpvf -s
Depending on which of the above commands you use, ctcpvf will produce one or two files: ctsrvr.pvf and (optionally) ctsrvr.fkf.
Save these files because they will be used by your standalone application and by FairCom DB Standalone SQL Service.
Phase 2: Configure Your Standalone Application
To make sure your standalone application is able to use the advanced encryption, we must make sure the files produced in Phase 1 are in the current working directory of your standalone application.
How to Configure Your Application to Use Advanced Encryption
Starting with c-tree version V11.8, all the standalone libraries compiled via mtmake are capable of handling advanced encryption. Note that the standalone program needs to make the proper calls to enabled advanced encryption.
Either of these techniques can be used to enable advanced encryption for your standalone application:
Using Environment Variables
The following environment variables can be used to enable advanced encryption for your standalone application:
CTREE_ADVANCED_ENCRYPTION=YES
CTREE_MASTER_KEY_FILE=ctsrvr.fkf
This can be done at the OS level, in the shell that will run the program or in the program itself by using the correct OS calls to set the environment variables. For example, on Windows, you can use SetEnvironmentVariable().
Using an API Call
Alternatively, you can use the facilities provided by one of the c-tree APIs to enable advanced encryption in your program.
FairCom DB API
The method to be called in FairCom DB API is ctdbSETENCRYPTParams(). Note: This requires that ctdbsdk.h is included in your C code.
The call is compatible with the ISAM API, however it must be called in the proper order. At the ISAM level it must be called after ctThrdInit() and before InitISAM(), for example:
ctThrdInit(3, 0L, NULL);
ctdbSETENCRYPTParams(1,"ctsrvr.fkf");
InitISAMXtd(16,16,16,16,0,"","","");
At the FairCom DB API level, ctdbSETENCRYPTParams() needs to be called between ctdbAllocSession() and ctdbLogon():
hSession = ctdbAllocSession(CTSESSION_CTREE);
ctdbSETENCRYPTParam(1, "ctsrvr.fkf");
ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");
ISAM
If you choose to use the ISAM API only, then call ctSETENCRYPT().
Phase 3: Encrypt Your New Tables
Once the standalone application is enabled for advanced encryption, requesting encryption for tables to be created requires a call to ctSETENCRYPT() or ctdbSETENCRYPT() before the table creation. This call informs the c-tree engine to encrypt the next tables that are going to be created. Examples are shown below:
ISAM
//enable encryption
ctSETENCRYPT(ctAES32, "MYKEY", 6);
//create some data
CreateIFile(&custmast_ifil)
//disable encryption, following creations will not be encrypted
ctSETENCRYPT(NULL, "", 0);
FairCom DB API
//enable encryption
ctdbSETENCRYPT(ctAES32, "MYKEY", 6);
//create some data
ctdbCreateTable(hTableCustMast, "custmast", CTCREATE_NORMAL)
//disable encryption, following creations will not be encrypted
ctdbSETENCRYPT(NULL, "ADMIN", 0);
Record insertions on an encrypted table will be automatically handled: you don’t need to call ctSETENCRYPT() or ctdbSETENCRYPT() to insert records.
Note, the ctcmpcif utility can also be used to add encryption to existing FairCom data files. See ctcmpcif - IFIL-based Compact Utility,
Phase 4: Import Your Standalone Data to FairCom DB Standalone SQL Service
Now that we have encrypted data from a standalone application, we could use FairCom DB Standalone SQL Service to guarantee SQL access to standalone data and work seamlessly with the existing standalone application.
To do this, FairCom DB Standalone SQL Service must be properly configured before importing any data with ctsqlimp.
Configuring FairCom DB Standalone SQL Service
To get FairCom DB Standalone SQL Service working with encrypted data, we need to configure it and provide the required files to handle encryption (created in phase 1 above).
To configure FairCom DB Standalone SQL Service to use advanced encryption, execute the following steps:
ADVANCED_ENCRYPTION YES
MASTER_KEY_FILE ctsrvr.fkf
Importing Your Data with ctsqlimp
To make your existing standalone data available for FairCom DB Standalone SQL Service at the SQL level, we will use ctsqlimp as provided in the tools/admin/client area of the FairCom DB Professional package.
The ctsqlimp utility supports both relative and absolute paths. Note: Because it is a pure client-server application, if a relative path is used, the path will be relative to the FairCom DB Standalone SQL Service LOCAL_DIRECTORY.
Also note that, as in the regular client-server SQL import phase, the file we are going to import is required to have the proper resources enabled (IFIL and DODA). For more information, refer to Using Existing ISAM Data with FairCom DB SQL.
Once you are ready to import the data, you will use ctsqlimp as follows:
ctsqlimp C:\Data\custmast.dat -u admin -a ADMIN -d ctreeSQL -s FAIRCOMS@localhost
If this command is successful, the table will be available in the SQL part of FairCom DB Standalone SQL Service.
You are now free to use one of our regular SQL clients to connect to the SQL port of FairCom DB Standalone SQL Service and query your data.
