httk.core.crypto
================

.. py:module:: httk.core.crypto

.. autoapi-nested-parse::

   Ed25519 signing with an optional accelerated backend.

   These signing primitives are used by project identity and trust.

   All private keys accepted and returned by this module are standard 32-byte
   Ed25519 seeds. The stdlib implementation follows RFC 8032 and is kept as a
   portable fallback; ``cryptography`` is used automatically when installed.
   The fallback uses variable-time Python arithmetic: use ``cryptography`` for
   private-key operations where timing exposure matters. Both backends reject
   non-canonical encodings and small-order public keys/signature points.



Functions
---------

.. autoapisummary::

   httk.core.crypto.ed25519_backend_available
   httk.core.crypto.ed25519_generate_seed
   httk.core.crypto.ed25519_public_key
   httk.core.crypto.ed25519_sign
   httk.core.crypto.ed25519_verify


Module Contents
---------------

.. py:function:: ed25519_backend_available(backend = 'cryptography')

   Return whether *backend* can perform Ed25519 operations.

   :param backend: Backend name: ``"cryptography"``, ``"pure"``, or ``"stdlib"``.
   :return: Whether the selected backend is available.
   :raises ValueError: If ``backend`` is not a supported backend name.


.. py:function:: ed25519_generate_seed()

   Generate a standard 32-byte Ed25519 private seed.

   :return: A newly generated private seed.


.. py:function:: ed25519_public_key(seed, *, backend = None)

   Derive the public key for a private seed.

   :param seed: 32-byte Ed25519 private seed.
   :param backend: Backend name, ``"auto"``, or ``None`` to select the accelerated backend when available.
   :return: The 32-byte Ed25519 public key.
   :raises ValueError: If ``seed`` is not exactly 32 bytes or ``backend`` is unsupported.
   :raises ImportError: If the requested ``cryptography`` backend is unavailable.


.. py:function:: ed25519_sign(seed, message, *, backend = None)

   Return an RFC 8032 Ed25519 signature for ``message``.

   :param seed: 32-byte Ed25519 private seed.
   :param message: Bytes to sign.
   :param backend: Backend name, ``"auto"``, or ``None`` to select the accelerated backend when available.
   :return: The 64-byte Ed25519 signature.
   :raises ValueError: If ``seed`` is not exactly 32 bytes or ``backend`` is unsupported.
   :raises ImportError: If the requested ``cryptography`` backend is unavailable.


.. py:function:: ed25519_verify(public_key, message, signature, *, backend = None)

   Return whether ``signature`` is valid, treating malformed input as false.

   Both backends require canonical points, a scalar below the group order,
   and non-small-order public and signature points. These input checks use
   public data only; private-key arithmetic remains in the selected backend.

   :param public_key: 32-byte Ed25519 public key.
   :param message: Bytes whose signature is being checked.
   :param signature: 64-byte Ed25519 signature.
   :param backend: Backend name, ``"auto"``, or ``None`` to select the accelerated backend when available.
   :return: Whether the signature verifies for the public key and message.
   :raises ValueError: If ``backend`` is unsupported.
   :raises ImportError: If the requested ``cryptography`` backend is unavailable.