Package io.github.ma1uta.matrix.server.api

Interface KeyApi

  • @Path("/_matrix/key/v2")
@Consumes("application/json")
@Produces("application/json")
public interface KeyApi
    Each homeserver publishes its public keys under /_matrix/key/v2/server/. Homeservers query for keys by either getting /_matrix/key/v2/server/ directly or by querying an intermediate notary server using a /_matrix/key/v2/query API. Intermediate notary servers query the /_matrix/key/v2/server/ API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys.
    This approach is borrowed from the Perspectives Project, but modified to include the NACL keys and to use JSON instead of XML. It has the advantage of avoiding a single trust-root since each server is free to pick which notary servers they trust and can corroborate the keys returned by a given notary server by querying other servers.

    • Method Summary

      Modifier and Type Method Description
      void bulkQuery​(QueryRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Query for keys from multiple servers in a batch format.
      void key​(String keyId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Gets the homeserver's published TLS fingerprints and signing keys.
      void query​(String serverName, String keyId, Long minimumValidUntilTs, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
      Query for another server's keys.

    • Method Detail

      • key

        @GET
@Path("/server/{keyId}")
void key​(@PathParam("keyId")
         String keyId,
         @Context
         javax.ws.rs.core.UriInfo uriInfo,
         @Context
         javax.ws.rs.core.HttpHeaders httpHeaders,
         @Suspended
         javax.ws.rs.container.AsyncResponse asyncResponse)
        Gets the homeserver's published TLS fingerprints and signing keys. The homeserver may have any number of active keys and may have a number of old keys.

        Intermediate notary servers should cache a response for half of its lifetime to avoid serving a stale response. Originating servers should avoid returning responses that expire in less than an hour to avoid repeated requests for a certificate that is about to expire. Requesting servers should limit how frequently they query for certificates to avoid flooding a server with requests.

        If the server fails to respond to this request, intermediate notary servers should continue to return the last response they received from the server so that the signatures of old events can still be checked.
        Return: KeyResponse

        Status code 200: The homeserver's keys

        Parameters:
        keyId - Deprecated. Servers should not use this parameter and instead opt to return all keys, not just the requested one. The key ID to look up.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • query

        @GET
@Path("/query/{serverName}/{keyId}")
void query​(@PathParam("serverName")
           String serverName,
           @PathParam("keyId")
           String keyId,
           @QueryParam("minimumValidUntilTs")
           Long minimumValidUntilTs,
           @Context
           javax.ws.rs.core.UriInfo uriInfo,
           @Context
           javax.ws.rs.core.HttpHeaders httpHeaders,
           @Suspended
           javax.ws.rs.container.AsyncResponse asyncResponse)
        Query for another server's keys. The receiving (notary) server must sign the keys returned by the queried server.
        Return: QueryResponse.

        Status code 200: The keys for the server, or an empty array if the server could not be reached and no cached keys were available.

        Parameters:
        serverName - Required. The server's DNS name to query.
        keyId - Deprecated. Servers should not use this parameter and instead opt to return all keys, not just the requested one. The key ID to look up.
        minimumValidUntilTs - A millisecond POSIX timestamp in milliseconds indicating when the returned certificates will need to be valid until to be useful to the requesting server. If not supplied, the current time as determined by the notary server is used.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.

      • bulkQuery

        @POST
@Path("/query")
void bulkQuery​(QueryRequest request,
               @Context
               javax.ws.rs.core.UriInfo uriInfo,
               @Context
               javax.ws.rs.core.HttpHeaders httpHeaders,
               @Suspended
               javax.ws.rs.container.AsyncResponse asyncResponse)
        Query for keys from multiple servers in a batch format. The receiving (notary) server must sign the keys returned by the queried servers.
        Return: QueryResponse.

        Status code 200: The keys for the queried servers, signed by the notary server. Servers which are offline and have no cached keys will not be included in the result. This may result in an empty array.

        Parameters:
        request - Bulk query request.
        uriInfo - Request Information.
        httpHeaders - Http headers.
        asyncResponse - Asynchronous response.