pycryptodome 4.2.0__tar.gz → 4.4.0__tar.gz

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/.github/workflows/codeql-analysis.yml

@@ -23,7 +23,7 @@ on:
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     strategy:
       fail-fast: false

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/.github/workflows/integration.yml

@@ -7,19 +7,19 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ ubuntu-latest ]
+        os: [ ubuntu-24.04 ]
         python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "3.15t" ]
         cffi: [ yes, no ]
         include:
-          - os: ubuntu-latest
-            python-version: pypy3.9
-            cffi: yes
-          - os: ubuntu-latest
+          - os: ubuntu-24.04
             python-version: pypy3.10
             cffi: yes
-          - os: ubuntu-latest
+          - os: ubuntu-24.04
             python-version: pypy3.11
             cffi: yes
+          - os: ubuntu-24.04
+            python-version: pypy3.12
+            cffi: yes
     env:
       CFLAGS: "-Wconversion"
 
@@ -47,8 +47,8 @@ jobs:
         pip install -v .
 
     # On x86-64, the big integer code (Crypto.Math._IntegerNat) and the
-    # NIST curves (Crypto.PublicKey._nist_ecc) must use their builds for
-    # CPUs with BMI2 and ADX, so that the tests cover them
+    # NIST curves and secp256k1 (Crypto.PublicKey._nist_ecc) must use their
+    # builds for CPUs with BMI2 and ADX, so that the tests cover them
     - name: Check that the BMI2/ADX build of the big integer code is used
       if: runner.arch == 'X64'
       run: |
@@ -115,6 +115,9 @@ jobs:
         PYCRYPTODOME_REQUIRE_SHA_NI: ${{ matrix.os == 'windows-latest' && '1' || '' }}
         # Likewise for AVX2, BMI2 and ADX, when built with clang-cl
         PYCRYPTODOME_REQUIRE_AVX2_BMI2: ${{ matrix.os == 'windows-latest' && '1' || '' }}
+        # The Windows ARM64 runners support the SHA-512 instructions of ARMv8.2:
+        # fail if they are not used (module not built, or CPU feature not detected)
+        PYCRYPTODOME_REQUIRE_SHA512_ARMV8: ${{ matrix.os == 'windows-11-arm' && '1' || '' }}
       run: |
         python -m Crypto.SelfTest
 
@@ -156,7 +159,7 @@ jobs:
         python -m Crypto.SelfTest
 
   ruff:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v7
     - name: Set up Python
@@ -174,7 +177,7 @@ jobs:
         ruff format --check .
 
   mypy:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v7
     - name: Set up Python
@@ -189,7 +192,7 @@ jobs:
         mypy lib/
 
   test_c_linux:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         sse: [0, 1]
@@ -218,6 +221,24 @@ jobs:
         cmake -B build -DSSE=${{ matrix.sse }} $EXTRA
         make -C build all test
 
+  test_c_linux_arm:
+    runs-on: ubuntu-24.04-arm
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        # Valgrind: without it, the constant-time tests (*_ct) are skipped
+        sudo apt-get install libubsan1 valgrind
+    - name: Test Linux ARM64
+      env:
+        PYTHON: python3
+      run: |
+        cd src/test
+        mkdir build
+        cmake -B build
+        make -C build all test
+
   test_c_windows:
     runs-on: ${{ matrix.os }}
     strategy:

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/.github/workflows/wheels.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   build_source:
     name: Build source package
-    runs-on: [ ubuntu-latest ]
+    runs-on: [ ubuntu-24.04 ]
     steps:
       - uses: actions/checkout@v7
 
@@ -44,12 +44,12 @@ jobs:
           echo 'CIBW_ARCHS=x86_64 universal2' >> $GITHUB_ENV
         if: runner.os == 'macOS'
 
-      - uses: pypa/cibuildwheel@v4.3.1
+      - uses: pypa/cibuildwheel@v4.3.4
         name: Build wheels
         env:
           # cibuildwheel will build wheel once and test it for each CPython version
           # and for PyPy >= 3.10
-          CIBW_BUILD: "cp39-* cp314-* cp315-* cp315t-* pp310-* pp311-*"
+          CIBW_BUILD: "cp39-* cp314-* cp315-* cp315t-* pp310-* pp311-* pp312*"
           # The manylinux images are set in pyproject.toml ([tool.cibuildwheel])
           CIBW_ENABLE: "pypy pypy-eol"
 
@@ -66,6 +66,10 @@ jobs:
           PYCRYPTODOME_CLANG_CL: ${{ matrix.os == 'windows-2025' && '1' || '' }}
           PYCRYPTODOME_REQUIRE_AVX2_BMI2: ${{ matrix.os == 'windows-2025' && '1' || '' }}
 
+          # The Windows ARM64 runners support the SHA-512 instructions of ARMv8.2:
+          # fail if they are not used (module not built, or CPU feature not detected)
+          PYCRYPTODOME_REQUIRE_SHA512_ARMV8: ${{ matrix.os == 'windows-11-arm' && '1' || '' }}
+
       - name: Delete manylinux1 wheels
         if: runner.os == 'Linux'
         run: |

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/Changelog.rst

@@ -1,6 +1,92 @@
 Changelog
 =========
 
+4.4.0 (7 November 2026)
++++++++++++++++++++++++++++
+
+New features
+------------
+* Added the elliptic curve secp256k1 to ``Crypto.PublicKey.ECC``: key generation,
+  import and export, ECDSA with ``Crypto.Signature.DSS``, and ECDH with
+  ``Crypto.Protocol.DH``.
+* Added the mode ``'sec1'`` to ``Crypto.Signature.DSS.new``, for randomized ECDSA on all Weierstrass
+  curves. Mode ``'fips-186-3'`` does not accept secp256k1, which is not a curve of that standard.
+* GH#759: Added the parameter ``low_s`` to ``Crypto.Signature.DSS.new``, for ECDSA signatures
+  in the low-S form (for all curves): signing normalizes ``s``, and verifying rejects a high ``s``.
+* ECDSA signatures in DER encoding are about 5-8x faster.
+
+Resolved issues
+---------------
+* ``ECC.import_key`` raised ``TypeError`` instead of ``ValueError`` for an OpenSSH public key
+  with an unsupported curve or key type, or with a malformed body.
+* ``ECC.import_key`` accepted an OpenSSH key (public or private) whose curve did not match its key type.
+* GH#960: In HPKE, a message rejected by ``unseal()`` consumed a sequence number, so all later
+  messages of that context failed too. The sequence number now only advances when ``unseal()``
+  succeeds (RFC 9180, Section 5.2). Thanks to Zulfareen Shaikh.
+* In HPKE, a ``seal()`` that raised an exception also consumed a sequence number,
+  so the receiver could not unseal the messages that followed.
+
+4.3.0 (2 November 2026)
+++++++++++++++++++++++++++
+
+New features
+------------
+* CTR mode is 2.5-3.5x faster on large data (and GCM about 2x),
+  on all platforms.
+* On 64-bit ARM CPUs (Linux, macOS and Windows), AES and GHASH use the instructions
+  of the ARMv8 Cryptography Extensions (AES and PMULL), when available.
+  On a Graviton3, AES-ECB is about 35x faster, GCM 7x, OCB 10-12x,
+  and CTR, CBC, CFB and OFB 3-6x.
+* ``Integer.random_range()`` is about 2x faster when the bounds are public,
+  with the same output: ECDSA signatures are about 13% faster (P-256),
+  DSA signatures about 4%, and ECC key generation about 35%.
+  The RSA modulus and the DSA subgroup order are now public ``Integer`` objects.
+* Faster RSA: on x86-64, signatures and decryption are 35-40% faster
+  (RSA-2048 to RSA-4096), verification and encryption 2-2.7x.
+  Modular exponentiation with a public exponent (like the RSA public exponent)
+  no longer uses the slower constant-time algorithm, which is only needed for
+  secret exponents, and the Montgomery context of a modulus is kept with it.
+  The RSA blinding factor is squared between uses (a new one every 32 uses,
+  and after a fork).
+* The Montgomery multiplication for x86-64 CPUs with BMI2 and ADX is about 20%
+  faster: DSA signatures and verification are about 25% faster.
+* ECDSA signatures are 3-6% faster for P-256 and P-384: the field inversion
+  uses the faster power for public exponents (the exponent p - 2 is public).
+* On 64-bit ARM CPUs, SHA-224 and SHA-256 use the SHA-256 instructions
+  of the ARMv8 Cryptography Extensions, and SHA-384 and SHA-512 the SHA-512
+  instructions of ARMv8.2, when available.
+  On a Graviton3, SHA-256 is about 3.8x faster, and SHA-512 2x.
+* On 64-bit ARM CPUs, KangarooTwelve, ML-KEM and ML-DSA compute 4 Keccak states at once
+  (2 with scalar code and 2 with NEON).
+  On a Graviton3, KangarooTwelve is 1.9x faster, ML-DSA 7-20% and ML-KEM 7-8%.
+* PKCS#1 v1.5 decryption (``Crypto.Cipher.PKCS1_v1_5``) performs implicit rejection,
+  as defined in section 7.2 of ``draft-irtf-cfrg-rsa-guidance``,
+  when ``decrypt()`` is called without a ``sentinel`` (which is now optional):
+  when the padding of a ciphertext is not correct, it returns a pseudo-random
+  message, which only depends on the private key and on the ciphertext.
+  With a ``sentinel``, ``decrypt()`` behaves as before.
+
+Other changes
+-------------
+* Updated the Wycheproof test vectors (new Ed25519 tests and the new ``chacha20_counter_test.json``).
+  XChaCha20 keeps the construction of draft-irtf-cfrg-xchacha (HChaCha20 and the ChaCha20
+  of RFC 8439), with a 32-bit block counter: the key stream ends after 256 GiB,
+  whereas libsodium and Wycheproof use a 64-bit counter.
+
+Resolved issues
+---------------
+* GH#481: PKCS#1 v1.5 decryption could be used as a Bleichenbacher oracle,
+  through the ``sentinel`` returned for ciphertexts with incorrect padding.
+  Calling ``decrypt()`` without ``sentinel`` (implicit rejection) is now
+  recommended. Thanks to tomato42 and eslerm.
+* PKCS#1 v1.5 ``decrypt()`` never returned a ``sentinel`` that is not a byte string
+  (such as ``None``), and it returned an empty byte string instead.
+* GH#954: ``Crypto.Util.asn1.DerObjectId`` accepted an ASN.1 OBJECT IDENTIFIER where an arc
+  is encoded with the initial octet 0x80 (invalid, as that would violate the minimal
+  encoding rule for BER) or where the last octet encoding the last arc has bit 7 set
+  (invalid, and that arc would also be dropped). In those cases, decoding now fails.
+  Thanks to Zulfareen Shaikh.
+
 4.2.0 (24 October 2026)
 ++++++++++++++++++++++++++
 
@@ -336,6 +422,20 @@ New features
 * Salsa20 raises ``OverflowError`` instead of silently reusing the key stream,
   when the data goes beyond its end (2\ :sup:`70` bytes per nonce).
 
+3.24.2 (5 November 2026)
+++++++++++++++++++++++++++
+
+This release is only for ``pycryptodomex``.
+
+Resolved issues
+---------------
+* GH#958: on Windows with PyPy, native modules built with setuptools 84.2 or newer
+  could not be loaded because they were named ``.pyd``.
+
+Other changes
+-------------
+* Build wheels for PyPy 8.0 (Python 3.11), in addition to PyPy 7.3.
+
 3.24.1 (11 October 2026)
 ++++++++++++++++++++++++++
 

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/Doc/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = python -m sphinx
+SPHINXBUILD   = python3 -m sphinx
 PAPER         =
 BUILDDIR      = _build
 

pycryptodome-4.4.0/Doc/_static/scorer.js

@@ -0,0 +1,29 @@
+// Search scorer: the defaults of Sphinx, plus a boost for the guides,
+// so that a search for a task ("encrypt", "sign", "password", ...)
+// shows the guide before the many API methods with the same name.
+var Scorer = {
+  score: (result) => {
+    const [docname, title, anchor, descr, score, filename, kind] = result;
+    return docname.startsWith("src/guides/") ? score + 8 : score;
+  },
+
+  // query matches the full name of an object
+  objNameMatch: 11,
+  // or matches in the last dotted part of the object name
+  objPartialMatch: 6,
+  // Additive scores depending on the priority of the object
+  objPrio: {
+    0: 15, // used to be importantResults
+    1: 5, // used to be objectResults
+    2: -5, // used to be unimportantResults
+  },
+  //  Used when the priority is not in the mapping.
+  objPrioDefault: 0,
+
+  // query found in title
+  title: 15,
+  partialTitle: 7,
+  // query found in terms
+  term: 5,
+  partialTerm: 2,
+};

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/Doc/conf.py

@@ -27,6 +27,8 @@ class MockLib:
     ghash_clmul = None
     ghash_expand_clmul = None
     ghash_destroy_clmul = None
+    AESNI_start_operation = None
+    AESNI_stop_operation = None
 
     def have_aes_ni(self):
         return True
@@ -41,7 +43,13 @@ class MockLib:
     have_bmi2 = have_avx2
     have_sha_ni = have_avx2
     have_adx = have_avx2
+    have_aes_armv8 = have_avx2
+    have_pmull = have_avx2
+    have_sha256_armv8 = have_avx2
+    have_sha512_armv8 = have_avx2
+    have_sha3_armv8 = have_avx2
     ec_nat_new_curve = lambda *x: 0
+    ec_nat_new_curve_secp256k1 = lambda *x: 0
     ec_nat_free_curve = lambda *x: None
     ec_nat_new_point = lambda *x: 0
     ec_nat_free_point = lambda *x: None
@@ -117,7 +125,7 @@ release = ".".join(str(x) for x in version_tuple)
 exclude_patterns = ["_build"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
-# default_role = None
+default_role = "py:obj"
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
@@ -199,6 +207,9 @@ html_title = "PyCryptodome"
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+# Rank the guides first in the search results
+html_search_scorer = "_static/scorer.js"
 html_css_files = ["custom.css"]
 
 
@@ -320,3 +331,36 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
+
+
+def _hide_cipher_mode_signature(app, what, name, obj, options, signature, return_annotation):
+    """The cipher objects of the modes of operation are created by the
+    ``new()`` function of the cipher module, never directly by the user:
+    do not show the internal parameters of their constructor."""
+
+    if what == "class" and name.startswith("Crypto.Cipher._mode_"):
+        return "", None
+    return None
+
+
+def _lower_search_priority_of_cipher_modes():
+    """The methods of the cipher objects (like ``GcmMode.encrypt``) would
+    otherwise be the first results when searching for common words
+    like "encrypt", ahead of the guides."""
+
+    from sphinx.domains.python import PythonDomain
+
+    get_objects = PythonDomain.get_objects
+
+    def patched_get_objects(self):
+        for name, dispname, objtype, docname, anchor, prio in get_objects(self):
+            if name.startswith("Crypto.Cipher._mode_"):
+                prio = 2  # "unimportant"
+            yield name, dispname, objtype, docname, anchor, prio
+
+    PythonDomain.get_objects = patched_get_objects
+
+
+def setup(app):
+    app.connect("autodoc-process-signature", _hide_cipher_mode_signature, priority=400)
+    _lower_search_priority_of_cipher_modes()

pycryptodome-4.4.0/Doc/index.rst

@@ -0,0 +1,74 @@
+PyCryptodome
+============
+
+PyCryptodome is a self-contained Python package of low-level
+cryptographic primitives, for Python 3.9 and newer.
+It needs no system libraries: install it with ``pip install pycryptodome``.
+
+What do you want to do?
+-----------------------
+
+.. include:: src/guides/tasks.rst.inc
+
+For instance, this is how to encrypt and authenticate a message
+with AES in GCM mode, and then decrypt it
+(see :doc:`src/guides/symmetric` for the details):
+
+.. code-block:: python
+
+    from Crypto.Cipher import AES
+    from Crypto.Random import get_random_bytes
+
+    key = get_random_bytes(32)
+    nonce = get_random_bytes(12)
+    cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+    ciphertext, tag = cipher.encrypt_and_digest(b"Attack at dawn")
+
+    # The receiver needs the key, the nonce, the ciphertext and the tag
+    cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+    plaintext = cipher.decrypt_and_verify(ciphertext, tag)
+
+Where to go next
+----------------
+
+* :doc:`src/guides/index`, for the common tasks, step by step.
+* :doc:`src/api`, for all the algorithms and their parameters, grouped by package.
+* :doc:`src/installation`, for the details of the installation.
+* :doc:`src/faq`, for the most frequent questions.
+
+.. toctree::
+   :hidden:
+   :caption: Getting started
+
+   Home <self>
+   Introduction <src/introduction>
+   src/features
+   src/installation
+
+.. toctree::
+   :hidden:
+   :caption: Guides
+
+   Overview <src/guides/index>
+   src/guides/symmetric
+   src/guides/passwords
+   src/guides/public_key_encryption
+   src/guides/signatures
+   src/guides/hashing
+   src/guides/keys
+
+.. toctree::
+   :hidden:
+   :caption: Reference
+
+   src/api
+   src/exceptions
+
+.. toctree::
+   :hidden:
+   :caption: Project
+
+   src/faq
+   src/contribute_support
+   src/changelog
+   src/license

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/Doc/src/api.rst

@@ -16,6 +16,10 @@ API documentation
 All cryptographic functionalities are organized in sub-packages;
 each sub-package is dedicated to solving a specific class of problems.
 
+This is the reference for all algorithms and their parameters.
+If you are looking for how to accomplish a task, like encrypting or signing data,
+start from the :doc:`guides <guides/index>`.
+
 .. csv-table:: 
     :header: Package, Description
     :widths: 25, 75

pycryptodome-4.4.0/Doc/src/cipher/aes.rst

@@ -0,0 +1,196 @@
+AES
+===
+
+.. py:currentmodule:: Crypto.Cipher.AES
+
+AES `(Advanced Encryption Standard)`__ is a symmetric block cipher standardized
+by NIST_ . It has a fixed data block size of 16 bytes.
+Its keys can be 128, 192, or 256 bits long.
+
+AES is very fast and secure, and it is the de facto standard for symmetric
+encryption.
+
+On its own, a block cipher can only encrypt a single block of 16 bytes.
+To protect messages of any length, you combine it with a *mode of operation*,
+which you select with the ``mode`` parameter of :func:`new`.
+The table in :ref:`aes_modes` lists the modes you can choose from.
+
+.. tip::
+
+    For a step-by-step explanation of how to encrypt data with AES,
+    including large files, see the guide :doc:`../guides/symmetric`.
+
+For instance, you can encrypt and authenticate a message with AES in GCM mode::
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto.Random import get_random_bytes
+    >>>
+    >>> data = b'The secret message'
+    >>> key = get_random_bytes(16)
+    >>> nonce = get_random_bytes(12)
+    >>> cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+    >>> ciphertext, tag = cipher.encrypt_and_digest(data)
+
+You must deliver the triple ``(nonce, ciphertext, tag)`` to the recipient.
+The nonce and the tag are not secret, but the key is.
+With the same key, the recipient decrypts the message and checks that it is authentic::
+
+    >>> from Crypto.Cipher import AES
+    >>>
+    >>> cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+    >>> try:
+    ...     plaintext = cipher.decrypt_and_verify(ciphertext, tag)
+    ...     print("The message is authentic:", plaintext)
+    ... except ValueError:
+    ...     print("Key incorrect or message corrupted")
+
+.. __: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard
+.. _NIST: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
+
+.. _aes_modes:
+
+Modes of operation
+------------------
+
+The object returned by :func:`new` depends on the mode of operation:
+follow the link in the last column for its methods and attributes.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 30 25 25
+
+    * - ``mode``
+      - Mode of operation
+      - Protects
+      - Cipher object
+    * - .. py:data:: MODE_GCM
+            :no-typesetting:
+
+        ``MODE_GCM``
+      - :ref:`Galois/Counter Mode <gcm_mode>`
+      - confidentiality + authenticity
+      - :class:`~Crypto.Cipher._mode_gcm.GcmMode`
+    * - .. py:data:: MODE_EAX
+            :no-typesetting:
+
+        ``MODE_EAX``
+      - :ref:`EAX mode <eax_mode>`
+      - confidentiality + authenticity
+      - :class:`~Crypto.Cipher._mode_eax.EaxMode`
+    * - .. py:data:: MODE_OCB
+            :no-typesetting:
+
+        ``MODE_OCB``
+      - :ref:`Offset CodeBook <ocb_mode>`
+      - confidentiality + authenticity
+      - :class:`~Crypto.Cipher._mode_ocb.OcbMode`
+    * - .. py:data:: MODE_SIV
+            :no-typesetting:
+
+        ``MODE_SIV``
+      - :ref:`Synthetic Initialization Vector <siv_mode>`
+      - confidentiality + authenticity
+      - :class:`~Crypto.Cipher._mode_siv.SivMode`
+    * - .. py:data:: MODE_CCM
+            :no-typesetting:
+
+        ``MODE_CCM``
+      - :ref:`Counter with CBC-MAC <ccm_mode>`
+      - confidentiality + authenticity
+      - :class:`~Crypto.Cipher._mode_ccm.CcmMode`
+    * - .. py:data:: MODE_CTR
+            :no-typesetting:
+
+        ``MODE_CTR``
+      - :ref:`Counter mode <ctr_mode>`
+      - confidentiality only
+      - :class:`~Crypto.Cipher._mode_ctr.CtrMode`
+    * - .. py:data:: MODE_CBC
+            :no-typesetting:
+
+        ``MODE_CBC``
+      - :ref:`Cipher-Block Chaining <cbc_mode>`
+      - confidentiality only
+      - :class:`~Crypto.Cipher._mode_cbc.CbcMode`
+    * - .. py:data:: MODE_CFB
+            :no-typesetting:
+
+        ``MODE_CFB``
+      - :ref:`Cipher FeedBack <cfb_mode>`
+      - confidentiality only
+      - :class:`~Crypto.Cipher._mode_cfb.CfbMode`
+    * - .. py:data:: MODE_OFB
+            :no-typesetting:
+
+        ``MODE_OFB``
+      - :ref:`Output FeedBack <ofb_mode>`
+      - confidentiality only
+      - :class:`~Crypto.Cipher._mode_ofb.OfbMode`
+    * - .. py:data:: MODE_OPENPGP
+            :no-typesetting:
+
+        ``MODE_OPENPGP``
+      - :ref:`OpenPGP mode <openpgp_mode>`
+      - confidentiality only
+      - :class:`~Crypto.Cipher._mode_openpgp.OpenPgpMode`
+    * - .. py:data:: MODE_ECB
+            :no-typesetting:
+
+        ``MODE_ECB``
+      - :ref:`Electronic CodeBook <ecb_mode>`
+      - confidentiality only (weak)
+      - :class:`~Crypto.Cipher._mode_ecb.EcbMode`
+    * - .. py:data:: MODE_KW
+            :no-typesetting:
+
+        ``MODE_KW``
+      - :ref:`Key Wrap <kw_mode>`
+      - keys (confidentiality + authenticity)
+      - :class:`~Crypto.Cipher._mode_kw.KWMode`
+    * - .. py:data:: MODE_KWP
+            :no-typesetting:
+
+        ``MODE_KWP``
+      - :ref:`Key Wrap with Padding <kwp_mode>`
+      - keys (confidentiality + authenticity)
+      - :class:`~Crypto.Cipher._mode_kwp.KWPMode`
+
+Which mode should I use?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* If in doubt, use **GCM**, with a random 12-byte nonce.
+  It is an *authenticated* mode (AEAD):
+  the recipient detects if the message was modified or encrypted with a different key.
+  It is also the most widely supported by other libraries.
+  The other authenticated modes (EAX, OCB, CCM) are equally secure.
+* Use **SIV** if you cannot guarantee that a nonce is never reused with the same key.
+* Use the *confidentiality only* modes, like CTR or CBC, only to interoperate with existing
+  protocols, and then combine them with a MAC (like :mod:`Crypto.Hash.HMAC`).
+  Never use ECB to encrypt more than one block.
+* Use **KW** or **KWP** only to wrap other cryptographic keys.
+
+Using the cipher object
+-----------------------
+
+* :meth:`encrypt` and :meth:`decrypt` process data.
+  You can call them several times, each with the next piece of the message.
+* The authenticated modes also have :meth:`update` (for associated data, that is,
+  data that is authenticated but not encrypted, like a header),
+  :meth:`digest` and :meth:`verify` (to create and check the MAC tag),
+  and :meth:`encrypt_and_digest` and :meth:`decrypt_and_verify` (to do everything in one call).
+  See the :ref:`introduction to modern modes <modern_cipher_modes>`.
+* KW and KWP only have :meth:`seal` and :meth:`unseal`.
+* The object also holds the parameters you must deliver to the recipient,
+  such as :attr:`nonce` or :attr:`iv`, which :func:`new` generates if you don't pass them.
+
+A cipher object is *stateful* and it can only process one message,
+either for encryption or for decryption.
+Create a new object (with a new nonce or IV) for each message.
+
+API
+---
+
+.. automodule:: Crypto.Cipher.AES
+   :members:
+   :exclude-members: MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR, MODE_OPENPGP, MODE_CCM, MODE_EAX, MODE_SIV, MODE_GCM, MODE_OCB, MODE_KW, MODE_KWP
+   :member-order: bysource

{pycryptodome-4.2.0 → pycryptodome-4.4.0}/Doc/src/cipher/cipher.rst

@@ -4,14 +4,15 @@
 Introduction
 ------------
 
-.. toctree::
-    :hidden:
-
-    oaep
-
 The :mod:`Crypto.Cipher` package contains algorithms for protecting the confidentiality
 of data.
 
+.. tip::
+
+    To learn how to encrypt data, start from the guides
+    :doc:`../guides/symmetric`, :doc:`../guides/passwords`,
+    and :doc:`../guides/public_key_encryption`.
+
 There are three types of encryption algorithms:
 
 1. **Symmetric ciphers**: all parties use the same key, for both
@@ -121,6 +122,11 @@ authentication (MAC). For instance:
     salsa20
     chacha20_poly1305
 
+.. toctree::
+    :hidden:
+
+    oaep
+
 Legacy ciphers
 --------------