pamoja_security/lib.rs
1#![cfg_attr(not(test), no_std)]
2
3//! Device identity and signed telemetry for the pamoja SDK.
4//!
5//! Many of the deployments this SDK is built for - vaccine fridges, clinic
6//! telemetry, water and energy metering - need their data to be trustworthy, not
7//! just delivered. A reading that drives a health or billing decision has to be
8//! provably from the device that claims to have sent it, and provably unaltered on
9//! the way. This crate provides that foundation with ed25519 signatures:
10//!
11//! - [`DeviceIdentity`] - a device's private key, built from a provisioned 32-byte
12//! seed, that signs the payloads the device emits.
13//! - [`PublicIdentity`] - the matching public key, safe to share, that a gateway or
14//! auditor uses to verify a payload is authentic and unaltered.
15//! - [`Signature`] - the 64-byte detached signature carried alongside a payload.
16//!
17//! Signing and verifying are deterministic and need no randomness, so the crate is
18//! `no_std` and runs unchanged on a microcontroller that signs its own telemetry.
19//! It is the groundwork the security pillar builds on, ahead of transport-level
20//! TLS/DTLS and signed over-the-air updates.
21//!
22//! # Examples
23//!
24//! Sign a reading on the device, then verify it as an auditor would:
25//!
26//! ```
27//! use pamoja_security::DeviceIdentity;
28//!
29//! // A device is provisioned with a 32-byte secret seed.
30//! let device = DeviceIdentity::from_seed(&[42u8; 32]);
31//! let public = device.public();
32//!
33//! // It signs a reading; the signature travels with the data.
34//! let reading = b"fridge-1: 4.8C @ 1700";
35//! let signature = device.sign(reading);
36//!
37//! // An auditor with the device's public identity confirms it is authentic.
38//! assert!(public.verify(reading, &signature).is_ok());
39//!
40//! // A tampered reading does not verify.
41//! assert!(public.verify(b"fridge-1: 9.9C @ 1700", &signature).is_err());
42//! ```
43
44extern crate alloc;
45
46mod identity;
47mod signature;
48
49pub use identity::{DeviceIdentity, PublicIdentity};
50pub use signature::Signature;