Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Using Advanced Encryption

Advanced Encryption requires a master encryption key to access encrypted data. This key must be presented at server startup for any access to encrypted data, thereby ensuring ONLY the intended client applications that have access and knowledge of the master encryption key can view the data.

Also note that FairCom DB supports passwords on files, which may further help protect against unwanted access. Proper implementation of user-access controls within FairCom DB is also recommended to prevent unauthorized access to data, even if it is not protected by other means.

FairCom DB File and User Security are available only when using the client/server operational model.

Current customers: Please be sure to see additional application-level security details in the Knowledge Base in the Support Portal.

Setting Up Encryption

For a FairCom DB file to be protected by Advanced Encryption, it must be created as an encrypted file. The FairCom utility ctcmpcif.exe provides a mechanism for adding encryption support to an existing file. To create a file as encrypted you must call SetEncryption() before your file creation calls:

SetEncryption(pTEXT mod, pTEXT key, VRLEN keylen)

  • mod -- reserved for Advanced Encryption options and should be NULL for default encryption.
  • key -- pointer to a byte array containing the developer-specified encryption key of length keylen.
  • keylen -- length of key

For more details about using this function, see SetEncryption.

SetEncryption() does NOT assume that key points to a null-terminated ASCII string. The key can be any arbitrary array of bytes and is determined by the programmer. Key lengths of 7 bytes or more should be adequate. All create operations performed after SetEncryption() will result in encrypted files.

To stop encrypting new files, call SetEncryption() with key set to NULL and/or keylen set to zero.

SetEncryption() only affects file creation operations. All files created after a given call to SetEncryption(), with a non-NULL key and a keylen greater than zero, will be encrypted with the same key. Therefore, at the ISAM level, a data file and its associated indexes will be created with the same encryption key. Turning encryption on and off through calls to SetEncryption() only affects whether new files are encrypted. Once a file is set for encryption, it is always encrypted and no special calls are required to read from or write to the file.

Note: key may be thought of as a public key that changes the nature of the encryption, however, is not required to open the file. File passwords should be used to protect the ability to open a file. As described in Hidden Key Support, a hidden key may be embedded within a client executable and FairCom Server to give your application an exclusive ability to decrypt the file.

The following pseudo-code results in the first ISAM data file and its indexes to be encrypted with AES32 advanced encryption and the second ISAM data file and its indexes not to be encrypted:

InitISAM(...)

SetEncryption( (pTEXT)ctAES32,key,(VRLEN) 23)

CreateIFile(..1..)

SetEncryption(NULL,NULL,(VRLEN) 0)

CreateIFile(..2..)

To encode index and data files with a parameter file, use the user profile bit, USERPRF_ENCRYPT, in CreateISAMXtd() to enable encryption. All files created by, and after, CreateISAMXtd() will be encrypted with the same key, selected automatically by FairCom DB. New data and index files created after a call to SetEncryption() with a NULL key and/or zero keylen are not encrypted.

Errors

Two error codes have been defined: DCOD_ERR (606) is returned when an application cannot decode an encrypted file. RCOD_ERR (607) is returned when automatic recovery cannot decode an encrypted file.

TOCIndex