Skip to content

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 to signer 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

RFC Type RFC/Link to RFC Version Note
Concept 0003-protocols AIP V1.0, Reformatted
Concept 0004-agents AIP V1.0, Unchanged
Concept 0005-didcomm AIP V1.0, Minimally Updated
Concept 0008-message-id-and-threading AIP V1.0, Updated
Concept 0011-decorators AIP V1.0, Updated
Concept 0017-attachments AIP V1.0, Updated
Concept 0020-message-types AIP V1.0, Updated
Mandates message prefix https://didcomm.org for Aries Protocol messages.
Concept 0046-mediators-and-relays AIP V1.0, Minimally Updated
Concept 0047-json-LD-compatibility AIP V1.0, Minimally Updated
Concept 0050-wallets AIP V1.0, Unchanged
Concept 0094-cross-domain messaging AIP V1.0, Updated
Concept 0519-goal-codes πŸ†•
Feature 0015-acks AIP V1.0, Updated
Feature 0019-encryption-envelope AIP V1.0, Updated
See envelope note below
Feature 0023-did-exchange πŸ†•
Feature 0025-didcomm-transports AIP V1.0, Minimally Updated
Feature 0035-report-problem AIP V1.0, Updated
Feature 0044-didcomm-file-and-mime-types πŸ†•
Feature 0048-trust-ping πŸ†•
Feature 0183-revocation-notification πŸ†•
Feature 0360-use-did-key πŸ†•
Feature 0434-outofband πŸ†•
Feature 0453-issue-credential-v2 Update to V2 Protocol
Feature 0454-present-proof-v2 Update to V2 Protocol
Feature 0557-discover-features-v2 πŸ†•

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 πŸ†•
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, or after 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 of please-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 the ack can be sent back to the sender. When an on 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 of please-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 of please-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 cases 1. 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