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>

