Configuring encryption per table (TDE)

Configure transparent data encryption (TDE) on a per table basis. You can configure encryption with or without compression.

Designate transparent data encryption (TDE) on a per table basis. Using encryption, your application can read and write to SSTables that use different encryption algorithms or use no encryption at all. You must login as a superuser to encrypt data. For example:

$ cqlsh -u cassandra -p cassandra

System key overview  

  • You can create any number of system keys using the dsetool createsystemkey command.
  • Different tables can use different system keys.
  • All of the system keys must be consistent cluster-wide at the location set by the system_key_directory property in dse.yaml.
  • The system keys must have read write permissions for the user.
  • To use a specific system key for any table, specify the 'system_key_file':'system_key_filename' subproperty in the CREATE TABLE or ALTER TABLE statement.
  • A default global system key for the DataStax Enterprise cluster is used when the 'system_key_file':'system_key_filename' subproperty is not specified.
    • The global system key is an encryption key that you create in the location that is specified for the system_key_directory property in the dse.yaml file.
    • You can use any name for the global key file. With the dsetool createsystemkey command, use the file option to specify a key name. For example: dsetool createsystemkey file globalsystemkey .... If you do not specify the key name, the default key name is system_key. The default key name is not configurable.

    The default global system key file is inserted in the dse_system.encrypted_keys table that is used across the cluster.

Encrypting table data with encryption and compression

You can use a single CREATE TABLE or ALTER TABLE statement to set encryption and compression. The single CQL statement is:
CREATE TABLE users
  ... 
  WITH compression =
  { 'sstable_compression' : 'EncryptingSnappyCompressor',
  'cipher_algorithm' : 'AES/ECB/PKCS5Padding',
  'secret_key_strength' : 128,
,  'chunk_length_kb' : 128 };
Note: Designating data for encryption using ALTER TABLE does not encrypt existing SSTables, just new SSTables that are generated.

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.

The high-level container options for encryption and/or compression that can be used in the CREATE TABLE and ALTER TABLE statements are:
Encryptor Encrypts table data
EncryptingDeflateCompressor Encrypts table data and uses Deflate compression algorithm
EncryptingSnappyCompressor Encrypts table data and uses Snappy compression algorithm
DeflateCompressor Does not encrypt table data, uses Deflate compression algorithm
SnappyCompressor Does not encrypt table data, uses Snappy compression algorithm
LZ4Compressor (default) Does not encrypt table data, uses LZ4 compression algorithm
If defining a table with the Encryptor encryptor, set the young generation heap (-Xmn) parameter to a larger space to improve garbage collection (GC).

For example if running cassandra-stress, set : -Xmn1600M. The encryption and compression sub-options are:

cipher-algorithm sub-option

When Java Cryptography Extension (JCE) is installed, the cipher_algorithm options and acceptable secret_key_strength values 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
When JCE is installed, the following encryption options are valid:
  • sstable_compression = EncryptingDeflateCompressor
  • cipher_algorithm = 'AES/CBC/PKCS5Padding'
  • secret_key_strength = 256
  • chunk_length_kb = 128
  • key_provider = KmipKeyProviderFactory
  • kmip_host = kmip_group2

You can install custom providers for your JVM. The AES-512 is not supported out-of the box.

key_provider
Specify KmipKeyProviderFactory to use the KMIP key server for encryption.
kmip_host
The name of the KMIP key server group set in the kmip_hosts section in dse.yaml.
The key location sub-option

Create encryption keys using the dsetool createsystemkey command. You can create a global encryption key in the location that is specified by system_key_directory in the dse.yaml file. This default global encryption key is used when the system_key_file subproperty is not specified.

To use a specific encryption key, use:
'system_key_file':'name_of_system_key_file'
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, DataStax Enterprise looks for the system key as specified in dse.yaml. You do not need to specify the location of keytab file that contains the system key.

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 to implement encryption 

To use the SolrJ-Auth libraries to implement encryption, follow instructions in the solrj-auth-README.md file.

The default location of the solrj-auth-README.md file depends on the type of installation:
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 clients directory in DataStax Enterprise distribution. The SolrJ-Auth code is public.

The default location of the clients directory depends on the type of installation:
Debian installations /usr/share/dse/clients
Binary installations install_location/clients