tsp_sdk/
lib.rs

1#![deny(rustdoc::broken_intra_doc_links)]
2
3//! # Trust Spanning Protocol
4//!
5//! The Trust Spanning Protocol (TSP) is a protocol for secure communication
6//! between entities identified by their Verified Identities (VIDs).
7//!
8//! The primary API this crates exposes is the [AsyncSecureStore] struct, which
9//! is used to manage and resolve VIDs, as well as send and receive messages
10//! between them.
11//!
12//! ## Core protocol
13//!
14//! By default this library comes with methods to send and receive messages
15//! over various transport and code to resolve and verify various VIDs.
16//!
17//! If your use-case only requires the core protocol, you can disable the
18//! `async` feature to remove the transport layer and resolve methods.
19//!
20//! The [AsyncSecureStore] uses the tokio async runtime and offers a high level API.
21//!
22//! The [SecureStore] struct implements managing VIDs and sealing / opening
23//! TSP messages (low level API), it does not require an async runtime.
24//! ## Example
25//!
26//! The following example demonstrates how to send a message from Alice to Bob
27//!
28//! ```rust
29//! use futures::StreamExt;
30//! use tsp_sdk::{AsyncSecureStore, Error, OwnedVid, ReceivedTspMessage};
31//!
32//! #[tokio::main]
33//! async fn main() -> Result<(), Error> {
34//!     // bob wallet
35//!     let mut bob_db = AsyncSecureStore::new();
36//!     let bob_vid = OwnedVid::from_file("../examples/test/bob/piv.json").await?;
37//!     bob_db.add_private_vid(bob_vid)?;
38//!     bob_db.verify_vid("did:web:raw.githubusercontent.com:openwallet-foundation-labs:tsp:main:examples:test:alice", Some("alice".into())).await?;
39//!
40//!     let mut bobs_messages = bob_db.receive("did:web:raw.githubusercontent.com:openwallet-foundation-labs:tsp:main:examples:test:bob").await?;
41//!
42//!     // alice wallet
43//!     let mut alice_db = AsyncSecureStore::new();
44//!     let alice_vid = OwnedVid::from_file("../examples/test/alice/piv.json").await?;
45//!     alice_db.add_private_vid(alice_vid)?;
46//!     alice_db.verify_vid("did:web:raw.githubusercontent.com:openwallet-foundation-labs:tsp:main:examples:test:bob", Some("bob".into())).await?;
47//!
48//!     // send a message
49//!     alice_db.send(
50//!         "did:web:raw.githubusercontent.com:openwallet-foundation-labs:tsp:main:examples:test:alice",
51//!         "did:web:raw.githubusercontent.com:openwallet-foundation-labs:tsp:main:examples:test:bob",
52//!         Some(b"extra non-confidential data"),
53//!         b"hello world",
54//!     ).await?;
55//!
56//!    // first, receive a Relationship request as this is the first contact
57//!     let Some(Ok(ReceivedTspMessage::RequestRelationship { .. }))=
58//!         bobs_messages.next().await else {
59//!         panic!("bob did not receive a relationship request message")
60//!     };
61//!
62//!     // receive a generic message
63//!     let Some(Ok(ReceivedTspMessage::GenericMessage { message, .. }))=
64//!         bobs_messages.next().await else {
65//!         panic!("bob did not receive a generic message")
66//!     };
67//!
68//!     assert_eq!(message.iter().as_slice(), b"hello world");
69//!
70//!     Ok(())
71//! }
72//! ```
73
74/// Provides minimalist CESR encoding/decoding support that is sufficient for
75/// generating and parsing TSP messages; to keep complexity to a minimum,
76/// we explicitly do not provide a full CESR decoder/encoder.
77pub mod cesr;
78
79/// Contains the cryptographic core of the TSP protocol
80///   - generating non-confidential messages signed using Ed25519
81///   - generating confidential messages encrypted using
82///     [HPKE-Auth](https://datatracker.ietf.org/doc/rfc9180/);
83///     using DHKEM(X25519, HKDF-SHA256) as asymmetric primitives and
84///     ChaCha20/Poly1305 as underlying AEAD encrypting scheme,
85///     and signed using Ed25519 to achieve **non-repudiation**
86///     (more precisely "strong receiver-unforgeability under chosen
87pub mod crypto;
88
89/// Defines several common data structures, traits and error types that are used throughout the project.
90pub mod definitions;
91mod error;
92mod store;
93
94/// Contains code for handling *verified identifiers* and identities.
95/// Currently only an extended form of `did:web` and `did:peer` are supported.
96pub mod vid;
97
98/// Code (built using [tokio](https://tokio.rs/) foundations) for actually
99/// sending and receiving data over a transport layer.
100#[cfg(feature = "async")]
101pub mod transport;
102
103#[cfg(feature = "async")]
104mod async_store;
105
106#[cfg(feature = "async")]
107mod secure_storage;
108
109#[cfg(not(feature = "pq"))]
110#[cfg(feature = "async")]
111#[cfg(test)]
112mod test;
113
114#[cfg(feature = "async")]
115pub use async_store::AsyncSecureStore;
116
117#[cfg(feature = "async")]
118pub use secure_storage::AskarSecureStorage;
119#[cfg(feature = "async")]
120pub use secure_storage::SecureStorage;
121
122pub use definitions::{Payload, PrivateVid, ReceivedTspMessage, RelationshipStatus, VerifiedVid};
123pub use error::Error;
124pub use store::{Aliases, SecureStore};
125pub use vid::{ExportVid, OwnedVid, Vid};
tsp_sdk/lib.rs

tsp_sdk/
lib.rs
