0302: Aries Interop Profile¶
- Authors: Stephen Curran, John Jordan Province of British Columbia
- Status: ADOPTED
- Since: 2021-01-06
- Status Note: This RFC defines an Aries Interop Profile process and Aries Interop Profile versions
- Supersedes:
- Start Date: 2019-11-06
- Tags: concept
Summary¶
This RFC defines the process for the community of Aries agent builders to:
- enumerate a versioned set of Aries concept and feature RFCs which are collectively referred to as 'Aries Interop Profile Vx.y'
- track Aries Interop Profile versions.
"Agent builders" are organizations or teams that are developing open source code upon which agents can be built (e.g. aries-framework-dotnet), or deployable agents (e.g. Aries Mobile Agent Xamarin), or commercially available agents.
An Aries Interop Profile (AIP) version provides a clearly defined set of versions of RFCs for Aries agent builders to target their agent implementation when they wish it to be interoperable with other agents supporting the same Aries Interop Profile version. The Aries Interop Profile versioning process is intended to provide clarity and predictability for Aries agent builders and others in the broader Aries community. The process is not concerned with proposing new, or evolving existing, RFCs, nor with the development of Aries code bases.
At all times, the Reference section of this RFC defines one or more current Aries Interop Profile versions -- a number and set of links to specific commits of concept and ../../features RFCs, along with a list of all previous Aries Interop Profile versions. Several current Aries Interop Profile versions can coexist during periods when multiple major Aries Interop Profile versions are in active use (e.g. 1.x and 2.x). Each entry in the previous versions list includes a link to the commit of this RFC associated with that Aries Interop Profile version. The Reference section MAY include one <major>.next
version for each existing current major Aries Interop Profile versions. Such "next" versions are proposals for what is to be included in the next minor AIP version.
Once a suitably populated Aries test suite is available, each Aries Interop Profile version will include a link to the relevant subset of test cases. The test cases will include only those targeting the specific versions of the ../../concepts and ../../features RFCs in that version of Aries Interop Profile. A process for maintaining the link between the Aries Interop Profile version and the test cases will be defined in this RFC once the Aries test suite is further evolved.
This RFC includes a section maintained by Aries agent builders listing their Aries agents or agent deployments (whether open or closed source). This list SHOULD include the following information for each listed agent:
- The name, version and link to the agent (code or deployment)
- The type of the agent (see below)
- The name and link to the builder(s)
- The version of Aries Interop Profile supported
- A link to the test suite results or a summary of caveats/details about the agent's AIP support
- Notes about the agent
An Aries agent builder SHOULD include an entry in the table per major version supported. Until there is a sufficiently rich test suite that produces linkable results, builders SHOULD link to and maintain a page that summarizes any exceptions and extensions to the agent's AIP support.
The type of the agent MUST be selected from an enumerated list above the table of builder agents.
Motivation¶
The establishment of Aries Interop Profile versions defined by the Aries agent builder community allows the independent creation of interoperable Aries agents by different Aries agent builders. Whether building open or closed source implementations, an agent that aligns with the set of RFC versions listed as part of an Aries Interop Profile version should be interoperable with any other agent built to align with that same version.
Tutorial¶
This RFC MUST contain the current Aries Interop Profile versions as defined by a version number and a set of links to concept and feature RFCs which have been agreed to by a community of Aries agent builders. "Agreement" is defined as when the community agrees to merge a Pull Request (PR) to this RFC that affects an Aries Interop Profile version number and/or any of the links to concept and feature RFCs. PRs that do not impact the Aries Interop Profile version number or links can (in general) be merged with less community scrutiny.
Each link to a concept or feature RFCs MUST be to a specific commit of that RFC. RFCs in the list MAY be flagged as deprecated. Linked RFCs that reference external specs or standards MUST refer to as specific a version of the external resource as possible.
Aries Interop Profile versions SHOULD have a link (or links) to a version (specific commit) of a test suite (or test cases) which SHOULD be used to verify compliance with the corresponding version of Aries Interop Profile. Aries agent builders MAY self-report their test results as part of their entries in the list of agents.
Aries Interop Profile versions MUST evolve at a pace determined by the Aries agent builder community. This pace SHOULD be at a regular time interval so as to facilitate the independent but interoperable release of Aries Agents. Aries agent builders are encouraged to propose either updates to the list of RFCs supported by Aries Interop Profile through GitHub Issues or via a Pull Request. Such updates MAY trigger a change in the Aries Interop Profile version number.
All previous versions of Aries Interop Profile MUST be listed in the Previous Versions section of the RFP and must include a link to the latest commit of this RFC at the time that version was active.
A script in the /code
folder of this repo can be run to list RFCs within an AIP
version that have changed since the AIP version was set. For script usage information
run the following from the root of the repo:
python code/aipUpdates.py --help
Sub-targets¶
AIP 2.0 is organized into a set of base requirements, and additional optional targets. These requirements are listed below. When indicating levels of support for AIP 2.0, subtargets are indicated in this format: AIP 2.0/INDYCREDS/MEDIATE
with the subtargets listed in any order.
Any RFCs within a single AIP Version and it's subtargets MUST refer to the exact same version of the RFC.
Discover Features Usage¶
AIP Targets can be disclosed in the discover_../../features protocol, using the feature-type
of aip
. The feature's id
is AIP<major>.<minor>
for base compatibility, and AIP<major>.<minor>/<subtarget>
for subtargets, each subtarget being included individually.
Example:
{
"@type": "https://didcomm.org/discover-features/2.0/disclosures",
"disclosures": [
{
"feature-type": "aip",
"id": "AIP2.0",
},
{
"feature-type": "aip",
"id": "AIP2.0/INDYCRED"
}
]
}
Reference¶
The Aries Interop Profile version number and links to other RFCs in this section SHOULD only be updated with the agreement of the Aries agent builder community. There MAY be multiple active major Aries Interop Profile versions. A list of previous versions of Aries Interop Profile are listed after the current version(s).
Aries Interop Profile Version: 1.0¶
The initial version of Aries Interop Profile, based on the existing implementations such as aries-cloudagent-python, aries-framework-dotnet, Open Source Mobile Agent and Streetcred.id's IOS agent. Agents adhering to AIP 1.0 should be able to establish connections, exchange credentials and complete a connection-less proof-request/proof transaction.
RFC Type | RFC/Link to RFC Version |
---|---|
Concept | 0003-protocols |
Concept | 0004-agents |
Concept | 0005-didcomm |
Concept | 0008-message-id-and-threading |
Concept | 0011-decorators |
Concept | 0017-attachments |
Concept | 0020-message-types |
Concept | 0046-mediators-and-relays |
Concept | 0047-json-LD-compatibility |
Concept | 0050-wallets |
Concept | 0094-cross-domain messaging |
Feature | 0015-acks |
Feature | 0019-encryption-envelope |
Feature | 0160-connection-protocol |
Feature | 0025-didcomm-transports |
Feature | 0035-report-problem |
Feature | 0036-issue-credential |
Feature | 0037-present-proof |
Feature | 0056-service-decorator |
Changelog - AIP 1.0¶
The original commit used in the definition of AIP 1.0 was: 64e5e55
The following clarifications have been made to RFCs that make up AIP 1.0:
- RFC 0160 Connection:
signers
was updated tosigner
in the Signature decorator example, following the RFC.
AIP v1.0 Test Suite¶
To Do: Link(s) to version(s) of the test suite/test cases applicable to this Aries Interop Profile version.
Aries Interop Profile Version: 2.0¶
The following are the goals used in selecting RFC versions for inclusion in AIP 2.0, and the RFCs added as a result of each goal:
-
From AIP 1.0: Aries Agents must be able to establish connections, exchange credentials and complete a connection-less proof-request/proof transaction.
-
Aries agents must be able to reuse connections.
-
RFCs 0434, 0023, 0519, 0360
-
Enable access to actionable information in Mobile Agents to enable improvements in the user experience (vs. AIP 1.0-based mobile agents).
-
RFCs 0183, 0095, 0557
-
Improve support for credential revocation use cases, independent of the revocation mechanism being used.
-
RFCs 0183
-
Improve the low-level messaging cryptography and enable a transition to DIDComm 2.0 to improve the security of the communication paths between agents.
-
RFCs 0044, 0360, 0334
-
Use protocols and standards that support multiple ledger types and verifiable credential formats.
-
RFCs 0434, 0023, 0453, 0454
-
Where appropriate, enable standard mediator coordination capabilities for mobile agents and multi-tenant agencies.
- RFC 0211
AIP 2.0 Changelog by Pull Requests¶
Since approval of the AIP 2.0 profile, the following RFCs have been clarified by updating the commit in the link to the RFC:
- 2022-03: RFC 0004 Agents, RFC 0005 DIDComm, RFC 0046 Mediators and Relays, RFC 0211 Route Coordination
- Note: In this update, a number of RFCs were changed solely for the purpose of changing a link in the RFC to reference the "main" branch.
-
Pull request: #724
-
2022-06: RFC 0023 DID Exchange, RFC 0025 DIDComm Transports, RFC 0434 Out of Band
-
Pull request: #739
-
2024-02: Clarifications and removals of RFCs that have been determined to be impractical for AIP 2.0.
- See the AIP 2.0 RFC Removed section for details about the removed RFCs
- See the updated implementer's note on encryption envelopes in AIP 2.0 that highlights the removal of RFC 0587-encryption-envelope-v2.
-
Pull request: #814
-
2024-03: Clarifications and removals of RFCs that have been determined to be impractical for AIP 2.0.
- See the AIP 2.0 RFC Removed section for details about the removed RFCs
- Pull request: #820
AIP 2.0 Changelog by Clarifications¶
The original commit used in the definition of AIP 2.0 was: b3a3942ef052039e73cd23d847f42947f8287da2
The following clarifications have been made to RFCs that make up AIP 2.0. This list excludes commits changed solely because of status changes:
- RFC 0003 Protocols: A correction to the tic-tac-toe example protocol was made; clarifications and additional guidance about the handling of minor differences in protocols by implementations.
- RFC 0017 Attachments: A clarification was made around the use of base64url encoding/decoding.
- RFC 0441 Present Proof Best Practices: A convention for representing dates to enable simple "older than" predicates was added.
- RFC 0592 Indy Attachment Format: The encoding algorithm used for credential attributes was added from RFC 0036.
- RFC 0008 Message ID and Threading: Clarification on having an empty
~thread
on a first message. - RFC 0519 Goal Codes: Added some commonly used Goal Codes.
- RFC 0015 Acks: Clarification that an "Ack" value should not be "Fail" and Acks relationship with RFC 0035 Problem Report.
- RFC 0023 DID Exchange: Status update to Adopted, added to example the use of a DID Rotate attachment to include a signature on the the DID.
- RFC 0035 Report Problem: Clarification that a
description.code
is required, clarification on conventions for warnings. - RFC 0044 DIDComm File and MIME Types: Clarifications on fallbacks for the mime types and why, and on using JWEs.
- RFC 0211 Route Coordination: Clarification to add a missing comma to an example.
- RFC 0434 Out of Band: Clarification that did:peer:2 can be used for reuse.
- RFC 0453 Issue Credential: Clarification about the protocol version (2.0) and that payments are not part of AIP 2.0.
- RFC 0454 Present Proof: Clarification about the protocol version (2.0) and that payments are not part of AIP 2.0.
- RFC 0592 Indy Attachments: Clarification on handling "unrevealed attributes" and on encoding integer strings as numbers (e.g. encoding both
"1"
vs.1
as integers) - RFC 0510 DIF Presentation Exchange Attachment: Correction of reference into the DIF spec that there is an "s" on "definitions" in
dif/presentation-exchange/definitions@v1.0
Base Requirements¶
MEDIATE: Mediator Coordination¶
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0211-route-coordination | |
Feature | 0092-transport-return-route |
INDYCRED: Indy Based Credentials¶
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0592-indy-attachments | Evolved from AIP V1.0 |
Concept | 0441-present-proof-best-practices |
LDCRED: JSON-LD Based Credentials¶
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0593-json-ld-cred-attach | |
Feature | 0510-dif-pres-exch-attach |
BBSCRED: BBS+ Based Credentials¶
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0593-json-ld-cred-attach | |
Feature | 0646-bbs-credentials | |
Feature | 0510-dif-pres-exch-attach |
CHAT: Chat related ../../features¶
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0095-basic-message |
AIP 2.0 RFCs Removed¶
[!WARNING]
After discussion amongst the Aries implementers, the following RFCs initially in AIP 2.0 have been removed as both never implemented (as far as we know) and/or impractical to implement. Since the RFCs have never been implemented, their removal does not have a practical impact on implementations. Commentary below the table listing the removed RFCs provides the reasoning for the removal of each RFC.
RFC Type | RFC/Link to RFC Version | Note |
---|---|---|
Feature | 0317-please-ack | Removed from AIP 2.0 |
Feature | 0587-encryption-envelope-v2 | Removed from AIP 2.0 |
Feature | 0627-static-peer-dids | The use of static peer DIDs in Aries has evolved and all AIP 2.0 implementations should be using DID Peer types 4 (preferred), 1 or 2. |
- 0317-please-ack: While the idea of a generic ACK request to be sent either immediately
on receipt
, orafter processing
seemed like a good idea, attempts to implement the feature proved ill-advised. - The feature was never implemented, and there have been (as far as we know) no requests for its implementation. A good idea in theory, but not needed in practice.
- The
on receipt
use ofplease-ack
might be feasible as a generic feature, but does not appear to be useful except in protocol specific ways, such as in implementing a texting protocol to get "read receipts". However, even in that case, it is not useful for the existing 0095-basic-messaging protocol, because the protocol will be complete (and likely deleted) before theack
can be sent back to the sender. When anon receipt
ACK is needed, it is much preferred to add it in a protocol specific way vs. in a generic way. - The
after processing
use ofplease-ack
turned out to be impossible because its introduction changes every protocol state machine in protocol specific ways. We have determined that it is not possible to "generically" (without changing each protocol) to add such a feature and so we have decided that if there is a use case ofplease-ack
-style functionality in a given protocol, it should be added/included in that protocol. Further, no one has requested that the feature be used in any implementation. - See the RFC 0317 Please Ack for more details on it's change of status to
RETIRED
and links to unmerged PRs that attempted to design and implement the functionality. - 0587-encryption-envelope-v2
- While this RFC will be crucial when the transition to DIDComm v2 is started, it is not of use until then, and hence not applicable to AIP 2.0.
- 0627-static-peer-dids: The inclusion of static peer DIDs was a transitory approach as the DID Peer specification evolved. The use of static peer DIDs is not in use in Aries, the DID Peer specification has stabilized, and the existing implementations are settled on the use of
did:peer
4
(preferred),2
and in some cases1
. The removal of static peer DIDs from AIP 2.0 is to indicate where the community is currently and to lead newcomers to the community to follow the existing practices in the use of DID Peer.
AIP v2.0 Test Suite¶
The Aries Agent Test Harness has a set of tests tagged to exercise AIP 1.0 and AIP 2.0, including the extended targets.
Implementers Note about DIDComm Envelopes and the ACCEPT
element¶
[!WARNING]
The following paragraph is struck out as no longer relevant, since the 0587-encryption-envelope-v2 RFC has been removed from AIP 2.0. The upcoming (to be defined) AIP 3.0 will include the transition from DIDComm v1 to the next DIDComm generation, and at that time, the 0587-encryption-envelope-v2 will again be relevant.
AIP 2.0 contains two RFCs that reference envelopes 0019-encryption-envelope and 0587-encryption-envelope-v2 (links above).
The important feature that Aries implementers should understand to differentiate which envelope format can or is being used by an agent is the
accept
element of the DIDComm service endpoint and the out-of-band invitation
message. If the accept
element is not present, the
agent can only use the RFC 0019-encryption-envelope present. If it is present, the values indicate the envelope format(s)
the agent does support. See the RFCs for additional details.
Previous Versions¶
- None
Will be the version number as a link to the latest commit of this RFC while the version was current.
Aries Agent Builders and Agents¶
A list of agents that claim compatibility with versions of Aries Interop Profile. A entry can be included per agent and per major Aries Interop Profile version.
The agent type MUST be one of the following:
- Mobile - A mobile agent; does not require mediator routing capabilities, credential issuing capabilities.
- I/V - A cloud-based Issuer/Verifier agent; does not require credential holding support.
- Mediator - A mediator/relay agent; does not require verifiable credential exchange protocol capabilities.
- Holder - A cloud-based holder/prover agent; does not require credential issuing capabilities.
- Framework - A general purpose agent code base for an agent that is the basis for deployments of agents; typically supports all AIP protocols.
Name / Version / Link | Agent Type | Builder / Link | Aries Interop Profile Version | Test Results | Notes |
---|---|---|---|---|---|
Drawbacks¶
It may be difficult to agree on the exact list of RFCs to support in a given version.
Rationale and alternatives¶
Continuing with the current informal discussions of what agents/frameworks should support and when is an ineffective way of enabling independent building of interoperable agents.
Prior art¶
This is a typical approach to creating an early protocol certification program.
Unresolved questions¶
- The community agreement process for setting Aries Interop Profile versions needs to be tried and adjusted as appropriate.
- The tracking of who is part of the Aries agent builders community needs to be defined so we know who should have the strongest say in the setting of Aries Interop Profile versions.
- Should the Implementations table in all RFCs (below) be used for the agent builders table (above)? Or, should we eliminate the per RFC βimplementations table (below and in all RFCs) and just use this RFC to track implementations?
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.
Implementation Notes may need to include a link to test results.
Name / Link | Implementation Notes |
---|---|