Merge remote-tracking branch 'origin/9.4' into 9.4

Author: johnbywater

.readthedocs.yaml

@@ -22,13 +22,44 @@ build:
 #      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
 #      - POETRY=/home/docs/.local/bin/poetry VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make install-packages
 ##      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --extras "crypto" --with docs
-  commands:
+
+#  commands:
+#      - POETRY=/home/docs/.local/bin/poetry make install-poetry
+#      - POETRY=/home/docs/.local/bin/poetry make install
+#      - POETRY=/home/docs/.local/bin/poetry make docs
+#      - ls -l ./docs/_build/html/*
+#      - mkdir --parents $READTHEDOCS_OUTPUT/html/
+#      - cp --recursive ./docs/_build/html/* $READTHEDOCS_OUTPUT/html/
+
+  jobs:
+    install:
       - POETRY=/home/docs/.local/bin/poetry make install-poetry
       - POETRY=/home/docs/.local/bin/poetry make install
-      - POETRY=/home/docs/.local/bin/poetry make docs
-      - ls -l ./docs/_build/html/*
-      - mkdir --parents $READTHEDOCS_OUTPUT/html/
-      - cp --recursive ./docs/_build/html/* $READTHEDOCS_OUTPUT/html/
+    build:
+      html:
+        - echo "Override default build command for html format"
+        - POETRY=/home/docs/.local/bin/poetry make docs
+        - ls -l ./docs/_build/html/*
+        - mkdir --parents $READTHEDOCS_OUTPUT/html/
+        - cp --recursive ./docs/_build/html/* $READTHEDOCS_OUTPUT/html/
+      epub:
+        - echo "Override default build command for epub format"
+        - POETRY=/home/docs/.local/bin/poetry make docs-epub
+        - ls -l ./docs/_build/epub/*
+        - mkdir -p $READTHEDOCS_OUTPUT/epub/
+        - cp ./docs/_build/epub/eventsourcing.epub $READTHEDOCS_OUTPUT/epub/
+      pdf:
+        - echo "Override default build command for pdf format"
+        - POETRY=/home/docs/.local/bin/poetry make docs-pdf
+        - ls -l ./docs/_build/latex/*
+        - mkdir -p $READTHEDOCS_OUTPUT/pdf/
+        - cp ./docs/_build/latex/eventsourcing.pdf $READTHEDOCS_OUTPUT/pdf/
+#      htmlzip:
+#        - echo "Override default build command for htmlzip format"
+#        - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/
+
+
+
 #  jobs:
 #    pre_create_environment:
 #      # Select Python version (keep in sync with other versions):
@@ -56,9 +87,9 @@ sphinx:
   # fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
+formats:
+    - pdf
+    - epub
 
 # Optional but recommended, declare the Python requirements required
 # to build your documentation

Makefile

@@ -15,15 +15,16 @@ install-poetry:
 
 .PHONY: install
 install:
-	$(POETRY) install --sync --extras "crypto" --with "docs" -vv $(opts)
+	$(POETRY) install --sync --extras "crypto cryptography" --with "docs" -vv $(opts)
 
 .PHONY: install-packages
 install-packages:
-	$(POETRY) install --sync --no-root --extras "crypto" --with "docs" -vv $(opts)
+	$(POETRY) install --sync --no-root --extras "crypto cryptography" --with "docs" -vv $(opts)
 
 .PHONY: update-lockfile
 update-lockfile:
-	$(POETRY) lock --no-update
+	$(POETRY) lock
+# 	$(POETRY) lock --no-update
 
 .PHONY: update-packages
 update-packages: update-lockfile install-packages
@@ -173,6 +174,14 @@ docker-logs:
 docs:
 	cd docs && make html
 
+.PHONY: docs-epub
+docs-epub:
+	cd docs && make epub
+
+.PHONY: docs-pdf
+docs-pdf:
+	cd docs && make latexpdf
+
 #
 # .PHONY: brew-services-start
 # brew-services-start:

README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg?branch=main)](https://github.com/pyeventsourcing/eventsourcing/tree/main)
+[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg)](https://github.com/pyeventsourcing/eventsourcing)
 [![Coverage Status](https://coveralls.io/repos/github/pyeventsourcing/eventsourcing/badge.svg?branch=main)](https://coveralls.io/github/pyeventsourcing/eventsourcing?branch=main)
 [![Documentation Status](https://readthedocs.org/projects/eventsourcing/badge/?version=stable)](https://eventsourcing.readthedocs.io/en/stable/)
 [![Latest Release](https://badge.fury.io/py/eventsourcing.svg)](https://pypi.org/project/eventsourcing/)

dev/MACOS_SETUP_NOTES.md

@@ -30,3 +30,7 @@ postgres=> ALTER DATABASE eventsourcing OWNER TO eventsourcing;
 - use psql with the eventsourcing user to create schema in eventsourcing database
 $ psql -U eventsourcing
 eventsourcing=> CREATE SCHEMA myschema AUTHORIZATION eventsourcing;
+
+
+To build PDF docs (make docs-pdf), download and install MacTeX from https://www.tug.org/mactex/mactex-download.html
+and then make sure latexmk is on your PATH (export PATH="$PATH:/Library/TeX/texbin").

eventsourcing/cipher.py

@@ -16,7 +16,8 @@
 
 class AESCipher(Cipher):
     """
-    Cipher strategy that uses AES cipher in GCM mode.
+    Cipher strategy that uses AES cipher (in GCM mode)
+    from the Python pycryptodome package.
     """
 
     CIPHER_KEY = "CIPHER_KEY"
@@ -71,6 +72,7 @@ def encrypt(self, plaintext: bytes) -> bytes:
 
         # Return ciphertext.
         return nonce + tag + encrypted
+        # return nonce + tag + encrypted
 
     def construct_cipher(self, nonce: bytes) -> GcmMode:
         cipher = AES.new(

eventsourcing/cryptography.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+from base64 import b64decode, b64encode
+from typing import TYPE_CHECKING
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from eventsourcing.persistence import Cipher
+
+if TYPE_CHECKING:
+    from eventsourcing.utils import Environment
+
+
+class AESCipher(Cipher):
+    """
+    Cipher strategy that uses AES cipher (in GCM mode)
+    from the Python cryptography package.
+    """
+
+    CIPHER_KEY = "CIPHER_KEY"
+    KEY_SIZES = (16, 24, 32)
+
+    @staticmethod
+    def create_key(num_bytes: int) -> str:
+        """
+        Creates AES cipher key, with length num_bytes.
+
+        :param num_bytes: An int value, either 16, 24, or 32.
+
+        """
+        AESCipher.check_key_size(num_bytes)
+        key = AESGCM.generate_key(num_bytes * 8)
+        return b64encode(key).decode("utf8")
+
+    @staticmethod
+    def check_key_size(num_bytes: int) -> None:
+        if num_bytes not in AESCipher.KEY_SIZES:
+            msg = f"Invalid key size: {num_bytes} not in {AESCipher.KEY_SIZES}"
+            raise ValueError(msg)
+
+    @staticmethod
+    def random_bytes(num_bytes: int) -> bytes:
+        return os.urandom(num_bytes)
+
+    def __init__(self, environment: Environment):
+        """
+        Initialises AES cipher with ``cipher_key``.
+
+        :param str cipher_key: 16, 24, or 32 bytes encoded as base64
+        """
+        cipher_key = environment.get(self.CIPHER_KEY)
+        if not cipher_key:
+            msg = f"'{self.CIPHER_KEY}' not in env"
+            raise OSError(msg)
+        key = b64decode(cipher_key.encode("utf8"))
+        AESCipher.check_key_size(len(key))
+        self.key = key
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        """Return ciphertext for given plaintext."""
+
+        # Construct AES-GCM cipher, with 96-bit nonce.
+        aesgcm = AESGCM(self.key)
+        nonce = AESCipher.random_bytes(12)
+        res = aesgcm.encrypt(nonce, plaintext, None)
+        # Put tag at the front for compatibility with eventsourcing.crypto.AESCipher.
+        tag = res[-16:]
+        encrypted = res[:-16]
+        return nonce + tag + encrypted
+
+    def decrypt(self, ciphertext: bytes) -> bytes:
+        """Return plaintext for given ciphertext."""
+
+        # Split out the nonce, tag, and encrypted data.
+        nonce = ciphertext[:12]
+        if len(nonce) != 12:
+            msg = "Damaged cipher text: invalid nonce length"
+            raise ValueError(msg)
+
+        # Expect tag at the front.
+        tag = ciphertext[12:28]
+        if len(tag) != 16:
+            msg = "Damaged cipher text: invalid tag length"
+            raise ValueError(msg)
+        encrypted = ciphertext[28:]
+
+        aesgcm = AESGCM(self.key)
+        try:
+            plaintext = aesgcm.decrypt(nonce, encrypted + tag, None)
+        except InvalidTag as e:
+            msg = "Invalid cipher tag"
+            raise ValueError(msg) from e
+        # Decrypt and verify.
+        return plaintext