|
|
|
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.
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 |
ctCAMO not defined. Service 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.
