Apache Cassandra connections

DataMasque masks Apache Cassandra tables in place.

• Required privileges
• Connection parameters
• Encrypted connections
  • Publicly trusted certificates
  • Custom or private CAs
  • Rotating a certificate
• Masking process
  • Failed runs
  • Write time and TTL
  • Removing unmasked data from disk
• Masking Cassandra tables
  • Collections, tuples, user-defined types, and vectors
  • Primary key columns
  • Static columns
  • Wildcard rules
  • Filtering rows with where
• Limitations

Required privileges

A DataMasque connection for Apache Cassandra requires a role with the following permissions on the keyspace to be masked:

• SELECT, to read the tables to be masked.
• MODIFY, to write masked values and to TRUNCATE the tables to be masked.
• CREATE and DROP, to create and drop the staging tables (see Masking process) and to create the run history table.

CREATE ROLE <connection user> WITH PASSWORD = '<password>' AND LOGIN = true;

GRANT SELECT ON KEYSPACE <keyspace> TO <connection user>;
GRANT MODIFY ON KEYSPACE <keyspace> TO <connection user>;
GRANT CREATE ON KEYSPACE <keyspace> TO <connection user>;
GRANT DROP ON KEYSPACE <keyspace> TO <connection user>;

Note: DataMasque reads the table definitions from the system_schema keyspace, which every role can read. No explicit grant is required.

Connection parameters

Apache Cassandra connections use the following parameters:

• Host: The hostname or IP address of a Cassandra node (the contact point). DataMasque discovers the other nodes in the cluster from it.
• Port: The native protocol port (default: 9042).
• Keyspace: The keyspace to mask. In a ruleset, the keyspace takes the place of the schema.
• Username / Password: Credentials for PasswordAuthenticator. Optional when the cluster does not require authentication. If a user is provided, a password is also required.
• Local Datacenter: The datacenter that DataMasque sends requests to. Optional. Defaults to the datacenter of the contact point.
• Enable TLS/SSL: Connect to the cluster using TLS (client-to-node encryption). Shown under Advanced Settings. See Encrypted connections.
• Apache Cassandra CA Certificate: An optional CA certificate used to trust a custom or private CA. Shown under Advanced Settings once TLS is enabled. See Custom or private CAs.
• Direct Connection: Send every request to the host given above, not to the node addresses that the cluster advertises. Enable this for a multi-node cluster whose node addresses DataMasque cannot reach, for example behind NAT, in Kubernetes, or through an SSH tunnel. Shown under Advanced Settings.

Notes:

1. DataMasque reads and writes at the LOCAL_QUORUM consistency level.

2. Cassandra folds unquoted identifiers to lower case. Specify keyspace, table, and column names in lower case unless they were created as quoted identifiers.

3. Read-only connections are not supported.

Encrypted connections

DataMasque supports encrypted connections to Apache Cassandra clusters. Enable TLS/SSL on the connection to connect over TLS.

Publicly trusted certificates

When TLS is enabled without a CA certificate, the system CA trust store is used to verify each node. The certificate of each node must contain the node's IP address.

Custom or private CAs

To trust nodes whose certificates are not publicly trusted:

1. Upload a CA certificate on the Files page.
2. Edit the connection and enable TLS/SSL.
3. Under Advanced Settings, select the certificate as the Apache Cassandra CA Certificate.

The certificate is only used when TLS is enabled. Selecting one while TLS is disabled is rejected.

DataMasque verifies the node certificates against the uploaded CA. It does not check that a certificate names the node's address, except when it connects directly to a host name. Use a CA that signs only the certificates of your cluster.

The certificate must be uploaded as a .zip file containing a single ca.pem file:

File Name	Description
ca.pem	The certificate(s) used to verify the nodes, in PEM format.

What ca.pem should contain depends on how the node certificates were issued:

The node certificates are…	Put this in ca.pem
Self-signed	Each node's own certificate (each acts as its own trust anchor).
Issued by a private/internal CA	That CA's certificate (the issuer).
Issued via one or more intermediate CAs	The full chain: the root CA plus every intermediate CA, concatenated into ca.pem.

If you are unsure, include the full chain (the root CA and all intermediates). ca.pem must be in PEM format, i.e. one or more -----BEGIN CERTIFICATE----- blocks.

Client certificates (mutual TLS) are not supported. The uploaded certificate is used only to verify the nodes.

Rotating a certificate

Connection fileset names must be unique, so re-uploading a file with the same name is rejected. To rotate the CA certificate a connection uses:

1. Upload the new certificate as a new fileset (with a new, unique name).
2. Edit the connection and select the new certificate as the Apache Cassandra CA Certificate.
3. Delete the old fileset from the Files page.

Masking process

DataMasque masks each table into a staging table in the same keyspace, then truncates the table and copies the masked rows back.

• The table is empty from the TRUNCATE until the copy-back is complete.
• TRUNCATE fails if a node in the cluster is down.
• The staging table needs the same disk space as the table.
• Staging table names start with dm_stage_.

Important! Mask a copy of the cluster, not a cluster that applications use. A write to a table during a run can be lost.

Failed runs

A run that fails before the TRUNCATE leaves the table unchanged. A run that stops after the TRUNCATE can leave the table incomplete. The masked rows are then in the staging table, which the run log names. The next run of the task drops that staging table, so restore the table, for example from a backup, before you run the task again.

Write time and TTL

DataMasque keeps the TTL (time to live) of each cell. A cell that expires during the run is not written.

A cell that a rule masks gets a new write time. All other cells keep their original write time.

Each row gets a new row marker (the row's own liveness information). The marker has a TTL only when every cell of the row has a TTL. So a row that was created by UPDATE statements can continue to exist after its other cells are deleted or expire.

On Apache Cassandra 4.1, the elements of non-frozen collections and non-frozen user-defined types lose their own write time and TTL. The run log shows a warning that names the columns.

Removing unmasked data from disk

When auto_snapshot is enabled (the default), TRUNCATE and the drop of the staging table each write a snapshot on every node. These snapshots keep unmasked data on disk. The run log shows a warning when auto_snapshot is enabled and the connection role can read system_views.

After masking, remove the snapshots on every node:

nodetool clearsnapshot --all -- <keyspace>

Alternatively, mask a copy of the cluster in which auto_snapshot is disabled.

Masking Cassandra tables

Collections, tuples, user-defined types, and vectors

Columns of the collection types (list, set, and map), tuple, user-defined types, and vector are given to masks as JSON. Use the json mask to mask values inside them. Any other mask on such a column must return JSON of the same shape.

For example, a map<text, text> column is given to masks as a JSON object, and a list<int> column as a JSON array.

Primary key columns

To mask primary key columns, use imitate_unique or another unique mask, so that no two rows are given the same key.

All rows of one partition must keep one partition key. To mask a partition key column, use a deterministic mask, for example with hash_columns. Do not mask a partition key column when a where filter or max_rows selects only some rows of a partition. If rows of one partition are given different partition keys, the run fails before the table is changed.

Static columns

A static column holds one value for each partition. DataMasque masks static columns once for each partition, after the rules for all other columns. With a where filter, the static columns of a partition are masked when at least one row of the partition is selected.

• A rule that masks a static column may reference only partition key and static columns, including in if conditions.
• A rule that masks a static column cannot also mask a partition key column.
• A rule that masks any other column cannot reference a static column that another rule masks.

DataMasque refuses a task that breaks one of these rules.

Wildcard rules

A rule with column: "*" (a wildcard rule) masks each regular column that no other rule in the task masks. A regular column is a column that is not a primary key column and not a static column. A wildcard rule does not mask null cells.

If the table has static columns, mask each static column with a rule of its own.

Filtering rows with where

The where parameter of a mask_table task is a CQL condition. DataMasque runs it with ALLOW FILTERING.

Limitations

• Supported versions are Apache Cassandra 4.1 and 5.0.
• Only clusters that use Murmur3Partitioner are supported.
• Counter tables cannot be masked.
• Materialized views cannot be masked. Mask the base table.
• Do not run two tasks on the same table at once.
• imitate_date needs explicit min and max bounds.
• Subsetting is not supported.
• run_sql, build_temp_table, and run_data_discovery tasks are not supported.
• mask_unique_key tasks are not supported. Use the imitate_unique mask instead.
• The secure_shuffle mask is not supported.
• The joins and alias parameters and use_calculated_bounds: false are not supported in mask_table tasks.