Main site

Using CipherStash Encryption Migrator

CipherStash Encryption Migrator is used to encrypt existing data or to apply index changes after encryption configuration changes of a protected database. For information about the available options when using CipherStash Encryption Migrator, see CipherStash Encryption Migrator options.

CipherStash Encryption Migrator is bundled into the cipherstash-proxy Docker image.

CipherStash Encryption Migrator uses CipherStash Proxy to encrypt.

This guide assumes:

  • CipherStash Proxy is installed, configured and running
  • the target table has a corresponding dataset configured to encrypt one or more columns.

See the imtroduction to CipherStash Proxy. A CipherStash account can be created in the CipherStash Dashboard.

Encrypt the source column data in a table into the specified encrypted target column.

1cipherstash-migrator [OPTIONS] --table <TABLE> --columns <SOURCE_COLUMN=TARGET_COLUMN> --database-name <DATABASE_NAME> --username <USERNAME> --password <PASSWORD>

Encrypting existing data requires running an UPDATE of the column to be encrypted through CipherStash Proxy.

At a high level, the process is:

1For each record in {table}
2 - SELECT {pk} {column} FROM {table};
3 - UPDATE {table} SET column = {column_value} WHERE {pk} = {pk_value};

CipherStash Proxy encrypts the {column_value} and creates any encrypted indexes required.

1cipherstash-migrator --table users --columns name=encrypted_name email=encrypted_email --database-name postgres --username postgres --password password

Specify the primary key column:

1cipherstash-migrator --table users --primary-key user_id --columns name=encrypted_name email=encrypted_email --database-name postgres --username postgres --password password

Specify multiple primary key columns (compound key):

1cipherstash-migrator --table users --primary-key user_id order_id  --columns name=encrypted_name email=encrypted_email --database-name postgres --username postgres --password password

Run as dry-run

1cipherstash-migrator --table users --primary-key user_id --columns name=encrypted_name email=encrypted_email --database-name postgres --username postgres --password password --dry-run

The --dry-run option will SELECT and load data from the table, but does execute any UPDATES

Assuming a container called cipherstash-proxy:

1docker exec cipherstash-proxy cipherstash-migrator --table users --columns name=encrypted_name email=encrypted_email

If the container is running with the CS_DATABASE__NAME, CS_DATABASE__USERNAME, CS_DATABASE__PASSWORD ENV variables, they will be reused by CipherStash Migrator and don't need to passed.

Data can be decrypted from an encrypted source to a plaintext target using the --decrypt flag.

All other command libne options remain the same.

1cipherstash-migrator --decrypt --table users --columns encrypted_name=name encrypted_email=email --database-name postgres --username postgres --password password