pamoja-security

ed25519 device identity: sign a reading and verify it, so a gateway can prove it is authentic. One capability of pamoja, one memory-safe Rust core with bindings for TypeScript, Python, and C#.

Install

pip install pamoja-security

from pamoja import security

This pulls in pamoja-native, the compiled engine. pip install pamoja is the whole framework in one package.

Example

The script the test suite runs, spliced here as it ran.

From bindings/python/guides/security.py:

from pamoja.security import DeviceIdentity, fingerprint, verify, verify_message

# The seed is provisioned into the device once and never leaves it. A real one comes from
# the factory or a secure element; any 32 bytes stand in here.
device = DeviceIdentity.from_seed(bytes([7]) * 32)

# Only the 32-byte public key travels to the gateway. Its fingerprint is the short form an
# operator reads off a screen to tell one device from another.
gateway_key = device.public_key
print(f"device     {fingerprint(gateway_key)}")

# Signing is deterministic, so the same reading always produces the same 64 bytes and there
# is no randomness to get wrong on a microcontroller.
reading = "meter-4 1182.750 kWh"
signature = device.sign(reading)
if verify(gateway_key, reading, signature):
    print(f"accepted   {reading}")
else:
    print("rejected   a reading the device really did sign, which should never happen")

# A digit changed in transit no longer matches what was signed.
edited = "meter-4 1082.750 kWh"
if verify(gateway_key, edited, signature):
    print("accepted   an edited reading, which should never happen")
else:
    print(f"rejected   {edited}")

# Nor does the same reading offered under another device's key.
impostor = DeviceIdentity.from_seed(bytes([90]) * 32)
if verify(impostor.public_key, reading, signature):
    print("accepted   an impostor, which should never happen")
else:
    print("rejected   a signature offered under another device's key")

# On a link the signature and the reading usually travel as one message, signature first,
# and the gateway gets the reading back only once it has checked it.
message = device.sign_message(reading)
print(f"message    {len(message)} bytes on the wire, the signature and the reading together")
carried = verify_message(gateway_key, message)
if carried is not None:
    print(f"accepted   {carried.decode()}, read out of the message")
else:
    print("rejected   a message the device really did sign, which should never happen")

# A message that lost its last byte on the way is refused whole.
if verify_message(gateway_key, message[:-1]) is not None:
    print("accepted   a message cut short, which should never happen")
else:
    print("rejected   a message that lost its last byte on the way")

The same capability in every language

Documentation

• pamoja.security reference, every class and function in this module.
• The Device identity guide, with the same example in Rust, TypeScript, and C#.
• Every capability, and the install page.

License

MIT