Troubleshooting the driver

When using the CipherStash driver in your application, you may run into situations where queries, encryption, and authentication aren’t working as you expect.

This how to guide covers:

• How to reveal more information about what the driver is doing
  • CS_DEBUG
  • RUST_LOG
• How to change behaviour of the driver
  • CS_PASSTHROUGH
  • CS_DISABLE_RUNTIME_CACHE
• How to send CipherStash support information you have collected

How to reveal more information about what the driver is doing

There are several ways to get the driver to say more about how it is behaving.

CS_DEBUG

CS_DEBUG controls debugging information output by the driver on stdout.

Valid values:

• true
• y
• 1

Example usage:

export CS_DEBUG=true

What the output looks like:

[Debug]: Mapped query: Some("SELECT a.attname, format_type(a.atttypid, a.atttypmod), pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod, c.collname, col_description(a.attrelid, a.attnum) AS comment, attgenerated AS attgenerated FROM pg_attribute a LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum LEFT JOIN pg_type t ON a.atttypid = t.oid LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation WHERE a.attrelid = '\"patients\"'::regclass AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum")
[Debug]: Attempting to map query: SHOW max_identifier_length
[Debug]: Mapped query: Some("SHOW max_identifier_length")
[Debug]: Mapped query to: SELECT patients.id, COALESCE(patients.__full_name_encrypted, patients.full_name::text) AS full_name, COALESCE(patients.__email_encrypted, patients.email::text) AS email, COALESCE(patients.__dob_encrypted, patients.dob::text) AS dob, COALESCE(patients.__weight_encrypted, patients.weight::text) AS weight, COALESCE(patients.__allergies_encrypted, patients.allergies::text) AS allergies, COALESCE(patients.__medications_encrypted, patients.medications::text) AS medications, patients.created_at, patients.updated_at FROM patients ORDER BY patients.id DESC LIMIT $1 OFFSET $2
[Debug]: Mapped query params to: [Some("30"), Some("0")]

RUST_LOG

RUST_LOG controls the level of output from Rust libraries used in the driver core.

Valid values:

• error
• warn
• info
• debug
• trace

Example usage:

export RUST_LOG=trace

What the output looks like:

[2023-06-09T07:18:00Z DEBUG vitur::decrypt] decrypting records
[2023-06-09T07:18:00Z DEBUG vitur::decrypt] waiting for access token
[2023-06-09T07:18:00Z DEBUG vitur_console_auth_credentials] getting token (waiting for lock)
[2023-06-09T07:18:00Z DEBUG vitur_console_auth_credentials] getting token (got lock)
[2023-06-09T07:18:00Z DEBUG vitur_console_auth_credentials] found cached token
[2023-06-09T07:18:00Z DEBUG vitur_console_auth_credentials] using cached token
[2023-06-09T07:18:00Z DEBUG vitur::decrypt] got token, decrypting 180 records
[2023-06-09T07:18:00Z TRACE vitur_client::decrypt] retrieving keys
[2023-06-09T07:18:00Z TRACE vitur_client::retrieve_keys] preparing payloads
[2023-06-09T07:18:00Z TRACE vitur_client::retrieve_keys] sending requests with 5 parallel requests and 500 keys per request
[2023-06-09T07:18:00Z TRACE vitur_client::retrieve_keys] sending request with 180 keys
[2023-06-09T07:18:00Z TRACE want] signal: Want
[2023-06-09T07:18:00Z TRACE want] signal found waiting giver, notifying
[2023-06-09T07:18:00Z TRACE want] signal: Want
[2023-06-09T07:18:00Z TRACE want] poll_want: taker wants!
[2023-06-09T07:18:00Z TRACE want] signal: Want
[2023-06-09T07:18:00Z TRACE vitur_client::retrieve_keys] retrieved keys - creating data keys
[2023-06-09T07:18:00Z TRACE vitur_client::retrieve_keys] successfully generated 180 keys
[2023-06-09T07:18:00Z TRACE vitur_client::decrypt] retrieved keys - decrypting records
[2023-06-09T07:18:00Z TRACE vitur_client::decrypt] decrypted 180 records
[2023-06-09T07:18:00Z DEBUG vitur::decrypt] success, decrypted 180 records

How to change behaviour of the driver

There are several ways to change the internal behaviour of the driver.

CS_PASSTHROUGH

CS_PASSTHROUGH controls if the driver does any query mapping.

Query mapping transforms your app’s SQL queries from using the unencrypted columns to using the encrypted columns.

Enabling passthrough mode:

• Doesn’t fetch the encryption schema. This means the driver won’t try to authenticate with CipherStash.
• Disables any query mapping. This means no encrypted columns are ever queried.

Setting CS_PASSTHROUGH can be useful for isolating if the CipherStash driver is causing unexpected behaviour in your app, like hangs from threading/forking behaviour.

Valid values:

• true
• y
• 1

Example usage:

export CS_PASSTHROUGH=true

If you are running the driver in plaintext-duplicate or encrypted-duplicate mode, the driver should be able to successfully query plaintext columns.

However, if you are running the driver in encrypted mode, your queries will fail.

CS_DISABLE_RUNTIME_CACHE

CS_DISABLE_RUNTIME_CACHE controls if the driver uses a runtime cache.

The runtime cache is used to improve performance of authentication and encryption operations.

Valid values:

• true
• y
• 1

Example usage:

export CS_DISABLE_RUNTIME_CACHE=true

How to send CipherStash support information you have collected

If you are having problems using CipherStash, we want to help!

1. Check out the support knowledge base for answers to common problems.
2. Submit a support request.

When submitting a support request, please attach output from your app or tool:

• Make sure you set the CS_DEBUG environment variable to true to get extra output. This makes understanding what is happening inside the driver much easier. This produces a lot of output, so only set it for the duration of your troubleshooting.
• Ideally also set the RUST_LOG environment variable to trace. This produces a lot of output, so only set it for the duration of your troubleshooting.

Please take care to never send us:

• Your CipherStash client ID (as found in the CS_CLIENT_ID environment variable)
• Your CipherStash client key (as found in the CS_CLIENT_KEY environment variable)