first cut mkdocs build with doctests.

Author: michelp

.dockerignore

@@ -6,3 +6,4 @@ psql.sh
 .cache
 test/
 example/
+.virt

.github/workflows/jekyll-gh-pages.yml

@@ -13,54 +13,54 @@ jobs:
       - name: Run tests
         run: |
           ./test.sh
-  test_windows:
-    name: Windows build and tests
-    runs-on: windows-latest
-    steps:
-      - name: Checkout source code
-        uses: actions/checkout@v2
+  # test_windows:
+  #   name: Windows build and tests
+  #   runs-on: windows-latest
+  #   steps:
+  #     - name: Checkout source code
+  #       uses: actions/checkout@v2
 
-      - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v1
+  #     - name: Add msbuild to PATH
+  #       uses: microsoft/setup-msbuild@v1
 
-      - name: Install dependencies
-        run: |
-          Invoke-WebRequest -URI https://download.libsodium.org/libsodium/releases/libsodium-1.0.18-stable-msvc.zip -OutFile libsodium-1.0.18-stable-msvc.zip
-          tar -xf libsodium-1.0.18-stable-msvc.zip
-          rm libsodium-1.0.18-stable-msvc.zip
-          cp .\libsodium\x64\Release\v143\dynamic\libsodium.dll $env:PGROOT\lib
-          Invoke-WebRequest -URI https://github.com/theory/pgtap/archive/refs/tags/v1.2.0.zip -OutFile pgtap.zip
-          tar -xf pgtap.zip
-          rm pgtap.zip
-          cd pgtap-1.2.0
-          cp .\sql\pgtap.sql.in .\sql\pgtap.sql
-          perl.exe '-pi.bak' -e "s/TAPSCHEMA/tap/g" .\sql\pgtap.sql
-          perl.exe '-pi.bak' -e "s/__OS__/win32/g" .\sql\pgtap.sql
-          perl.exe '-pi.bak' -e "s/__VERSION__/0.24/g" .\sql\pgtap.sql
-          perl.exe '-pi.bak' -e "s/^-- ## //g" .\sql\pgtap.sql
-          cp .\sql\pgtap.sql $env:PGROOT\share\extension
-          cp .\pgtap.control $env:PGROOT\share\extension
-          cp .\contrib\pgtap.spec $env:PGROOT\share\contrib
-          ren $env:PGROOT\share\extension\pgtap.sql $env:PGROOT\share\extension\pgtap--1.2.0.sql
-        shell: pwsh
+  #     - name: Install dependencies
+  #       run: |
+  #         Invoke-WebRequest -URI https://download.libsodium.org/libsodium/releases/libsodium-1.0.18-stable-msvc.zip -OutFile libsodium-1.0.18-stable-msvc.zip
+  #         tar -xf libsodium-1.0.18-stable-msvc.zip
+  #         rm libsodium-1.0.18-stable-msvc.zip
+  #         cp .\libsodium\x64\Release\v143\dynamic\libsodium.dll $env:PGROOT\lib
+  #         Invoke-WebRequest -URI https://github.com/theory/pgtap/archive/refs/tags/v1.2.0.zip -OutFile pgtap.zip
+  #         tar -xf pgtap.zip
+  #         rm pgtap.zip
+  #         cd pgtap-1.2.0
+  #         cp .\sql\pgtap.sql.in .\sql\pgtap.sql
+  #         perl.exe '-pi.bak' -e "s/TAPSCHEMA/tap/g" .\sql\pgtap.sql
+  #         perl.exe '-pi.bak' -e "s/__OS__/win32/g" .\sql\pgtap.sql
+  #         perl.exe '-pi.bak' -e "s/__VERSION__/0.24/g" .\sql\pgtap.sql
+  #         perl.exe '-pi.bak' -e "s/^-- ## //g" .\sql\pgtap.sql
+  #         cp .\sql\pgtap.sql $env:PGROOT\share\extension
+  #         cp .\pgtap.control $env:PGROOT\share\extension
+  #         cp .\contrib\pgtap.spec $env:PGROOT\share\contrib
+  #         ren $env:PGROOT\share\extension\pgtap.sql $env:PGROOT\share\extension\pgtap--1.2.0.sql
+  #       shell: pwsh
 
-      - name: Run msbuild
-        working-directory: ./build
-        run: |
-          msbuild pgsodium.vcxproj /p:libsodiumLocation=..\libsodium /p:PostgreSQLLocation=%PGROOT% /p:Configuration=Release /p:Platform=x64 /p:platformToolset=v143
+  #     - name: Run msbuild
+  #       working-directory: ./build
+  #       run: |
+  #         msbuild pgsodium.vcxproj /p:libsodiumLocation=..\libsodium /p:PostgreSQLLocation=%PGROOT% /p:Configuration=Release /p:Platform=x64 /p:platformToolset=v143
 
-      - name: Install pgsodium, update config, and restart
-        run: |
-          cp .\build\x64\Release\pgsodium.dll $env:PGROOT\lib
-          cp pgsodium.control $env:PGROOT\share\extension
-          cp .\sql\* $env:PGROOT\share\extension
-          cp .\getkey_scripts\pgsodium_getkey.bat $env:PGDATA\
-          ((Get-Content -Path $env:PGDATA\postgresql.conf) -Replace "#shared_preload_libraries = ''","shared_preload_libraries = 'pgsodium'") | Set-Content -Path $env:PGDATA\postgresql.conf
-          Add-Content -Path  $env:PGDATA\postgresql.conf -Value ("pgsodium.getkey_script = '$env:PGDATA\pgsodium_getkey.bat'" -Replace "\\","/")
-          & $env:PGBIN\pg_ctl restart -D $env:PGDATA
-        shell: pwsh
+  #     - name: Install pgsodium, update config, and restart
+  #       run: |
+  #         cp .\build\x64\Release\pgsodium.dll $env:PGROOT\lib
+  #         cp pgsodium.control $env:PGROOT\share\extension
+  #         cp .\sql\* $env:PGROOT\share\extension
+  #         cp .\getkey_scripts\pgsodium_getkey.bat $env:PGDATA\
+  #         ((Get-Content -Path $env:PGDATA\postgresql.conf) -Replace "#shared_preload_libraries = ''","shared_preload_libraries = 'pgsodium'") | Set-Content -Path $env:PGDATA\postgresql.conf
+  #         Add-Content -Path  $env:PGDATA\postgresql.conf -Value ("pgsodium.getkey_script = '$env:PGDATA\pgsodium_getkey.bat'" -Replace "\\","/")
+  #         & $env:PGBIN\pg_ctl restart -D $env:PGDATA
+  #       shell: pwsh
 
-      - name: Run pgsodium tests
-        run: |
-          & $env:PGBIN\psql -q -U postgres -f .\test\test.sql
-        shell: pwsh
+  #     - name: Run pgsodium tests
+  #       run: |
+  #         & $env:PGBIN\psql -q -U postgres -f .\test\test.sql
+  #       shell: pwsh

.github/workflows/pages.yml

@@ -5,7 +5,8 @@ ARG DEBIAN_FRONTEND=noninteractive
 # install base dependences
 RUN apt-get update && \
     apt-get install -y make cmake git curl build-essential m4 sudo gdbserver \
-    gdb libreadline-dev bison flex zlib1g-dev tmux zile zip vim gawk wget libicu-dev pkg-config
+    gdb libreadline-dev bison flex zlib1g-dev tmux zile zip vim gawk wget libicu-dev pkg-config \
+    python3 python3-pip python3-venv
 
 # add postgres user and make data dir
 RUN groupadd -r postgres && useradd --no-log-init -r -m -s /bin/bash -g postgres -G sudo postgres

.github/workflows/test.yml

@@ -0,0 +1 @@
+# AEAD

Dockerfile

@@ -0,0 +1,87 @@
+# Public Key Cryptography
+
+
+The `box` API uses public key encryption
+to securely send messages between two parties who only know each
+others public keys.  Each party has a secret key that is used to
+encrypt messages.
+
+[Libsodium Documentation](https://doc.libsodium.org/public-key_cryptography/authenticated_encryption)
+
+`crypto_box_new_keypair()` returns a new, randomly generated, pair of
+keys for public key encryption.  The public key can be shared with
+anyone.  The secret key must never be shared.
+
+`crypto_box_noncegen()` generates a random nonce which will be used
+when encrypting messages.  For security, each nonce must be used only
+once, though it is not a secret.  The purpose of the nonce is to add
+randomness to the message so that the same message encrypted multiple
+times with the same key will produce different ciphertexts.
+
+`crypto_box()` encrypts a message using a nonce, the intended
+recipient's public key and the sender's secret key.  The resulting
+ciphertext can only be decrypted by the intended recipient using their
+secret key.  The nonce must be sent along with the ciphertext.
+
+`crypto_box_open()` descrypts a ciphertext encrypted using
+`crypto_box()`.  It takes the ciphertext, nonce, the sender's public
+key and the recipient's secret key as parameters, and returns the
+original message.  Note that the recipient should ensure that the
+public key belongs to the sender.
+
+
+Public key encryption requires each party have a pair of keys, one
+public and one private, and a nonce.  The nonce doesn't have to be
+confidential, but it should never ever be reused with the same
+key. The easiest way to generate a nonce is to use
+`crypto_box_noncegen`:
+``` postgres-console
+select crypto_box_new_seed() seed \gset
+SELECT pgsodium.crypto_box_noncegen() nonce \gset
+```
+Now create a new keypair for both bob and alice.
+``` postgres-console
+SELECT public, secret FROM crypto_box_new_keypair() \gset bob_
+SELECT public, secret FROM crypto_box_seed_new_keypair(:'seed') \gset alice_
+SELECT pgsodium.crypto_box('hello bob', :'nonce', :'bob_public', :'alice_secret') atob \gset
+SELECT :'atob';
+┌──────────────────────────────────────────────────────┐
+│                       ?column?                       │
+├──────────────────────────────────────────────────────┤
+│ \x7fdd158c74cc98a57abcc69eaf2c83e48e3e46150a018b2e4e │
+└──────────────────────────────────────────────────────┘
+(1 row)
+
+select pgsodium.crypto_box_open(:'atob', :'nonce', :'alice_public', :'bob_secret');
+┌──────────────────────┐
+│   crypto_box_open    │
+├──────────────────────┤
+│ \x68656c6c6f20626f62 │
+└──────────────────────┘
+(1 row)
+
+```
+Sealed boxes are designed to anonymously send messages to a recipient
+given its public key.
+
+Only the recipient can decrypt these messages, using its private
+key. While the recipient can verify the integrity of the message, it
+cannot verify the identity of the sender.
+
+A message is encrypted using an ephemeral key pair, whose secret part
+is destroyed right after the encryption process.
+
+Without knowing the secret key used for a given message, the sender
+cannot decrypt its own message later. And without additional data, a
+message cannot be correlated with the identity of its sender.
+``` postgres-console
+SELECT pgsodium.crypto_box_seal('bob is your uncle', :'bob_public') sealed \gset
+SELECT pgsodium.crypto_box_seal_open(:'sealed', :'bob_public', :'bob_secret');
+┌──────────────────────────────────────┐
+│         crypto_box_seal_open         │
+├──────────────────────────────────────┤
+│ \x626f6220697320796f757220756e636c65 │
+└──────────────────────────────────────┘
+(1 row)
+
+```

docs/aead.md

@@ -0,0 +1,29 @@
+# Key Derivation
+
+Multiple secret subkeys can be derived from a single master key.
+
+Given the master key and a key identifier, a subkey can be
+deterministically computed. However, given a subkey, an attacker
+cannot compute the master key nor any other subkeys.
+
+The crypto_kdf API can derive up to 2^64 keys from a single master key
+and context, and individual subkeys can have an arbitrary length
+between 128 (16 bytes) and 512 bits (64 bytes).
+``` postgres-console
+select pgsodium.derive_key(42);
+┌────────────────────────────────────────────────────────────────────┐
+│                             derive_key                             │
+├────────────────────────────────────────────────────────────────────┤
+│ \xedb9dad4a157825d64966a45baab5050d8a443084dc2c0b738016eda4a3fabea │
+└────────────────────────────────────────────────────────────────────┘
+(1 row)
+
+select pgsodium.derive_key(42, 64, 'foozbarz');
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│                                                             derive_key                                                             │
+├────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+│ \xba70d8f39bb7803a1b89e14d949f545ea1a0cc03357368f38c57cfe61b61ecfddfe15957bffb9ded0c85cf0b0a0714f69413cb297c59cb4e4e9d0a55e9032aa0 │
+└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+(1 row)
+
+```