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.
decode_base64
$bytes = decode_base64( $base64 )Returns a byte string containing the bytes obtained by decoding the given character string. This is re-exported from MIME::Base64 for convenience.
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.
signed_json
my $data = signed_json( $data, ... )Returns a new HASH reference by cloning the original and applying "sign_json" to it. The originally-passed data is unmodified. Takes the same arguments as "sign_json".
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.
redact_event
redact_event( $event )Modifies the given HASH reference in-place to apply the transformation given by the Matrix Event Redaction specification.
sign_event_json
sign_event_json( $data, secret_key => $key, origin => $name, key_id => $id )Modifies the given HASH reference in-place to add a hash and signature, presuming it to be a Matrix event structure. This operates in a fashion analogous to "sign_json".
signed_event_json
my $event = signed_event_json( $event, ... )Returns a new HASH reference by cloning the original and applying "sign_event_json" to it. The originally-passed data is unmodified. Takes the same arguments as "sign_event_json".
verify_event_json_signature
verify_event_json_signature( $event, public_key => $key, origin => $name, key_id => $id )AUTHOR
Paul Evans <leonerd@leonerd.org.uk>