Crate ssb_validate[−][src]

Expand description

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 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 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 (8 core arm64) shows that batch processing is ~3.3 times faster.

Modules

error

Custom error type with all possible variants for this library.

message

Functions for validating messages in the form of KVT (key, value, timestamp).

message_value

Functions for validating message values (ie. just the value without key and timestamp).

test_data

Secure Scuttlebutt messages used for testing.

utils

Helper functions used during validation computations.