Documentation › Encryption and your own key

Encryption and your own key

SerenForce encrypts every secret it keeps. Each organization has its own key, separate from the platform’s, and you can even bring your own.

⏱ 9 minutes📍 Administration · platform setup · organization enrollment

What is protected

Every secret SerenForce keeps is encrypted: connection strings, client secrets, storage and cache keys, email and AI service keys, and the values marked Secret in an API call of a process. Each organization (tenant) has its own key, separate from the platform’s: the secrets of one organization cannot be read with the key of another.

The key source

The screen asks the questions one at a time; the next one only appears once you answer:

  1. How are the data keys protected?: With the root key of the installation (nothing else to do; the Status page then shows a warning) or With a key in a vault, that is your own key (BYOK). For an organization it needs the Business plan or an Enterprise license of the platform; for the platform itself, no license is needed.
  2. Which vault?: Azure Key Vault (or Managed HSM), AWS KMS or Google Cloud KMS.
  3. For Azure, A new vault or an existing one? A new vault always gets a new key.
  4. In an existing vault, and for AWS or Google, A new key or an existing one? An existing key is given by its address (URI, ARN or name); a new key is generated for you.
  5. For a new vault or a new key in Azure: SerenForce creates it now (you sign in to Azure) or I run a script (Bicep, ARM or Terraform). For AWS and Google, the new key is generated by a script (Terraform, CloudFormation or gcloud), then you type its address.

The key must be protected against deletion: purge protection (Azure), a deletion always delayed (AWS), at least 24 hours before destruction (Google). Your answers are kept: after a reload of the page, the screen finds them again.

The platform vault and the Dedicated key managed by SerenForce are no longer offered: an organization that already uses one keeps it until you choose another key, and its dedicated key can still be revoked or destroyed (see below).

The Check the key button runs five checks: the key is allowed, reachable, yours, able to wrap and unwrap, and protected against deletion.

Proving the key is yours

SerenForce shows an ownership token of your organization. It prevents using the key of another organization:

A key of AWS or Google protects the secrets; the database and the files of an organization can only use a key of Azure.

During platform setup

The Encryption step (optional, after License) asks the questions above, whatever the license of the platform (SaaS or Enterprise). The root key of the platform can be in Azure Key Vault or in Google Cloud KMS (by a script or with an existing key); Google Cloud KMS is offered only if the platform is set up for it. The service account shown must get the roles "Cloud KMS CryptoKey Encrypter/Decrypter" and "Cloud KMS Viewer" on the key. AWS KMS is shown as (coming soon).

For an existing vault, sign in under Connect to Azure, type the subscription and click Find my vaults. Choose the vault and click Use this vault: its resource group and name are filled in. For an existing key, then click Find the keys of the vault, choose the key and click Use this key: its URI is filled in. You can also type everything yourself. Your access to Azure is never kept.

Without an answer, the Use this key button asks you to choose the root key or a vault. See Set up the platform.

When adding an organization

In the administration, adding an organization has an Encryption step. With your own key, the database (Azure SQL or Azure Database for PostgreSQL) and the files (Azure Blob Storage or Amazon S3) are encrypted with it too. Tick Only the secrets to use it for the secrets only. Give the subscription and the resource group to apply it now, or download the script.

To put the key in an existing vault, do as in the setup: sign in to Azure, type the subscription, click Find my vaults then Find the keys of the vault. Only the keys given to this organization (with its serenforce-tenant tag) are listed. The vault chosen is kept with the enrollment in progress, never your access to Azure. The same list is on the Encryption page.

Without an answer at this step, the organization uses the key of the platform: the vault or the root key of the platform, else the Azure Key Vault or Google Cloud KMS key chosen for the catalog at the setup. If none fits (for example an AWS KMS key for the catalog), the enrollment fails. Choose a vault then.

The Encryption page of the administration

Choose the catalog or an organization: the page shows the key in use, its data keys, the latest changes and the next yearly rotation. Two actions:

Both actions ask you to sign in again with a second factor (less than 10 minutes old). See Second factor. Every change is recorded and emailed to all super administrators. The data key is renewed at least once a year in any case (see below). The Renewal of the data key field chooses, for the catalog or the organization, whether it is renewed Automatic (once a year) or On demand.

Renewing the key of your organization

With the Business plan (or an Enterprise license), the people who hold the Security administrator role manage the encryption of their organization themselves: Administration › Encryption. The tab shows the key that protects the secrets, when it was last renewed and by when it must be renewed. Not even the Administrator role sees it: the role is given on purpose (see the built-in roles).

Renew the key now asks you to sign in again with your second factor (less than 10 minutes old). The key can be renewed once every 24 hours: the tab then says from when you can renew it again. Every change is recorded and emailed to the super administrators and to the administrators of the organization; the emails never contain a link to click, only “sign in to SerenForce”.

An organization that shares its space with other organizations (the Team plan) does not manage its key: the tab says that the administrator of the platform manages it.

Second factor

Changing, renewing, revoking or destroying a key needs a second factor less than 10 minutes old. If your sign-in proves one, there is nothing more to do. Otherwise (Google or Amazon Cognito sign-in…), click Get a code by email: a 6-digit code, valid 10 minutes, is sent to you. After 5 wrong codes, ask for a new one.

Revoking or destroying the dedicated key

Every step is emailed to the administrators of the organization and to the super administrators, and written in the audit trail.

Daily check and continuity

Revoking your own key

Installation without Azure DevOps or on your own server

The root key is created with a command. Keep the recovery copy and its passphrase in two separate safe places.

SerenForce.Api keys init     # creates the root key (and the recovery copy)
SerenForce.Api keys rotate   # replaces it with a new key (the former one stays readable during the change)
SerenForce.Api keys import   # restores it on another server
SerenForce.Api keys check    # checks it
SerenForce.Api keys restore-data-key <id>   # restores a destroyed data key (90 days)

The recovery copy is encrypted with a passphrase the command asks you for (and asks again when importing); the passphrase is never kept.