pamoja.security

  1"""Idiomatic device-identity facade.
  2
  3Wraps the native :class:`pamoja._native.DeviceIdentity` with a Python-native
  4surface: ``str`` or ``bytes`` payloads, properties instead of getters, and a
  5named constructor. It adds ergonomics only; the signing and verifying happen in
  6the Rust core.
  7"""
  8
  9from __future__ import annotations
 10
 11from typing import Union
 12
 13from pamoja._native import DeviceIdentity as _NativeDeviceIdentity
 14from pamoja._native import fingerprint as _native_fingerprint
 15from pamoja._native import verify as _native_verify
 16from pamoja._native import verify_message as _native_verify_message
 17
 18__all__ = ["DeviceIdentity", "Payload", "fingerprint", "verify", "verify_message"]
 19
 20#: A payload to sign or verify; ``str`` is encoded as UTF-8.
 21Payload = Union[str, bytes, bytearray, memoryview]
 22
 23
 24def _to_bytes(payload: Payload) -> bytes:
 25    """Encode a payload to bytes, so callers may pass either text or raw data.
 26
 27    :param payload: The value to encode.
 28    :returns: The payload as bytes.
 29    """
 30    if isinstance(payload, str):
 31        return payload.encode("utf-8")
 32    return bytes(payload)
 33
 34
 35class DeviceIdentity:
 36    """A device's private signing identity.
 37
 38    A reading that drives a health or billing decision has to be provably from
 39    the device that claims to have sent it, and provably unaltered on the way.
 40    Sign it here, and any holder of :attr:`public_key` can check it with
 41    :func:`verify`.
 42
 43    Example::
 44
 45        device = DeviceIdentity.from_seed(seed)
 46        signature = device.sign("21.5")
 47        verify(device.public_key, "21.5", signature)  # True
 48    """
 49
 50    __slots__ = ("_native",)
 51
 52    def __init__(self, seed: bytes) -> None:
 53        """Create an identity from a provisioned 32-byte secret seed.
 54
 55        :param seed: The device's 32-byte secret, held on the device only.
 56        :raises ValueError: If the seed is not exactly 32 bytes.
 57        """
 58        self._native = _NativeDeviceIdentity(bytes(seed))
 59
 60    @classmethod
 61    def from_seed(cls, seed: bytes) -> "DeviceIdentity":
 62        """Create an identity from a provisioned 32-byte secret seed.
 63
 64        :param seed: The device's 32-byte secret, held on the device only.
 65        :returns: The identity that seed determines.
 66        :raises ValueError: If the seed is not exactly 32 bytes.
 67        """
 68        return cls(seed)
 69
 70    @staticmethod
 71    def native(identity: "DeviceIdentity") -> _NativeDeviceIdentity:
 72        """Hand the generated identity to another capability facade.
 73
 74        The audit and update capabilities sign with an identity this class
 75        holds, and the generated bindings take the generated type. This is how
 76        the two meet without a caller ever seeing it.
 77
 78        :param identity: The identity to unwrap.
 79        :returns: The generated identity inside it.
 80        """
 81        return identity._native
 82
 83    @property
 84    def public_key(self) -> bytes:
 85        """The 32-byte public key matching this identity, safe to share."""
 86        return self._native.public_key
 87
 88    @property
 89    def fingerprint(self) -> str:
 90        """A 16-character lowercase hex label for this identity."""
 91        return self._native.fingerprint
 92
 93    def sign(self, payload: Payload) -> bytes:
 94        """Sign a payload.
 95
 96        :param payload: The bytes to cover; ``str`` is encoded as UTF-8.
 97        :returns: The 64-byte detached signature.
 98        """
 99        return self._native.sign(_to_bytes(payload))
100
101    def sign_message(self, payload: Payload) -> bytes:
102        """Sign a payload and return one message carrying both.
103
104        The message is the signature followed by the payload, which is usually what
105        goes on a link: one blob to send, rather than a payload and a detached
106        signature to keep together and split correctly at the far end.
107        :func:`verify_message` reverses it.
108
109        :param payload: The bytes to cover; ``str`` is encoded as UTF-8.
110        :returns: The signature followed by the payload.
111        """
112        return self._native.sign_message(_to_bytes(payload))
113
114    def __repr__(self) -> str:
115        return f"DeviceIdentity(fingerprint={self.fingerprint!r})"
116
117
118def verify(public_key: bytes, payload: Payload, signature: bytes) -> bool:
119    """Verify that a signature covers a payload and was made by a public key.
120
121    :param public_key: The 32-byte public key of the claimed signer.
122    :param payload: The bytes the signature should cover.
123    :param signature: The 64-byte detached signature.
124    :returns: ``True`` if the signature is authentic, and ``False`` if the
125        payload was altered or was signed by a different device.
126    :raises ValueError: If an argument is not the expected length.
127    """
128    return _native_verify(bytes(public_key), _to_bytes(payload), bytes(signature))
129
130
131def verify_message(public_key: bytes, message: bytes) -> bytes | None:
132    """Verify a signed message and return the payload it carries.
133
134    :param public_key: The 32-byte public key of the claimed signer.
135    :param message: The signature followed by the payload, as
136        :meth:`DeviceIdentity.sign_message` wrote it.
137    :returns: The payload if the message is authentic, and ``None`` if it is too
138        short to hold a signature, was altered, or was signed by a different device.
139    :raises ValueError: If the key is not the expected length.
140    """
141    return _native_verify_message(bytes(public_key), bytes(message))
142
143
144def fingerprint(public_key: bytes) -> str:
145    """Return the short hex fingerprint of a public key.
146
147    :param public_key: The 32-byte public key to label.
148    :returns: A 16-character lowercase hex label.
149    :raises ValueError: If the key is not exactly 32 bytes.
150    """
151    return _native_fingerprint(bytes(public_key))