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