Skip to content

Message Delivery to Applications

Applications registered in the Trust Framework's Directory may deliver messages to other Applications outside of data transfers.

Messages are JSON data structures with a schema defined in the Registry. Each Application registers a Delivery URL in the Directory. Other Applications send messages with a POST request to this Delivery URL. Access control uses a X.509 client certificate to identify the sender.

Reliability

Message delivery operates on a reasonable best-efforts basis, with no expectation of guaranteed delivery.

While failed message delivery must be retried a reasonable number of times, there is no requirement to persist messages in a database or other durable storage. If the server process is long-lived, in memory queuing for retry using a simple library is sufficient.

As a result:

  • Schemes must agree an SLA for availability and message delivery reliability.
  • Senders should not rely on the message being processed, even if the message as been accepted.
  • Messages must be idempotent.
  • There must be a mechanism to handle missed messages, for example:
    • Toleration of missed messages.
    • Searching logs to meet audit requirements.
    • Polling for data, in addition to notification of data availability.
    • Error results on next use of an API.

Message format

Messages are JSON objects with the following properties:

ib1:message
A property, with the value of the URL of the Trust Framework, which identifies this structure as a message.
subject
A Registry URL which specifies the meaning of the message.
body
A JSON data structure which is defined by the subject and conforms to a JSON Schema document stored in the Registry.

Example

{
  "ib1:message": "https://registry.core.trust.ib1.org/trust-framework",
  "subject": "https://registry.trust.ib1.org/message/revoke",
  "body": {
    // defined by message schema
  }
}

Registry Message Format RDF document

RDF documents describing the message format are fetched from the Registry by requesting the subject URL. The RDF document contains:

rdfs:comment
The human-readable name of this type of message.
ib1:messageSchema
The URL of a JSON Schema which describes the format of the body property in the message.

Directory Application RDF document

The Application URL may be fetched from the Directory, and contains message delivery information alongside other information about the Application.

ib1:messageDelivery
The URL of the delivery endpoint.

The Directory will include cache control headers in the response. When a delivery URL is changed, the recipient must maintain the old URL for the maximum age of the response.

Delivery

To deliver a message, an Application:

  • Fetches the URL of the other Application from the Directory.
    • If this request fails, retry with exponential backoff.
    • The HTTP client should cache the response.
  • Parses the RDF document to find the ib1:messageDelivery URL.
  • POSTs the message JSON document to this URL
    • Present the sender's client certificate in the MTLS connection.
    • If this request fails, retry with exponential backoff.

Identity of sender and recipient

The identity of the sender is sent in the client X.509 certificate used in the MTLS connection for the delivery HTTP request.

The identity of the recipient is verified by confirming that the delivery URL has a server certificate, issued by the Directory, where the hostname matches the hostname of the URL in the Directory.

Either the Application URL of the sender or the Roles of the sender may be used for access control.

Some messages senders will not be naturally part of an Application, for example, OAuth Issuers. A separate Application may be registered in the Directory for these components to avoid sharing certificates between unrelated functions. This Application must have all the roles of the Applications which rely on this component.

Advice for implementation

Sending implementations should:

  • Use a common HTTP client library.
  • Verify the server certificate using a public CA for Directory URLs, and the Trust Framework private CA for the delivery URLs.
  • When making HTTP requests, use a library which extends the HTTP client to implement retries with exponential backoff.
  • To avoid repeatedly fetching information from the Directory, when fetching the Application RDF document from the Directory, use a library which extends the HTTP client to implement caching of responses according to the Cache-Control headers in the response.
  • If the process which is sending messages is long-lived, the cache and the retry queues may be in memory, otherwise they must be serialized to persistent storage.
  • Log all actions and monitor SLAs.

Receiving implementations should:

  • Add the Application URL, Member URL, and Roles from the client certificate to the message before passing to a handler function or storing in a queue.