diff --git a/apps/docs/pages/guides/database/vault.mdx b/apps/docs/pages/guides/database/vault.mdx index 4b49c769697..35e8bf5aa73 100644 --- a/apps/docs/pages/guides/database/vault.mdx +++ b/apps/docs/pages/guides/database/vault.mdx @@ -48,6 +48,7 @@ There are two main parts to the Vault UI, Secrets and Encryption Keys: As we mentioned, the Vault uses pgsodium's 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, and where are encryption keys store? 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]() encryption algorithm based on libsodium. “Authenticated Encryption” means that in addition to the data being encrypted, it is also “signed” so that it cannot be forged, the decryption function verifies that the signature is valid **before decrypting the value**. “Associated Data” means that in addition to signing the secret, you can include any other columns in your row in the signature computation, “associating” those columns with the secret. This doesn't encrypt those other columns, but it does ensure that **they are authentic** and cannot be forged because they are included in the secret's signature. So you know when you restore your database dumps, not only are the secrets safe, but also the “associated” columns are also authentic and unforged. Another important feature of pgsodium is that the encryption keys are never stored in the database alongside the encrypted data. Instead, only a **Key ID** is stored, which is a reference to the key that is only accessible outside of SQL. Even if an attacker can capture a dump of your entire database, they will see only encrypted data and key IDs, *never the raw key itself*.