Struct XMatrix 

#[non_exhaustive]
pub struct XMatrix {
    pub origin: OwnedServerName,
    pub destination: Option<OwnedServerName>,
    pub key: OwnedServerSigningKeyId,
    pub sig: Base64,
}

Available on crate features client or server only.

Typed representation of an X-Matrix authentication scheme, as defined in the Matrix Server-Server API.

This is a scheme used in an Authorization HTTP header, as defined in RFC 7235.

It can be extracted from an incoming HTTP request using XMatrix::parse() or XMatrix::extract_from_http_headers(). The HTTP request should then be verified with XMatrix::verify_http_request().

It can also be generated by signing an outgoing request with XMatrix::sign_http_request().

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

origin: OwnedServerName

The server name of the sending server.

destination: Option<OwnedServerName>

The server name of the receiving sender.

For compatibility with older servers, recipients should accept requests without this parameter, but MUST always send it. If this property is included, but the value does not match the receiving server’s name, the receiving server must deny the request with a 401 Unauthorized HTTP status code.

key: OwnedServerSigningKeyId

The ID - including the algorithm name - of the sending server’s key that was used to sign the request.

sig: Base64

The signature of the canonical JSON request object.

Implementations

impl XMatrix

pub const AUTH_SCHEME: &'static str = "X-Matrix"

The auth-scheme token used to identify the X-Matrix authentication scheme in the Authorization HTTP header.

pub fn new( origin: OwnedServerName, destination: OwnedServerName, key: OwnedServerSigningKeyId, sig: Base64, ) -> Self

Construct a new X-Matrix authentication scheme from its parts.

pub fn parse(s: impl AsRef<str>) -> Result<Self, XMatrixParseError>

Parse an X-Matrix authentication scheme from the given string.

The string should be the value of an Authorization HTTP header.

Errors

Returns an error if the scheme could not be parsed.

pub fn extract_from_http_headers( headers: &HeaderMap, ) -> Result<Self, XMatrixExtractError>

Try to extract an X-Matrix authentication scheme from the given HTTP headers.

Errors

Returns an error if the Authorization header is not found in the map, or if the scheme could not be parsed.

pub fn request_object<T: AsRef<[u8]>>( request: &Request<T>, origin: &ServerName, destination: &ServerName, ) -> Result<CanonicalJsonObject, Error>

Construct the canonical JSON object representation to sign to generate or verify the X-Matrix authentication scheme for the given request, with the given origin and destination.

Errors

Returns an error if the body of the request could not be serialized to canonical JSON.

pub fn sign_http_request<T: AsRef<[u8]>>( request: &Request<T>, input: XMatrixSigningInput<'_>, ) -> Result<Self, XMatrixFromRequestError>

Try to generate an X-Matrix authentication scheme by signing the given HTTP request with the given signing input.

The returned scheme should be added as the value of the Authorization header of the request.

Errors

Returns an error if the body of the request could not be serialized to canonical JSON or if the ID of the signing key pair is invalid.

pub fn verify_http_request<T: AsRef<[u8]>>( &self, request: &Request<T>, destination: &ServerName, public_key_map: &PublicKeyMap, ) -> Result<(), XMatrixVerificationError>

Verify that the signature in the sig field of this X-Matrix authentication scheme is valid for the given incoming HTTP request and destination, with the given public keys map from the origin.

Errors

Returns an error if the given destination doesn’t match the one present in the scheme, if the body of the request could not be serialized to canonical JSON, or it the verification of the signature failed.

Trait Implementations

impl Clone for XMatrix

fn clone(&self) -> XMatrix

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for XMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for XMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&XMatrix> for HeaderValue

fn from(value: &XMatrix) -> Self

Converts to this type from the input type.

impl FromStr for XMatrix

type Err = XMatrixParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl TryFrom<&HeaderValue> for XMatrix

type Error = XMatrixParseError

The type returned in the event of a conversion error.

fn try_from(value: &HeaderValue) -> Result<Self, Self::Error>

Performs the conversion.