Aries RFC 0048: Trust Ping Protocol 1.0¶
- Authors: Daniel Hardman
- Status: ADOPTED
- Since: 2019-02-01
- Status Note: Numerous implementations.
- Supersedes: Indy HIPE 0032
- Start Date: 2018-12-11
- Tags: feature, protocol, test-anomaly
Summary¶
Describe a standard way for agents to test connectivity, responsiveness, and security of a pairwise channel.
Motivation¶
Agents are distributed. They are not guaranteed to be connected or running all the time. They support a variety of transports, speak a variety of protocols, and run software from many different vendors.
This can make it very difficult to prove that two agents have a functional pairwise channel. Troubleshooting connectivity, responsivenes, and security is vital.
Tutorial¶
This protocol is analogous to the familiar ping
command in networking--but because it operates
over agent-to-agent channels, it is transport
agnostic and asynchronous, and it can produce insights
into privacy and security that a regular ping
cannot.
Roles¶
There are two parties in a trust ping: the sender
and the receiver
. The sender initiates the trust
ping. The receiver responds. If the receiver wants
to do a ping of their own, they can, but this is a
new interaction in which they become the sender.
Messages¶
The trust ping interaction begins when sender
creates a ping
message like this:
{
"@type": "https://didcomm.org/trust_ping/1.0/ping",
"@id": "518be002-de8e-456e-b3d5-8fe472477a86",
"~timing": {
"out_time": "2018-12-15 04:29:23Z",
"expires_time": "2018-12-15 05:29:23Z",
"delay_milli": 0
},
"comment": "Hi. Are you listening?",
"response_requested": true
}
Only @type
and @id
are required; ~timing.out_time
, ~timing.expires_time
,
and ~timing.delay_milli
are optional message timing decorators, and comment
follows the conventions of localizable message fields. If present, it may
be used to display a human-friendly description of the ping to a user
that gives approval to respond. (Whether an agent responds to a trust
ping is a decision for each agent owner to make, per policy and/or
interaction with their agent.)
The response_requested
field deserves special mention. The normal
expectation of a trust ping is that it elicits a response. However, it
may be desirable to do a unilateral trust ping at times--communicate
information without any expecation of a reaction. In this case,
"response_requested": false
may be used. This might be useful, for
example, to defeat correlation between request and response (to generate
noise). Or agents A and B might agree that periodically A will ping B
without a response, as a way of evidencing that A is up and functional.
If response_requested
is false, then the receiver MUST NOT respond.
When the message arrives at the receiver, assuming that response_requested
is not false
, the receiver should reply as quickly as possible with a
ping_response
message that looks like this:
{
"@type": "https://didcomm.org/trust_ping/1.0/ping_response",
"@id": "e002518b-456e-b3d5-de8e-7a86fe472847",
"~thread": { "thid": "518be002-de8e-456e-b3d5-8fe472477a86" },
"~timing": { "in_time": "2018-12-15 04:29:28Z", "out_time": "2018-12-15 04:31:00Z"},
"comment": "Hi yourself. I'm here."
}
Here, @type
and ~thread
are required, and the rest is optional.
Trust¶
This is the "trust ping protocol", not just the "ping protocol." The "trust" in its name comes from several ../../features that the interaction gains by virtue of its use of standard agent-to-agent conventions:
-
Messages should be associated with a message trust context that allows sender and receiver to evaluate how much trust can be placed in the channel. For example, both sender and receiver can check whether messages are encrypted with suitable algorithms and keys.
-
Messages may be targeted at any known agent in the other party's sovereign domain, using cross-domain routing conventions, and may be encrypted and packaged to expose exactly and only the information desired, at each hop along the way. This allows two parties to evaluate the completeness of a channel and the alignment of all agents that maintain it.
-
This interaction may be traced using the general message tracing mechanism.
Implementations¶
The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.
Name / Link | Implementation Notes |
---|---|
Indy Cloud Agent - Python | Reference agent implementation contributed by Sovrin Foundation and Community; MISSING test results |
Aries Framework - .NET | .NET framework for building agents of all types; MISSING test results |
Streetcred.id | Commercial mobile and web app built using Aries Framework - .NET; MISSING test results |
Aries Cloud Agent - Python | Contributed by the government of British Columbia.; MISSING test results |
Aries Static Agent - Python | Useful for cron jobs and other simple, automated use cases.; MISSING test results |
Aries Protocol Test Suite | MISSING test results |