- Authors: Daniel Hardman
- Status: ADOPTED (may be RETIRED when v2.0 of the protocol has enough gravitas)
- Since: 2019-05-01
- Status Note: One of our earliest DIDComm protocols; reached FCP (standards track) status in Indy, and implemented in at least two codebases there. Converted to an Aries RFC Implemented in a handful of Aries codebases. With the advent of DIDComm v2 at DIF, it became clear that we wanted to discover features beyond just protocol support, so this version of the protocol is now superseded by v2.0 in RFC 0557.
- Supersedes: Indy HIPE PR #73.
- Start Date: 2018-12-17
- Tags: feature, protocol, test-anomaly
Describes how agents can query one another to discover which features it supports, and to what extent.
Though some agents will support just one protocol and will be statically configured to interact with just one other party, many exciting uses of agents are more dynamic and unpredictable. When Alice and Bob meet, they won't know in advance which features are supported by one another's agents. They need a way to find out.
This RFC introduces a protocol for discussing the protocols an agent
can handle. The identifier for the message family used by this protocol is
discover-features, and the fully qualified URI for its definition is:
https://didcomm.org/discover-features/1.0
This protocol is now superseded by v2.0 in RFC 0557. Prefer the new version where practical.
There are two roles in the discover-features protocol: requester and
responder. The requester asks the responder about the protocols it
supports, and the responder answers. Each role uses a single message type.
This is a classic two-step request~response interaction, so it uses the
predefined state machines for any requester and responder:
A discover-features/query message looks like this:
{
"@type": "https://didcomm.org/discover-features/1.0/query",
"@id": "yWd8wfYzhmuXX3hmLNaV5bVbAjbWaU",
"query": "https://didcomm.org/tictactoe/1.*",
"comment": "I'm wondering if we can play tic-tac-toe..."
}Query messages say, "Please tell me what your capabilities are with respect to the protocols that match this string." This particular example asks if another agent knows any 1.x versions of the tictactoe protocol.
The query field may use the * wildcard. By itself, a query with just
the wildcard says, "I'm interested in anything you want to share with
me." But usually, this wildcard will be to match a prefix that's a little
more specific, as in the example that matches any 1.x version.
Any agent may send another agent this message type at any time. Implementers of agents that intend to support dynamic relationships and rich features are strongly encouraged to implement support for this message, as it is likely to be among the first messages exchanged with a stranger.
A discover-features/disclose message looks like this:
{
"@type": "https://didcomm.org/discover-features/1.0/disclose",
"~thread": { "thid": "yWd8wfYzhmuXX3hmLNaV5bVbAjbWaU" },
"protocols": [
{
"pid": "https://didcomm.org/tictactoe/1.0",
"roles": ["player"]
}
]
}The protocols field is a JSON array of protocol support descriptor
objects that match the query. Each descriptor has a pid that contains
a protocol version (fully qualified message family identifier such as
https://didcomm.org/tictactoe/1.0), plus a roles
array that enumerates the roles the responding agent
can play in the associated protocol.
Response messages say, "Here are some protocols I support that matched your query, and some things I can do with each one."
Responses do not have to contain exhaustive detail. For example, the following response is probably just as good:
{
"@type": "https://didcomm.org/discover-features/1.0/disclose",
"~thread": { "thid": "yWd8wfYzhmuXX3hmLNaV5bVbAjbWaU" },
"protocols": [
{"pid": "https://didcomm.org/tictactoe/1.0"}
]
}The reason why less detail probably suffices is that agents do not need to
know everything about one another's implementations in order to start an
interaction--usually the flow will organically reveal what's needed. For
example, the outcome message in the tictactoe protocol isn't needed
until the end, and is optional anyway. Alice can start a tictactoe game
with Bob and will eventually see whether he has the right idea about
outcome messages.
The missing roles in this response does not say, "I support no roles
in this protocol." It says, "I support the protocol but
I'm providing no detail about specific roles."
Even an empty protocols map does not say, "I support no protocols
that match your query." It says, "I'm not telling you that I support any
protocols that match your query." An agent might not tell another that
it supports a protocol for various reasons, including: the trust that
it imputes to the other party based on cumulative interactions so far,
whether it's in the middle of upgrading a plugin, whether it's currently
under high load, and so forth. And responses to a discover-features request are
not guaranteed to be true forever; agents can be upgraded or downgraded,
although they probably won't churn in their protocol support from moment
to moment.
Because the regex in a request message can be very inclusive, the discover-features
protocol could be used to mine information suitable for agent fingerprinting,
in much the same way that browser fingerprinting works. This is antithetical
to the ethos of our ecosystem, and represents bad behavior. Agents should
use discover-features to answer legitimate questions, and not to build detailed
profiles of one another. However, fingerprinting may be attempted
anyway.
For agents that want to maintain privacy, several best practices are recommended:
Only reveal supported features based on trust in the relationship. Even if you support a protocol, you may not wish to use it in every relationship. Don't tell others about protocols you do not plan to use with them.
Patterns are easier to see in larger data samples. However, a pattern of ultra-minimal data is also a problem, so use good judgment about how forthcoming to be.
Sometimes, you might prettify your agent plaintext message one way, sometimes another.
If more than one key matches a query, do not always return them in alphabetical order or version order. If you do return them in order, do not always return them in ascending order.
If a query could match multiple message families, then occasionally you might add some made-up message family names as matches. If a regex allows multiple versions of a protocol, then sometimes you might use some made-up versions. And sometimes not. (Doing this too aggressively might reveal your agent implementation, so use sparingly.)
How you ask questions may also be fingerprintable.
The query message contains a comment field that is localizable.
This field is optional and may not be often used, but when it is,
it is to provide a human-friendly justification for the query. An
agent that consults its master before answering a query could present
the content of this field as an explanation of the request.
All message types in this family thus have the following implicit decorator:
{
"~l10n": {
"locales": { "en": ["comment"] },
"catalogs": ["https://github.com/hyperledger/aries-rfcs/blob/a9ad499/features/0031-discover-features/catalog.json"]
}
}As shown in the above ~l10n decorator, all agents using this protocol have
a simple message catalog in scope. This allows agents to
send problem-reports to complain about something related to discover-features issues.
The catalog looks like this (see catalog.json):
{
"query-too-intrusive": {
"en": "Protocol query asked me to reveal too much information."
}
}
For more information, see the localization RFC.
- Do we want to support the discovery of features that are not protocol-related?
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 |
|---|---|
| Streetcred.id | Commercial mobile and web app built using Aries Framework - .NET MISSING test results |
| Aries Protocol Test Suite |