Crate ruma_signatures
source · [−]Expand description
Digital signatures according to the Matrix specification.
Digital signatures are used by Matrix homeservers to verify the authenticity of events in the Matrix system, as well as requests between homeservers for federation. Each homeserver has one or more signing key pairs (sometimes referred to as “verify keys”) which it uses to sign all events and federation requests. Matrix clients and other Matrix homeservers can ask the homeserver for its public keys and use those keys to verify the signed data.
Each signing key pair has an identifier, which consists of the name of the digital signature algorithm it uses and a “version” string, separated by a colon. The version is an arbitrary identifier used to distinguish key pairs using the same algorithm from the same homeserver.
Arbitrary JSON objects can be signed as well as JSON representations of Matrix events. In both
cases, the signatures are stored within the JSON object itself under a signatures key. Events
are also required to contain hashes of their content, which are similarly stored within the
hashed JSON object under a hashes key.
In JSON representations, both signatures and hashes appear as base64-encoded strings, using the standard character set, without padding.
Signing and hashing
To sign an arbitrary JSON object, use the sign_json function. See the documentation of this
function for more details and a full example of use.
Signing an event uses a more complicated process than signing arbitrary JSON, because events can
be redacted, and signatures need to remain valid even if data is removed from an event later.
Homeservers are required to generate hashes of event contents as well as signing events before
exchanging them with other homeservers. Although the algorithm for hashing and signing an event
is more complicated than for signing arbitrary JSON, the interface to a user of ruma-signatures
is the same. To hash and sign an event, use the hash_and_sign_event function. See the
documentation of this function for more details and a full example of use.
Verifying signatures and hashes
When a homeserver receives data from another homeserver via the federation, it’s necessary to verify the authenticity and integrity of the data by verifying their signatures.
To verify a signature on arbitrary JSON, use the verify_json function. To verify the
signatures and hashes on an event, use the verify_event function. See the documentation for
these respective functions for more details and full examples of use.
Structs
An Ed25519 key pair.
A digital signature.
Enums
The algorithm used for signing data.
The set of possible errors when serializing to canonical JSON.
Represents a canonical JSON value as per the Matrix specification.
ruma-signature’s error type, wraps a number of other error types.
All errors related to JSON validation/parsing.
Errors relating to parsing of all sorts.
Errors relating to verification of events and signatures.
A value returned when an event is successfully verified.
Traits
A cryptographic key pair for digitally signing data.
Functions
Converts an event into the canonical string form.
Creates a content hash for an event.
Hashes and signs an event and adds the hash and signature to objects under the keys hashes and
signatures, respectively.
Redacts an event using the rules specified in the Matrix client-server specification.
Redacts event content using the rules specified in the Matrix client-server specification.
Redacts an event using the rules specified in the Matrix client-server specification.
Creates a reference hash for an event.
Signs an arbitrary JSON object and adds the signature to an object under the key signatures.
Verifies that the signed event contains all the required valid signatures.
Uses a set of public keys to verify a signed JSON object.
Type Definitions
The inner type of CanonicalJsonValue::Object.
A map from entity names to sets of public keys for that entity.
A set of public keys for a single homeserver.