FairCom ISAM for C

SetEncryption

Enable or disable encryption and set or reset encryption key.

Short Name

ctSETENCRYPT()

Type

Server only. This function is a server-only feature.

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

Declaration

COUNT SetEncryption(pTEXT mod, pTEXT key, VRLEN keylen)

Description

To encode index and data files without a parameter file, use SetEncryption() before the create file calls.

mod - use one of the symbolic constants listed below for Advanced File Encryption(NULL disables Advanced Encryption: instead, a legacy, less-secure technique, called Data Camouflage, is used even if ADVANCED_ENCRYPTION YES is set in server configuration file).
key - points to a byte array (of length keylen) which comprises the encryption key for basic encryption.
keylen indicates the length of the key. keylen of 0 disables encryption for any files created after that point.

SetEncryption() does not assume that key points to a null-terminated ASCII string. key can be any arbitrary array of bytes of length keylen. Key lengths of seven or more should be adequate.

To stop encrypting new files, call SetEncryption() with keylen set to zero. See ctSETENCRYPT - Passing a NULL to disable encryption.

key is ignored if any of the Advanced File Encryption algorithms are used.

Remember: Although key is ignored when using an Advanced Encryption cipher, keylen is used to enable or disable encryption as described above.

Available Ciphers

Symbolic Constant	Description
ctENCR	Advanced Encryption is not enabled; only the less-secure Data Camouflage is enabled - This mode is strongly discouraged for production systems or any place sensitive data is used. See Advanced File Encryption (Advanced File Encryption, Advanced Encryption).
ctAES16 ctAES24 ctAES32	Advanced Encryption Standard (AES) - Rijndael encryption algorithm implementation based on code made public by the Rijndael web page as an NIST AES finalist. For more information regarding this standard, refer to “Rijndael Web Site (AES Encryption)”. According to the Rijndael web site: “Rijndael is available for free. You can use it for whatever purposes you want, irrespective of whether it is accepted as AES or not."
ctDES8 ctDES16 ctDES24	Data Encryption Standard - DES encryption algorithm based on a description published by Bruce Schneier in “Applied Cryptography 2nd Edition.” (ISBN 0-471-12845-7)
ctBLF8 through ctBLF56	Blowfish encryption algorithm implementation based on code made public by Bruce Schneier of Counterpane Internet Security Inc. For more information regarding this standard, refer to “The Blowfish Encryption Algorithm.” According to the Counterpane web site about Blowfish: “Blowfish is unpatented and license-free, and is available free for all uses."
ctTWF16 ctTWF24 ctTWF32	Twofish encryption algorithm implementation based on code made public by Counterpane Internet Security Inc, as one of the NIST AES finalist. For more information regarding this standard, refer to the “Twofish Website”. According to the Counterpane web site about Twofish: “Twofish is unpatented, and the source code is uncopyrighted and license-free; it is free for all uses."

SetEncryption() only affects file creation operations. All files created after a given call to SetEncryption(), with 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 or not a new file is encrypted. Once a file is set for encryption, it is always encrypted.

SetEncryption Examples

The following pseudo-code encrypts the first ISAM data file and its indexes using Advanced Encryption ciphers, and does not encrypt the second ISAM data file and its indexes:

InitISAM(...)

SetEncryption (ctAES32, NULL, 1)

CreateIFile(..1..)

SetEncryption (NULL, NULL, 0)

CreateIFile(..2..)

Sample Calls to Enable or Disable Encryption

Either of these calls will enable AES encryption (if a key is specified, it is ignored):

ctSETENCRYPT(ctAES32, "mykey", 5);

ctSETENCRYPT(ctAES32, NULL, 5);

Any of these calls will disable encryption:

ctSETENCRYPT(ctENCR, NULL, 0);

ctSETENCRYPT(NULL, NULL, 0);

ctSETENCRYPT(NULL, NULL, -99);

ctSETENCRYPT(ctAES32, NULL, 0);

ctSETENCRYPT(ctAES32, NULL, -10);

Either of these calls will fail with PNUL_ERR (error 540) because key is NULL and it is required when enabling basic encryption:

ctSETENCRYPT(ctENCR, NULL, 5);

ctSETENCRYPT(NULL, NULL, 5);

Either of these calls will enable basic Data Camouflage, which provides some small amount of obscurity but does not qualify as encryption:

ctSETENCRYPT(ctENCR, "mykey", 5);

ctSETENCRYPT(NULL, "mykey", 5);

Note: SetEncryption() does not enable transaction log file encryption. Use the LOG_ENCRYPT configuration option to encrypt transaction log data.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful operation.
82	UALC_ERR	No memory available to allocate.
454	NSUP_ERR	Service not supported.

See c-tree Error Codes for a complete listing of valid c-tree error values.

ctSETENCRYPT - Passing a NULL to disable encryption

Note: A non-NULL key is required when a call to ctSETENCRYPT() is made that enables basic encryption; key is ignored when using Advanced Encryption.