1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
//! Validate Secure Scuttlebutt (SSB) messages and message values, either individually or as hash chains //! (with support for parallel batch validation). //! //! ## Validation Criteria //! //! Secure Scuttlebutt "feeds" are a sequence of messages published by one author. To be valid, a //! message must satisfy a number of critera. The exact criteria depend on the context of the //! message. It's important to note that this crate does not perform signature verification. See //! the [ssb-verify-signatures](https://github.com/sunrise-choir/ssb-verify-signatures) repo for //! that functionality. //! //! If the message is the first in the feed: //! //! - the value of the `previous` field must be `null` //! - the value of the `sequence` field must be `1` //! //! If the message is not the first in the feed: //! //! - the value of the `previous` field must be the hash of the previous message //! - the value of the `sequence` field must be 1 larger than the `sequence` of the previous //! message //! //! Other criteria which all messages must satisfy (unless they are being validated out-of-order): //! //! - the value of the `hash` field must be `sha256` //! - the `author` must not change compared the the previous message //! - if the message includes a `key`, it must be the hash of the `value` of the message //! - message `value` fields must be in the order: `previous`, `author` or `sequence`, `author` or //! `sequence`, `timestamp`, `hash`, `content`, `signature` //! - the message `value` must not include extra (unexpected) fields //! - the value of the message `content` field must be encoded in canonical base64 and contain //! `.box` if it is a string (encrypted private message) //! - the length of the serialized message `value` must not exceed 8192 UTF-16 code units //! //! All of the above criteria are validated by this library (either directly or via dependencies). //! //! You can check messages one by one or batch process a collection of them (uses //! [rayon](https://docs.rs/rayon/1.2.0/rayon/index.html) internally) //! //! ## Out-of-Order (OOO) and Multi-Author Validation //! //! In addition to validating messages using all of the above criteria, it is also possible to //! validate out-of-order messages or message values by satisfying a subset of those criteria. This //! crate provides functions to perform batch validation of such out-of-order messages. //! //! Out-of-order message validation may be performed for single-author or multi-author use cases //! (separate functions exist for each case). //! //! When performing validation for out-of-order messages from a single author, the messages must be //! authored by a single keypair. However, it is not required that the sequence number of a message //! be 1 larger than the sequence number of the previous message, nor is it required that the hash //! of the previous message match the hash given for the previous message in a message. //! //! Multi-author validation, by contrast to the above, does not perform any checks of //! the `previous` message. Indeed, it may be said that this method of validation has no concept of //! a previous message (except that the `previous` field must be present in the message in the //! correct order). //! //! ## Benchmarks //! //! Benchmarking on a 2016 2 core i5 shows that batch processing is ~1.6 times faster than processing //! one at a time. //! //! Benchmarking on Android on a [One Plus 5T](https://en.wikipedia.org/wiki/OnePlus_5T) (8 core arm64) //! shows that batch processing is ~3.3 times faster. pub mod error; pub mod message; pub mod message_value; pub mod test_data; pub mod utils;