Feat/docs 3.1.6

.gitignore

@@ -33,4 +33,5 @@
 *.su
 *~
 
-pgsodium_encrypted_root.key
+pgsodium_encrypted_root.key
+.ipynb_checkpoints/

docs/Authenticated_Encryption_With_Additional_Data.ipynb

@@ -7,6 +7,69 @@
    "source": [
     "# Authenticated Encryption with Associated Data"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "87fca072-a046-4426-9ff0-d9e9610e7af3",
+   "metadata": {},
+   "source": [
+    "Authenticated Encryption with Associated Data (AEAD) is a form of [Authenticated Encryption](https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD)) that associated an unencrypted plaintext along with the [authentication signature](https://en.wikipedia.org/wiki/Digital_signature) computed for the encrypted cyphertext.  In a sense one signature \"covers\" both the encrypted and unencrypted portion of a message.  For example, an application may want to encrypt a credit card number for payment, but then associate an account id with that credit card number, so that the credit card number can only be decrypted in the correct account number is provided as well.  This prevents substitution attacks where an different account number could be swapped in to cause payment to be charged to a different card.  pgsodium currently provides two AEAD constructions from libsodium:\n",
+    "\n",
+    "- The [crypto_aead_ietf](https://doc.libsodium.org/secret-key_cryptography/aead/chacha20-poly1305/ietf_chacha20-poly1305_construction) API.\n",
+    "- The [crypto_aead_det](https://github.com/jedisct1/libsodium-xchacha20-siv) API."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "33063881-b6ab-4955-9acd-c470a6465507",
+   "metadata": {},
+   "source": [
+    "## crypto_aead_ietf\n",
+    "\n",
+    "The IETF variant of the ChaCha20-Poly1305 construction can safely encrypt a practically unlimited number of messages, but individual messages cannot exceed 64*(2^32)-64 bytes (approximatively 256 GiB).\n",
+    "\n",
+    "### crypto_aead_ietf_keygen\n",
+    "\n",
+    "Creates a cryptographically random key for IETF AEAD.\n",
+    "\n",
+    "### crypto_aead_ietf_noncegen\n",
+    "\n",
+    "Creates a cryptographically random nonce for IETF AEAD.\n",
+    "\n",
+    "### crypto_aead_ietf_encrypt\n",
+    "\n",
+    "Encrypt and Authenticate a message with the given key and associated data.  This function only returns the encrypted and signed confidential part, it is up to the caller to preserve the non-confidential part. \n",
+    "\n",
+    "### crypto_aead_ietf_decrypt\n",
+    "\n",
+    "Decrypt a ciphertext with the provided key and associated data.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6fe42790-13ef-4fa8-8391-308794d2d321",
+   "metadata": {},
+   "source": [
+    "## crypto_aead_det\n",
+    "\n",
+    "Deterministic/nonce-reuse resistant authenticated encryption scheme using XChaCha20, implemented on libsodium.\n",
+    "\n",
+    "### crypto_aead_det_keygen\n",
+    "\n",
+    "Creates a cryptographically random key for deterministic AEAD.\n",
+    "\n",
+    "### crypto_aead_det_noncegen\n",
+    "\n",
+    "Creates a cryptographically random nonce for deterministic AEAD.\n",
+    "\n",
+    "### crypto_aead_det_encrypt\n",
+    "\n",
+    "Encrypt and Authenticate a message with the given key and associated data.  This function only returns the encrypted and signed confidential part, it is up to the caller to preserve the non-confidential part. \n",
+    "\n",
+    "### crypto_aead_det_decrypt\n",
+    "\n",
+    "Decrypt a ciphertext with the provided key and associated data.\n"
+   ]
   }
  ],
  "metadata": {

docs/Authenticated_Encryption_With_Additional_Data.md

@@ -1 +1,48 @@
 # Authenticated Encryption with Associated Data
+
+Authenticated Encryption with Associated Data (AEAD) is a form of [Authenticated Encryption](https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD)) that associated an unencrypted plaintext along with the [authentication signature](https://en.wikipedia.org/wiki/Digital_signature) computed for the encrypted cyphertext.  In a sense one signature "covers" both the encrypted and unencrypted portion of a message.  For example, an application may want to encrypt a credit card number for payment, but then associate an account id with that credit card number, so that the credit card number can only be decrypted in the correct account number is provided as well.  This prevents substitution attacks where an different account number could be swapped in to cause payment to be charged to a different card.  pgsodium currently provides two AEAD constructions from libsodium:
+
+- The [crypto_aead_ietf](https://doc.libsodium.org/secret-key_cryptography/aead/chacha20-poly1305/ietf_chacha20-poly1305_construction) API.
+- The [crypto_aead_det](https://github.com/jedisct1/libsodium-xchacha20-siv) API.
+
+## crypto_aead_ietf
+
+The IETF variant of the ChaCha20-Poly1305 construction can safely encrypt a practically unlimited number of messages, but individual messages cannot exceed 64*(2^32)-64 bytes (approximatively 256 GiB).
+
+### crypto_aead_ietf_keygen
+
+Creates a cryptographically random key for IETF AEAD.
+
+### crypto_aead_ietf_noncegen
+
+Creates a cryptographically random nonce for IETF AEAD.
+
+### crypto_aead_ietf_encrypt
+
+Encrypt and Authenticate a message with the given key and associated data.  This function only returns the encrypted and signed confidential part, it is up to the caller to preserve the non-confidential part. 
+
+### crypto_aead_ietf_decrypt
+
+Decrypt a ciphertext with the provided key and associated data.
+
+
+## crypto_aead_det
+
+Deterministic/nonce-reuse resistant authenticated encryption scheme using XChaCha20, implemented on libsodium.
+
+### crypto_aead_det_keygen
+
+Creates a cryptographically random key for deterministic AEAD.
+
+### crypto_aead_det_noncegen
+
+Creates a cryptographically random nonce for deterministic AEAD.
+
+### crypto_aead_det_encrypt
+
+Encrypt and Authenticate a message with the given key and associated data.  This function only returns the encrypted and signed confidential part, it is up to the caller to preserve the non-confidential part. 
+
+### crypto_aead_det_decrypt
+
+Decrypt a ciphertext with the provided key and associated data.
+

docs/Configuration.ipynb

@@ -17,7 +17,65 @@
     "\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."
+    "- \"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"
    ]
   }
  ],

docs/Configuration.md

@@ -5,3 +5,62 @@ pgsodium can be used in two ways:
 - 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
 
 - "preload" mode where you place `pgsodium` in your postgres server's `shared_preload_libraries` configuration variable.
+
+If you add pgsodium to your
+[`shared_preload_libraries`](https://www.postgresql.org/docs/current/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD)
+configuration and place a special script in your postgres shared
+extension directory, the server can preload a libsodium key on server
+start. **This root secret key cannot be accessed from SQL**.  The only
+way to use the server secret key is to derive other keys from it using
+`derive_key()` or use the key_id variants of the API that take key ids
+and contexts instead of raw `bytea` keys.
+
+Server managed keys are completely optional, pgsodium can still be
+used without putting it in `shared_preload_libraries`, but you will
+need to provide your own key management.  
+
+See the file
+[`getkey_scripts/pgsodium_getkey_urandom.sh`](../getkey_scripts/pgsodium_getkey_urandom.sh)
+for an example script that returns a libsodium key using the linux
+`/dev/urandom` CSPRNG.
+
+pgsodium also comes with example scripts for:
+
+  - [Amazon Web Service's Key Management
+    Service](../getkey_scripts/pgsodium_getkey_aws.sh).
+
+  - [Google Cloud's Cloud Key
+    Management](../getkey_scripts/pgsodium_getkey_gcp.sh).
+
+  - [Doppler SecretOps Platform](../getkey_scripts/pgsodium_getkey_doppler.sh).
+
+  - [Zymbit Zymkey 4i Hardware Security
+    Module](../getkey_scripts/pgsodium_getkey_zmk.sh).
+
+Next place `pgsodium` in your `shared_preload_libraries`.  For docker
+containers, you can append this after the run:
+
+    docker run -d ... -c 'shared_preload_libraries=pgsodium'
+
+When the server starts, it will load the secret key into memory, but
+this key is *never* accessible to SQL.  It's possible that a
+sufficiently clever malicious superuser can access the key by invoking
+external programs, causing core dumps, looking in swap space, or other
+attack paths beyond the scope of pgsodium.  Databases that work with
+encryption and keys should be extra cautious and use as many process
+hardening mitigations as possible.
+
+It is up to you to edit the get key script to get or generate the key
+however you want.  pgsodium can be used to generate a new random key
+with `select encode(randombytes_buf(32), 'hex')`.  Other common
+patterns including prompting for the key on boot, fetching it from an
+ssh server or managed cloud secret system, or using a command line
+tool to get it from a hardware security module.
+
+You can specify the location of the get key script with a database
+configuration variable in either `postgresql.conf` or using `ALTER
+SYSTEM`:
+
+    pgsodium.getkey_script = 'path_to_script'
+
+