Zaprite

Why We Encrypt Customer Data at Rest, and How We Still Search It

Why Zaprite encrypts customer data in the application with a key per merchant, and how merchants still search names and emails the database can't read.

Zaprite Team

5 min read

The name satoshi cut into three-letter pieces, next to a column of 64-bit search tokens.
On this page

Zaprite merchants trust us with their customers' names, emails, addresses and phone numbers. We encrypt all of it in our application before it reaches the database, with a separate key for every merchant. This post explains why we did that, how the keys work, and how merchants still search data the database can't read.

A copy of the database should be worthless

A production database doesn't stay in one place. It has backups, replicas and exports, and people and tools connect to it with credentials of their own. Across the industry, this is a common way for customer data to get out. Someone ends up with a copy of the data and never goes through the application that guards it.

Payment data raises the stakes. A list of people who pay in bitcoin, with names, emails and home addresses attached, is worth a lot to the wrong person.

So we designed for the worst case and assumed someone holds a full copy of our database. Our rule is that the copy contains no customer PII. Anything that reads the database without going through our application gets ciphertext.

One order row as our application reads it and as the database stores it.

Disk encryption doesn't cover a copy of the database

"Encrypted at rest" often means disk encryption. That protects a stolen disk. The database still returns plain text to anyone who can query it, and a dump made from it contains plain text too.

SQL crypto functions and vault extensions get closer, but the key sits with the database or travels to it inside the query. We wanted the database to hold data it has no way to read. So we encrypt and decrypt in the application, field by field, and the database stores bytes.

One key per merchant, locked by a key outside the database

Every merchant org has its own random 256-bit data key, so each merchant's data is cryptographically separate from every other merchant's. We store the data keys in the database, locked by a master key that lives in a KMS, outside the database and outside our app servers. A copy of the database contains locked keys and nothing that opens them.

The master key locks one data key per org. Each data key derives three purpose keys.

To read a row, the app unlocks the org's data key and decrypts the field with AES-256-GCM. We bind the table and column name into each ciphertext, so a value copied into another column fails to decrypt.

The two layers make rotation cheap. To rotate the master key we re-lock the data keys and never touch a customer field. Each locked key records the master key version that locked it, so both versions work during the switch.

From each data key we derive three keys with HKDF. One encrypts fields. The other two make search tokens.

Search has to work on data the database can't read

Encrypting the fields breaks search. ILIKE '%sato%' matches nothing in ciphertext, and a merchant who types "sato" still expects Satoshi to show up as they type.

The simplest fix decrypts all of an org's customers in memory and filters them in code. We built that first and measured it. A cold search over 100,000 customers took two to three seconds, which is too slow for a box people type into. We needed Postgres to narrow the search before we decrypted anything.

Three-letter pieces, hashed with the merchant's key

The trick is to give the database something it can index that isn't the name. We cut each name and email into overlapping three-letter pieces, the same way Postgres's pg_trgm does. satoshi becomes sat, ato, tos and so on. We run each piece through HMAC-SHA256 under the org's token key and keep the first 8 bytes as a 64-bit integer. The integers go into a bigint[] column with a GIN index.

The name satoshi becomes eight padded pieces, each hashed into an 8-byte token.

A search goes through the same steps. "sato" gives the pieces sat and ato, so two tokens, and we ask Postgres for the rows whose array contains both.

SELECT id FROM orders
WHERE org_id = $1
  AND search_tokens @> ARRAY[$2, $3]::bigint[]
LIMIT 1000;

Postgres gets two numbers and returns candidate rows. The app decrypts those and checks them against what the merchant typed, which drops false matches such as a row with sat in one word and ato in another. We decrypt a handful of candidates instead of the whole org.

Because the token key is per org, the same name hashes to different tokens for every merchant. Tokens from one org mean nothing in another.

We made a few more choices so the token column says as little as possible:

  • We deduplicate and sort the tokens in each row. Stored in write order, they would show which field and word each token came from.
  • Each field mixes its own name into the hash, so a name token never equals an email token.
  • We don't tokenize big email providers. A search for "gmail" would match half the table, and that token would be the most common value in the column.

Emails also get one exact token for the whole address, so pasting a full address is a single index lookup.

Free data gets no partial-search tokens

We decide which tokens a record gets when we write it.

Written byStored tokensSearch finds it by
Tier 1Anyone, for free, such as a public formExact email token onlyThe full email address
Tier 2A signed-in user, or a real paymentFull piece tokensAny part of the name or email

The reason is planted data. If anyone could submit names for free and get piece tokens back, they could work out which token each piece makes. So data from a public form gets the exact email token and nothing else, and a merchant can still find it by full email. It gets full tokens once a signed-in user enters it or a payment comes in. Full tokens come from the merchant's own team or from a paid order, and there is no free way to add them.

Merchants can delete what they don't need

Encryption protects the data we keep. The other half is keeping less of it. Once an order is finished, a merchant can delete its customer PII from the dashboard or through the API.

One transaction clears the encrypted fields and their search tokens together, so nothing searchable stays behind. The order and its payment record remain for the merchant's books, and we log that the clear happened without logging what was cleared.

One org at a time

We shipped this in steps we could undo. We wrote encrypted columns next to the existing ones, backfilled older rows, and ran a daily job to check that the two agreed. Then we switched reads and search one org at a time behind a flag, starting with our own. The last step retires the old columns.

Our bar for the project was that merchants wouldn't notice a change. There was no downtime, and search behaves the way it did before.

Published by Zaprite Team

Nov 11, 2026

Keep reading

More learn

Learn

Scaling Bitcoin Payments

At Zaprite, our goal is to contribute to and help accelerate growth in global adoption of bitcoin as money and a payment rail.

11 min read

Zaprite Imprint Digital Webinar September 2024

Learn

Webinar: Why Accept Bitcoin Payments

Join Zaprite and Imprint Digital for a webinar on the benefits of bitcoin payments and an effective marketing strategy.

1 min read

Ready to get started?

Start your Free Trial today or reach out to our Sales team with any questions.