Encryption

FairCom offers developers several advanced encryption routines, including AES (Rijndael), Blowfish, Twofish, and DES. Advanced encryption must be enabled at runtime via a configuration keyword. The choice of encryption algorithm and cipher strength is a per-file choice by the application developer at file creation time. A master password is then assigned. The password must be provided in some form at startup.

This chapter discusses encryption in your standalone application and in FairCom DB Standalone SQL Service.

Quick Start: Setting up Advanced Encryption for FairCom DB Standalone SQL Service

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
  • Using an API call

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:

  1. If running, shut down FairCom DB Standalone SQL Service.
  2. Copy ctsrvr.pvf and ctsrvr.fkf into the FairCom DB Standalone SQL Service executable directory.
  3. Edit the FairCom DB Standalone SQL Service configuration file and add the following keywords:

ADVANCED_ENCRYPTION YES

MASTER_KEY_FILE ctsrvr.fkf

  1. Restart FairCom DB Standalone SQL Service.

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. 

Advanced File Encryption

FairCom DB Standalone and FairCom DB Standalone SQL Service support encryption of data, index, and transaction log files. This technology provides the means to add an extra level of confidentiality to an application’s data. Once encrypted, it becomes difficult for a user to "dump" or "inspect" the data.

Advanced File Encryption includes a suite of protocols that will protect user data by what is loosely called "strong encryption" with a certain amount of performance overhead. Historically, enabling encryption impacted database performance, however with modern hardware performance, the impact of data encryption is approaching negligible levels for most applications.

The algorithms and protocols used are based on three primitives:

  • Secure One-Way Hash Function (MD5)
  • Block Ciphers (DES and AES)
  • Pseudo-Random Number Generators

 

When advanced encryption is enabled, FairCom DB Standalone SQL Service prompts for a master password at startup by default. For high availability, options are available to use a local key store file to maintain and verify the master password. The system administrator may encrypt existing files using the ctcv67 utility.

Developers can also implement the FairCom DB Server SDK to replace this prompt with an application-specific method of retrieving the master password.

Note: Prior to enabling advanced encryption, understand that there is no practical way to recover encrypted data without knowing the master password that was used to encrypt it. This applies to backed up data as well as live data. If a master password is changed, be sure to retain the old master password for any backups that may still be encrypted with the previous master password.

Encrypt and Decrypt Existing Tables with ctcmpcif Compact Utility

This utility can be used to encrypt and decrypt c-tree data files.

ctcmpcif reads the IFIL structure from DataFileName and calls CompactIFileXtd() and RebuildIFileXtd() to compact and rebuild DataFileName and its associated indexes. If ctcmpcif cannot extract the IFIL from the target file, it will ask for the name of another copy of the file from which to extract the IFIL information.

Changing Encryption Attributes

In V11 and later, the compact utility can optionally change the encryption attributes. To use this option, OR in the setencryptIFILoption bit into the tfilno field of the IFIL structure whose address you pass to the compact API function. When using this and other options, remember to negate the tfilno value after you OR in the options. For example:

myifil.tfilno = -(redosrlIFILoption | setencryptIFILoption);

CMPIFIL(&myifil);

Specifying the Encryption Cipher

In V11 and later, the ctcmpcif utility supports an option to specify the encryption cipher for the data and index files created by the compact operation. Usage:

-encrypt=cipher - Create the compacted file using the specified cipher:

  • for AES, use aes16, aes24, or aes32
  • for Blowfish, use blf8, blf9, ..., or blf56
  • for DES, use des8, des16, or des24
  • for Twofish, use twf16, twf24, or twf32
  • for no encryption, use none

Note: If an index file does not exist, the original data file's encryption attributes are used when creating that index file.

To change the encryption attributes of a file using the compact API function from a client, you must add the option CHANGE_ENCRYPTION_ON_COMPACT YES to ctsrvr.cfg. Otherwise, the operation fails with error NSUP_ERR (454, not supported).

Environment Variable to Enable Advanced Encryption

In V11.5 and later, c-tree supports enabling advanced encryption at run time using an environment variable. Set the environment variable CTREE_ADVANCED_ENCRYPTION to YES to enable advanced encryption if it is supported. This environment variable can be used to allow c-tree utilities to enable advanced encryption even if they haven't been updated yet to automatically enable advanced encryption when needed. Examples include the rebuild and compact utilities, ctrbldif and ctcmpcif.

Note: If c-tree does not support advanced encryption and this environment variable is set, the c-tree initialization will fail.

For more information, see ctcmpcif - IFIL-based Compact Utility.

Was this article helpful?

Give feedback about this article

Related Articles