{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "311d3b0e-9a61-4e3e-a8ba-69b63f7f2679",
   "metadata": {},
   "source": [
    "# Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3dc3b71-8fba-477d-a3b5-49234dc44b4c",
   "metadata": {},
   "source": [
    "pgsodium can be used in two ways:\n",
    "\n",
    "- either as a \"pure\" library extension with no server managed keys that you can load into your SQL session at any time with the `LOAD` command\n",
    "\n",
    "- \"preload\" mode where you place `pgsodium` in your postgres server's `shared_preload_libraries` configuration variable.\n",
    "\n",
    "If you add pgsodium to your\n",
    "[`shared_preload_libraries`](https://www.postgresql.org/docs/current/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD)\n",
    "configuration and place a special script in your postgres shared\n",
    "extension directory, the server can preload a libsodium key on server\n",
    "start. **This root secret key cannot be accessed from SQL**.  The only\n",
    "way to use the server secret key is to derive other keys from it using\n",
    "`derive_key()` or use the key_id variants of the API that take key ids\n",
    "and contexts instead of raw `bytea` keys.\n",
    "\n",
    "Server managed keys are completely optional, pgsodium can still be\n",
    "used without putting it in `shared_preload_libraries`, but you will\n",
    "need to provide your own key management.  \n",
    "\n",
    "See the file\n",
    "[`../getkey_scripts/pgsodium_getkey_urandom.sh`](../getkey_scripts/pgsodium_getkey_urandom.sh)\n",
    "for an example script that returns a libsodium key using the linux\n",
    "`/dev/urandom` CSPRNG.\n",
    "\n",
    "pgsodium also comes with example scripts for:\n",
    "\n",
    "  - [Amazon Web Service's Key Management\n",
    "    Service](../getkey_scripts/pgsodium_getkey_aws.sh).\n",
    "\n",
    "  - [Google Cloud's Cloud Key\n",
    "    Management](../getkey_scripts/pgsodium_getkey_gcp.sh).\n",
    "\n",
    "  - [Doppler SecretOps Platform](../getkey_scripts/pgsodium_getkey_doppler.sh).\n",
    "\n",
    "  - [Zymbit Zymkey 4i Hardware Security\n",
    "    Module](../getkey_scripts/pgsodium_getkey_zmk.sh).\n",
    "\n",
    "Next place `pgsodium` in your `shared_preload_libraries`.  For docker\n",
    "containers, you can append this after the run:\n",
    "\n",
    "    docker run -d ... -c 'shared_preload_libraries=pgsodium'\n",
    "\n",
    "When the server starts, it will load the secret key into memory, but\n",
    "this key is *never* accessible to SQL.  It's possible that a\n",
    "sufficiently clever malicious superuser can access the key by invoking\n",
    "external programs, causing core dumps, looking in swap space, or other\n",
    "attack paths beyond the scope of pgsodium.  Databases that work with\n",
    "encryption and keys should be extra cautious and use as many process\n",
    "hardening mitigations as possible.\n",
    "\n",
    "It is up to you to edit the get key script to get or generate the key\n",
    "however you want.  pgsodium can be used to generate a new random key\n",
    "with `select encode(randombytes_buf(32), 'hex')`.  Other common\n",
    "patterns including prompting for the key on boot, fetching it from an\n",
    "ssh server or managed cloud secret system, or using a command line\n",
    "tool to get it from a hardware security module.\n",
    "\n",
    "You can specify the location of the get key script with a database\n",
    "configuration variable in either `postgresql.conf` or using `ALTER\n",
    "SYSTEM`:\n",
    "\n",
    "    pgsodium.getkey_script = 'path_to_script'\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}