Rotating Sombra Keys

Rotating keys is a security best practice

NIST recommends rotating keys once a year.

Transcend allows you to rotate all the keys used by Sombra, granting you greater control over your security practices when using Transcend.

Sombra remembers the four (4) latest sets of keys. Older keys are "forgotten".

If Transcend hosts your Sombra instance, you can rotate the keys by following these steps:

  1. Navigate to "Settings > Sombra" on your Admin Dashboard

  2. Scroll to the "Hosted Sombra Keys" section

  3. Click on the "Rotate Sombra Keys" button

  4. Once the keys are finished rotating, you will be presented with your new INTERNAL_KEY. You will need to copy it down, as it will be lost once the modal is closed.

  5. After the modal closes, you will be redirected to the login page for the new keys to take effect.

In the key rotation process, we rotate two keys, the INTERNAL_KEY, and the JWT_ECDSA_KEY.

If you'd like for your internal application to authenticate with Sombra's internal API, you can do so by generating a symmetric key, called the INTERNAL_KEY. This key is then supposed to be sent as a Bearer token, with the x-sombra-authentication header.

INTERNAL_KEY_BIN=$(openssl rand 32)
INTERNAL_KEY=$(echo -n "$INTERNAL_KEY_BIN" | base64)
INTERNAL_KEY_HASH=$(echo -n "$INTERNAL_KEY_BIN" | openssl dgst -binary -sha256 | openssl base64)
echo "set in your service environments: INTERNAL_KEY: $INTERNAL_KEY"
echo "set gateway environment: INTERNAL_KEY_HASH: $INTERNAL_KEY_HASH"

You can then provide the hash of the internal key into the Sombra environment like:

INTERNAL_KEY_HASH="wm/mZTcSALaEibJXmhdq8g7lUN19kgXQ4hWgjt3woE8="

You can provide a CSV of internal key hashes to gracefully migrate from an old value to a new value like:

INTERNAL_KEY_HASH="old-key,new-key"

e.g.

INTERNAL_KEY_HASH="wm/mZTcSALaEibJXmhdq8g7lUN19kgXQ4hWgjt3woE8=,YOed1MK2eLVVqW3fqMtLadCKGFecz1liN96tXMDxDn0="

Note that it is safe to replace the INTERNAL_KEY_HASH in the environment without needing to cycle and data in your Transcend dashboard.

This is an asymmetric JSON web token key for signing Sombra payloads using the Elliptic Curve Digital Signature Algorithm. This key can also be used to derive other encryption keys used in Sombra.

The key is critical for decrypting data that is stored in the Transcend cloud and other data in the Transcend database must be migrated before you can remove an old key.

To generate a new key, you can run the command:

JWT_ECDSA_KEY=$(openssl ecparam -genkey -name secp384r1 -noout | base64)
echo "set gateway environment: JWT_ECDSA_KEY: ${JWT_ECDSA_KEY}"

You should then set the new key in the environment along side the old key:

JWT_ECDSA_KEY="new-key,old-key"

e.g.

JWT_ECDSA_KEY="LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1JR2tBZ0VCQkRCT0JkNExXVzNaTkJXOWhyTUJ4YlJUemx0SjZjWitIMm5GM3FybDgwdnpLbG1yMnFkRzU5YTUKOU1vWTJhWTJYWVNnQndZRks0RUVBQ0toWkFOaUFBUTBQOUI5Nm9FaVZhWmo3RnhRWThtM1JaMnRRRkVNaUhaWgpKTXk0NjdBcEJiRFRJZkpHRWh3MjAvcnljS3gxY25CUzRqYk5rdTVLNHh0TlpSMDcwVHNFWkREVmh3Y3kxNWRkCktWaDJGcVZvczkxVjVCSVUyK0xENUpYUGUweUVtM1U9Ci0tLS0tRU5EIEVDIFBSSVZBVEUgS0VZLS0tLS0K,LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1JR2tBZ0VCQkREYkZjZEZMemNEU0JXbkVrN1Q0TGZOY1cxMEJWdEVnKzczcDkyU1ZuRDlaaW5JUCs0bklneCsKYXV0WEpINlkwK3FnQndZRks0RUVBQ0toWkFOaUFBVEF3blpBcGx6ZmxHaFhmRkp6YVFKVkVnZFdWZ2NjZmhDRgpsOWVQQUZmMUxDd2Z6UzhSSFl0b3huQ2dUN0RSMWE0K1FOaXh5bWUvM3ZXSkRZU2JyQlZ5eU9NRVFvODEwRkRKCjZLTVBaWG90VEtSRU14c0FxS1pKS0UwNjVjZEpGckk9Ci0tLS0tRU5EIEVDIFBSSVZBVEUgS0VZLS0tLS0K"

It is recommended that you leave the old key around to decrypt data that was encrypted using that key. The first key in the CSV will be used to encrypt all data going forward. If you need to do an urgent key rotation, please reach out to support@transcend.io to assist to make sure no data is corrupted or lost during the cycle.

  1. Navigate to "Settings > Sombra" on your Admin Dashboard

  2. Scroll down to the "Request Security" section of the page

  3. Click on the "Re-Sign Encryption Contexts" button to update any requests that are failing due to the error Request's encryption context has expired...

  1. Navigate to "Settings > Sombra" on your Admin Dashboard
  2. Scroll down to the "Request Security" section of the page
  3. Click on the "Re-Sign SaaS Contexts" button to update all integrations in your organization