NAME

Protocol::Matrix - Helper functions for the Matrix protocol

DESCRIPTION

This module provides some helper functions for implementing a matrix client or server. Currently it only contains a few base-level functions to assist with signing and verifying signatures on federation-level events.

FUNCTIONS

encode_json_for_signing

$json = encode_json_for_signing( $data )

Encodes a given HASH reference as Canonical JSON, having removed the signatures and unsigned keys if present. This is the first step towards signing it or verifying an embedded signature in it. The hash referred to by $data remains unmodified by this function.

encode_base64_unpadded

$base64 = encode_base64( $bytes )

Returns a character string containing the Base-64 encoding of the given bytes, with no internal linebreaks and no trailing padding.

sign_json

sign_json( $data, secret_key => $key, origin => $name, key_id => $id )

Modifies the given HASH reference in-place to add a signature. This signature is created from the given key, and annotated as being from the given origin name and key ID. Existing signatures already in the hash are not disturbed.

The $key should be a plain byte string or Data::Locker object obtained from Crypt::NaCl::Sodium::sign's keypair method.

verify_json_signature

verify_json_signature( $data, public_key => $key, origin => $name, key_id => $id )

Inspects the given HASH reference to check that it contains a signature from the named origin, with the given key ID, and that it is actually valid.

This function does not return an interesting value; all failures are indicated by thrown exceptions. If no exception is thrown, it can be presumed valid.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>