Configuring encryption options
Configure encryption on a per table basis. Each node generates a separate key used for only that node’s SSTables.
You designate encryption on a per table basis. When using encryption, each node generates a separate key used for only that node’s SSTables. To encrypt data, first log in as the default superuser. For example:
$ cqlsh -u cassandra -p cassandra
The ALTER TABLE syntax for setting encryption options is the same as the syntax for setting data compression options.
For example, to set compression options in the users table:
ALTER TABLE users WITH compression = { 'sstable_compression' : 'DeflateCompressor', 'chunk_length_kb' : 64 };
To set encryption options in the users table, for example:
ALTER TABLE users WITH compression = { 'sstable_compression' : 'Encryptor', 'cipher_algorithm' : 'AES/ECB/PKCS5Padding', 'secret_key_strength' : 128, 'chunk_length_kb' : 1 };
Designating data for encryption using ALTER TABLE doesn't encrypt existing SSTables, just new SSTables that are generated. When setting up data to be encrypted, but not compressed, set the chunk_length_kb option to the lowest possible value, 1, as shown in the previous example. Setting this option to 1 improves read performance by limiting the data that needs to be decrypted for each read operation to 1 KB.
Setting encryption and compression together
Encryption and compression occur locally, which is more performant than trying to accomplish these tasks on the Cassandra-side. Encryption can be set together with compression using a single statement. The single CQL statement in is:
ALTER TABLE users WITH compression = { 'sstable_compression' : 'EncryptingSnappyCompressor', 'cipher_algorithm' : 'AES/ECB/PKCS5Padding', 'secret_key_strength' : 128, , 'chunk_length_kb' : 128 };
Encryption/compression options and sub-options
Using encryption, your application can read and write to SSTables that use different encryption algorithms or no encryption at all. Using different encryption algorithms to encrypt SSTable data is similar to using different compression algorithms to compress data. This section lists the options and sub-options.
- Encryptor
- EncryptingDeflateCompressor
- EncryptingSnappyCompressor
- DeflateCompressor
- SnappyCompressor
- LZ4Compressor (default)
The cipher_algorithm sub-option
When JCE is installed, the cipher_algorithm options and acceptable secret_key_strength for the algorithms are:
cipher_algorithm | secret_key_strength |
---|---|
AES/CBC/PKCS5Padding | 128, 192, or 256 |
AES/ECB/PKCS5Padding | 128, 192, or 256 |
DES/CBC/PKCS5Padding | 56 |
DESede/CBC/PKCS5Padding | 112 or 168 |
Blowfish/CBC/PKCS5Padding | 32-448 |
RC2/CBC/PKCS5Padding | 40-128 |
You can install custom providers for your JVM. The AES-512 is not supported out-of the box.
The key location sub-option
The system_key option replaces the secret_key_file option and is functionally different from the secret_key_file option. You create a file using the createsystemkey command. By default, DataStax Enterprise puts the system key you create in /etc/dse/conf. You can change the location of the system key by changing the path in the dse.yaml file.
Installer-Services | /etc/dse/dse.yaml |
Package installations | /etc/dse/dse.yaml |
Installer-No Services | install_location/resources/dse/conf/dse.yaml |
Tarball installations | install_location/resources/dse/conf/dse.yaml |
After specifying the data to be encrypted, a keytab file is automatically created in the directory set by the secret_key_file. If the directory does not exist, it is created. A failure to create the directory probably indicates a permissions problem. By default, DataStax Enterprise puts the keytab file in /etc/dse/conf, but it can reside in any directory.
Example values in the keytab file are:
AES/ECB/PKCS5Padding:256:bxegm8vh4wE3S2hO9J36RL2gIdBLx0O46J/QmoC3W3U= AES/CBC/PKCS5Padding:256:FUhaiy7NGB8oeSfe7cOo3hhvojVl2ijI/wbBCFH6hsE= RC2/CBC/PKCS5Padding:128:5Iw8EW3GqE6y/6BgIc3tLw==
Deleting, moving, or changing the data in the keytab file causes errors when the node restarts and you lose all your data. Consider storing the file on a network server or encrypting the entire file system of the nodes using a third-party tool.
The chunk_length_kb sub-option
On disk, SSTables are encrypted and compressed by block (to allow random reads). This subproperty of compression defines the size (in KB) of the block and is a power of 2. Values larger than the default value might improve the compression rate, but increases the minimum size of data to be read from disk when a read occurs. While the default value (64) is a good middle-ground for compressing tables, the maximum key size for Data Encryption Standard (DES) is 64 and the maximum key size for all other encryption algorithms is 128. For stronger encryption, install Java Cryptography Extension (JCE).
Using just encryption and no compression, the size of SSTables are larger than they would be if you combined compression. During creation of the table, specifying the location of keytab file, which contains the system key, is unnecessary. DataStax Enterprise looks for the system key as specified in dse.yaml file.
- sstable_compression = EncryptingDeflateCompressor
- cipher_algorithm = 'AES/CBC/PKCS5Padding'
- secret_key_strength = 256
- chunk_length_kb = 128
The iv_length sub-option
Not all algorithms allow you to set this sub-option, and most complain if it is not set to 16 bytes. Either use 16 or accept the default.
The syntax for setting this sub-option is similar to setting a compression algorithm to compress data.
ALTER TABLE users WITH compression = { 'sstable_compression' : 'EncryptingSnappyCompressor', 'cipher_algorithm' : 'AES/ECB/PKCS5Padding', 'secret_key_strength' : 128, 'iv_length' : 16 };
Using SolrJ Auth
Follow instructions in the solrj-auth-README.md file to use the SolrJ-Auth libraries to implement encryption. The SolrJ-auth-README.md file is located in the following directories:
- Debian installations: /usr/share/doc/dse-libsolr*
- RHEL-based installations: /usr/share/doc/dse-libsolr
- Binary installations: resources/solr
These SolrJ-Auth libraries are included in the DataStax Enterprise distribution:
- Debian installations: /usr/share/dse/clients
- Binary installations: install_location/clients
The SolrJ-Auth code is now public.