Fixed docs to mention the new eventsourcing.cryptography.AESCipher class. Also fixed refs to eventsourcing.persistence.Cipher.

Author: johnbywater

docs/topics/application.rst

@@ -1082,12 +1082,12 @@ of the application "on the wire" and "at rest".
 To enable application-level encryption, set the environment variable
 ``CIPHER_TOPIC`` to be the :ref:`topic <Topics>` of a cipher class.
 
-The library's :class:`~eventsourcing.cipher.AESCipher` class can
-be used to encrypt stored domain events.
+The library's older :class:`eventsourcing.cipher.AESCipher` class can
+be used to encrypt stored domain events. This class uses `Pycryptodome <https://pypi.org/project/pycryptodome/>`_.
 When using the library's :class:`~eventsourcing.cipher.AESCipher`
 class, set environment variable ``CIPHER_KEY`` to be a valid encryption
 key. You can use the static method :func:`~eventsourcing.cipher.AESCipher.create_key`
-on the :class:`~eventsourcing.cipher.AESCipher` class to generate a valid encryption key.
+on the :class:`eventsourcing.cipher.AESCipher` class to generate a valid encryption key.
 
 .. code-block:: python
 
@@ -1103,6 +1103,31 @@ on the :class:`~eventsourcing.cipher.AESCipher` class to generate a valid encryp
     os.environ["CIPHER_KEY"] = cipher_key
 
 
+Alternatively, the library's new :class:`eventsourcing.cryptography.AESCipher` class can
+be used to encrypt stored domain events. This class uses the newer "standard" Python
+`cryptography <https://pypi.org/project/cryptography/>`_ package. When using this
+:class:`~eventsourcing.cryptography.AESCipher` class, set environment variable ``CIPHER_KEY``
+to be a valid encryption key. You can use the static method :func:`~eventsourcing.cryptography.AESCipher.create_key`
+on the :class:`eventsourcing.cryptography.AESCipher` class to generate a valid encryption key.
+
+.. code-block:: python
+
+    from eventsourcing.cryptography import AESCipher
+
+    # Generate a cipher key (keep this safe).
+    cipher_key = AESCipher.create_key(num_bytes=32)
+
+    # Configure cipher topic.
+    os.environ["CIPHER_TOPIC"] = "eventsourcing.cryptography:AESCipher"
+
+    # Configure cipher key.
+    os.environ["CIPHER_KEY"] = cipher_key
+
+
+The classes :class:`eventsourcing.cipher.AESCipher` and :class:`eventsourcing.cryptography.AESCipher` are tested
+as being interoperable. You should be able to decrypt events with one that have been encrypted with the other, using
+the same cipher key.
+
 .. _Snapshotting:
 
 Snapshotting
@@ -1254,6 +1279,13 @@ Code reference
     :special-members:
     :exclude-members: __weakref__, __dict__
 
+.. automodule:: eventsourcing.cryptography
+    :show-inheritance:
+    :member-order: bysource
+    :members:
+    :special-members:
+    :exclude-members: __weakref__, __dict__
+
 .. automodule:: eventsourcing.cipher
     :show-inheritance:
     :member-order: bysource

docs/topics/installing.rst

@@ -85,7 +85,7 @@ for those unable to meet the prerequisites needed for building ``psycopg[c]``.
 This package now follows the recommendation that library's should depend only on the pure Python package, giving
 users the choice of either compiling the C optimization or using the pre-built binary or using the pure
 Python package. If you don't install either ``psycopg[c]`` or ``psycopg[binary]`` then you need to make sure
-the `libpq` is installed. The `libpq` is the client library used by psql, the PostgreSQL command line client. See
+the libpq is installed. The libpq is the client library used by psql, the PostgreSQL command line client. See
 the `Psycopg docs <https://www.psycopg.org/psycopg3/docs/basic/install.html#pure-python-installation>`_ for more
 information.
 

docs/topics/persistence.rst

@@ -596,12 +596,12 @@ Encryption
 ==========
 
 The :class:`~eventsourcing.persistence.Mapper` class has an optional constructor argument, ``cipher``,
-which accepts :class:`~eventsourcing.cipher.Cipher` objects. A cipher will encrypt and decrypt the state
+which accepts :class:`~eventsourcing.persistence.Cipher` objects. A cipher will encrypt and decrypt the state
 of stored events within an event-sourced application, inhibiting disclosure of sensitive information in
 case of unauthorised access to an application's database files and backups, or network interception.
 
-The library's :class:`~eventsourcing.cipher.AESCipher` class
-implements the abstract base class :class:`~eventsourcing.cipher.Cipher`.
+The library's :class:`eventsourcing.cipher.AESCipher` class
+implements the abstract base class :class:`~eventsourcing.persistence.Cipher`.
 It can be used to cryptographically encode and decode the state of stored
 events using the `AES cipher <https://pycryptodome.readthedocs.io/en/stable/src/cipher/aes.html>`_
 from the `PyCryptodome library <https://pycryptodome.readthedocs.io/en/stable/index.html>`_
@@ -611,7 +611,12 @@ standard for symmetric encryption. Galois/Counter Mode (GCM) is a mode of
 operation for symmetric block ciphers that is designed to provide both data
 authenticity and confidentiality, and is widely adopted for its performance.
 
-A :class:`~eventsourcing.cipher.Cipher` is constructed with an
+Alternatively, the library's :class:`eventsourcing.cryptography.AESCipher` class
+also implements the abstract base class :class:`~eventsourcing.persistence.Cipher` and
+is functionally equivalent, but uses the `Python cryptography library <https://cryptography.io>`_,
+and should work as a drop-in replacement for :class:`eventsourcing.cipher.AESCipher`.
+
+A :class:`~eventsourcing.persistence.Cipher` is constructed with an
 :class:`~eventsourcing.utils.Environment` object so that that
 encryption can be configured using environment variables.
 
@@ -650,7 +655,7 @@ than the state of a stored event that is not encrypted.
     assert len(encrypted_stored_event.state) > len(stored_event.state)
 
 If you want to use a different cipher strategy, then implement the base
-class :class:`~eventsourcing.cipher.Cipher`.
+class :class:`~eventsourcing.persistence.Cipher`.
 
 
 Compression and encryption

docs/topics/tutorial/part5.rst

@@ -362,15 +362,15 @@ we will also configure the system to compress and encrypt the domain events.
 
     import os
 
-    from eventsourcing.cipher import AESCipher
+    from eventsourcing.cryptography import AESCipher
 
     # Generate a cipher key (keep this safe).
     cipher_key = AESCipher.create_key(num_bytes=32)
 
     # Cipher key.
     os.environ['CIPHER_KEY'] = cipher_key
     # Cipher topic.
-    os.environ['CIPHER_TOPIC'] = 'eventsourcing.cipher:AESCipher'
+    os.environ['CIPHER_TOPIC'] = 'eventsourcing.cryptography:AESCipher'
     # Compressor topic.
     os.environ['COMPRESSOR_TOPIC'] = 'eventsourcing.compressor:ZlibCompressor'