Crate signatures

Available on crate feature signatures only.

Digital signatures according to the Matrix specification.

Digital signatures are used in several places in the Matrix specification, here are a few examples:

• Homeservers sign events to ensure their authenticity
• Homeservers sign requests to other homeservers to prove their identity
• Identity servers sign third-party invites to ensure their authenticity
• Clients sign user keys to mark other users as verified

Each signing key pair has an identifier, which consists of the name of the digital signature algorithm it uses and an opaque string called the “key name”, separated by a colon. The key name is used to distinguish key pairs using the same algorithm from the same entity. How it is generated depends on the entity that uses it. For example, homeservers use an arbitrary string called a “version” for their public keys, while cross-signing keys use the public key encoded as unpadded base64.

This library focuses on JSON objects signing. 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, usually 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

Ed25519KeyPair

An Ed25519 key pair.

Signature

A digital signature.

Enums

Error

ruma-signature’s error type, wraps a number of other error types.

IdParseError

An error encountered when trying to parse an invalid ID string.

JsonError

All errors related to JSON validation/parsing.

ParseError

Errors relating to parsing of all sorts.

SigningKeyAlgorithm

The signing key algorithms defined in the Matrix spec.

VerificationError

Errors relating to verification of signatures.

Verified

A value returned when an event is successfully verified.

Traits

KeyPair

A cryptographic key pair for digitally signing data.

Functions

canonical_json

Converts an event into the canonical string form.

content_hash

Creates a content hash for an event.

hash_and_sign_event

Hashes and signs an event and adds the hash and signature to objects under the keys hashes and signatures, respectively.

reference_hash

Creates a reference hash for an event.

sign_json

Signs an arbitrary JSON object and adds the signature to an object under the key signatures.

verify_canonical_json_bytes

Check a signed JSON object using the given public key and signature, all provided as bytes.

verify_event

Verifies that the signed event contains all the required valid signatures.

verify_json

Uses a set of public keys to verify a signed JSON object.

Type Aliases

PublicKeyMap

A map from entity names to sets of public keys for that entity.

PublicKeySet

A set of public keys for a single homeserver.