Decrypting Data with Your Encryption Key

This guide explains how to decrypt encrypted data using the encryption key provided to you. You will receive your encryption key as a Base64-encoded string, so the first step will be to decode it.

1. Retrieve and Decode Your Key

You will receive your key from our API endpoint as a Base64-encoded string. Before using it for decryption, you must decode it to raw bytes.

Example (in Go):

import "encoding/base64"

decodedKey, err := base64.StdEncoding.DecodeString(encodedKey)
if err != nil {
    // handle error
}

⚠️
The decoded key must be exactly 32 bytes long, corresponding to AES-256 encryption.

2. Obtain the Ciphertext

You will also receive the ciphertext (the encrypted data). It is the id field of response from getId webSDK call with external_id_type=encrypted_email_hash.

It contains both:

a nonce (initialization vector), and
the encrypted sha256 email hash itself.

The structure of the ciphertext is:

[ nonce | encrypted data ]

3. Initialize AES-GCM Decryption

Once you have the decoded key and the ciphertext, use them to initialize the AES cipher and GCM mode.

Example (in Go):

import "crypto/aes"
import "crypto/cipher"

block, err := aes.NewCipher(decodedKey)
if err != nil {
    // handle error: invalid key
}

gcm, err := cipher.NewGCM(block)
if err != nil {
    // handle error
}

4. Extract the Nonce and Encrypted Data

The GCM nonce is stored at the beginning of the ciphertext. You can extract it like this:

nonceSize := gcm.NonceSize()
nonce := ciphertext[:nonceSize]
encrypted := ciphertext[nonceSize:]

5. Perform Decryption

Now decrypt the data using the GCM cipher:

plaintext, err := gcm.Open(nil, nonce, encrypted, nil)
if err != nil {
    // handle error: wrong key or corrupted data
}

If decryption is successful, plaintext will contain the original unencrypted data - sha256 email hash.

Summary

Get your key (Base64-encoded) from the endpoint.
Decode the key from Base64 to bytes.
Get the ciphertext (nonce + encrypted data) from id field from getId Call on webSDK.
Initialize AES-GCM with your decoded key.
Split the nonce and ciphertext.
Call gcm.Open(...) to decrypt.
Use the plaintext result.

Data Structure Overview

Base64 Key → Decode → AES Key (32 bytes)
Ciphertext → [ Nonce | Encrypted Data ]
                     ↓
               Decrypt with AES-GCM
                     ↓
                 Plaintext