Encrypting tables

Configure table encryption using a local encryption key on a per table basis.

Configure transparent data encryption (TDE) with or without compression on a per table basis. Data is encrypted when written to disk (SSTable); after configuring an existing table to use encryption rewrite the tables to disk.

Two keys are for table encryption:
  • Local encryption key: Encrypts/decrypts internal table encryption key values.

    Distribute all local keys to all nodes in the cluster. Ensure that the DSE account owns the key files and has read/write access on them.

  • Table encryption key: DSE creates a single key entry in the dse_system.encrypted_keys for each cipher algorithm, key strength, and local encryption key combination that is defined for table encryption.

    Ensure that the dse_system keyspace has a replication factor of up to 3 in all datacenters.

    Note: Tables with the same encryption settings use the same encryption key.
Applications can read and write to SSTables that use different encryption algorithms or no encryption at all.
Warning: Primary keys are stored in plain text. Do NOT put sensitive information in partition key or clustering columns.

Table encryption options and syntax

When a table definition uses an encryption class, all table data except for primary keys is encrypted with a key entry from the dse_system.encrypted_keys table. If no keys match the cipher_algorithm, secret_key_strength, and system_key_file settings, a new key is created and added to the table.
Note: The following syntax only shows encryption options, all other compression options, such as chunk_length_kb, are also available.
Table encryption syntax:
COMPRESSION = { 
  'class' : 'encryption_class'[,
  'cipher_algorithm' : 'cipher_algorithm_type'] [,
  'secret_key_strength' : length] [,
  'system_key_file': 'key_filename'] };
Where:
  • Required. encryption_class: Use one of the class name from the following table.
    Name Encrypts Compresses
    Encryptor [1] Yes No
    EncryptingLZ4Compressor Yes Yes
    EncryptingDeflateCompressor Yes Yes
    EncryptingSnappyCompressor Yes Yes
    [1] When using the Encryptor class, specify a larger young generation heap (the -Xmn parameter) to improve garbage collection (GC). For example, set the size to: -Xmn1600M when running cassandra-stress.
  • Optional. cipher_algorithm_type: Sets the type of encryption key to use. The default is AES/CBC/PKCS5Padding. For the supported algorithms and types, see cipher_algorithm[/mode/padding].
  • Optional. length: Specifies the length of the key to use. The default is 128.
  • Optional. key_filename: Specifies the filename of the local encryption key used to encrypt the table key. Local keys are in the system_key_directory. The default is system_key.

Prerequisites

Complete the key setup described in Setting up local encryption keys.
Note: When using a local encryption key file, set the location system_key_directory and ensure that the key file is owned by the account running DSE.

Procedure

  • Creating a table with encryption enabled (and no compression):

    When configuring a table with encryption and that is NOT compressed, set the chunk_length_kb option to the lowest possible value, such as 1. A lower setting improves read performance by limiting the data that needs to be decrypted for each read operation.

    CREATE TABLE test.encryption_test_a (a int primary key) WITH 
       COMPRESSION = { 'class': 'Encryptor', 'chunk_length_kb' : 1 };
    Note: When the command excludes the optional settings, if a key with the default values already exists (SELECT key_id FROM dse_system.encrypted_keys WHERE key_file = 'system_key' AND cipher = 'AES' AND strength = 128;) that key is used to encrypt the table. If the key does not exist, DSE automatically creates it.
  • Creating a table with both encryption and compression:
    Encrypts a table using the DESede algorithm with a key length of 112 and compresses the data using the LZ4 compressor.
    CREATE TABLE test.encryption_test_d (d int primary key) WITH 
       COMPRESSION = {
          'class': 'EncryptingLZ4Compressor', 
          'cipher_algorithm' : 'DESede/CBC/PKCS5Padding', 
          'secret_key_strength' : 112,
          'system_key_file' : 'test-key' };
    
    Note: A local encryption key called 'test-key' must exist in the system_key_directory. If the DSE account does not have read/write permission or the file is missing, the error message Failed to initialize Encryptor occurs.
  • Setting up or changing encryption on an already existing table:
    1. Change the encryption settings:
      The following command changes the key used to encrypt the table data.
      ALTER TABLE test.encryption_test_d WITH
         COMPRESSION = { 
            'class': 'EncryptingLZ4Compressor', 
            'cipher_algorithm' : 'AES/ECB/PKCS5Padding', 
            'secret_key_strength' : 128,
            'system_key_file' : 'system_key'  };
      
    2. Rewrite the SSTables using the new encryption key (run on all nodes in the cluster):
      nodetool upgradesstables -a test encryption_test_d