more api details and formatting. (michelp#65)

ioguix · Jan 4, 2023 · 6fd7f9c · 6fd7f9c
1 parent f2e1253
commit 6fd7f9c
Show file tree

Hide file tree

Showing 23 changed files with 477 additions and 135 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -1,3 +1,3 @@
 [*]
-indent_style = tab
+indent_style = space
 indent_size = 4
diff --git a/docs/Authenticated_Encryption_With_Additional_Data.ipynb b/docs/Authenticated_Encryption_With_Additional_Data.ipynb
@@ -28,45 +28,47 @@
     "\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",
+    "### `crypto_aead_ietf_keygen()`\n",
     "\n",
     "Creates a cryptographically random key for IETF AEAD.\n",
     "\n",
-    "### crypto_aead_ietf_noncegen\n",
+    "### `crypto_aead_ietf_noncegen()`\n",
     "\n",
     "Creates a cryptographically random nonce for IETF AEAD.\n",
     "\n",
-    "### crypto_aead_ietf_encrypt\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",
+    "### `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": {},
+   "metadata": {
+    "tags": []
+   },
    "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",
+    "### `crypto_aead_det_keygen()`\n",
     "\n",
     "Creates a cryptographically random key for deterministic AEAD.\n",
     "\n",
-    "### crypto_aead_det_noncegen\n",
+    "### `crypto_aead_det_noncegen()`\n",
     "\n",
     "Creates a cryptographically random nonce for deterministic AEAD.\n",
     "\n",
-    "### crypto_aead_det_encrypt\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",
+    "### `crypto_aead_det_decrypt()`\n",
     "\n",
     "Decrypt a ciphertext with the provided key and associated data.\n"
    ]

diff --git a/docs/Authenticated_Encryption_With_Additional_Data.md b/docs/Authenticated_Encryption_With_Additional_Data.md
@@ -9,19 +9,19 @@ Authenticated Encryption with Associated Data (AEAD) is a form of [Authenticated
 
 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
+### `crypto_aead_ietf_keygen()`
 
 Creates a cryptographically random key for IETF AEAD.
 
-### crypto_aead_ietf_noncegen
+### `crypto_aead_ietf_noncegen()`
 
 Creates a cryptographically random nonce for IETF AEAD.
 
-### crypto_aead_ietf_encrypt
+### `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
+### `crypto_aead_ietf_decrypt()`
 
 Decrypt a ciphertext with the provided key and associated data.
 
@@ -30,19 +30,19 @@ Decrypt a ciphertext with the provided key and associated data.
 
 Deterministic/nonce-reuse resistant authenticated encryption scheme using XChaCha20, implemented on libsodium.
 
-### crypto_aead_det_keygen
+### `crypto_aead_det_keygen()`
 
 Creates a cryptographically random key for deterministic AEAD.
 
-### crypto_aead_det_noncegen
+### `crypto_aead_det_noncegen()`
 
 Creates a cryptographically random nonce for deterministic AEAD.
 
-### crypto_aead_det_encrypt
+### `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
+### `crypto_aead_det_decrypt()`
 
 Decrypt a ciphertext with the provided key and associated data.
 
diff --git a/docs/Configuration.ipynb b/docs/Configuration.ipynb
@@ -33,7 +33,7 @@
     "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",
+    "[`../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",

diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -20,7 +20,7 @@ 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)
+[`../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.
 

diff --git a/docs/Generating_Random_Data.ipynb b/docs/Generating_Random_Data.ipynb
@@ -26,9 +26,6 @@
    "execution_count": null,
    "id": "06c57255-4cbf-439c-a7f4-8b5112d14c35",
    "metadata": {
-    "jupyter": {
-     "source_hidden": true
-    },
     "tags": []
    },
    "outputs": [],
@@ -77,7 +74,7 @@
    "id": "f7fa16e6-ee55-4764-ab79-6f41cf9899b2",
    "metadata": {},
    "source": [
-    "### randombytes_random()"
+    "### `randombytes_random()`"
    ]
   },
   {
@@ -146,7 +143,7 @@
    "id": "63fd868c-0ba4-41b6-95c8-e2652ac7df96",
    "metadata": {},
    "source": [
-    "### randombytes_uniform()"
+    "### `randombytes_uniform(upper_bound interger)`"
    ]
   },
   {
@@ -210,7 +207,7 @@
    "id": "eb168c4d-416d-456a-8a1e-8dd3fd8d7b84",
    "metadata": {},
    "source": [
-    "### randombytes_buf()"
+    "### `randombytes_buf(buffer_size integer)`"
    ]
   },
   {

diff --git a/docs/Generating_Random_Data.md b/docs/Generating_Random_Data.md
@@ -32,7 +32,7 @@ CREATE EXTENSION IF NOT EXISTS pgsodium;
 
 
 
-### randombytes_random()
+### `randombytes_random()`
 
 Returns a random 32-bit signed integer.
 
@@ -70,7 +70,7 @@ Returns a random 32-bit signed integer.
 
 
 
-### randombytes_uniform()
+### `randombytes_uniform(upper_bound interger)`
 
 Returns a uniformally distributed random number between zero and the upper bound argument.
 
@@ -108,7 +108,7 @@ Returns a uniformally distributed random number between zero and the upper bound
 
 
 
-### randombytes_buf()
+### `randombytes_buf(buffer_size integer)`
 
 Returns a random buffer of bytes the size of the argument.
 

diff --git a/docs/HMAC.ipynb b/docs/HMAC.ipynb
@@ -16,7 +16,9 @@
     "any MAC, it may be used to simultaneously verify both the data\n",
     "integrity and authenticity of a message.\n",
     "\n",
-    "[C API Documentation](https://doc.libsodium.org/advanced/hmac-sha2)\n"
+    "[C API Documentation](https://doc.libsodium.org/advanced/hmac-sha2)\n",
+    "\n",
+    "pgsodium provides hmacsha512 and hmacsha256, only 512-bit examples are provided below, the 256-bit API is identical but using names like `crypto_auth_hmacsha256_*`.\n"
    ]
   },
   {
@@ -74,7 +76,7 @@
    "id": "d24f2168-7c64-42e9-b9f6-f6fa4cffe787",
    "metadata": {},
    "source": [
-    "### crypto_auth_hmacsha512_keygen()"
+    "### `crypto_auth_hmacsha512_keygen()`"
    ]
   },
   {
@@ -102,7 +104,7 @@
    "id": "101da183-2791-4436-b3e5-ae5335533dc4",
    "metadata": {},
    "source": [
-    "### crypto_auth_hmacsha512()"
+    "### `crypto_auth_hmacsha512(message bytea, key bytea)`"
    ]
   },
   {
@@ -130,7 +132,7 @@
    "id": "7313cbca-0e41-43e3-9816-94d7279bec0b",
    "metadata": {},
    "source": [
-    "### crypto_auth_hmacsha512_verify()"
+    "### `crypto_auth_hmacsha512_verify(signature bytea, message bytea, key bytea)`"
    ]
   },
   {

diff --git a/docs/HMAC.md b/docs/HMAC.md
@@ -11,6 +11,8 @@ integrity and authenticity of a message.
 
 [C API Documentation](https://doc.libsodium.org/advanced/hmac-sha2)
 
+pgsodium provides hmacsha512 and hmacsha256, only 512-bit examples are provided below, the 256-bit API is identical but using names like `crypto_auth_hmacsha256_*`.
+
 
 
 ```python
@@ -37,7 +39,7 @@ CREATE EXTENSION IF NOT EXISTS pgsodium;
 
 
 
-### crypto_auth_hmacsha512_keygen()
+### `crypto_auth_hmacsha512_keygen()`
 
 
 ```python
@@ -49,7 +51,7 @@ print(key)
     b'|\'\x88\xf1\x88\x82\x8b\xcb"O\x1a\'\xb8#c\xa6f\x1ag\x05nx5\xc2\xe5u8</\xa0\xbd\x18'
 
 
-### crypto_auth_hmacsha512()
+### `crypto_auth_hmacsha512(message bytea, key bytea)`
 
 
 ```python
@@ -61,7 +63,7 @@ print(signature)
     b'2\xae\x9d_\xb2\xaf\xf1\x08tq2\x97V*\xb1\x10\xb6b\xb1s\xcc\x06\x95\x12\x9f\xfb\xbc\x07-L]m\x88\\\x80\x98\x8cHc\xbd\x96\xe5\xb1\xd9{\x17\x1eP\x11^\xc3\x1f\x89\xb7\xacL&\x12\xd7\xefr\xe7j8'
 
 
-### crypto_auth_hmacsha512_verify()
+### `crypto_auth_hmacsha512_verify(signature bytea, message bytea, key bytea)`
 
 
 ```python

diff --git a/docs/Hashing.ipynb b/docs/Hashing.ipynb
@@ -14,7 +14,11 @@
    "cell_type": "markdown",
    "id": "80a1d42e-5c83-4388-b549-1fe2460b9f53",
    "metadata": {},
-   "source": []
+   "source": [
+    "libsodium provides functions for \"generic\" and \"short\" hashing.  \n",
+    "\n",
+    "Generic hashing is suitable for cryptographic purposes using the BLAKE2b algorithm."
+   ]
   },
   {
    "cell_type": "code",
@@ -71,7 +75,7 @@
    "id": "857d49ef-f874-474f-a076-a020ed22b2ae",
    "metadata": {},
    "source": [
-    "### crypto_generichash_keygen()"
+    "### `crypto_generichash_keygen()`"
    ]
   },
   {
@@ -99,7 +103,7 @@
    "id": "bc5faade-d3de-47d7-949d-14ffd6c46b73",
    "metadata": {},
    "source": [
-    "### crypto_generichash()"
+    "### `crypto_generichash(message bytea, key bytea = NULL)`"
    ]
   },
   {
@@ -142,12 +146,39 @@
     "print(signature[0][0].tobytes())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a6d1a008-a5ea-4c80-8c3c-ed67d565b0aa",
+   "metadata": {},
+   "source": [
+    "## Short Hashing"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "991bfd3c-8398-4694-b60b-12417d9b474d",
+   "metadata": {},
+   "source": [
+    "Many applications and programming language implementations were recently found to be vulnerable to denial-of-service (DoS) attacks when a hash function with weak security guarantees, such as MurmurHash3, was used to construct a hash table.\n",
+    "\n",
+    "To address this, Sodium provides the crypto_shorthash() function, which outputs short but unpredictable (without knowing the secret key) values suitable for picking a list in a hash table for a given key.\n",
+    "\n",
+    "This function is optimized for short inputs.\n",
+    "\n",
+    "The output of this function is only 64 bits. Therefore, it should not be considered collision-resistant.\n",
+    "\n",
+    "Use cases:\n",
+    "- Hash tables\n",
+    "- Probabilistic data structures, such as Bloom filters\n",
+    "- Integrity checking in interactive protocols"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "0fc90170-fcca-4417-9d02-2b8faf49eb1d",
    "metadata": {},
    "source": [
-    "### crypto_shorthash_keygen()"
+    "### `crypto_shorthash_keygen()`"
    ]
   },
   {
@@ -175,7 +206,7 @@
    "id": "e0f52ba7-8fa7-4fcb-bd43-003cd5420aa7",
    "metadata": {},
    "source": [
-    "### crypto_shorthash()"
+    "### `crypto_shorthash(message bytea, key bytea)`"
    ]
   },
   {