Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: clarify Vault/pgsodium root key lifecycle and portability (#47876)

Andrey A.f0d2ae8e249c
diff --git a/apps/docs/content/guides/database/extensions/pgsodium.mdx b/apps/docs/content/guides/database/extensions/pgsodium.mdx
index 73f7e71ccdc..12bcd02127b 100644
--- a/apps/docs/content/guides/database/extensions/pgsodium.mdx
+++ b/apps/docs/content/guides/database/extensions/pgsodium.mdx
@@ -4,13 +4,15 @@ title: 'pgsodium (pending deprecation): Encryption Features'
description: 'Encryption library for Postgres'
---
-Supabase DOES NOT RECOMMEND any new usage of [`pgsodium`](https://github.com/michelp/pgsodium).
+Supabase **does not recommend** the usage of [pgsodium](https://github.com/michelp/pgsodium) as it will be deprecated. Use [Supabase Vault](/docs/guides/database/vault) instead.
-The [`pgsodium`](https://github.com/michelp/pgsodium) extension is expected to go through a deprecation cycle in the near future. We will reach out to owners of impacted projects to assist with migrations away from [`pgsodium`](https://github.com/michelp/pgsodium) once the deprecation process begins.
+We will reach out to owners of impacted projects to assist with migrations away from [pgsodium](https://github.com/michelp/pgsodium) once the deprecation process begins.
+
+Vault and `pgsodium` are **separate** extensions. Vault doesn't depend on `pgsodium` and **is not** affected by this deprecation.
<Admonition type="note">
-The [Vault extension](/docs/guides/database/vault) won’t be impacted. Its internal implementation will shift away from pgsodium, but the interface and API will remain unchanged.
+Vault is self-contained and doesn't depend on `pgsodium`. It shares the same per-project [root key](/docs/guides/database/vault#encryption-key-location) (same format and location) but exposes its own interface - the `vault.secrets` table and `decrypted_secrets` view - so switching to Vault does not change how your key is managed.
</Admonition>
@@ -22,14 +24,11 @@ Note that Supabase projects are encrypted at rest by default which likely is suf
## Get the root encryption key for your Supabase project
-Encryption requires keys. Keeping the keys in the same database as the encrypted data would be unsafe. For more information about managing the `pgsodium` root encryption key on your Supabase project see **[encryption key location](/docs/guides/database/vault#encryption-key-location)**. This key is required to decrypt values stored in [Supabase Vault](/docs/guides/database/vault) and data encrypted with Transparent Column Encryption.
+Encryption requires keys. Keeping the keys in the same database as the encrypted data would be unsafe. Supabase Vault and `pgsodium` share the same per-project root encryption key; for more information about managing it see **[encryption key location](/docs/guides/database/vault#encryption-key-location)**. This key is required to decrypt values stored in [Supabase Vault](/docs/guides/database/vault) and data encrypted with Transparent Column Encryption.
## Resources
- [Supabase Vault](/docs/guides/database/vault)
- Read more about Supabase Vault in the [blog post](/blog/vault-now-in-beta)
- [Supabase Vault on GitHub](https://github.com/supabase/vault)
-
-## Resources
-
- Official [`pgsodium` documentation](https://github.com/michelp/pgsodium)
diff --git a/apps/docs/content/guides/database/vault.mdx b/apps/docs/content/guides/database/vault.mdx
index 8d703a5d509..3d129d73579 100644
--- a/apps/docs/content/guides/database/vault.mdx
+++ b/apps/docs/content/guides/database/vault.mdx
@@ -173,11 +173,11 @@ updated_at | 2022-12-14 02:51:13.938396+00
></iframe>
</div>
-As we mentioned, Vault uses Transparent Column Encryption (TCE) to store secrets in an authenticated encrypted form. There are some details around that you may be curious about. What does authenticated mean? Where is the encryption key stored? This section explains those details.
+As we mentioned, Vault stores secrets in an authenticated encrypted form. There are some details around that you may be curious about. What does authenticated mean? Where is the encryption key stored? This section explains those details.
### Authenticated encryption with associated data
-The first important feature of TCE is that it uses an [Authenticated Encryption with Associated Data](<https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD)>) encryption algorithm (based on `libsodium`).
+The first important feature is that it uses an [Authenticated Encryption with Associated Data](<https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD)>) encryption algorithm (based on `libsodium`).
### Encryption key location
@@ -189,12 +189,31 @@ Another important feature is that the encryption key is never stored in the data
This is an important safety precaution - there is little value in storing the encryption key in the database itself as this would be like locking your front door but leaving the key in the lock! Storing the key outside the database fixes this issue.
-Where is the key stored? Supabase creates and manages the encryption key in our secured backend systems. We keep this key safe and separate from your data. You remain in control of your key - a separate API endpoint is available that you can use to access the key if you want to decrypt your data outside of Supabase.
+Where is the key stored? Supabase creates and manages a unique encryption key for each project in our secured backend systems. We keep this key safe and separate from your data. You remain in control of your key - the [Management API endpoint](/docs/reference/api/v1-get-pgsodium-config) returns your project's 64-character hex root key so you can decrypt your data outside of Supabase or copy it to another project.
-Which roles should have access to the `vault.secrets` table should be carefully considered. There are two ways to grant access, the first is that the `postgres` user can explicitly grant access to the vault table itself.
+Which roles should have access to the `vault.secrets` table should be carefully considered. One example would be the `postgres` user explicitly granting access to the vault table.
+
+### Key portability and migration
+
+Each Supabase project has its own root encryption key. Same-project operations - pausing and restoring, and Point-in-Time or in-place restores - keep the same key, so your secrets stay readable automatically. The [Restore to a new project](/docs/guides/platform/clone-project) and [Branching](/docs/guides/deployment/branching) flows also copy the key to the new project.
+
+However, if you migrate to a **new** project with a manual `pg_dump` / `pg_restore`, that project is created with its own fresh key and **cannot decrypt** secrets copied from the old project. Before relying on the migrated data, copy the old project's root key to the new project. The `pgsodium` Management API endpoint returns and accepts the 64-character hex root key, and is only available for active (not paused or removed) projects:
+
+```bash
+export OLD_PROJECT_REF="<old_project_ref>"
+export NEW_PROJECT_REF="<new_project_ref>"
+export SUPABASE_ACCESS_TOKEN="<personal_access_token>"
+
+curl "https://api.supabase.com/v1/projects/$OLD_PROJECT_REF/pgsodium" \
+ -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" |
+curl "https://api.supabase.com/v1/projects/$NEW_PROJECT_REF/pgsodium" \
+ -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
+ -X PUT --json @-
+```
+
+See [Backup and restore using the CLI](/docs/guides/platform/migrating-within-supabase/backup-restore) for the full restore procedure.
### Resources
- Read more about Supabase Vault in the [blog post](/blog/vault-now-in-beta)
- [Supabase Vault on GitHub](https://github.com/supabase/vault)
-- [Column Encryption](/docs/guides/database/column-encryption)
diff --git a/apps/docs/content/guides/platform/clone-project.mdx b/apps/docs/content/guides/platform/clone-project.mdx
index 833091c0f1b..3cbf16324d6 100644
--- a/apps/docs/content/guides/platform/clone-project.mdx
+++ b/apps/docs/content/guides/platform/clone-project.mdx
@@ -15,6 +15,7 @@ You can clone your Supabase project by restoring your data from an existing proj
- All data and indexes
- Database roles, permissions and users
- Auth user data (user accounts, hashed passwords, and authentication records from the auth schema)
+- Encryption root key (so [Vault](/docs/guides/database/vault) secrets and encrypted columns remain readable in the new project)
**What needs manual reconfiguration?**
diff --git a/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx b/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx
index cd989bbccc6..444fb1e514d 100644
--- a/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx
+++ b/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx
@@ -90,6 +90,12 @@ breadcrumb: 'Migrations'
### Restore backup using CLI
+<Admonition type="note">
+
+These steps cover a manual logical restore (`pg_dump` / `psql`) into a project you create yourself. The [Restore to a new project](/docs/guides/platform/clone-project) and [Branching](/docs/guides/deployment/branching) flows copy your encryption root key to the new project automatically, so the key-copy step below does not apply to them.
+
+</Admonition>
+
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Create project" fullWidth>
@@ -147,7 +153,7 @@ breadcrumb: 'Migrations'
type="underlined"
defaultActiveId="no-column-encryption"
>
- <TabPanel id="no-column-encryption" label="Column encryption disabled">
+ <TabPanel id="no-column-encryption" label="No Vault or column encryption">
Run these commands after replacing ```[CONNECTION_STRING]``` with your connection string from the previous steps:
@@ -163,8 +169,17 @@ breadcrumb: 'Migrations'
```
</TabPanel>
- <TabPanel id="column-encryption" label="Column encryption enabled">
- If you use [column encryption](/docs/guides/database/column-encryption), copy the root encryption key to your new project using your [Personal Access Token](/dashboard/account/tokens).
+ <TabPanel id="column-encryption" label="Supabase Vault or column encryption">
+
+ <Admonition type="caution">
+
+ Retrieve the root encryption key from the **old** project _before_ you pause or delete it. The API below only returns the key for active projects - once the old project is paused or removed, the key (and any data encrypted with it) can no longer be retrieved.
+
+ Backup files never contain the root key; they hold only encrypted data. A newly created project is initialized with its own fresh root key, so Vault secrets and encrypted columns restored from the old project cannot be decrypted until you copy the old key across. Overwriting a project's root key makes any data encrypted under a different key inaccessible.
+
+ </Admonition>
+
+ If you use [Supabase Vault](/docs/guides/database/vault) or [pgsodium](/docs/guides/database/extensions/pgsodium), copy the root encryption key to your new project using your [Personal Access Token](/dashboard/account/tokens). Both rely on the same per-project root key.
You can restore the project using both the old and new project ref (the project ref is the value between "https://" and ".supabase.co" in the URL) instead of the URL.
@@ -179,6 +194,8 @@ breadcrumb: 'Migrations'
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
-X PUT --json @-
```
+
+ The endpoint both returns and expects the 64-character hex root key.
</TabPanel>
</Tabs>
</StepHikeCompact.Details>