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.

The high-level container option for encryption and/or compression used in the ALTER TABLE statement are:
  • Encryptor
  • EncryptingDeflateCompressor
  • EncryptingSnappyCompressor
  • DeflateCompressor
  • SnappyCompressor
  • LZ4Compressor (default)
Note: If defining a table with the Encryptor encryptor, set the young generation heap (-Xmn) parameter to a larger space to improve garbage collection. For example if running cassandra-stress, set : -Xmn1600M.

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.

The location of the dse.yaml file depends on the type of installation:
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.

Example of valid encryption options when JCE is installed:
  • 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.