Product Documentation

FairCom DB Function DescriptionsSetEncryption

FairCom ISAM for C

Previous Topic

Next Topic

SetEncryption

Enable or disable encryption and set or reset encryption key.

Short Name

ctSETENCRYPT()

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
  • keylen indicates the length of the key. keylen of 0 disables encryption for any files created after that point.

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

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

ctAES16 ctAES24 ctAES32

Advanced Encryption Standard (AES)

Ciphers available prior to V13

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).

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);

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.

1210

CAMO_NSUP_ERR

Camouflage not supported

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

See Also

Passing a NULL value for the key parameter to ctSETENCRYPT was inadvertently resetting keylen to 0, which was disabling encryption. In V10.3 and later, the code in the client library interface to ctSETENCRYPT() has been changed so that it is consistent with the following definition:

In the ctSETENCRYPT() function, keylen > 0 enables encryption for all files created after that point, and keylen <= 0 disables encryption. This is true regardless of whether key is NULL or not.

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.

Previous Topic

Next Topic

ctSETENCRYPT - Passing a NULL to disable encryption

Passing a NULL value for the key parameter to ctSETENCRYPT was inadvertently resetting keylen to 0, which was disabling encryption. In V10.3 and later, the code in the client library interface to ctSETENCRYPT() has been changed so that it is consistent with the following definition:

In the ctSETENCRYPT() function, keylen > 0 enables encryption for all files created after that point, and keylen <= 0 disables encryption. This is true regardless of whether key is NULL or not.

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.

TOCIndex