diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..b44347e3d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,39 @@ + # For details on how this file works refer to: + # - https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file +version: 2 +updates: + # Maintain dependencies for GitHub Actions + # - Check for updates once a week + # - Group all updates into a single PR + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + groups: + all-actions: + patterns: [ "*" ] + + # Maintain dependencies for Python Packages + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + time: "04:00" + timezone: "Canada/Pacific" + ignore: + - dependency-name: "*" + update-types: ["version-update:semver-major"] + + # Maintain dependencies for Python Packages + - package-ecosystem: "pip" + directory: "/.circleci" + schedule: + interval: "weekly" + day: "monday" + time: "04:00" + timezone: "Canada/Pacific" + ignore: + - dependency-name: "*" + update-types: ["version-update:semver-major"] + diff --git a/.github/workflows/indexgenerate.yml b/.github/workflows/indexgenerate.yml deleted file mode 100644 index 273731124..000000000 --- a/.github/workflows/indexgenerate.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: Index Generation - -on: - pull_request: - branches: [master] - types: [closed] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-python@v1 - with: - python-version: "3.7" - - name: Generate Index - run: | - python code/generate_index.py - - name: Create Pull Request - id: cpr - uses: peter-evans/create-pull-request@v3 - with: - commit-message: Generate Index - author: GitHub Action - committer: GitHub Action - signoff: true - branch: index-generator - title: "[AUTO] Update Index" - body: | - Update Index diff --git a/.github/workflows/publish-site.yml b/.github/workflows/publish-site.yml new file mode 100644 index 000000000..d03d4007b --- /dev/null +++ b/.github/workflows/publish-site.yml @@ -0,0 +1,39 @@ +name: publish-docs + +on: + push: + # Publish `main` as latest, and when pushes are done to branches with "v-doc" prefix + branches: + - main + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # fetch all commits/branches + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - uses: actions/cache@v4 + with: + key: ${{ github.ref }} + path: .cache + - name: Install Python dependencies + run: pip install -r ./mkdocs-requirements.txt + - name: Configure git user + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + - name: Deploy docs + run: | + python --version + # Generate the content into the docs folder + code/genSite.sh + mike deploy --push --update-aliases main latest + mike set-default latest diff --git a/.gitignore b/.gitignore index fc427a3eb..3b7c0be90 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ __pycache__ *.pyc *.tmp .pytest_cache +docs \ No newline at end of file diff --git a/0000-template-protocol.md b/0000-template-protocol.md index 927f1a3c3..a18427487 100644 --- a/0000-template-protocol.md +++ b/0000-template-protocol.md @@ -1,6 +1,6 @@ # Aries RFC 0000: Your Protocol 0.9 -- Authors: [your name](you@github-email) -- email is optional +- Authors: [your name](mailto:you@github-email) -- email is optional - Status: [PROPOSED](/README.md#proposed) - Since: 2019-12-26 (date you submit your PR) - Status Note: (explanation of current status) @@ -31,7 +31,7 @@ Specify the official name of the protocol and its version, e.g., "My Protocol 0. Protocol names are often either lower_snake_case or kebob-case. The non-version components of the protocol named are matched exactly. -URI: https://didcomm.org/lets_do_lunch// +URI: `https://didcomm.org/lets_do_lunch//` Message types and protocols are identified with special URIs that match certain conventions. See [Message Type and Protocol Identifier URIs](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0003-protocols/README.md#message-type-and-protocol-identifier-uris) for more details. @@ -159,7 +159,7 @@ Adoption should be declared in an "Adopted" subsection of "Messages". When adoption is specified, it should include a __minimum adopted version__ of the adopted message type: "This protocol adopts `ack` with version >= 1.4". All versions of the adopted message that share -the same major number should be compatible, given the [semver rules](concepts/0003-protocols/semver.md) +the same major number should be compatible, given the [semver rules](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0003-protocols/README.md#semver-rules-for-protocols) that apply to protocols. ### Constraints diff --git a/0000-template.md b/0000-template.md index 707ba5ae2..f6608e2ef 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,5 +1,5 @@ # Title (Ex. 0000: RFC Topic) -- Authors: [your name](you@github-email) -- email is optional +- Authors: [your name](mailto:you@github-email) -- email is optional - Status: [PROPOSED](/README.md#proposed) - Since: 2019-12-26 (date you submit your PR) - Status Note: (explanation of current status) diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 000000000..7def48055 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,73 @@ +# Maintainers + +## Active Maintainers + + + +| Name | Github | LFID | +| ---------------- | ---------------- | ---------------- | +| Daniel Hardman | dhh1128 | | +| George Aristy | llorllale | | +| Nathan George | nage | | +| Stephen Curran | swcurran | | +| Drummond Reed | talltree | | +| Sam Curren | TelegramSam | | + +## Emeritus Maintainers + +| Name | Github | LFID | +|--------------|---------|---------| +| | | | + +## Becoming a Maintainer + +The Aries community welcomes contributions. Contributors may progress to become a +maintainer. To become a maintainer the following steps occur, roughly in order. + +- 5 significant changes have been authored by the proposed maintainer and + accepted. +- The proposed maintainer has the sponsorship of at least one other maintainer. + - This sponsoring maintainer will create a PR modifying the list of + maintainers. + - The proposed maintainer accepts the nomination and expresses a willingness + to be a long-term (more than 6 month) committer. + - This would be a comment in the above PR. + - This PR will be communicated in all appropriate communication channels. It + should be mentioned in any maintainer/community call. It should also be + posted to the appropriate mailing list or chat channels if they exist. +- Approval by at least 3 current maintainers within two weeks of the proposal or + an absolute majority of current maintainers. + - These votes will be recorded in the PR modifying the list of maintainers. +- No veto by another maintainer within two weeks of proposal are recorded. + - All vetoes must be accompanied by a public explanation as a comment in the + PR for adding this maintainer + - The explanation of the veto must be reasonable. + - A veto can be retracted, in that case the approval/veto timeframe is reset. + - It is bad form to veto, retract, and veto again. +- The proposed maintainer becomes a maintainer + - Either two weeks have passed since the third approval, + - Or an absolute majority of maintainers approve. + - In either case, no maintainer presents a veto. + +## Removing Maintainers + +Being a maintainer is not a status symbol or a title to be maintained +indefinitely. It will occasionally be necessary and appropriate to move a +maintainer to emeritus status. This can occur in the following situations: + +- Resignation of a maintainer. +- Violation of the Code of Conduct warranting removal. +- Inactivity. + - A general measure of inactivity will be no commits or code review comments + for one reporting quarter, although this will not be strictly enforced if + the maintainer expresses a reasonable intent to continue contributing. + - Reasonable exceptions to inactivity will be granted for known long term + leave such as parental leave and medical leave. +- Other unspecified circumstances. + +Like adding a maintainer the record and governance process for moving a +maintainer to emeritus status is recorded in the github PR making that change. + +Returning to active status from emeritus status uses the same steps as adding a +new maintainer. Note that the emeritus maintainer already has the 5 required +significant changes as there is no contribution time horizon for those. diff --git a/README.md b/README.md index b8b3867a5..a89ea2b48 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ If you are here to learn about Aries, we recommend you use the [the RFC Index](i There are 2 types of Aries RFCs: -* RFCs that describe individual features (in the [features](./features) folder) -* RFCs that explain concepts underpinning many features (in the [concepts](./concepts) folder) +* RFCs that describe individual features (in the `./features` folder) +* RFCs that explain concepts underpinning many features (in the `./concepts` folder) RFCs are for developers *building on* Aries. They don't provide guidance on how Aries components implement features internally; individual Aries repos have design docs for that. Each @@ -20,7 +20,18 @@ Aries RFC includes an "implementations" section and all RFCs with a status great RFCs go through a standard lifecycle. -![lifecycle](lifecycle.png) + + +![lifecycle](https://www.plantuml.com/plantuml/png/TP1DZeCm38NtEKK6rbnXHAKUe6gNg8iKN43AJ-GOUlsIoa60mYQs_Db-UQu3AQJ9QF570nYGy_X2PKayI178uWuq8dI5L45oBilbINm9MZFdVCjlwBmBiQR7Vg0U0IoZAnXd0w6YBBwqBVWJv3sw-O1MfQefVvLdzR_J43l1gdCVk-bCSeAJJ0Uh7lPeU5CJ7SSUlX0lESUyAeytLZ3wMpdVLt1Cq-iFqvoemNQJqLy0) #### PROPOSED To __propose__ an RFC, [use these instructions to raise a PR]( @@ -33,13 +44,17 @@ exploring. __Demonstrated__ RFCs have one or more implementations available, listed in the "Implementations" section of the RFC document. As with the PROPOSED status, demonstrated RFCs haven't been endorsed by the community, but the ideas put forth have been more thoroughly explored through the implementation(s). The demonstrated status is an optional step in the lifecycle. For protocol-related RFCs, work on protocol tests SHOULD begin in the [test suite repo](https://github.com/hyperledger/aries-protocol-test-suite) by the time this status is assigned. #### ACCEPTED -To get an RFC __accepted__, [build consensus](contributing.md#how-to-get-an-RFC-accepted) for your RFC on [chat](https://chat.hyperledger.org/channel/aries) and in community meetings. If your RFC is a feature that's protocol- or decorator-related, it MUST have reasonable tests in the [test suite repo](https://github.com/hyperledger/aries-protocol-test-suite), it MUST list the test suite in the protocol RFC's [Implementations section](../0000-template.md#implementations), at least one other implementation must have passed the relevant portions of the test suite, and all implementations listed in this section of the RFC MUST hyperlink to their test results. An accepted RFC is incubating on a standards track; the community has decided to polish it and is exploring or pursuing implementation. +To get an RFC __accepted__, [build consensus](contributing.md#how-to-get-an-RFC-accepted) for your RFC on [chat](https://chat.hyperledger.org/channel/aries) and in community meetings. If your RFC is a feature that's protocol- or decorator-related, it MUST have reasonable tests in the [test suite repo](https://github.com/hyperledger/aries-agent-test-harness), it MUST list the test suite in the protocol RFC's [Implementations section](/0000-template.md#implementations), at least one other implementation must have passed the relevant portions of the test suite, and all implementations listed in this section of the RFC MUST hyperlink to their test results. An accepted RFC is incubating on a standards track; the community has decided to polish it and is exploring or pursuing implementation. #### ADOPTED To get an RFC __adopted__, [socialize and implement](contributing.md#how-to-get-an-rfc-adopted). An RFC gets this status once it has significant momentum--when implementations accumulate, or when the mental model it advocates has begun to permeate our discourse. In other words, adoption is acknowledgment of a _de facto_ standard. To __refine__ an RFC, propose changes to it through additional PRs. Typically these changes are driven by experience that accumulates during or after adoption. Minor refinements that just improve clarity can happen inline with lightweight review. Status is still ADOPTED. +#### STALLED +An RFC is __stalled__ when a [proposed](#proposed) RFC makes +no progress towards implementation such that it is extremely unlikely it will ever move forward. The __stalled__ state differs from [retired](#retired) in that it is an RFC that has never been implemented or superseded. Like the [retired](#retired) state, it is (likely) an end state and the RFC will not proceed further. Such an RFC remains in the repository on the off chance it will ring a chord with others, be returned to the [proposed](#proposed) state, and continue to evolve. + #### RETIRED An RFC is __retired__ when it is withdrawn from community consideration by its authors, when implementation seems permanently stalled, or when significant refinements require a superseding document. If a retired RFC has been superseded, its `Superseded By` field should contain a link to the newer spec, and the newer spec's `Supersedes` field should contain a link to the older spec. Permalinks are not broken. diff --git a/code/aipUpdates.py b/code/aipUpdates.py index 8961c1ba1..8c01cc6fc 100755 --- a/code/aipUpdates.py +++ b/code/aipUpdates.py @@ -11,12 +11,13 @@ description='List the RFCs set in an Aries Interop Profile (AIP) that have subsequently evolved. ' + 'By default, the AIPs in the local version of the file are processed. A specific version can be ' + 'specified, and then only that AIP version is processed. The AIP version can be a previous (not current) ' + - 'AIP. Optionally, the diffs between RFCs set in processed AIP and the "master" branch can be included.') + 'AIP. Optionally, the diffs between RFCs set in processed AIP and the "main" branch can be included.') # add arguments to the parser parser.add_argument('--version', '-v', help='The AIP version to display. Defaults to the current version(s) in the local file') parser.add_argument('--diffs', '-d', dest='diffs', action='store_true', help='Display the diffs of any updated RFCs found') +parser.add_argument('--list', '-l', help='List the RFCs and commits in the AIP with a prefixed by the name of a (for example) shell script') # parse the arguments args = parser.parse_args() @@ -64,10 +65,10 @@ def readAIP( aip_path, version ): if aip_version: # Check if we want all the AIPs in the file or this one if ( not(args.version) or aip_version.group(1) == args.version ): - print("Aries Interop Profile: %s" % (aip_version.group(1))) + print("# Aries Interop Profile: %s" % (aip_version.group(1))) ListVersionRFCs = True else: - # Not this one...don't list the changed verion + # Not this one...don't list the changed version ListVersionRFCs = False rfc = re.search(_aip_commit_and_file, line) @@ -76,14 +77,16 @@ def readAIP( aip_path, version ): # From the RFC line, get the commit ID and protocol file commit = rfc.group(3) protocol = rfc.group(5) - changed = re.search(protocol, subprocess.run(['git', 'diff', '--name-only', commit, 'master'], stdout=subprocess.PIPE).stdout.decode('utf-8')) + changed = re.search(protocol, subprocess.run(['git', 'diff', '--name-only', commit, 'main'], stdout=subprocess.PIPE).stdout.decode('utf-8')) # Has this RFC changed since it was set in the RFC? - if changed: + if args.list: + print('%s %s %s' % (args.list, protocol, commit)) + elif changed: # Yes - list it. print('>>>>>>>> Changed protocol: %s, latest commit to protocol: %s' % (protocol, subprocess.run(['git', 'log', '-n', '1', '--pretty=format:%H', '--', protocol], stdout=subprocess.PIPE).stdout.decode('utf-8'))) if args.diffs: # If we're showing diffs, then show the diffs print('') - print(subprocess.run(['git', 'diff', commit, 'master', protocol], stdout=subprocess.PIPE).stdout.decode('utf-8')) + print(subprocess.run(['git', 'diff', commit, 'main', protocol], stdout=subprocess.PIPE).stdout.decode('utf-8')) exit() diff --git a/code/cpAIPs.sh b/code/cpAIPs.sh new file mode 100755 index 000000000..6d38c7016 --- /dev/null +++ b/code/cpAIPs.sh @@ -0,0 +1,19 @@ +#! /bin/bash + +# Usage: Given an RFC name and a commit, retrieve all the files of the RFC into the AIP RFC at the right commit. +# Example: code/cpAIP.sh concepts/0003-protocols c3b0e2120ad24810598375663b6922b980f85d00 +# Designed to fetch files in subdirectories, although it is not clear how to add them to the documentatioon + +PROTOCOL=$1 +COMMIT=$2 +AIP2=aip2 + +# echo Getting AIP docs for RFC $PROTOCOL, Commit $COMMIT +cd docs +for i in $(find $PROTOCOL -type f); do + AIPFile=$(echo $i | sed -r "s#(features|concepts)/#${AIP2}/#") + # echo $i $AIPFile + mkdir -p $(dirname $AIPFile) + curl -s https://raw.githubusercontent.com/hyperledger/aries-rfcs/${COMMIT}/$i -o $AIPFile +done +cd .. diff --git a/code/genSite.sh b/code/genSite.sh new file mode 100755 index 000000000..e56f2ee65 --- /dev/null +++ b/code/genSite.sh @@ -0,0 +1,75 @@ +#!/bin/bash + +# echo Updating the Docs for Aries RFCs + +# Clean out the docs folder +rm -rf docs/* +mkdir -p docs + +# Root folder -- README.md +cp -r contributing.md github-issues.md MAINTAINERS.md README.md SECURITY.md tags.md 0000*.md *.png collateral docs +cp LICENSE docs/LICENSE.md +sed -e "s#/tags.md#tags.md#g" index.md > docs/RFCindex.md + +# Features and Concept -- collect all of the RFCs +cp -r features concepts docs + +# Update the index.md file +python code/generate_index.py + +# Make a copy of AIP 2 RFCs using the right commit for each +python code/aipUpdates.py -v 2.0 -l "./code/cpAIPs.sh" | \ + sed -e "/0317-please-ack/d" -e "/0587-encryption-envelope-v2/d" -e "/0627-static-peer-dids/d" \ + > copy_aip.sh +source copy_aip.sh +rm copy_aip.sh + +# Cleanup a few things in README, contributing and 0000-templates +for i in docs/contributing.md docs/README.md docs/0000*.md; do + sed \ + -e 's#../../##g' \ + -e 's#index.md#RFCindex.md#' \ + -e 's#LICENSE)#LICENSE.md)#' \ + $i >$i.tmp + mv $i.tmp $i +done + + +# Cleanup missing mailtos -- will always be needed for aip2 folder, but will be cleaned up in files +for i in docs/features/*/README.md docs/concepts/*/README.md docs/aip2/*/README.md; do + sed -e '/Authors/s#](#](mailto:#g' -e 's#mailto:mailto:#mailto:#g' $i >$i.tmp; mv $i.tmp $i +done + +# Cleanup the links in the RFCs +for i in docs/features/*/README.md docs/concepts/*/README.md docs/aip2/*/README.md; do + sed \ + -e 's#(/#(../../#g' \ + -e 's#index.md#RFCindex.md#' \ + -e 's#[\./]*\(concepts\)#../../\1#g' \ + -e 's#[\./]*\(features\)#../../\1#g' \ + -e 's#discover-../../#discover-#g' \ + $i >$i.tmp + mv $i.tmp $i +done + +# Remove the existing AIP and By Status Links -- we'll add them back +MKDOCS=mkdocs.yml +MKDOCSTMP=${MKDOCS}.tmp +MKDOCSIDX=mkdocs_index.yml + +# Strip off the old navigation +sed '/RFCs by AIP and Status/,$d' ${MKDOCS} >${MKDOCSTMP} + +# Add back in the marker +echo '# RFCs by AIP and Status' >>${MKDOCSTMP} + +# Navigation for AIP 2.0 files +echo "- AIP 2.0:" >>${MKDOCSTMP} +for i in docs/aip2/*/README.md ; do head -n 1 $i | sed -e "s/# / - /" -e "s/: / /" -e "s#\$#: $i#" -e "s#docs/##"; done >>${MKDOCSTMP} + +# Navigation for all RFCs by Status +python code/generate_mkdocs_index.py +cat ${MKDOCSIDX} >>${MKDOCSTMP} +rm ${MKDOCSIDX} + +mv ${MKDOCSTMP} ${MKDOCS} diff --git a/code/generate_mkdocs_index.py b/code/generate_mkdocs_index.py new file mode 100644 index 000000000..65fc7b36b --- /dev/null +++ b/code/generate_mkdocs_index.py @@ -0,0 +1,46 @@ +import argparse +from operator import itemgetter +import os +from pathlib import Path +import sys + +import rfcs + +def update(fname, tmp_fname): + if not os.path.exists(fname): + os.rename(tmp_fname, fname) + # print('Generated %s.' % fname) + return + with open(fname, encoding='utf-8', mode='rt') as f: + old = f.read() + with open(tmp_fname, encoding='utf-8', mode='rt') as f: + new = f.read() + if old == new: + # print('No change to %s.' % fname) + return + os.remove(fname) + os.rename(tmp_fname, fname) + # print('Updated %s.' % fname) + + +def main(fname = None): + if not fname: + fname = os.path.join(rfcs.root_folder, 'mkdocs_index.yml') + # Load all metadata + all = [rfc for rfc in rfcs.walk()] + all.sort(key=lambda x: x.num) + tmp_fname = fname + '.tmp' + with open(tmp_fname, 'w', encoding='utf-8') as out: + for status in rfcs.status_list: + out.write(f"- {status}:\n") + with_status = [rfc for rfc in all if rfc.status == status] + for rfc in with_status: + out.write(f" - {rfc.num} {rfc.title}: {rfc.relpath}\n") + update(fname, tmp_fname) + + +if __name__ == '__main__': + ap = argparse.ArgumentParser('Generate index') + ap.add_argument('altpath', metavar='PATH', nargs='?', default=None, help='override where index is generated') + args = ap.parse_args() + main(args.altpath) diff --git a/code/rfcs.py b/code/rfcs.py index aa0a04940..320862e5b 100644 --- a/code/rfcs.py +++ b/code/rfcs.py @@ -6,7 +6,7 @@ ' status_note start_date supersedes superseded_by tags content_idx impl_count impl_table') -status_list = ["ADOPTED", "ACCEPTED", "DEMONSTRATED", "PROPOSED", "RETIRED"] +status_list = ["ADOPTED", "ACCEPTED", "DEMONSTRATED", "PROPOSED", "STALLED", "RETIRED"] root_folder = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')) diff --git a/collateral/favicon.ico b/collateral/favicon.ico new file mode 100644 index 000000000..90697b9fd Binary files /dev/null and b/collateral/favicon.ico differ diff --git a/concepts/0003-protocols/README.md b/concepts/0003-protocols/README.md index 1159ccc99..54e4af608 100644 --- a/concepts/0003-protocols/README.md +++ b/concepts/0003-protocols/README.md @@ -1,7 +1,7 @@ # Aries RFC 0003: Protocols -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-04-01 - Status Note: standards track and beginning to influence many mental models, but not yet [ADOPTED](/README.md#rfc-lifecycle). - Supersedes: [Indy PR #69]( https://github.com/hyperledger/indy-hipe/pull/69) @@ -370,16 +370,35 @@ message family](https://semver.org/#spec-item-8). Within a given major version of a protocol, an agent should: -- respond to a minimum supported minor version, defaulting to "0" -- respond with or initiate a protocol instance the current fully supported minor version +- Respond to a minimum supported minor version, defaulting to "0". + - An agent SHOULD keep minimum supported minor version at "0" unless it is unsecure or extremely complicated to do so. +- Respond with or initiate a protocol instance the current fully supported minor version. This leads to the following received message handling rules: -- message types received with a minor versions below the minimum may be answered with a `problem-report` message with code `version-not-supported` -- message types received with a minor version at or higher than the minimum supported and less than the current minor version are processed, ideally with a response using the same minor version of the received message - - The recipient may want to send a warning `problem-report` message with code `version-with-degraded-features` -- message types received with a minor version higher than the current minor version are processed with any unrecognized fields ignored - - The recipient may want to send a warning `problem-report` message with code `fields-ignored-due-to-version-mismatch` +- Message types received with minor versions below the minimum MAY be ignored, or preferably, MAY be answered only with a `problem-report` message with code `version-not-supported`. +- Message types received with a minor version __at or higher than__ the minimum supported __and less than__ the current minor version are processed as follows: + - The processing MAY be with the same minor version of the received message. + - To support this, an implementation must implement each minor version from minimum to current within the major version. + - The processing MAY be with the current minor version (higher than received). + - This approach is used when maintaining each minor version from minimum to current within the major version is impractical. + - Recipients of the response message SHOULD detect from the response [PIURI](#piuri) that a higher minor version was used in the response, and to compensate if needed and as necessary. + - Prior wording of this protocol included the following suggestion that is now considered deprecated. See note below about deprecating the "warning" problem reports. + - In addition to responding with the protocol message (if necessary), the agent MAY also want to send a warning `problem-report` message with code `version-with-degraded-features`. +- Message types received with a minor version higher than the current minor version MUST be processed with any unrecognized fields ignored. + - The response MUST use the current minor version. + - Recipients of the response message SHOULD detect from the response [PIURI](#piuri) that a lower minor version was used in the response, and to compensate if needed and as necessary. + - Prior wording of this protocol included the following that is now considered deprecated. See note below about deprecating the "warning" problem reports. + - In addition to responding with the protocol message, an agent MAY send a warning `problem-report` message with code `fields-ignored-due-to-version-mismatch` + +**Note:** The deprecation of the "warning" `problem-reports` in cases of minor +version mismatches is because the recipient of the response can detect the +mismatch by looking at the [PIURI](#piuri), making the "warning" unnecessary, +and because the `problem-report` message may be received after (and definitely +at a different time than) the response message, and so the warning is of very +little value to the recipient. Recipients should still be aware that minor +version mismatch warning `problem-report` messages may be received and handle +them appropriately, likely by quietly ignoring them. As documented in the semver documentation, these requirements are not applied when major version 0 is used. In that case, minor version increments are considered breaking. diff --git a/concepts/0004-agents/README.md b/concepts/0004-agents/README.md index dabe7e47c..0fb1e6d39 100644 --- a/concepts/0004-agents/README.md +++ b/concepts/0004-agents/README.md @@ -1,6 +1,6 @@ # Aries RFC 0004: Agents -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [ACCEPTED](/README.md#accepted) - Since: 2019-01-15 - Status Note: On a standards track and beginning to influence many mental models, but not yet [ADOPTED](/README.md#rfc-lifecycle). diff --git a/concepts/0005-didcomm/README.md b/concepts/0005-didcomm/README.md index d105e166e..14ece200a 100644 --- a/concepts/0005-didcomm/README.md +++ b/concepts/0005-didcomm/README.md @@ -1,7 +1,7 @@ # Aries RFC 0005: DID Communication -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-11-21 - Status Note: Mature as concept, with multiple implementations. - Supersedes: [Indy PR #98](https://github.com/hyperledger/indy-hipe/pull/98) diff --git a/concepts/0008-message-id-and-threading/README.md b/concepts/0008-message-id-and-threading/README.md index 6ccdc6915..bbd875dea 100644 --- a/concepts/0008-message-id-and-threading/README.md +++ b/concepts/0008-message-id-and-threading/README.md @@ -1,7 +1,7 @@ # Aries RFC 0008: Message ID and Threading -- Authors: [Daniel Bluhm](daniel.bluhm@sovrin.org), [Sam Curren](sam@sovin.org), [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Daniel Bluhm](mailto:daniel.bluhm@sovrin.org), [Sam Curren](mailto:sam@sovin.org), [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2018-10-01 - Status Note: Implemented broadly in Indy, but not yet elsewhere. - Start Date: 2018-08-03 @@ -71,6 +71,10 @@ Message threading will be implemented as a [decorator](../0011-decorators/README The `~thread` decorator is generally required on any type of response, since this is what connects it with the original request. +While not recommended, the initial message of a new protocol instance MAY have an +empty (`{}`) `~thread` item. Aries agents receiving a message with an empty +`~thread` item MUST gracefully handle such a message. + #### Thread object A thread object has the following fields discussed below: diff --git a/concepts/0011-decorators/README.md b/concepts/0011-decorators/README.md index 6d2574559..e92b20217 100644 --- a/concepts/0011-decorators/README.md +++ b/concepts/0011-decorators/README.md @@ -1,7 +1,7 @@ # Aries RFC 0011: Decorators - Authors: Daniel Hardman -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-01-31 - Status Note: broadly used in Indy, but not yet harmonized with DIF work on hubs. - Start Date: 2018-12-14 diff --git a/concepts/0013-overlays/README.md b/concepts/0013-overlays/README.md index 9a088d9ca..1684d860f 100644 --- a/concepts/0013-overlays/README.md +++ b/concepts/0013-overlays/README.md @@ -1,216 +1,8 @@ # Aries RFC 0013: Overlays -- Authors: Paul Knowles, Dativa -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-05-20 -- Status Note: socialized for many months; no implementations yet +- Authors: Paul Knowles, The Human Colossus Foundation +- Status: [RETIRED](/README.md#retired) +- Since: 2023-01-15 +- Status Note: Although this RFP is in the **retired** status, the use of overlays and the Overlays Capture Architecture (OCA) is active in Aries. This RFP is an early of the OCA specification, and its content is replaced by the [Overlays Capture Architecture Specification](https://oca.colossi.network/specification/). The use of OCA in Aries is described in [RFC 0755: OCA for Aries](../../features/0755-oca-for-aries/README.md). - Start Date: 2018-10-01 - Tags: [concept](/tags.md#concept) - -## Summary - -Describes a standard approach to data capture that separates raw schema -building blocks from additional semantic layers such as data entry business -logic and constraints, knowledge about data sensitivity, and so forth. - -## Motivation - -The post millennial generation has witnessed an explosion of captured data points which has sparked profound possibilities in both Artificial Intelligence (AI) and Internet of Things (IoT) solutions. This has spawned the collective realization that society’s current technological infrastructure is simply not equipped to fully protect personally identifiable information (PII) or to entice corporations to break down internal data silos, streamline data harmonization processes and ultimately resolve worldwide data duplication and storage resource issues. - -The FAIR Data Principles are a set of guiding principles in order to make data findable, accessible, interoperable and reusable (Wilkinson et al., 2016). These principles provide guidance for scientific data management and stewardship and are relevant to all stakeholders in the current digital ecosystem. - -In line with the FAIR principles, data harmonization and interoperability processes between internal departments and functions is a high priority for companies but the current cognitive framework available for global data capture is hampered by limitations to the foundational data object architecture. - -## Tutorial - -In terms of creating a fully-fledged decentralized data economy, we are still in the early turbulent stages of business, legal and technological innovation with gaps, grey areas and required revision aplenty but, one thing is for certain, we are heading into an era where siloed data ownership will be superseded by consented access to subsets of decentralized data. - -Data-centric innovation points to a future society where new values and services will be created continuously, making people’s lives more conformable and sustainable. Developing and deploying the right data capture architecture will improve the quality of externally pooled data for future AI and IoT solutions. The Overlays Data Capture Architecture (ODCA) was conceived for this purpose. - -### Overlays Data Capture Architecture (ODCA) - -ODCA is a standardized global solution for data capture and exchange which protects PII data and provides a positive alternative to current architectures. - -A schema, a machine-readable definition of the semantics of a data structure, is typically created as a single data object. However, ODCA represents a schema as a multi-dimensional object consisting of a stable schema base and linked overlays, data objects that provide additional extensions, coloration, and functionality to the base object. Any sponsor can use a pre-existing schema base and build their own suite of linked overlays to add extra context to transform how information is displayed to a viewer or to guide an agent in how to apply a custom process to schema data. - -ODCA was primarily devised for data object interoperability and privacy compliant data sharing. The architecture promises to significantly enhance the ability to pool data more effectively in terms of simplicity, accuracy, and allocation of resources. The degree of separation between schema bases and overlays allows multiple parties to use the same base objects for similar data capture requirements thus providing a standard base from which to decentralize data. - -![Figure 1: Muliple overlays developed by different organizations to provide a set of metadata that adequately describes a single set of data](figure-1.png) - -ODCA offers many advantages, including: - -1. Data pooling. Decoupling can occur at any time as overlays are linked objects. With all coloration stored in the overlays, combining data from related sources becomes much easier. Overlays can be removed from the base objects before the data merging process begins and reapplied to ensure consistent coloration post data pooling. -2. Stable schema bases. Most schema updates tend to be done at the application layer. In the case of ODCA, all extension, coloration, and functionality definitions are applied in the overlays. This enables issuers to edit one or more of the linked objects to create simple updates rather than having to reissue schema bases on an ongoing basis. -3. PII encryption. Using the Blinding Identity Taxonomy (BIT) as a reference [see section below], issuers can flag PII attributes in the schema base. With PII attributes flagged at the base object layer, all corresponding data can be treated as sensitive throughout the data lifecycle and encrypted or removed at any stage. This ensures that data protection of personal data is guaranteed as entity identification is impossible. -4. Data decentralization. ODCA enables schema base definitions to remain in their purest form thus providing a standard base from which to decentralize data. Organizations wishing to contribute data to a decentralized data lake for consented third-party usage can capture data using generic open source schema bases. This ensures that data standardization is done prior to any data lake migration. - -#### BLINDING IDENTITY TAXONOMY (BIT) - -Internet-related services and social media companies founded in the late ‘90s and early ‘00s triggered a digital hoarding revolution with large amounts of personal data captured and stored in corporate data silos under centralized control. Silicon Valley’s largest technology companies have subsequently seen revenue figures soar through deployed marketing tools built to enable third party vendors to target subsets of individuals according to dynamic criteria searches. Revenue models have tended to rely heavily on these targeted advertising mechanisms which has encouraged an unparalleled corporate drive for data ownership. - -Corporate responsibility regarding data privacy should have escalated in parallel with the relentless drive for data ownership but, until the General Data Protection Regulation (GDPR) came into force in May 2018, strong legislation was not in place to prevent the unethical distribution of personal data. - -GDPR is a set of laws that provide a legal framework for the data protection and privacy of all individuals within the European Union (EU) and the European Economic Area (EEA) whilst also addressing the export of personal data outside the EU and EEA areas. It aims to empower individuals by improving their right to self-determination regarding their personal data. However well intentioned, GDPR does not sufficiently define a concrete list of PII elements which is problematic when it comes to tech implementation and personal data processing. - -The Blinding Identity Taxonomy (BIT) was created to define a list of elements that could potentially unblind the identity of a person, an organization, or a thing. - -![Figure 2: The Blinding Identity Taxonomy is a list of 46 PII elements that could potentially unblind the identity of a person, an organization, or a thing.](figure-2.png) - -The BIT is one of those critical pieces of behind-the-scenes plumbing that is expected to fundamentally improve data protection of personal data as deployment rates in both traditional and distributed ledger technology (DLT) domains rise. - -In terms of ODCA implementation, issuers can reference the BIT and flag PII attributes in the schema bases. With PII attributes flagged at the base object layer, all corresponding data can be treated as sensitive throughout the data lifecycle and encrypted or removed at any stage, making identifying individuals impossible and thus guaranteeing their privacy. - -The BIT resides with Kantara Initiative, a non-profit industry consortium and professional trade association dedicated to advancing technical and legal innovation and trust framework operations related to digital identity management and data privacy. - -The latest version of the BIT is available at: - ->https://kantarainitiative.org/confluence/display/infosharing/Blinding+Identity+Taxonomy - -### Background - -In conjunction with the exponential rise of data capture, Satoshi Nakamoto’s groundbreaking white paper “Bitcoin: A Peer-to-Peer Electronic Cash System” was published in November 2008 triggering a peer-to-peer (P2P) computing revolution where files and transaction proofs could be shared directly between network nodes without the need of a central server. In 2009, Bitcoin became the first cryptocurrency to utilize a decentralized ledger to keep a record of all transactions taking place across a P2P network. It was not until the launch of Ethereum in July 2015, that the foundational technology, “blockchain”, would feature smart contract functionality giving rise to a golden age of DLT solutions that continue to mould a decentralized data economy. - -DLT solutions will continue to drive uniform data processing mechanisms, verifiable proof of consent, secure data portability and self-sovereign identity (SSI). With ODCA, a standardized global solution for data capture and exchange, community driven data standards, interoperable data capture objects and PII encryption capability can also be realized. - -It is ultimately a combination of these ingredients that will enable an improved ontology-driven approach to data management allowing data to be decentralized and better AI and IoT solutions to be built for societal benefit. - -### Methods - -Rather than a schema being created as a single data object, ODCA represents a schema as a multi-dimensional object consisting of a schema base and linked overlays. Each of these data objects serve a specific function in the overall schema definition which, when amalgamated, provide a set of metadata that adequately describes a single set of data. - -Each data object contains its own decentralized identifier (DID), a new type of identifier that is globally unique, resolvable with high availability, and cryptographically verifiable. In order for an overlay to be linked to a schema base, the DID of the base object must be referenced in the metadata block of the overlay. In other words, a linked overlay will contain both its own DID and, for coupling purposes, the DID of the schema base. - -#### Schema Base - -A schema base is a stable base object that defines a single set of data in its purest form thus providing a standard base from which to decentralize data. - -Apart from any metadata relating to the object, attribute names and types are defined in the schema base. The construct also facilitates a PII schema object which allows the issuer to flag PII attributes. With PII attributes flagged at the base layer, all corresponding data can be treated as sensitive throughout the data lifecycle and encrypted or removed at any stage thus protecting the identity of captured data subjects. - -The DID of the schema base is contained in the metadata and allows the object to remain immutable and interoperable in both traditional and DLT environments. - -![Figure 3: Example of a Schema Base. Attribute names and types are defined in the schema base. The construct also facilitates a PII schema object for flagging PII attributes.](figure-3.png) - -#### Source Overlay - -A source overlay is an optional linked object that can be used to specify an endpoint path containing a dynamic variable whose address is determined when the program is run. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the source overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -#### Encode Overlay - -An encode overlay is a core linked object that can be used to specify a character encoding standard (e.g. UTF-8, ISO-8859-1, Windows-1251, Base58Check, etc.) or character set (e.g. English, Japanese, Arabic, etc.) for the schema. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the encode overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -#### Entry Overlay - -An entry overlay is a core linked object that can be used to add predefined field values in a specified language to schema attributes. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the entry overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -![Figure 4: Example of an entry overlay. Predefined field values are defined in an entry overlay.](figure-4.png) - -#### Label Overlay - -A label overlay is a core linked object that can be used to add labels in a specified language to schema attributes and categories. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the label overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -![Figure 5: Example of a label overlay. Labels for schema attributes and categories are defined in a label overlay.](figure-5.png) - -#### Format Overlay - -A format overlay is a core linked object that can be used to add formats and field lengths to schema attributes. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the format overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -#### Conditional Overlay - -A conditional overlay is an optional linked object that can be used to add simple conditional logic within the schema definition to trigger certain actions. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the conditional overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -![Figure 6: Example of a conditional overlay. Simple conditional logic can be added to the schema definition to trigger certain actions. The logic is defined in a conditional overlay.](figure-6.png) - -#### Subset Overlay - -A subset overlay is an optional linked object that can be used to create a schema subset. - -DIDs for both the overlay and associated schema base are referenced in the metadata block of the subset overlay. The DID for the schema base can then be used as a coupling point to link the two data objects. - -![Figure 7: Example of a subset overlay. A schema subset is defined in a subset overlay.](figure-7.png) - -#### Sensitive Overlay (Holder Only) - -In contrast to other overlay types which are assigned by an issuer, a sensitive overlay is an optional object assigned by the data holder that can be used to flag user-defined sensitive attributes. For example, gender is not defined as a PII element in its most common presentation of male or female as, in isolation, it cannot identify an individual. However, Thailand has 18 different gender identities that are recognized in the local lexicon and, as such, may be deemed as sensitive to a Thai citizen. In this case, a sensitive overlay could be coupled to a data vault on a personal device or a data repository held by a trusted agent to flag the element. - -![Figure 8: Example of a sensitive overlay. User-defined sensitive attributes are defined in a sensitive overlay by the data holder. Rather than coupling the object to a schema base, a sensitive overlay can be coupled to a data vault on a personal device or a data repository held by a trusted agent.](figure-8.png) - -### Conclusion - -Primarily devised for data object interoperability and privacy compliant data sharing, ODCA significantly enhances the ability to pool data more effectively in terms of simplicity, accuracy, and allocation of resources. The degree of separation between schema bases and overlays allows multiple parties to use the same base objects for similar data capture requirements thus providing a standard base from which to decentralize data. - -ODCA aims to provide a standardized global solution for data capture and exchange which can facilitate a global decentralized lake containing non-PII data to be used for societal benefit. - -## Reference - -Provide guidance for implementers, procedures to inform testing, -interface definitions, formal function prototypes, error codes, -diagrams, and other technical details that might be looked up. -Strive to guarantee that: - -- Interactions with other features are clear. -- Implementation trajectory is well defined. -- Corner cases are dissected by example. - -## Drawbacks - -Why should we *not* do this? - -## Rationale and alternatives - -- Why is this design the best in the space of possible designs? -- What other designs have been considered and what is the rationale for not -choosing them? -- What is the impact of not doing this? - -## Prior art - -Discuss prior art, both the good and the bad, in relation to this proposal. -A few examples of what this can include are: - -- Does this feature exist in other SSI ecosystems and what experience have -their community had? -- For other teams: What lessons can we learn from other attempts? -- Papers: Are there any published papers or great posts that discuss this? -If you have some relevant papers to refer to, this can serve as a more detailed -theoretical background. - -This section is intended to encourage you as an author to think about the -lessons from other implementers, provide readers of your proposal with a -fuller picture. If there is no prior art, that is fine - your ideas are -interesting to us whether they are brand new or if they are an adaptation -from other communities. - -Note that while precedent set by other communities is some motivation, it -does not on its own motivate an enhancement proposal here. Please also take -into consideration that Aries sometimes intentionally diverges from common -identity features. - -## Unresolved questions - -- What parts of the design do you expect to resolve through the -enhancement proposal process before this gets merged? -- What parts of the design do you expect to resolve through the -implementation of this feature before stabilization? -- What related issues do you consider out of scope for this -proposal that could be addressed in the future independently of the -solution that comes out of this doc? - -## 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 ---- | --- - | | diff --git a/concepts/0017-attachments/README.md b/concepts/0017-attachments/README.md index f6dc843aa..2e193e236 100644 --- a/concepts/0017-attachments/README.md +++ b/concepts/0017-attachments/README.md @@ -1,8 +1,8 @@ # Aries RFC 0017: Attachments -- Authors: [Daniel Hardman](daniel.hardman@gmail.com), Sam Curren, Andrew Whitehead -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2019-01-31 +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com), Sam Curren, Andrew Whitehead +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Used in a number of other RFCs. - Start Date: 2018-12-24 - Tags: [concept](/tags.md#concept) diff --git a/concepts/0020-message-types/README.md b/concepts/0020-message-types/README.md index 18d119b56..804ae747d 100644 --- a/concepts/0020-message-types/README.md +++ b/concepts/0020-message-types/README.md @@ -1,7 +1,7 @@ # Aries RFC 0020: Message Types - Authors: Daniel Bluhm, Sam Curren -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-05-24 - Status Note: - Supersedes: [HIPE 0021 Message Types](https://github.com/hyperledger/indy-hipe/tree/main/text/0021-message-types) diff --git a/concepts/0021-didcomm-message-anatomy/README.md b/concepts/0021-didcomm-message-anatomy/README.md index 34e50ecfe..6ee2b9606 100644 --- a/concepts/0021-didcomm-message-anatomy/README.md +++ b/concepts/0021-didcomm-message-anatomy/README.md @@ -1,7 +1,7 @@ # Aries RFC 0021: DIDComm Message Anatomy -- Authors: [Tobias Looker](tobias.looker@mattr.global), [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) +- Authors: [Tobias Looker](mailto:tobias.looker@mattr.global), [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-05-25 - Start Date: 2019-05-25 - Tags: [concept](/tags.md#concept), [decorator](/tags.md#decorator) diff --git a/concepts/0029-message-trust-contexts/README.md b/concepts/0029-message-trust-contexts/README.md index a5e2815bb..80af2bc8c 100644 --- a/concepts/0029-message-trust-contexts/README.md +++ b/concepts/0029-message-trust-contexts/README.md @@ -1,9 +1,9 @@ # Aries RFC 0029: Message Trust Contexts -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [DEMONSTRATED](/README.md#demonstrated) -- Since: 2019-05-10 -- Status Note: Only implemented in one codebase and in the sample code here. +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: Not practically applied. - Supersedes: [Indy HIPE PR #120](https://github.com/hyperledger/indy-hipe/pull/120) - Start Date: 2018-02-10 (approx, backdated) - Tags: [concept](/tags.md#concept) diff --git a/concepts/0046-mediators-and-relays/README.md b/concepts/0046-mediators-and-relays/README.md index fe7f389d8..a24e82f0f 100644 --- a/concepts/0046-mediators-and-relays/README.md +++ b/concepts/0046-mediators-and-relays/README.md @@ -1,6 +1,6 @@ # Aries RFC 0046: Mediators and Relays -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [ACCEPTED](/README.md#accepted) - Since: 2019-02-01 - Status Note: Socialized and broadly understood in other conceptual RFCs about routing. @@ -245,3 +245,4 @@ Name / Link | Implementation Notes --- | --- [Connect.Me](https://www.evernym.com/blog/connect-me-sovrin-digital-wallet/) | Free mobile app from Evernym. Installed via app store on iOS and Android. [Verity](https://www.evernym.com/products/) | Commercially licensed enterprise agent, SaaS or on-prem. +[DIDComm mediator](https://github.com/Sirius-social/didcomm-mediator) | Open source cloud-based mediator with Firebase support. diff --git a/concepts/0047-json-ld-compatibility/README.md b/concepts/0047-json-ld-compatibility/README.md index d6c2749a8..fdde98d7c 100644 --- a/concepts/0047-json-ld-compatibility/README.md +++ b/concepts/0047-json-ld-compatibility/README.md @@ -1,6 +1,6 @@ # Aries RFC 0047: JSON-LD Compatibility -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [ACCEPTED](/README.md#accepted) - Since: 2019-02-20 - Status Note: Has guided Indy design choices for several months. Not yet ratified by greater Aries community. diff --git a/concepts/0049-repudiation/README.md b/concepts/0049-repudiation/README.md index e75bf153b..217c49f23 100644 --- a/concepts/0049-repudiation/README.md +++ b/concepts/0049-repudiation/README.md @@ -1,6 +1,6 @@ # Aries RFC 0049: Repudiation -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [ACCEPTED](/README.md#accepted) - Since: 2019-03-01 - Status Note: Well understood and baked into various protocol designs and DIDComm processes--but not yet ratified by the larger Aries community. diff --git a/concepts/0051-dkms/README.md b/concepts/0051-dkms/README.md index 5b39b6cc9..d3a0a9539 100644 --- a/concepts/0051-dkms/README.md +++ b/concepts/0051-dkms/README.md @@ -1,9 +1,9 @@ # Aries RFC 0051: Decentralized Key Management -- Authors: [Drummond Reed](drummond@connect.me) et al. -- Status: [DEMONSTRATED](/README.md#demonstrated) -- Since: 2019-03-29 -- Status Note: Somewhat familiar to many in the community, and influential in the designs of other RFCs--but not yet deeply explored or socialized. +- Authors: [Drummond Reed](mailto:drummond@connect.me) et al. +- Status: [RETIRED](/README.md#retired) +- Since: 2024-04-03 +- Status Note: Covered elsewhere and not specific to Aries. - Start Date: 2018-09-01 (approx, backdated) - Tags: [concept](/tags.md#concept) diff --git a/concepts/0094-cross-domain-messaging/README.md b/concepts/0094-cross-domain-messaging/README.md index c975c9c5c..604a0fba3 100644 --- a/concepts/0094-cross-domain-messaging/README.md +++ b/concepts/0094-cross-domain-messaging/README.md @@ -1,8 +1,8 @@ # Aries RFC 0094: Cross-Domain Messaging -- Authors: [Stephen Curran](swcurran@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2018-10-29 +- Authors: [Stephen Curran](mailto:swcurran@gmail.com) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Socialized and broadly understood in other conceptual RFCs about routing. - Supersedes: [0022-Cross-Domain-Messaging](https://github.com/hyperledger/indy-RFC/blob/master/text/0022-cross-domain-messaging/README.md) - Start Date: 2018-08-13 diff --git a/concepts/0207-credential-fraud-threat-model/README.md b/concepts/0207-credential-fraud-threat-model/README.md index 522eb7fd0..200494607 100644 --- a/concepts/0207-credential-fraud-threat-model/README.md +++ b/concepts/0207-credential-fraud-threat-model/README.md @@ -1,8 +1,8 @@ # 0207: Credential Fraud Threat Model -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-08-30 -- Status Note: socialized on an informal credential fraud study group (https://groups.google.com/d/forum/credential-fraud-study) since ~May 2019. +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. Socialized on an informal credential fraud study group (https://groups.google.com/d/forum/credential-fraud-study) circa 2019. - Start Date: 2019-05-23 - Tags: [concept](/tags.md#concept), [credentials](/tags.md#credentials) diff --git a/concepts/0217-linkable-message-paths/README.md b/concepts/0217-linkable-message-paths/README.md index a303c65fb..d2a5345d7 100644 --- a/concepts/0217-linkable-message-paths/README.md +++ b/concepts/0217-linkable-message-paths/README.md @@ -1,8 +1,8 @@ # Aries RFC 0217: Linkable Message Paths -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-09-10 -- Status Note: Purely theoretical at this point, but may be relevant to efforts to join subprotocols to superprotocols. Mentioned in [RFC 0214 "Help Me Discover" Protocol](../../features/0214-help-me-discover/README.md). +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Start Date: 2019-08-26 - Tags: [concept](/tags.md#concept) diff --git a/concepts/0231-biometric-service-provider/README.md b/concepts/0231-biometric-service-provider/README.md index 14396c869..78b6caca1 100644 --- a/concepts/0231-biometric-service-provider/README.md +++ b/concepts/0231-biometric-service-provider/README.md @@ -1,6 +1,6 @@ # Aries RFC 0231: Biometric Service Provider -- Authors: [John Callahan](jcallahan@acm.org), [Daniel Hardman](daniel.hardman@gmail.com), [Asem Othman](aothman@veridiumid.com) +- Authors: [John Callahan](mailto:jcallahan@acm.org), [Daniel Hardman](mailto:daniel.hardman@gmail.com), [Asem Othman](mailto:aothman@veridiumid.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-09-24 - Status Note: Proposed for now based on authors joint work diff --git a/concepts/0250-rich-schemas/README.md b/concepts/0250-rich-schemas/README.md index 6ca616744..953ea67fa 100644 --- a/concepts/0250-rich-schemas/README.md +++ b/concepts/0250-rich-schemas/README.md @@ -1,8 +1,8 @@ # RFC 0250: Rich Schema Objects -- Author: [Ken Ebert](ken@sovrin.org), [Brent Zundel](brent.zundel@evernym.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2019-10-08 -- Status Note: Port of [this HIPE](https://github.com/hyperledger/indy-hipe/tree/main/text/0119-rich-schemas/README.md) +- Author: [Ken Ebert](mailto:ken@sovrin.org), [Brent Zundel](mailto:brent.zundel@evernym.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No recent progress and no implementations have been created. - Supersedes: [this HIPE](https://github.com/hyperledger/indy-hipe/tree/main/text/0119-rich-schemas/README.md) - Start Date: 2019-03-19 - Tags: [concept](/tags.md#concept), [rich-schemas](/tags.md#rich-schemas) @@ -341,7 +341,7 @@ Here is the paper that defines [Camenisch-Lysyanskaya signatures.][CL-signatures] They are the source for [Indy's AnonCreds protocol](https://github.com/hyperledger/indy-hipe/pull/109). -[CL-signatures]: (https://groups.csail.mit.edu/cis/pubs/lysyanskaya/cl02b.pdf) +[CL-signatures]: https://groups.csail.mit.edu/cis/pubs/lysyanskaya/cl02b.pdf ## Drawbacks diff --git a/concepts/0257-private-credential-issuance/README.md b/concepts/0257-private-credential-issuance/README.md index 107af2adf..36a7c9335 100644 --- a/concepts/0257-private-credential-issuance/README.md +++ b/concepts/0257-private-credential-issuance/README.md @@ -1,8 +1,8 @@ # Aries RFC 0257: Private Credential Issuance - Authors: Daniel Hardman and Lovesh Harchandani -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-10-16 -- Status Note: under study +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No recent progress and no implementations have been created. - Start Date: 2019-08-26 - Tags: [concept](/tags.md#concept), [protocol](/tags.md#protocol) diff --git a/concepts/0268-unified-didcomm-agent-deeplinking/README.md b/concepts/0268-unified-didcomm-agent-deeplinking/README.md index 0d1526f78..353d49a30 100644 --- a/concepts/0268-unified-didcomm-agent-deeplinking/README.md +++ b/concepts/0268-unified-didcomm-agent-deeplinking/README.md @@ -1,8 +1,8 @@ # Aries RFC 0268: Unified DIDCOMM Deeplinking -- Authors: [Dev Bharel](dev@spaceman.id), [Alexi Falquier](alexis@spaceman.id) +- Authors: [Dev Bharel](mailto:dev@spaceman.id), [Alexi Falquier](mailto:alexis@spaceman.id) - Status: [PROPOSED](/README.md#proposed) -- Since: 2019-10-23 -- Status Note: Proposed +- Since: 2019-10-23 +- Status Note: Proposed - Start Date: 2018-10-04 - Tags: [concept](/tags.md#concept) @@ -69,6 +69,7 @@ Furthermore, messages must also be base64 encoded serialized jsons, stripped of This puts extra work on wallet developers to ensure a good experience. +On iOS only one app can be registered to handle `didcomm://` at a time; the first one to be installed will prevent others from using this custom scheme. ## Rationale and alternatives diff --git a/concepts/0270-interop-test-suite/README.md b/concepts/0270-interop-test-suite/README.md index 6a441493d..a4f350710 100644 --- a/concepts/0270-interop-test-suite/README.md +++ b/concepts/0270-interop-test-suite/README.md @@ -1,5 +1,5 @@ # 0270: Interop Test Suite -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-10-25 - Status Note: Codifies some thinking about scope and mental model that are already socialized. Provides some new thinking as well. diff --git a/concepts/0289-toip-stack/README.md b/concepts/0289-toip-stack/README.md index cbb87aa5b..8d4b10332 100644 --- a/concepts/0289-toip-stack/README.md +++ b/concepts/0289-toip-stack/README.md @@ -1,8 +1,8 @@ # 0289: The Trust Over IP Stack -- Authors: Matthew Davie, [Dan Gisolfi](dan.gisolfi@gmail.com), [Daniel Hardman](daniel.hardman@evernym.com), [John Jordan](john.jordan@gov.bc.ca), Darrell O'Donnell, [Drummond Reed](drummond.reed@evernym.com), [Oskar van Deventer](oskar.vandeventer@tno.nl) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-11-04 -- Status Note: Initial Proposal +- Authors: Matthew Davie, [Dan Gisolfi](mailto:dan.gisolfi@gmail.com), [Daniel Hardman](mailto:daniel.hardman@evernym.com), [John Jordan](mailto:john.jordan@gov.bc.ca), Darrell O'Donnell, [Drummond Reed](mailto:drummond.reed@evernym.com), [Oskar van Deventer](mailto:oskar.vandeventer@tno.nl) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No recent progress and no implementations have been created. - Start Date: 2019-01-01 - Tags: [concept](/tags.md#concept), stack, trust layer, governance framework diff --git a/concepts/0302-aries-interop-profile/README.md b/concepts/0302-aries-interop-profile/README.md index ac2760b16..91d415c49 100644 --- a/concepts/0302-aries-interop-profile/README.md +++ b/concepts/0302-aries-interop-profile/README.md @@ -1,7 +1,7 @@ # 0302: Aries Interop Profile - Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca), [John Jordan](mailto:john.jordan@gov.bc.ca) Province of British Columbia -- Status: [ACCEPTED](https://github.com/hyperledger/aries-rfcs/blob/main/README.md#accepted) +- Status: [ADOPTED](https://github.com/hyperledger/aries-rfcs/blob/main/README.md#adopted) - Since: 2021-01-06 - Status Note: This RFC defines an Aries Interop Profile process and Aries Interop Profile versions - Supersedes: @@ -19,7 +19,7 @@ This RFC defines the process for the community of Aries agent builders to: 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](#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](#reference) section MAY include one ".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. +At all times, the [Reference](#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](#reference) section MAY include one `.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. @@ -47,7 +47,7 @@ The establishment of Aries Interop Profile versions defined by the Aries agent b 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. +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. @@ -112,13 +112,21 @@ Concept | [0050-wallets](https://github.com/hyperledger/aries-rfcs/tree/64e5e55c Concept | [0094-cross-domain messaging](https://github.com/hyperledger/aries-rfcs/tree/64e5e55c123b2efaf38f4b0911a71a1c40a7f29d/concepts/0094-cross-domain-messaging) Feature | [0015-acks](https://github.com/hyperledger/aries-rfcs/tree/5cc750f0fe18e3918401489066566f22474e25a8/features/0015-acks) Feature | [0019-encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/9b0aaa39df7e8bd434126c4b33c097aae78d65bf/features/0019-encryption-envelope) -Feature | [0160-connection-protocol](https://github.com/hyperledger/aries-rfcs/tree/9b0aaa39df7e8bd434126c4b33c097aae78d65bf/features/0160-connection-protocol) +Feature | [0160-connection-protocol](https://github.com/hyperledger/aries-rfcs/tree/4d9775490359e234ab8d1c152bca6f534e92a38d/features/0160-connection-protocol) Feature | [0025-didcomm-transports](https://github.com/hyperledger/aries-rfcs/tree/b490ebe492985e1be9804fc0763119238b2e51ab/features/0025-didcomm-transports) Feature | [0035-report-problem](https://github.com/hyperledger/aries-rfcs/tree/89d14c15ab35b667e7a9d04fe42d4d48b10468cf/features/0035-report-problem) Feature | [0036-issue-credential](https://github.com/hyperledger/aries-rfcs/tree/bb42a6c35e0d5543718fb36dd099551ab192f7b0/features/0036-issue-credential) Feature | [0037-present-proof](https://github.com/hyperledger/aries-rfcs/tree/4fae574c03f9f1013db30bf2c0c676b1122f7149/features/0037-present-proof) Feature | [0056-service-decorator](https://github.com/hyperledger/aries-rfcs/tree/527849ec3aa2a8fd47a7bb6c57f918ff8bcb5e8c/features/0056-service-decorator) +#### Changelog - AIP 1.0 + +The original commit used in the definition of AIP 1.0 was: 64e5e55c123b2efaf38f4b0911a71a1c40a7f29d + +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. @@ -139,7 +147,7 @@ The following are the goals used in selecting RFC versions for inclusion in AIP - 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, 0587 + - RFCs 0044, 0360, 0334 - Use protocols and standards that support multiple ledger types and verifiable credential formats. - RFCs 0434, 0023, 0453, 0454 @@ -147,75 +155,140 @@ The following are the goals used in selecting RFC versions for inclusion in AIP - 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](https://github.com/hyperledger/aries-rfcs/pull/724) + +- 2022-06: RFC 0023 DID Exchange, RFC 0025 DIDComm Transports, RFC 0434 Out of Band + - Pull request: [#739](https://github.com/hyperledger/aries-rfcs/pull/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](#aip-20-rfcs-removed) section for details about the removed RFCs + - See the updated [implementer's note on encryption envelopes in AIP 2.0](#implementers-note-about-didcomm-envelopes-and-the-accept-element) that highlights the removal of RFC 0587-encryption-envelope-v2. + - Pull request: [#814](https://github.com/hyperledger/aries-rfcs/pull/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](#aip-20-rfcs-removed) section for details about the removed RFCs + - Pull request: [#820](https://github.com/hyperledger/aries-rfcs/pull/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](https://github.com/hyperledger/aries-rfcs/tree/7abf421a5d8452535c95321f66cb50ff52567f37/concepts/0003-protocols) | [AIP V1.0, Reformatted](https://gist.github.com/swcurran/6976dc1fd1b10c51343cf3812288b345/revisions?diff=unified) -Concept | [0004-agents](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0004-agents) | AIP V1.0, Unchanged -Concept | [0005-didcomm](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0005-didcomm) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/788195ea0bccec53e1f9fe3509034341/revisions?diff=unified) -Concept | [0008-message-id-and-threading](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0008-message-id-and-threading) | [AIP V1.0, Updated](https://gist.github.com/swcurran/db72109ea4f2e336ac91f4fbab3f4048/revisions?diff=unified) -Concept | [0011-decorators](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0011-decorators) | [AIP V1.0, Updated](https://gist.github.com/swcurran/04229583a509f12258352f9c85b9c9b6/revisions?diff=unified) +Concept | [0003-protocols](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0003-protocols) | [AIP V1.0, Reformatted](https://gist.github.com/swcurran/6976dc1fd1b10c51343cf3812288b345/revisions?diff=unified) +Concept | [0004-agents](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/concepts/0004-agents) | AIP V1.0, Unchanged +Concept | [0005-didcomm](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0005-didcomm) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/788195ea0bccec53e1f9fe3509034341/revisions?diff=unified) +Concept | [0008-message-id-and-threading](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0008-message-id-and-threading) | [AIP V1.0, Updated](https://gist.github.com/swcurran/db72109ea4f2e336ac91f4fbab3f4048/revisions?diff=unified) +Concept | [0011-decorators](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0011-decorators) | [AIP V1.0, Updated](https://gist.github.com/swcurran/04229583a509f12258352f9c85b9c9b6/revisions?diff=unified) Concept | [0017-attachments](https://github.com/hyperledger/aries-rfcs/tree/7759addb1506d107fddec692403bbc9e55fe491f/concepts/0017-attachments) | [AIP V1.0, Updated](https://gist.github.com/swcurran/7d88f9866175af96a70e5c6c00fa0148/revisions?diff=unified) -Concept | [0020-message-types](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0020-message-types) | [AIP V1.0, Updated](https://gist.github.com/swcurran/8f95c25b5c778426d3a47fe6d7c46c70/revisions?diff=unified)
Mandates message prefix `https://didcomm.org` for Aries Protocol messages. -Concept | [0046-mediators-and-relays](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0046-mediators-and-relays) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/2486b63615f7a36c1e997b6c8b10c245/revisions?diff=unified) -Concept | [0047-json-LD-compatibility](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0047-json-ld-compatibility) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/8ef311d793fc6964328687af3c0efd34/revisions?diff=unified) -Concept | [0050-wallets](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0050-wallets) | AIP V1.0, Unchanged +Concept | [0020-message-types](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0020-message-types) | [AIP V1.0, Updated](https://gist.github.com/swcurran/8f95c25b5c778426d3a47fe6d7c46c70/revisions?diff=unified)
Mandates message prefix `https://didcomm.org` for Aries Protocol messages. +Concept | [0046-mediators-and-relays](https://github.com/hyperledger/aries-rfcs/tree/45b4233fcffda14f1339380ae2233289f21296b0/concepts/0046-mediators-and-relays) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/2486b63615f7a36c1e997b6c8b10c245/revisions?diff=unified) +Concept | [0047-json-LD-compatibility](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/concepts/0047-json-ld-compatibility) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/8ef311d793fc6964328687af3c0efd34/revisions?diff=unified) +Concept | [0050-wallets](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/concepts/0050-wallets) | AIP V1.0, Unchanged Concept | [0094-cross-domain messaging](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0094-cross-domain-messaging) | [AIP V1.0, Updated](https://gist.github.com/swcurran/e3f27e3ab85a260aaf279352ecc4e1fb/revisions?diff=unified) -Concept | [0519-goal-codes](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/concepts/0519-goal-codes) | :new: -Feature | [0015-acks](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0015-acks) | [AIP V1.0, Updated](https://gist.github.com/swcurran/81af391bfd79539edec530150045fe51/revisions?diff=unified) -Feature | [0019-encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0019-encryption-envelope) | [AIP V1.0, Updated](https://gist.github.com/swcurran/c652dfd39706e50be4145568797e667a/revisions?diff=unified)
See envelope note below -Feature | [0023-did-exchange](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0023-did-exchange) | :new: -Feature | [0025-didcomm-transports](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0025-didcomm-transports) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/1e64cba5f6c524d38ad596209df090df/revisions?diff=unified) -Feature | [0035-report-problem](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0035-report-problem) | [AIP V1.0, Updated](https://gist.github.com/swcurran/d9432abc436e6a069d6ffcd41dc86060/revisions?diff=unified) -Feature | [0044-didcomm-file-and-mime-types](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0044-didcomm-file-and-mime-types) | :new: -Feature | [0048-trust-ping](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0048-trust-ping) | :new: -Feature | [0183-revocation-notification](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0183-revocation-notification) | :new: -Feature | [0360-use-did-key](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0360-use-did-key) | :new: -Feature | [0434-outofband](https://github.com/hyperledger/aries-rfcs/tree/bed4989dd6517f7a9de3696800e57e4c6ef49231/features/0434-outofband) | :new: -Feature | [0453-issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0453-issue-credential-v2) | Update to V2 Protocol -Feature | [0454-present-proof-v2](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0454-present-proof-v2) | Update to V2 Protocol +Concept | [0519-goal-codes](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/concepts/0519-goal-codes) | :new: +Feature | [0015-acks](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0015-acks) | [AIP V1.0, Updated](https://gist.github.com/swcurran/81af391bfd79539edec530150045fe51/revisions?diff=unified) +Feature | [0019-encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0019-encryption-envelope) | [AIP V1.0, Updated](https://gist.github.com/swcurran/c652dfd39706e50be4145568797e667a/revisions?diff=unified)
See envelope note below +Feature | [0023-did-exchange](https://github.com/hyperledger/aries-rfcs/tree/bf3d796cc33ce78ed7cde7f5422b10719a68be21/features/0023-did-exchange) | :new: +Feature | [0025-didcomm-transports](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0025-didcomm-transports) | [AIP V1.0, Minimally Updated](https://gist.github.com/swcurran/1e64cba5f6c524d38ad596209df090df/revisions?diff=unified) +Feature | [0035-report-problem](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0035-report-problem) | [AIP V1.0, Updated](https://gist.github.com/swcurran/d9432abc436e6a069d6ffcd41dc86060/revisions?diff=unified) +Feature | [0044-didcomm-file-and-mime-types](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0044-didcomm-file-and-mime-types) | :new: +Feature | [0048-trust-ping](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0048-trust-ping) | :new: +Feature | [0183-revocation-notification](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/features/0183-revocation-notification) | :new: +Feature | [0360-use-did-key](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/features/0360-use-did-key) | :new: +Feature | [0434-outofband](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0434-outofband) | :new: +Feature | [0453-issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/e8a23a7b80db5db5a12fd786aec9343116cf5147/features/0453-issue-credential-v2) | Update to V2 Protocol +Feature | [0454-present-proof-v2](https://github.com/hyperledger/aries-rfcs/tree/e8a23a7b80db5db5a12fd786aec9343116cf5147/features/0454-present-proof-v2) | Update to V2 Protocol Feature | [0557-discover-features-v2](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0557-discover-features-v2) | :new: -Feature | [0627-static-peer-dids](https://github.com/hyperledger/aries-rfcs/tree/4739fbf6de07a54c3fee072bd85741422730b3cd/features/0627-static-peer-dids) | :new: #### MEDIATE: Mediator Coordination RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0211-route-coordination](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0211-route-coordination) | :new: +Feature | [0211-route-coordination](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0211-route-coordination) | :new: Feature | [0092-transport-return-route](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0092-transport-return-route) | :new: #### INDYCRED: Indy Based Credentials RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0592-indy-attachments](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0592-indy-attachments) | :new: Evolved from AIP V1.0 -Concept | [0441-present-proof-best-practices](https://github.com/hyperledger/aries-rfcs/tree/910d79aa72a9e656f0003b4eab5d49549cca361e/concepts/0441-present-proof-best-practices) | :new: +Feature | [0592-indy-attachments](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0592-indy-attachments) | :new: Evolved from AIP V1.0 +Concept | [0441-present-proof-best-practices](https://github.com/hyperledger/aries-rfcs/tree/4e78319e5f79df2003ddf37f8f497d0fae20cc63/concepts/0441-present-proof-best-practices) | :new: #### LDCRED: JSON-LD Based Credentials RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0593-json-ld-cred-attach](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0593-json-ld-cred-attach) | :new: -Feature | [0510-dif-pres-exch-attach](https://github.com/hyperledger/aries-rfcs/tree/7a44f650d3cebf5b3047c1680618978393a497d5/features/0510-dif-pres-exch-attach) | :new: +Feature | [0593-json-ld-cred-attach](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0593-json-ld-cred-attach) | :new: +Feature | [0510-dif-pres-exch-attach](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0510-dif-pres-exch-attach) | :new: #### BBSCRED: BBS+ Based Credentials RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0593-json-ld-cred-attach](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0593-json-ld-cred-attach) | :new: +Feature | [0593-json-ld-cred-attach](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0593-json-ld-cred-attach) | :new: Feature | [0646-bbs-credentials](https://github.com/hyperledger/aries-rfcs/blob/7a44f650d3cebf5b3047c1680618978393a497d5/features/0646-bbs-credentials/README.md) | :new: -Feature | [0510-dif-pres-exch-attach](https://github.com/hyperledger/aries-rfcs/tree/7a44f650d3cebf5b3047c1680618978393a497d5/features/0510-dif-pres-exch-attach) | :new: +Feature | [0510-dif-pres-exch-attach](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0510-dif-pres-exch-attach) | :new: + +#### CHAT: Chat related features -#### DIDCOMMV2PREP: DIDComm v2 Prep RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0587-encryption-envelope-v2](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0587-encryption-envelope-v2) | :new:
See envelope note below +Feature | [0095-basic-message](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0095-basic-message) | :new: + +#### 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. -#### CHAT: Chat related features RFC Type | RFC/Link to RFC Version | Note --- | --- | --- -Feature | [0095-basic-message](https://github.com/hyperledger/aries-rfcs/tree/b3a3942ef052039e73cd23d847f42947f8287da2/features/0095-basic-message) | :new: +Feature | [0317-please-ack](https://github.com/hyperledger/aries-rfcs/tree/e8a23a7b80db5db5a12fd786aec9343116cf5147/features/0317-please-ack) | Removed from AIP 2.0 +Feature | [0587-encryption-envelope-v2](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/0587-encryption-envelope-v2) | Removed from AIP 2.0 +Feature | [0627-static-peer-dids](https://github.com/hyperledger/aries-rfcs/tree/c3b0e2120ad24810598375663b6922b980f85d00/features/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](https://github.com/hyperledger/aries-rfcs/tree/main/features/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]. + +[DID Peer]: https://identity.foundation/peer-did-method-spec/ #### AIP v2.0 Test Suite @@ -223,25 +296,18 @@ The [Aries Agent Test Harness](https://github.com/hyperledger/aries-agent-test-h #### Implementers Note about DIDComm Envelopes and the `ACCEPT` element -AIP 2.0 contains two RFCs that reference envelopes 0019-encryption-envelope and 0587-encryption-envelope-v2 (links above). +> [!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. - -#### Changelog - AIP 2.0 - -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: - -- RFC 0003 Protocols: A correction to the tic-tac-toe example protocol was made. -- RFC 0017 Attachments: A clarification was made around the use of base64url encoding/decoding. -- RFC 0434 Out of Band: The RFC status was changed to "Accepted." -- RFC 0627 Static Peer DIDs: The RFC status was changed to "Accepted." -- RFC 0441 Present Proof Best Practices: A convention for representing dates to enable simple "older than" predicates was added. -- RFC 0510 DIF Presentation Exchange Attachment: The RFC Status was changed to "Accepted." -- RFC 0646 BBS Credentials: The RFC Status was changed to "Accepted." +the agent does support. See the RFCs for additional details.~~ ### Previous Versions diff --git a/concepts/0345-community-coordinated-update/README.md b/concepts/0345-community-coordinated-update/README.md index 6669414e4..51f666d6c 100644 --- a/concepts/0345-community-coordinated-update/README.md +++ b/concepts/0345-community-coordinated-update/README.md @@ -1,5 +1,5 @@ # 0345: Community Coordinated Update -- Authors: [Sam Curren](telegramsam@gmail.com) +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-12-26 (date you submit your PR) - Status Note: Initial Draft diff --git a/concepts/0346-didcomm-between-two-mobile-agents/README.md b/concepts/0346-didcomm-between-two-mobile-agents/README.md index 56bf052d7..a5531134b 100644 --- a/concepts/0346-didcomm-between-two-mobile-agents/README.md +++ b/concepts/0346-didcomm-between-two-mobile-agents/README.md @@ -1,5 +1,5 @@ # 0346: DIDComm Between Two Mobile Agents Using Cloud Agent Mediator -- Author: [Sukalpo Mitra](sukalpomitra@gmail.com) +- Author: [Sukalpo Mitra](mailto:sukalpomitra@gmail.com) - Start Date: 2019-06-23 - Tags: [concept](/tags.md#concept) - Status: [PROPOSED](/README.md#proposed) diff --git a/concepts/0420-rich-schemas-common/README.md b/concepts/0420-rich-schemas-common/README.md index dfc085988..e692d652a 100644 --- a/concepts/0420-rich-schemas-common/README.md +++ b/concepts/0420-rich-schemas-common/README.md @@ -1,8 +1,8 @@ # 0420: Rich Schema Objects Common - Author: [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com), [Brent Zundel](mailto:brent.zundel@evernym.com), [Ken Ebert](mailto:ken@sovrin.org) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-02-13 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No recent progress and no implementations have been created. - Start Date: 2020-02-05 - Tags: [concept](/tags.md#concept), [rich-schemas](/tags.md#rich-schemas) diff --git a/concepts/0430-machine-readable-governance-frameworks/README.md b/concepts/0430-machine-readable-governance-frameworks/README.md index 47f2eabe1..1bd706926 100644 --- a/concepts/0430-machine-readable-governance-frameworks/README.md +++ b/concepts/0430-machine-readable-governance-frameworks/README.md @@ -1,5 +1,5 @@ # Aries RFC 0430: Machine-Readable Governance Frameworks -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2020-02-24 - Status Note: early proposal only diff --git a/concepts/0440-kms-architectures/README.md b/concepts/0440-kms-architectures/README.md index cb872cd9d..a9c6eeba6 100644 --- a/concepts/0440-kms-architectures/README.md +++ b/concepts/0440-kms-architectures/README.md @@ -1,5 +1,5 @@ # 0440: KMS Architectures -- Authors: [Michael Lodder](mike@sovrin.org) +- Authors: [Michael Lodder](mailto:mike@sovrin.org) - Status: [PROPOSED](/README.md#proposed) - Since: 2020-03-06 - Status Note: Proposed diff --git a/concepts/0441-present-proof-best-practices/README.md b/concepts/0441-present-proof-best-practices/README.md index 92e446811..97d864388 100644 --- a/concepts/0441-present-proof-best-practices/README.md +++ b/concepts/0441-present-proof-best-practices/README.md @@ -1,8 +1,8 @@ # 0441: Prover and Verifier Best Practices for Proof Presentation -- Authors: [Stephen Klump](stephen.klump@becker-carroll.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-04-15 -- Status Note: Interoperability guidance when using Indy AnonCreds Present Proof. An element of the Indy AnonCreds subtarget for [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md). +- Authors: [Stephen Klump](mailto:stephen.klump@becker-carroll.com) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 +- Status Note: Interoperability guidance when using AnonCreds Present Proof. An element of the AnonCreds subtarget for [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md). - Start Date: 2020-10-31 - Tags: [concept](/tags.md#concept), [credentials](/tags.md#credentials) diff --git a/concepts/0478-coprotocols/README.md b/concepts/0478-coprotocols/README.md index 583765d0b..5bfae4d9f 100644 --- a/concepts/0478-coprotocols/README.md +++ b/concepts/0478-coprotocols/README.md @@ -1,8 +1,8 @@ # Aries RFC 0478: Coprotocols -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-05-19 -- Status Note: Sister RFC to [Aries RFC 0482](../../features/0482-coprotocol-protocol/README.md), which documents a specific protocol to facilitate protocol interactions. Socialized on Aries community call in Feb 2020, using [these slides](https://docs.google.com/presentation/d/17hk6QqLW5M9E4TBPZwXIUBu9eEinMNXReceyZTF4LpA/edit). Discussed again in May 2020. Source files for graphics are either checked in or are published at https://j.mp/2XgyjH3. +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No recent progress and no implementations have been created. - Start Date: 2020-02-03 - Tags: [concept](/tags.md#concept), [protocol](/tags.md#protocol) diff --git a/concepts/0519-goal-codes/README.md b/concepts/0519-goal-codes/README.md index 052f86155..5a4bb89f8 100644 --- a/concepts/0519-goal-codes/README.md +++ b/concepts/0519-goal-codes/README.md @@ -1,5 +1,5 @@ # 0519: Goal Codes -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [ACCEPTED](/README.md#accepted) - Since: 2021-04-15 - Status Note: Used in several protocols that are part of [AIP 2.0](../0302-aries-interop-profile/README.md), such as the [Out-of-Band](../../features/0434-outofband/README.md) protocol. @@ -126,17 +126,41 @@ aries | Hyperledger Aries Community | TBD The following goal codes are defined here because they already have demonstrated utility, based on early SSI work in Aries and elsewhere. ##### `aries.vc` + Participate in some form of VC-based interaction. + ##### `aries.vc.issue` + Issue a verifiable credential. + ##### `aries.vc.verify` + Verify or validate VC-based assertions. + ##### `aries.vc.revoke` + Revoke a VC. + ##### `aries.rel` -Create, maintain, or end something that humans would consider a relationship. This should not to be confused with building a DIDComm channel. (Building a DIDComm channel is a low-level procedure, not a high-level goal.) + +Create, maintain, or end something that humans would consider a relationship. +This may be accomplished by establishing, updating or deleting a DIDComm +messaging connection that provides a secure communication channel for the +relationship. The DIDComm connection itself is not the relationship, but would +be used to carry out interactions between the parties to facilitate the +relationship. + ##### `aries.rel.build` -Create a relationship. Carries the meaning implied today by a LinkedIn invitation to connect or a Facebook "Friend" request. + +Create a relationship. Carries the meaning implied today by a LinkedIn +invitation to connect or a Facebook "Friend" request. Could be as limited +as creating a DIDComm Connection. + +##### `aries.vc.verifier.once` + +Create a DIDComm connection for the sole purpose of doing the one-time execution of a [Present Proof](/features/0454-present-proof-v2/README.md) protocol. Once the protocol execution is complete, both sides **SHOULD** delete the connection, as it will not be used again by either side. + +The purpose of the goal code flow is to accomplish the equivalent of a "connection-less" present proof by having the agents establish a DIDComm connection, execute the present proof protocol, and delete the connection. The need for this goal code is when an actual connection-less present proof cannot be used because the [out-of-band](/features/0434-outofband/README.md) (OOB) message (including the presentation request) is too large for the transport being used--most often a QR code (although it may be useful for Bluetooth scenarios as well)--and a URL shortner option is not available. By using a one-time connection, the OOB message is small enough to fit into easily into a QR code, the present proof protocol can be executed using the established connection, and at the end of the interaction, no connection remains for either side to use or manage. ## Implementations diff --git a/concepts/0530-goal-human-readable-verified-identifer/README.md b/concepts/0530-goal-human-readable-verified-identifer/README.md new file mode 100644 index 000000000..943b36320 --- /dev/null +++ b/concepts/0530-goal-human-readable-verified-identifer/README.md @@ -0,0 +1,57 @@ +# Aries RFC 0530: Goal - Human Readable Verifiable Identifier + +- Authors: [Sam Curren](telegramsam@gmail.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2020-08-26 +- Status Note: Early Proposal +- Start Date: 2020-08-26 +- Tags: goalcode + +## Summary + +DIDs are not human friendly. DIDComm provides a secure connection between two DIDs. This goal code seeks to provide a verifiable, human readable identifier from one party to another. + +## Motivation + +Presenting a Human Readable Verifiable Identifier over a DIDComm connection aids the user in positive connection identification. It also plays a role in Man-in-the-Middle (MitM) attack prevention. + +## Reference + +### Goal Code + +`aries.receive.verifiable.identifier` + +### Explanation + +The party presenting this goal code has a goal of receiving a human readable verifiable identifier from the party it presents it to. + +### Key Concepts + +Human Readable implies that the identifier is meaningful to a human. This might be an identifier already used to communicate, such as an email address, phone number, website domain name, or social media account name. + +A Verifiable identifier requires that some level of assurance is provided that control has been proven over the identifier. + +Governance Frameworks that serve this goal code must provide details about which identifiers are acceptable, and how they are to be verified. + +## Governance Frameworks + +The following Governance Frameworks are related to this goal code. + +- Domain Control +- Email Ownership + +## Unresolved questions + +- + +## Implementations + +> NOTE: This section should remain in the RFC as is on first release. Remove this note and leave the rest of the text as is. Template text in all other sections should be removed before submitting your Pull Request. + +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](README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | diff --git a/concepts/0559-pppu/README.md b/concepts/0559-pppu/README.md index 3256d526f..8ae7669e3 100644 --- a/concepts/0559-pppu/README.md +++ b/concepts/0559-pppu/README.md @@ -1,5 +1,5 @@ # Aries RFC 0559: Privacy-Preserving Proof of Uniqueness -- Authors: [Daniel Hardman](daniel.hardman@gmail.com), Drummond Reed, Lovesh Harchandani, Jason Law, Brent Zundel +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com), Drummond Reed, Lovesh Harchandani, Jason Law, Brent Zundel - Status: [PROPOSED](/README.md#proposed) - Since: 2020-10-21 - Status Note: documents ideas mentioned at RWOT 9 (Sep 2019) and in informal conversations before and since. This is a defensive publication by the Aries community, to prevent such ideas from being encumbered by patents. diff --git a/concepts/0566-issuer-hosted-custodidal-agents/README.md b/concepts/0566-issuer-hosted-custodidal-agents/README.md index bdf5b8515..3e3ad9a43 100644 --- a/concepts/0566-issuer-hosted-custodidal-agents/README.md +++ b/concepts/0566-issuer-hosted-custodidal-agents/README.md @@ -1,5 +1,5 @@ # 0566: Issuer-Hosted Custodial Agents -- Authors: [Sam Curren](telegramsam@gmail.com) +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2020-11-16 - Status Note: Draft diff --git a/concepts/0700-oob-through-redirect/README.md b/concepts/0700-oob-through-redirect/README.md index 0c0bbbcfc..14dfdd1bf 100644 --- a/concepts/0700-oob-through-redirect/README.md +++ b/concepts/0700-oob-through-redirect/README.md @@ -1,6 +1,6 @@ # Aries RFC 0700: Out-of-Band through redirect -- Authors: [Sudesh Shetty](sudesh.shetty@securekey.com) +- Authors: [Sudesh Shetty](mailto:sudesh.shetty@securekey.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2021-10-08 - Status Note: implementation is being explored by SecureKey diff --git a/concepts/0757-push-notification/README.md b/concepts/0757-push-notification/README.md new file mode 100644 index 000000000..af4b219a0 --- /dev/null +++ b/concepts/0757-push-notification/README.md @@ -0,0 +1,57 @@ +# 0757: Push Notification +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2022-11-02 +- Status Note: +- Start Date: 2022-11-02 +- Tags: [concept](/tags.md#concept) + +## Summary + +This RFC Describes the general concept of push notification as it applies to Aries Agents. There are a variety of push notification systems and methods, each of which is described in it's own feature RFC. + +> Note: These protocols operate only between a mobile app and it's mediator(s). There is no requirement to use these protocols when mobile apps and mediator services are provided as a bundle. These protocols exist to facilitate cooperation between open source mediators and mobile apps not necessarily developed between the same parties. + +## Motivation + +Mobile agents typically require the use of Mediators to receive DIDComm Messages. When messages arrive at a mediator, it is optimal to send a push notification to the mobile device to signal that a message is waiting. This provides a good user experience and allows mobile agents to be responsive without sacrificing battery life by routinly checking for new messages. + +## Tutorial + +Though push notification is common mobile platforms, there are a variety of different systems with various requirements and mecanisms. Most of them follow a familiar pattern: + +#### Setup Phase +1. Notification Sender (mediator) registers with a push notification service. This typically involves some signup procedure. +2. Notification Recipient (mobile app) registers with the push notification service. This typically involves some signup procedure. For some platforms, or for a mediator and mobile app by the same vendor, this will be accomplished in step 1. +3. Notification Recipient (mobile app) adds code (with config values obtained in step 2) to connect to the push notification service. +4. Notification Recipient (mobile app) communicates necessary information to the Notification Sender (mediator) for use in sending notifications. + +#### Notification Phase +5. A message arrives at the Notification Sender (mediator) destined for the Notification Recipient (mobile app). +6. Notification Sender (mediator) calls an API associated with the push notification service with notification details, typically using the information obtained in step 4. +7. Notification Recipient (mobile app) is notified (typically via a callback function) of the notification details. +8. Notification Recipient (mobile app) then connects to the Notification Sender (mediator) and receives waiting messages. + +In spite of the flow similarities between the push notification platforms, the implementations, libraries used, and general code paths vary substantially. +Each push notification method is described in it's own protocol. This allows the protocol to fit the specific needs and terminology of the notification method it enables. Feature Discovery can be used between the Notification Sender and the Notification Recipient to discover push notification compatibility. + +### Public Mediators + +Some push notification methods require matching keys or secrets to be used in both sending and receiving notifications. This requirement makes these push notification methods unusable by public mediators. + +Public mediators SHOULD only implement push notification methods that do not require sharing secrets or keys with application implementations. + +## Push Notification Protcols + +0699 - [Push Notification APNS 1.0](../../features/0699-push-notifications-apns/README.md) (Apple Push Notification Service) + +## 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](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | + diff --git a/concepts/0781-trust-input-protocol/README.md b/concepts/0781-trust-input-protocol/README.md new file mode 100644 index 000000000..aad9f021f --- /dev/null +++ b/concepts/0781-trust-input-protocol/README.md @@ -0,0 +1,185 @@ + +# RFC 0781 Trust Input Protocol +- Authors: Mathieu Glaude, Subhasis Ojha +- Status: PROPOSED +- Since: 2023-11-23 +- Status Note: New RFC being proposed +- Supersedes: None +- Start Date: 2023-11-23 + + ## Summary + + The Trust Input Protocol is a conceptual framework designed to assist with the making of trust decisions within digital interactions. It emphasizes the importance of both technical (cryptographic) trust and human trust. The protocol introduces the concept of "Trust Inputs," which are sources of information that assist entities in making trust decisions. For the purpose of this RFC, trust inputs may only come from Trust Registries that support DIDComm-based messaging, based on [RFC 0160: Connection Protocol](https://github.com/hyperledger/aries-rfcs/blob/main/features/0160-connection-protocol/README.md). The first use case that this framework looks to support is allowing verifiers of a digital credential proof presentation to query the authoritativeness of digital credential issuers against trust registries. + + ## Motivation + +The primary motivation for creating a Trust Input Protocol is to address the challenges of establishing trust in digital interactions. As digital transactions become more prevalent, there's a growing need to ensure that parties can trust each other, especially in contexts where real or perceived risks are involved. Traditional cryptographic methods provide technical trust, ensuring that data hasn't been altered or falsified. However, they don't address the human aspect of trust, such as verifying the authenticity of a claim or ensuring that a claim has been issued by a recognized authority. The Trust Input Protocol aims to bridge this gap by providing a framework where parties can seek trust inputs from various sources to make informed trust decisions. Although we focus on trust registries in the short-term, we imagine this protocol being capable of allowing trust decision making entities to seek inputs from sources outside of trust registries. For this reason, we will use the broader term `trust-input`. + +![Making a trust decision](https://github.com/Northern-Block/trustinputprotocol/blob/main/trust-inputs-flow.png) + +This above diagram was taken from a June 29, 2023 presentation given to the Trust over IP Foundation ([Slides](https://docs.google.com/presentation/d/1UMacqKZOEXiisNMz38_47FmJBUj69XePcTg9WbUCJtw/edit?usp=sharing), [Recording](https://zoom.us/rec/share/Hx-3oOZBL_vIPgf-2I6zP7QuBdQNKki4yULa2U71-VMvIrXUrS21HBAobYKBoUV5.gDEK5BKn5yJUq7nN)). + +Trust registries are authoritative sources of information that we can use as inputs to make trust decisions. In the digital credentialing world, we can imagine sometimes needing to check an authoritative source to know if a credential was issued by an authority. And the reason for a protocol? We want to make sure we avoid building proprietary solutions and rather work with the community to develop standards and protocols that can be used by any implementer. + +Inspiration for this protocol was taken from [RFC 0113: Question Answer Protocol](https://github.com/hyperledger/aries-rfcs/blob/main/features/0113-question-answer/README.md). We have gone beyond this protocol by adding structure to it, since we need a standard method for requesting for authorization related to credential issuance contexts. + + ## Tutorial + + This RFC introduces a protocol for interacting with trust registries. The identifier for the message family used by this protocol is `trust-input`, and the fully qualified URI for its definition is: + + *https://didcomm.org/trust-input/1.0* + + ## Roles + + There are two roles in the `trust-input` protocol: `requestor` and `trust-registry`. The `requestor` asks the `trust-registry` if credential metadata of a verifiable credential shared by a holder was issued by an authorized issuer, and the `trust-registry` responds with an answer. Any type of entity can be a requestor and inquire about the authority of an issuing entity. All the requests sent by the requestor are sent in a single message type, and the same is true for the response from the `trust-registry`. + + ## States + + This is a classic two-step request~response interaction, so it uses the predefined state machines for any `requestor` and `trust-registry`: + + + + ## Messages + + ### query Message Type + +A trust-input-protocol/query message looks like this: + + { + "@type": "https://didcomm.org/trust-input/1.0/query", + "@id": "yWd8wfYzhmuXX3hmLNaV5bVbAjbWaU", + "query": { + "trust-task":"issuance", + "include-governance":"yes", + "credentialmetadata":[ + { + "credential-id": "http://university.example/credentials/1872", + "credential-format": "1", + "issuer-did": "did:example:123456abcdef" + } + ] + }, + "comment": "Please tell me if this issuer is authoritative to issue this credential type..." + } + +The query message says, “ Please tell me if the issuer: ‘did:example:123456abcdef’ is authorized to issue the credential: ‘http://university.example/credentials/1872’. And please give me information about the governance framework that governs the trust registry operation.” Please refer to the Localisation section below for further details. + +The `requestor` can send an array of issuers and credentials in their request to the trust registry. If they’re seeking multiple trust inputs from a single trust registry, they can get them in a single request. + +The values for `credential-format` are: + + 1 = AnonCreds + 2 = JSON-LD + 3 = JWT + +Additional formats can be supported and added to this above list. + +The credential field within the requestor’s `query` may include a * wildcard. An example use of this could be “I’m interested in knowing all the credentials that this specific issuer is authorized to offer”. This may be useful for discovery purposes. + +### response Message Type + +A trust-input/response message looks like this: + + { + "@type": "https://didcomm.org/trust-input/1.0/response", + "~thread": { + "thid": "yWd8wfYzhmuXX3hmLNaV5bVbAjbWaU" + }, + "governance":"http://university.example/governanceframework", + "response":[ + { + "credential-id": "http://university.example/credentials/1872", + "status": "2", + "status_date":"yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fff'Z'" + } + ] + } + +The `response` field is a JSON array of response support descriptor objects that matches the query. Each descriptor has a `credential-id` that contains a credential (fully qualified verifiable credential id), plus the current authoritative `status` of the credential issuer to issue said credential. + +The response returns the current status of the credential issuer(s) against their authority to issue credentials at the time of `query`. + +The values for `status` are: + + 1 = Not found + 2 = Valid + 3 = Expired (not renewed after the previous valid registration period) [when was it expired] + 4 = Terminated (voluntary termination by the registered party) [when was it terminated] + 5 = Revoked [when was it revoked] + +For status values 3, 4, 5; the trust registry will return a date value of when that status became that value. + +A `query` which contains a *wildcard would return all the credentials offered by the issuer’s DID. +The date format returned in the response is a web UTC format. The date represents the status changes of status values and the `requestor` can use that info to make their trust decision. + +## Trust Registry Considerations + +### Connection Establishment + +The connection between the `requestor` and the `trust-registry` is established via an out-of-band message sent to the `requestor`. Other connection methods such as [RFC 0160](https://github.com/hyperledger/aries-rfcs/blob/main/features/0160-connection-protocol/README.md) can also be used. + +### Identifier + +`trust-registry` must have a resolvable Verifiable Identifier (VID). + +### Governance + +The trust registries that an entity using this protocol will interact with should ensure their trust registries are aligned with the [Trust over IP’s Trust Registry Governance Framework](https://github.com/trustoverip/tswg-trust-registry-tf/blob/main/v2/requirements.md#governing-authorities). + +A governance document must be published to be able to respond to a request that asks for governance. + +## Localization + +Because the `requestor` is being returned a status number to represent the status, the implementers can use this to localise it in the language of their choice and make it friendly to their application or user experience. + +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/features/trust-input/requestor/catalog.json"] + + } + } + + +For more information, see the [localization RFC](https://github.com/hyperledger/aries-rfcs/blob/main/features/0043-l10n/README.md). + + +## Open Topics + +- How to implement using [RFC 0434: Out-of-Band Protocol 1.1](https://github.com/hyperledger/aries-rfcs/blob/main/features/0434-outofband/README.md)? We plan to leave this out of scope until a further version. +- Governance on how the credential id is entered into a trust registry will be required. And this is dependent on the credential format. So there will likely be a required field in the trust registry for credential format, which would then dictate how the credential id is entered. The format for the credential metadata in the trust registry must align with the format received by the `requestor`. + + +## Acknowledgements + +Although many people helped with the thinking behind this protocol, the authors would like to specifically thank these following people for their support and contributions: + +- British Columbia Government - Kyle Robinson and Nancy Norris + +- CIRA - Jacques Latour and Jesse Carter + +- Continuum Loop - Darrell O’Donnell + +- IDLab - Cosanna Preston-Idedia and Hadrien Seymour-Provencher + +- Trust over IP’s Trust Registry Task Force + + +## 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 | +|--|--| +| [nborbit.io](http://nborbit.io) | Commercial trust task orchestration application built by [Northern Block](https://northernblock.io/) using Aries Cloud Agent Python (ACA-Py). | + + + + + diff --git a/concepts/0781-trust-input-protocol/Test b/concepts/0781-trust-input-protocol/Test new file mode 100644 index 000000000..9c558e357 --- /dev/null +++ b/concepts/0781-trust-input-protocol/Test @@ -0,0 +1 @@ +. diff --git a/concepts/0781-trust-input-protocol/trust-input-states.png b/concepts/0781-trust-input-protocol/trust-input-states.png new file mode 100644 index 000000000..df70b57e4 Binary files /dev/null and b/concepts/0781-trust-input-protocol/trust-input-states.png differ diff --git a/concepts/0781-trust-input-protocol/trust-inputs-flow.png b/concepts/0781-trust-input-protocol/trust-inputs-flow.png new file mode 100644 index 000000000..17eb7c4b3 Binary files /dev/null and b/concepts/0781-trust-input-protocol/trust-inputs-flow.png differ diff --git a/concepts/0799-long-term-support/README.md b/concepts/0799-long-term-support/README.md new file mode 100644 index 000000000..a02d4fedc --- /dev/null +++ b/concepts/0799-long-term-support/README.md @@ -0,0 +1,44 @@ +# 0799: Aries Long Term Support Releases +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2023-11-07 +- Start Date: 2023-11-07 +- Tags: [concept](/tags.md#concept) + +Long Term Support Releases of Aries projects will assist those using the software to integrate within their development processes. + +## Motivation + +Long Term Support releases allow stable use of projects without frequent code updates. Designating LTS releases frees projects to develop features without worry of disrupting those seeking feature stable deployments. + +## Project LTS Releases +- Details specific to each project will be found within the relevant repositories. +- Projects SHOULD create an LTS policy within the code repository for the project. +- Projects MAY alter any of these suggestions to match the needs of the project. + +## LTS Release Tagging + +- No Specific version number scheme for LTS releases are set Aries-wide. Each project can use any version numbering they desire. Projects must have a way to indicate patch releases. +- The README.md file within each repository must indicate which version is an LTS release, with a link to the release or branch of the LTS +- Each LTS release MUST include detailed release notes detailing the changes from the last LTS release, including complex details or gotchas. +- It is recommended, when possible, to designate an LTS release when a project reaches compliance with an Interop Profile, including an AIP. + +## LTS Support Timeline + +- Each LTS release MUST be supported for at least 9 months AFTER the next LTS release is designated. +- When the next LTS release is designated, the prior LTS release must clearly indicate the End of Support Date at least 9 months in future. +- A branch SHOULD be created to ease bugfixes and the maintenance of LTS patch releases. +- If a support term in excess of the minimum 9 months is chosen and and End of Support Date published, that period MUST be honored for that release. +- Projects may may designate an LTS release with any candance desired by the project. +- Frequent LTS relases may result in multiple LTS releases receiving support. Seeking community input for LTS release timing may decrease support efforts. + +## LTS Release Updates + +- Each LTS release MUST be updated for security updates via patch releases for the duration of its support lifetime. +- Each LTS release MAY include bugfixes that impact usability of the release. +- LTS patch releases MUST include detailed release notes. +- Updates MUST NOT include API updates, programatic interface changes, or major logic changes. + +## References +This policy is inspired by the Fabric LTS Policy https://hyperledger.github.io/fabric-rfcs/text/0005-lts-release-strategy.html + diff --git a/contributing.md b/contributing.md index 1f124209e..936ee09c9 100644 --- a/contributing.md +++ b/contributing.md @@ -12,7 +12,7 @@ invisible to those consuming Aries, should be documented elsewhere. ### Preparation Before writing an RFC, consider exploring the idea on -[chat](https://chat.hyperledger.org/channel/aries), on community calls +[the aries chat channel](https://chat.hyperledger.org), on community calls (see the [Hyperledger Community Calendar]( https://wiki.hyperledger.org/community/calendar-public-meetings)), or on [aries@lists.hyperledger.org]( @@ -27,8 +27,8 @@ is a good sign that you're on the right track. for guidance. - Decide which parent folder is appropriate for your RFC. If it is about a specific protocol or decorator or feature, its parent - should be /features; if it is about a concept that will be used in many - different features, its parent should be /concepts. + should be `/features`; if it is about a concept that will be used in many + different features, its parent should be `/concepts`. - Create the folder and copy either `0000-template.md` or `0000-template-protocol.md` (if your RFC is for a protocol) to `//README.md`. - Fill in the RFC. [Use MUST and SHOULD per standard conventions](https://tools.ietf.org/html/rfc2119). Put care into the details: RFCs that do not present convincing motivation, demonstrate an understanding of the impact of the @@ -43,13 +43,8 @@ is a good sign that you're on the right track. this repo to figure out what the next PR number will be). Rename your folder from `` to `-`. At the top of your README.md, modify the title so it is in the form: `: Friendly Version of Your Title`. Commit your changes. - - In the root of the repo, run `python code/generate_index.py` to update the index - with your new RFC. - - In the root of your repo, run `pytest code` to see whether your RFC passes all - automated tests. The RFC tests are simple. They just check for things like - naming conventions and hyperlink correctness. - - Commit the updated version of /index.md and push your changes. + number>: Friendly Version of Your Title`. + - Commit and push your changes. - Submit a pull request. Make sure that all of your commits satisfy the [DCO requirements]( @@ -70,7 +65,7 @@ in the lifecycle, submit a PR with the following characteristics: - The title of the PR should include a deadline date for merging the PR and the referenced RFC. - Example: `Status to Accepted, deadline 2019.08.15, RFC 0095-basic-message` - The PR comment should document why the status is being changed. -- The deadline date should be 2 weeks after announcing the proposed status change on an Aries WG call. The PR should also be announced on the [#aries rocketchat channel](https://chat.hyperledger.org/channel/aries). +- The deadline date should be 2 weeks after announcing the proposed status change on an Aries WG call. The PR should also be announced on the [#aries channel](https://chat.hyperledger.org). - Barring negative feedback from the community, the repo's maintainers should merge the PR after the deadline. - The deadline should be moved by two weeks after addressing each substantive change to the RFC made during the status change review period. diff --git a/features/0015-acks/README.md b/features/0015-acks/README.md index acb69681e..bb272a6eb 100644 --- a/features/0015-acks/README.md +++ b/features/0015-acks/README.md @@ -1,8 +1,8 @@ # Aries RFC 0015: ACKs -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-04-15 +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Broadly implemented, adopted into many protocols and part of [AIP 1 and 2](../../concepts/0302-aries-interop-profile/README.md). - Start Date: 2018-12-26 - Tags: [feature](/tags.md#feature) @@ -12,9 +12,11 @@ Explains how one party can send acknowledgment messages (ACKs) to confirm receipt and clarify the status of complex processes. -## Change log +## Change Log -- Mar 25, 2020: In the ~thread decorator section of the sample in the [Explicit ACKs section](#explicit-acks), 'myindex' was changed to 'sender_order' and 'lrecs' to 'received_orders'. This is in accordance with the field names as defined in [RFC 0008](https://github.com/hyperledger/aries-rfcs/tree/64e5e55c123b2efaf38f4b0911a71a1c40a7f29d/concepts/0008-message-id-and-threading#threaded-messages). +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. +- 20220322: Clarification that an Ack `Fail` must not be used, and that a [Report Problem](../0035-report-problem/README.md) must be used in its place. Remove Ack `Fail` from the RFC. +- 20200325: In the ~thread decorator section of the sample in the [Explicit ACKs section](#explicit-acks), 'myindex' was changed to 'sender_order' and 'lrecs' to 'received_orders'. This is in accordance with the field names as defined in [RFC 0008](https://github.com/hyperledger/aries-rfcs/tree/64e5e55c123b2efaf38f4b0911a71a1c40a7f29d/concepts/0008-message-id-and-threading#threaded-messages). ## Motivation @@ -99,12 +101,18 @@ handler--but still have all the standardization of generic acks. ### ack status -The `status` field in an ack tells whether the ack is final or not with respect to -the message being acknowledged. It has 3 predefined values: `OK` (which means an -outcome has occurred, and it was positive); `FAIL` (an outcome has occurred, and -it was negative); and `PENDING`, which acknowledges that no outcome is yet known. -In addition, more advanced usage is possible. See the [details in the Reference -section](#reference). +The `status` field in an ack tells whether the ack is final or not with respect +to the message being acknowledged. It has 2 predefined values: `OK` (which means +an outcome has occurred, and it was positive); and `PENDING`, which acknowledges +that no outcome is yet known. + +There is not an ack `status` of `FAIL`. In the case of a protocol failure a +[Report Problem](../0035-report-problem/README.md) message must be used to +inform the other party(ies). For more details, see the [next +section](#relationship-to-problem-report). + +In addition, more advanced ack usage is possible. See the [details in the +Reference section](#reference). ### Relationship to `problem-report` @@ -119,14 +127,14 @@ arises, best practice is to report it to the sender of the message that triggered the problem. This is the subject of the [problem reporting mechanism](../0035-report-problem/README.md). A `problem_report` is inherently a sort of ACK. In fact, the `ack` message type -and the `problem_report` message type are both members of the same `notification` -message family. Both help a sender learn about status. Therefore, a -requirement for an `ack` can *often* be satisfied by a `problem_report` message. -Where this is truly the case, it is recommended, as it decreases chattiness. - -But notice the hedge word "often." We are hedging for at least two reasons. -First, some `ack`s may be sent before a final outcome, so a final `problem_report` -may not be enough. Second, an ack request may be sent after a previous +and the `problem_report` message type are both members of the same +`notification` message family. Both help a sender learn about status. Therefore, +a requirement for an `ack` is that a status of `FAIL` be satisfied by a +`problem_report` message. + +However, there is some subtlety in the use of the two types of messages. +Some `ack`s may be sent before a final outcome, so a final `problem_report` +may not be enough. As well, an ack request may be sent after a previous `ack` or `problem_report` was lost in transit. Because of these caveats, developers whose code creates or consumes acks should be thoughtful about where the two message types overlap, and where they do not. Carelessness here is likely to cause subtle, @@ -142,18 +150,13 @@ maybe their own decorators. However, reusing the field names and conventions in this RFC may still be desirable, if there is significant overlap in the concepts. -### Requesting ACKs - -A decorator, `~please_ack`, allows one agent to request an ad hoc ACK from -another agent. This is described in the [0317-please-ack RFC](../0317-please-ack/README.md). - ## Reference ### `ack` message #### __`status`__ -Required. As discussed [above](#ack-status), this tells whether the ack is final +Required, values `OK` or `PENDING`. As discussed [above](#ack-status), this tells whether the ack is final or not with respect to the message being acknowledged. #### __`~thread.thid`__ diff --git a/features/0019-encryption-envelope/README.md b/features/0019-encryption-envelope/README.md index a2e89a445..08b8eaa9e 100644 --- a/features/0019-encryption-envelope/README.md +++ b/features/0019-encryption-envelope/README.md @@ -1,7 +1,7 @@ # Aries RFC 0019: Encryption Envelope -- Authors: [Kyle Den Hartog](kyle.denhartog@evernym.com), [Stephen Curran](swcurran@gmail.com), [Sam Curren](sam@sovrin.org), [Mike Lodder](mike@sovrin.org) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Kyle Den Hartog](mailto:kyle.denhartog@evernym.com), [Stephen Curran](mailto:swcurran@gmail.com), [Sam Curren](mailto:sam@sovrin.org), [Mike Lodder](mailto:mike@sovrin.org) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-05-04 - Status Note: - Supersedes: [INDY 0028 Wire Level Format](https://github.com/hyperledger/indy-hipe/tree/main/text/0028-wire-message-format) diff --git a/features/0023-did-exchange/README.md b/features/0023-did-exchange/README.md index 583df639b..ab63d725f 100644 --- a/features/0023-did-exchange/README.md +++ b/features/0023-did-exchange/README.md @@ -1,7 +1,7 @@ -# Aries RFC 0023: DID Exchange Protocol 1.0 +# Aries RFC 0023: DID Exchange v1 -- Authors: [Ryan West](ryan.west@sovrin.org), [Daniel Bluhm](daniel.bluhm@sovrin.org), Matthew Hailstone, Stephen Curran, [Sam Curren](sam@sovrin.org), [Stephen Curran](swcurran@cloudcompass.ca), [George Aristy](george.aristy@securekey.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Ryan West](mailto:ryan.west@sovrin.org), [Daniel Bluhm](mailto:daniel.bluhm@sovrin.org), Matthew Hailstone, [Sam Curren](mailto:sam@sovrin.org), [Stephen Curran](mailto:swcurran@cloudcompass.ca), [George Aristy](mailto:george.aristy@securekey.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-04-15 - Status Note: Replaces [RFC 0160 - Connection Protocol](../../features/0160-connection-protocol/README.md) and is a part of [AIP 2.0](../../concepts/0302-aries-interop-profile/README.md). - Supersedes: [RFC 0160 - Connection Protocol](../../features/0160-connection-protocol/README.md) @@ -16,6 +16,12 @@ This RFC describes the protocol to exchange DIDs between agents when establishin Aries agent developers want to create agents that are able to establish relationships with each other and exchange secure information using keys and endpoints in DID Documents. For this to happen there must be a clear protocol to exchange DIDs. +## Version Change Log + +### Version 1.1 - Signed Rotations without DID Documents + +Added the optional `did_rotate~attach` attachment for provenance of rotation without an attached DID Document. + ## Tutorial We will explain how DIDs are exchanged, with the roles, states, and messages required. @@ -95,7 +101,7 @@ No errors are sent in timeout situations. If the _requester_ or _responder_ wish ``` jsonc { - "@type": "https://didcomm.org/didexchange/1.0/problem_report", + "@type": "https://didcomm.org/didexchange/1.1/problem_report", "@id": "5678876542345", "~thread": { "thid": "<@id of message related to problem>" }, "~l10n": { "locale": "en"}, @@ -141,7 +147,7 @@ The _requester_ may provision a new DID according to the DID method spec. For a ```jsonc { "@id": "5678876542345", - "@type": "https://didcomm.org/didexchange/1.0/request", + "@type": "https://didcomm.org/didexchange/1.1/request", "~thread": { "thid": "5678876542345", "pthid": "" @@ -173,7 +179,7 @@ The _requester_ may provision a new DID according to the DID method spec. For a * The [`~thread`](../../concepts/0008-message-id-and-threading/README.md#thread-object) decorator MUST be included: * It MUST include the ID of the parent thread (`pthid`) such that the `request` can be correlated to the corresponding (implicit or explicit) `invitation`. More on correlation [below](#correlating-requests-to-invitations). * It MAY include the `thid` property. This works according to the [`thid`](../../concepts/0008-message-id-and-threading/README.md#thread-id-thid) property in the thread decorator, meaning that if `thid` is not defined it is implicitly defined as the `@id` on the same `request` message. -* The `label` attribute provides a suggested label for the DID being exchanged. This allows the user to tell multiple exchange requests apart. This is not a trusted attribute. +* The `label` attribute provides a suggested label for the DID being exchanged. This allows the user to tell multiple exchange requests apart. This is not a trusted attribute. (See note on `label` below) * The `goal_code` (optional) is a self-attested code the receiver may want to display to the user or use in automatically deciding what to do with the request message. The goal code might be used particularly when the request is sent to a resolvable DID without reference to a specfic invitation. * The goal (optional) is a self-attested string that the receiver may want to display to the user about the context-specific goal of the request message. * The `did` attribute MUST be included. It indicates the DID being exchanged. @@ -181,6 +187,9 @@ The _requester_ may provision a new DID according to the DID method spec. For a * If the `did` is resolvable (either an inline `peer:did` or a publicly resolvable DID), the `did_doc~attach` attribute should not be included. * If the DID is a `did:peer` DID, the DIDDoc must be as outlined in [RFC 0627 Static Peer DIDs](../0627-static-peer-dids/README.md). + +The `label` property was intended to be declared as an optional property, but was added to the RFC as a required property. If an agent wishes to not use a label in the request, an empty string (`""`) or the set value `Unspecified` may be used to indicate a non-value. This approach ensures existing AIP 2.0 implementations do not break. + #### Correlating requests to invitations An invitation is presented in one of two forms: @@ -197,7 +206,7 @@ When a `request` responds to an implicit invitation, its `~thread.pthid` MUST co ```jsonc { "@id": "a46cdd0f-a2ca-4d12-afbf-2e78a6f1f3ef", - "@type": "https://didcomm.org/didexchange/1.0/request", + "@type": "https://didcomm.org/didexchange/1.1/request", "~thread": { "thid": "a46cdd0f-a2ca-4d12-afbf-2e78a6f1f3ef", "pthid": "032fbd19-f6fd-48c5-9197-ba9a47040470" @@ -228,7 +237,7 @@ When a `request` responds to an implicit invitation, its `~thread.pthid` MUST co ```jsonc { "@id": "a46cdd0f-a2ca-4d12-afbf-2e78a6f1f3ef", - "@type": "https://didcomm.org/didexchange/1.0/request", + "@type": "https://didcomm.org/didexchange/1.1/request", "~thread": { "thid": "a46cdd0f-a2ca-4d12-afbf-2e78a6f1f3ef", "pthid": "did:example:21tDAKCERh95uGgKbJNHYp#didcomm" @@ -303,7 +312,7 @@ The exchange response message is used to complete the exchange. This message is ```json { - "@type": "https://didcomm.org/didexchange/1.0/response", + "@type": "https://didcomm.org/didexchange/1.1/response", "@id": "12345678900987654321", "~thread": { "thid": "" @@ -322,6 +331,19 @@ The exchange response message is used to complete the exchange. This message is "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)" } } + }, + "did_rotate~attach": { + "mime-type": "text/string", + "data": { + "base64": "Qi5kaWRAQjpB", + "jws": { + "header": { + "kid": "did:key:z6MkmjY8GnV5i9YTDtPETC2uUAW6ejw3nk5mXF5yci5ab7th" + }, + "protected": "eyJhbGciOiJFZERTQSIsImlhdCI6MTU4Mzg4... (bytes omitted)", + "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)" + } + } } } ``` @@ -334,8 +356,9 @@ The invitation's `recipientKeys` should be dedicated to envelopes authenticated * The `~thread` decorator MUST be included. It contains a `thid` reference to the `@id` of the request message. * The `did` attribute MUST be included. It denotes the DID in use by the responder. Note that this MAY NOT be the same DID used in the invitation. * The `did_doc~attach` optional, contains the DID Doc associated with the `did`, if required. - * If the `did` is resolvable (either an inline `peer:did` or a publicly resolvable DID), the `did_doc~attach` attribute should not be included. + * If the `did` is resolvable (either an inline `did:peer` or a publicly resolvable DID), the `did_doc~attach` attribute should not be included. * If the DID is a `did:peer` identifier, the DIDDoc must be as outlined in [RFC 0627 Static Peer DIDs](../0627-static-peer-dids/README.md). +* The `did_rotate~attach` attribute is optional, but SHOULD be included if the `did` attribute is resolvable and the `did_doc~attach` is not included. The value is the Base64url encoded DID, and signed with the key used in the invitation. In addition to a new DID, the associated DID Doc might contain a new endpoint. This new DID and endpoint are to be used going forward in the relationship. @@ -347,7 +370,7 @@ When the message is sent, the _responder_ are now in the `response-sent` state. #### Response Processing -When the requester receives the `response` message, they will decrypt the authenticated envelope which confirms the source's authenticity. After decryption validation, they will update their wallet with the new information, and use that information in sending the `complete` message. +When the requester receives the `response` message, they will decrypt the authenticated envelope which confirms the source's authenticity. After decryption validation, the signature on the `did_doc~attach` or `did_rotate~attach` MUST be validated, if present. The key used in the signature MUST match the key used in the invitation. After attachment signature validation, they will update their wallet with the new information, and use that information in sending the `complete` message. #### Response Errors @@ -376,7 +399,7 @@ The exchange `complete` message is used to confirm the exchange to the _responde ```jsonc { - "@type": "https://didcomm.org/didexchange/1.0/complete", + "@type": "https://didcomm.org/didexchange/1.1/complete", "@id": "12345678900987654321", "~thread": { "thid": "", diff --git a/features/0024-didcomm-over-xmpp/README.md b/features/0024-didcomm-over-xmpp/README.md index 8275dfe4b..f6d8feb22 100644 --- a/features/0024-didcomm-over-xmpp/README.md +++ b/features/0024-didcomm-over-xmpp/README.md @@ -1,9 +1,9 @@ # Aries RFC 0024: DIDComm over XMPP -- Authors: [Oskar van Deventer](oskar.vandeventer@tno.nl), [Galit Rahim](galit.rahim@tno.nl), [Alexander Blom](alexander.blom@bloqzone.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-06-14 -- Status Note: , moving from Indy to Aries. +- Authors: [Oskar van Deventer](mailto:oskar.vandeventer@tno.nl), [Galit Rahim](mailto:galit.rahim@tno.nl), [Alexander Blom](mailto:alexander.blom@bloqzone.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: [Indy DIDComm-over-XMPP](https://github.com/Oskar-van-Deventer/indy-hipe/tree/main/text/didcom-over-xmpp) - Start Date: 2019-04-23 - Tags: [feature](/tags.md#feature) diff --git a/features/0025-didcomm-transports/README.md b/features/0025-didcomm-transports/README.md index 336a7171d..c37883883 100644 --- a/features/0025-didcomm-transports/README.md +++ b/features/0025-didcomm-transports/README.md @@ -1,7 +1,7 @@ # Aries RFC 0025: DIDComm Transports -- Authors: [Sam Curren](sam@sovrin.org) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Sam Curren](mailto:sam@sovrin.org) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-12-05 - Status Note: - Supersedes: [INDY PR 94](https://github.com/hyperledger/indy-hipe/pull/94) @@ -22,7 +22,13 @@ Standardized transport methods are detailed here. ### HTTP(S) -HTTP(S) is the first transport for DID Communication that has received heavy attention. +HTTP(S) is the first, and most used transport for DID Communication that has received heavy attention. + +While it is recognized that all DIDComm messages are secured through strong encryption, making HTTPS somewhat redundant, it will likely cause issues with mobile clients because venders (Apple and Google) are limiting application access to the HTTP protocol. For example, on iOS 9 or above where [ATS])(https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity) is in effect, any URLs using HTTP must have an exception hard coded in the application prior to uploading to the iTunes Store. This makes DIDComm unreliable as the agent initiating the the request provides an endpoint for communication that the mobile client must use. If the agent provides a URL using the HTTP protocol it will likely be unusable due to low level operating system limitations. + +As a best practice, when HTTP is used in situations where a mobile client (iOS or Android) may be involved it is highly recommended to use the HTTPS protocol, specifically TLS 1.2 or above. + +Other important notes on the subject of using HTTP(S) include: - Messages are transported via HTTP POST. - The MIME Type for the POST request is `application/didcomm-envelope-enc`; see [RFC 0044: DIDComm File and MIME Types](../0044-didcomm-file-and-mime-types/README.md) for more details. diff --git a/features/0028-introduce/README.md b/features/0028-introduce/README.md index d6aa2528d..27c68c1e1 100644 --- a/features/0028-introduce/README.md +++ b/features/0028-introduce/README.md @@ -12,6 +12,10 @@ Describes how a go-between can introduce two parties that it already knows, but that do not know each other. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + ## Motivation Introductions are a fundamental activity in human relationships. They allow @@ -218,8 +222,7 @@ introducee is the object of the sender's interest: ``` The recipient can choose whether or not to honor it in their own way, on -their own schedule. However, a `~please_ack` decorator could be used to make -it more interactive, and a `problem_report` could be returned if the +their own schedule. However, a `problem_report` could be returned if the recipient chooses not to honor it. ### Advanced Use Cases diff --git a/features/0030-sync-connection/README.md b/features/0030-sync-connection/README.md index 672398bfb..328d67c0c 100644 --- a/features/0030-sync-connection/README.md +++ b/features/0030-sync-connection/README.md @@ -1,9 +1,9 @@ # Aries RFC 0030: Sync Connection Protocol 1.0 -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-07-03 -- Status Note: used by the [peer DID method spec](https://openssi.github.io/peer-did-method-spec). Implementation beginning. +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: [Indy HIPE PR #104](https://github.com/hyperledger/indy-hipe/pull/104) - Start Date: 2018-10-01 - Tags: [feature](/tags.md#feature), [decorator](/tags.md#decorator), [protocol](/tags.md#protocol) @@ -15,6 +15,10 @@ common store of state like a blockchain), whereby parties using [peer DIDs]( https://openssi.github.io/peer-did-method-spec) can synchronize the state of their shared relationship by direct communication with one another. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + ## Motivation For Alice and Bob to interact, they must establish and maintain state. diff --git a/features/0030-sync-connection/abandon-connection-protocol/README.md b/features/0030-sync-connection/abandon-connection-protocol/README.md index b429daeaf..dd655a076 100644 --- a/features/0030-sync-connection/abandon-connection-protocol/README.md +++ b/features/0030-sync-connection/abandon-connection-protocol/README.md @@ -51,8 +51,7 @@ An `announce` message from Alice to Bob looks like this: ```json { "@type": "https://didcomm.org/abandon_connection/1.0/announce", - "@id": "c17147d2-ada6-4d3c-a489-dc1e1bf778ab", - "~please_ack": {} + "@id": "c17147d2-ada6-4d3c-a489-dc1e1bf778ab" } ``` @@ -64,20 +63,3 @@ forth. The nature of the relationship, the need for a historical audit trail, re requirements, and many other factors may influence what's appropriate; the protocol simply requires that the message be understood to have permanent termination semantics. -It may be desirable to use the [`~please_ack` decorator](../../0317-please-ack/README.md) -to request acknowledgment that the severance has been processed. The example shows -this, but including it is optional. - -##### `ack` - -The [`ack` message](../../0015-acks/README.md#explicit-acks) is [adopted]( -../../../0000-template-protocol.md#adopted-messages) into this protocol. If an -`announce` message includes the -`~please_ack` decorator and the ack is sent, it looks something like this: - -```json -{ -"@type": "https://didcomm.org/abandon_connection/1.0/ack", -"~thread": { "thid": "c17147d2-ada6-4d3c-a489-dc1e1bf778ab" } -} -``` diff --git a/features/0030-sync-connection/abandon-connection-protocol/announce.json b/features/0030-sync-connection/abandon-connection-protocol/announce.json index c2aedf617..67ceeff4c 100644 --- a/features/0030-sync-connection/abandon-connection-protocol/announce.json +++ b/features/0030-sync-connection/abandon-connection-protocol/announce.json @@ -1,6 +1,5 @@ { "@type": "https://didcomm.org/abandon_connection/1.0/announce", - "@id": "c17147d2-ada6-4d3c-a489-dc1e1bf778ab", - "~please_ack": {} + "@id": "c17147d2-ada6-4d3c-a489-dc1e1bf778ab" } diff --git a/features/0031-discover-features/README.md b/features/0031-discover-features/README.md index 76ab6561e..18707a18f 100644 --- a/features/0031-discover-features/README.md +++ b/features/0031-discover-features/README.md @@ -1,7 +1,7 @@ # Aries RFC 0031: Discover Features Protocol 1.0 - Authors: Daniel Hardman -- Status: [ACCEPTED](/README.md#accepted) (may be RETIRED when [v2.0](README.md) of the protocol has enough gravitas) +- Status: [ADOPTED](/README.md#adopted) (may be RETIRED when [v2.0](README.md) 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](../0557-discover-features-v2/README.md). - Supersedes: [Indy HIPE PR #73](https://github.com/hyperledger/indy-hipe/pull/73). diff --git a/features/0032-message-timing/README.md b/features/0032-message-timing/README.md index 687bec12a..626a03df2 100644 --- a/features/0032-message-timing/README.md +++ b/features/0032-message-timing/README.md @@ -1,6 +1,6 @@ # Aries RFC 0032: Message Timing -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [DEMONSTRATED](/README.md#demonstrated) - Since: 2019-05-01 - Status Note: Broadly socialized but not yet implemented. diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index 1622113d3..382bddf79 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -60,7 +60,21 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi and handled at its final destination) with the `~trace` attribute. Here is the simplest possible example: -[![example of ~trace](msg-with-trace.png)](msg-with-trace.json) +``` +{ + "@type": "did:sov:BzCBs...;spec/routing/1.0/forward", + "@id": "abc-def-...", + "msg": "U2Vl...", + "~trace": { + "target": "http://example.com/tracer", + "full_thread": true + } +} +``` + +The `"target"` can refer to a url (as above) or the term `"log"`, which is a request to +append trace information to the standard log file. (Information can then be manually +collated from agents.) This example asks the handler of the message to perform an HTTP POST of a __trace report__ about the message to the URI `http://example.com/tracer`. @@ -85,7 +99,19 @@ even if it is expired or invalid. The rationale for this choice is: The body of the HTTP request (the _trace report_) is a JSON document that looks like this: -[![trace report](trace-report.png)](trace-report.json) +``` +{ + "@type": "did:sov:BzCBs...;spec/1.0/trace_report", + "msg_id": "abc-def-...df", + "thread_id": "hij-klm-nop-...qr", + "handler": "did:sov:1234abcd#3", + "ellapsed_milli": 27, + "traced_type": "did:sov:BzCBs...;spec/routing/1.0/forward", + "str_time": "2018-03-27 18:23:45.123Z", + "timestamp": "1234567890.123456", + "outcome": "OK ..." +} +``` ### Subtleties @@ -97,7 +123,7 @@ connection when the reports are analyzed together. ![tracing unrelated messages](trace-xyz.png) -To solve this problem, traced messages use an ID convention that permits ordering. +To solve this problem, traced messages *may* use an ID convention that permits ordering. Assume that the inner application message has a base ID, _X_. Containing messages (e.g., `forward` messages) have IDs in the form _X_.1, _X_.2, _X_.3, and so forth -- where numbers represent the order in @@ -187,8 +213,9 @@ plaintext of the report, as utf8. * `@type`: Should always be `"https://didcomm.org/tracing/1.0/trace_report"`, or some evolved version thereof. Required for version control and to support trace sinks that process other HTTP payloads as well. -* `for_id`: The ID of the message that the handler is looking at when it composes the +* `msg_id`: The ID of the message that the handler is looking at when it composes the trace report. Required. +* `thread_id`: The ID of the protocol thread. Required. * `handler`: A string that identifies the handler in a way that's useful for troubleshooting purposes. For example, it might identify a particular agent by DID+keyref, or it might be a friendly string like "iPhone" or "AgentsRUs Cloud Agent, geocaching extension v1.3.7". Optional but @@ -197,9 +224,10 @@ plaintext of the report, as utf8. the trace report? If the same handler emits more than one trace report, how long has it been since the last trace was composed? Optional but encouraged. * `traced_type`: What was the message type of the traced message? Optional but encouraged. -* `report_time`: What was the UTC timestamp of the system clock of the handler +* `str_time`: What was the UTC timestamp of the system clock of the handler when the handler composed the trace report? ISO 8601 format with millisecond precision. Optional but encouraged. +* `timestamp`: Value fo the `str_time` field in milliseconds (UNIX time format). * `outcome`: A string that describes the outcome of the message handling. The string MUST begin with one of the following tokens: `"OK"` (meaning the handler completed its processing successfully; `"ERR"` (the handler failed), or `"PEND"` (the handler is still working on the diff --git a/features/0035-report-problem/README.md b/features/0035-report-problem/README.md index 8c8c563d2..9e2b3ce91 100644 --- a/features/0035-report-problem/README.md +++ b/features/0035-report-problem/README.md @@ -1,8 +1,8 @@ # Aries RFC 0035: Report Problem Protocol 1.0 -- Authors: [Stephen Curran](swcurran@cloudcompass.ca), [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-03-15 +- Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca), [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Implemented in multiple codebases. - Supersedes: [Indy HIPE PR #65]( https://github.com/hyperledger/indy-hipe/pull/65) - Start Date: 2018-11-26 @@ -13,6 +13,10 @@ Describes how to report errors and warnings in a powerful, interoperable way. All implementations of SSI agent or hub technology SHOULD implement this RFC. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + ## Motivation Effective reporting of errors and warnings is difficult in any system, and particularly so in @@ -117,11 +121,6 @@ Reporting problems uses a simple one-step [notification protocol]( The protocol includes the standard `notifier` and `notified` roles. It defines a single message type `problem-report`, introduced here. -It also [adopts](../../0000-template-protocol.md#adopted-messages) the -`ack` message from the [`ACK 1.0` protocol](../0015-acks/README.md), -to accommodate the possibility that the [`~please_ack`](../0317-please-ack/README.md) -[decorator]( ../../concepts/0011-decorators/README.md) may be used on the - notification. A `problem-report` communicates about a problem when an agent-to-agent message is possible and a recipient for the problem report is known. This covers, for example, @@ -172,6 +171,8 @@ to a message, the thread decorator is mostly redundant, as `~thread.thid` must e **description**: Contains human-readable, localized alternative string(s) that explain the problem. It is highly recommended that the message follow use the guidance in [the l10n RFC](../0043-l10n/README.md), allowing the error to be searched on the web and documented formally. +**description.code**: Required. Contains the code that indicates the problem being communicated. Codes are described in protocol RFCs and other relevant places. New Codes SHOULD follow the [Problem Code](https://identity.foundation/didcomm-messaging/spec/#problem-codes) naming convention detailed in the DIDComm v2 spec. + **problem_items**: A list of one or more key/value pairs that are parameters about the problem. Some examples might be: - a list of arguments that didn’t pass input validation @@ -237,6 +238,12 @@ Each item in the list must be a tagged pair (a JSON {key:value}, where the key n The following is a categorization of a number of examples of errors and (current) Best Practice handling for those types of errors. The new `problem-report` message type is used for some of these categories, but not all. +### Unknown Error + +Errors of a known error code will be processed according to the understanding of what the code means. Support of a protocol includes support and proper processing of the error codes detailed within that protocol. + +Any unknown error code that starts with `w.` in the DIDComm v2 style may be considered a warning, and the flow of the active protocol SHOULD continue. All other unknown error codes SHOULD be considered to be an end to the active protocol. + ### Error While Processing a Received Message An Agent Message sent by a Sender and received by its intended Recipient cannot be processed. diff --git a/features/0036-issue-credential/README.md b/features/0036-issue-credential/README.md index 0ebeb0794..554ff4dce 100644 --- a/features/0036-issue-credential/README.md +++ b/features/0036-issue-credential/README.md @@ -1,7 +1,7 @@ # Aries RFC 0036: Issue Credential Protocol 1.0 - Authors: Nikita Khateev -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) (But should move to deprecated) - Since: 2019-05-28 - Status Note: See [RFC 0037](../0037-present-proof/README.md) for the presentation part of using credentials. - Supersedes: [Indy HIPE PR #89]( https://github.com/hyperledger/indy-hipe/blob/2e85595e9a948a2fbfd58400191d112caff5a14b/text/credential-exchange-message-family/README.md); also [Credential Exchange 0.1 -- IIW 2019](https://hackmd.io/@QNKW9ANJRy6t81D7IfgiZQ/HkklVzww4?type=view) diff --git a/features/0037-present-proof/README.md b/features/0037-present-proof/README.md index 1674509c6..a9da30713 100644 --- a/features/0037-present-proof/README.md +++ b/features/0037-present-proof/README.md @@ -1,7 +1,7 @@ # Aries RFC 0037: Present Proof Protocol 1.0 - Authors: Nikita Khateev -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) (But should move to deprecated) - Since: 2019-05-28 - Status Note: This v1.x version of the protocol will be replaced by version v2 defined in [RFC 454](../0454-present-proof-v2/README.md). - Supersedes: [Indy HIPE PR #89](https://github.com/hyperledger/indy-hipe/blob/2e85595e9a948a2fbfd58400191d112caff5a14b/text/credential-exchange-message-family/README.md); also [Credential Exchange 0.1 -- IIW 2019](https://hackmd.io/@QNKW9ANJRy6t81D7IfgiZQ/HkklVzww4?type=view) diff --git a/features/0042-lox/README.md b/features/0042-lox/README.md index 39296d164..21e70d965 100644 --- a/features/0042-lox/README.md +++ b/features/0042-lox/README.md @@ -1,6 +1,6 @@ # Aries RFC 0042: LOX -- A more secure pluggable framework for protecting wallet keys -- Authors: [Michael Lodder](mike@sovrin.org) +- Authors: [Michael Lodder](mailto:mike@sovrin.org) - Status: [DEMONSTRATED](/README.md#demonstrated) - Since: 2019-05-30 - Start Date: 2019-05-30 diff --git a/features/0044-didcomm-file-and-mime-types/README.md b/features/0044-didcomm-file-and-mime-types/README.md index 3e154e95a..2bbd56cc7 100644 --- a/features/0044-didcomm-file-and-mime-types/README.md +++ b/features/0044-didcomm-file-and-mime-types/README.md @@ -54,12 +54,12 @@ Although the format of encrypted envelopes is derived from JSON and the JWT/JWE of specs, no useful processing of these files will take place by viewing them as JSON, and viewing them as generic JWEs will greatly constrain which semantics are applied. Therefore, the recommended MIME type for *.dee files is -`application/didcomm-enc-env`, with `application/jwe` as a fallback, and +`application/didcomm-envelope-enc`, with `application/jwe` as a fallback, and `application/json` as an even less desirable fallback. (In this, we are making a choice similar to the one that views `*.docx` files primarily as `application/msword` instead of `application/xml`.) If format evolution takes place, the version could become a parameter as [described in RFC 1341](https://www.w3.org/Protocols/rfc1341/4_Content-Type.html): -`application/didcomm-enc-env;v=2`. +`application/didcomm-envelope-enc;v=2`. A recipient using the media type value MUST treat it as if `“application/”` were prepended to any `"typ"` or `"cty"` value not containing a ‘/’ in compliance with the [JWE](https://tools.ietf.org/html/rfc7516) /[JWS](https://tools.ietf.org/html/rfc7515) family of specs. @@ -195,7 +195,7 @@ Because media types differ from DIDComm V1 to V2, and because media types are ea Nature of Content | V1 | V2 --- | --- | --- -encrypted| `application/didcomm-enc-env`
DIDComm V1 Encrypted Envelope
*.dee | `application/didcomm-encrypted+json`
DIDComm Encrypted Message
*.dcem +encrypted| `application/didcomm-envelope-enc`
DIDComm V1 Encrypted Envelope
*.dee | `application/didcomm-encrypted+json`
DIDComm Encrypted Message
*.dcem signed| `application/didcomm-sig-env`
DIDComm V1 Signed Envelope
*.dse | `application/didcomm-signed+json`
DIDComm Signed Message
*.dcsm plaintext| `application/json;flavor=didcomm-msg`
DIDComm V1 Message
*.dm | `application/didcomm-plain+json`
DIDComm Plaintext Message
*.dcpm diff --git a/features/0048-trust-ping/README.md b/features/0048-trust-ping/README.md index 8eb948560..e15cd6790 100644 --- a/features/0048-trust-ping/README.md +++ b/features/0048-trust-ping/README.md @@ -1,7 +1,7 @@ # Aries RFC 0048: Trust Ping Protocol 1.0 -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-02-01 - Status Note: Numerous implementations. - Supersedes: [Indy HIPE 0032](https://github.com/hyperledger/indy-hipe/tree/main/text/0032-trust-ping) diff --git a/features/0056-service-decorator/README.md b/features/0056-service-decorator/README.md index 3b56fc44a..b7e5de431 100644 --- a/features/0056-service-decorator/README.md +++ b/features/0056-service-decorator/README.md @@ -1,6 +1,6 @@ # Aries RFC 0056: Service Decorator -- Authors: [Sam Curren](sam@sovrin.org), Tobias Looker +- Authors: [Sam Curren](mailto:sam@sovrin.org), Tobias Looker - Status: [PROPOSED](/README.md#proposed) - Since: 2019-06-03 - Status Note: Needs refinement and validation, will be useful in any connectionless communication. @@ -23,7 +23,7 @@ The `~service` decorator on a message contains the service definition that you m Usage looks like this, with the contents defined the [Service Endpoint section of the DID Spec](https://w3c-ccg.github.io/did-spec/#service-endpoints): -```json= +```json { "@type": "somemessagetype", "~service": { @@ -34,11 +34,9 @@ Usage looks like this, with the contents defined the [Service Endpoint section o } ``` - - ## Reference -The contents of the `~service` decorator are defined by the [Service Endpoint section of the DID Spec](https://w3c-ccg.github.io/did-spec/#service-endpoints). +The contents of the `~service` decorator are defined by the [Service Endpoint section of the DID Spec](https://w3c-ccg.github.io/did-spec/#service-endpoints). The decorator should not be used when the message recipient already has a service endpoint. @@ -65,6 +63,6 @@ The Connect Protocol had previously included this same information as an attribu 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 ---- | --- - | | +| Name / Link | Implementation Notes | +| ----------- | -------------------- | +| | diff --git a/features/0066-non-repudiable-cryptographic-envelope/README.md b/features/0066-non-repudiable-cryptographic-envelope/README.md index 92e98e2d9..4d1cab72e 100644 --- a/features/0066-non-repudiable-cryptographic-envelope/README.md +++ b/features/0066-non-repudiable-cryptographic-envelope/README.md @@ -1,6 +1,6 @@ # Aries RFC 0066: Non-Repudiable Signature for Cryptographic Envelope -- Authors: [Kyle Den Hartog](indy@kyledenhartog.com) +- Authors: [Kyle Den Hartog](mailto:indy@kyledenhartog.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-04-15 - Status Note: This is a second attempt to integrate non-repudiable digital signatures based on learnings and discussions over the past few months. This focuses only on the signing of entire messages. Signature Decorators will be handled seperately. diff --git a/features/0067-didcomm-diddoc-conventions/README.md b/features/0067-didcomm-diddoc-conventions/README.md index 66c2e6c85..42872fef3 100644 --- a/features/0067-didcomm-diddoc-conventions/README.md +++ b/features/0067-didcomm-diddoc-conventions/README.md @@ -1,6 +1,6 @@ # Aries RFC 0067: DIDComm DID document conventions -- Authors: [Tobias Looker](tobias.looker@mattr.global), [Stephen Curran](swcurran@gmail.com) +- Authors: [Tobias Looker](mailto:tobias.looker@mattr.global), [Stephen Curran](mailto:swcurran@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-06-10 - Status Note: This revises the former [INDY HIPE](https://github.com/hyperledger/indy-hipe/pull/92) @@ -163,7 +163,7 @@ Alices agent goes to prepare a message `desired_msg` for Bob. 1. Alices agent resolves the above DID document `did:example:1234abcd` for Bob and resolves the `did-communication` service definition. 2. Alices agent then packs `desired_msg` in an encrypted envelope message to the resolved keys defined in the `recipientKeys` array. -3. Because the the `routingKeys` array is not empty, a content level message of type `forward` is prepared where the `to` field of the forward message is set to the resolved keys and the `msg` field of the forward message is set to the encrypted envelope from the previous step. +3. Because the `routingKeys` array is not empty, a content level message of type `forward` is prepared where the `to` field of the forward message is set to the resolved keys and the `msg` field of the forward message is set to the encrypted envelope from the previous step. 4. The resulting forward message from the previous step is then packed inside another encrypted envelope for the first and only key in the `routingKeys` array. 5. Inspection of the service endpoint, reveals it is a did url and leads to resolving another `did-communication` service definition, this time owned and controlled by `agents-r-us`. 6. Because in the `agents-r-us` service definition there is a recipient key. A content level message of type `forward` is prepared where the `to` field of the forward message is set to the recipient key and the `msg` field of the forward message is set to the encrypted envelope from the previous step. diff --git a/features/0075-payment-decorators/README.md b/features/0075-payment-decorators/README.md index ff49c3036..6c2ff22ac 100644 --- a/features/0075-payment-decorators/README.md +++ b/features/0075-payment-decorators/README.md @@ -1,9 +1,9 @@ # Aries RFC 0075: Payment Decorators -- Authors: [Sam Curren](sam@sovrin.org), [Daniel Hardman](daniel.hardman@gmail.com), Tomislav Markovski -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-06-11 -- Status Note: Still being studied. +- Authors: [Sam Curren](mailto:sam@sovrin.org), [Daniel Hardman](mailto:daniel.hardman@gmail.com), Tomislav Markovski +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: [Indy HIPE PR #129]( https://github.com/hyperledger/indy-hipe/pull/129) - Start Date: 2019-04-22 - Tags: [feature](/tags.md#feature), [decorator](/tags.md#decorator) diff --git a/features/0092-transport-return-route/README.md b/features/0092-transport-return-route/README.md index b121e2371..7018151ea 100644 --- a/features/0092-transport-return-route/README.md +++ b/features/0092-transport-return-route/README.md @@ -1,8 +1,8 @@ # Aries RFC 0092: Transports Return Route -- Authors: [Sam Curren](sam@sovrin.org) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2019-12-06 +- Authors: [Sam Curren](mailto:sam@sovrin.org) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: - Supersedes: [INDY HIPE PR 116](https://github.com/hyperledger/indy-hipe/pull/116) - Start Date: 2019-03-04 diff --git a/features/0095-basic-message/README.md b/features/0095-basic-message/README.md index f43183e8a..953a040e8 100644 --- a/features/0095-basic-message/README.md +++ b/features/0095-basic-message/README.md @@ -1,7 +1,7 @@ # Aries RFC 0095: Basic Message Protocol 1.0 - Authors: Sam Curren -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2019-08-06 - Status Note: - Supersedes: [Indy 0033](https://github.com/hyperledger/indy-hipe/edit/master/text/0033-basic-message/README.md) diff --git a/features/0113-question-answer/README.md b/features/0113-question-answer/README.md index b0cb93e03..249eb339d 100644 --- a/features/0113-question-answer/README.md +++ b/features/0113-question-answer/README.md @@ -1,6 +1,6 @@ # Aries RFC 0113: Question Answer Protocol 0.9 -- Authors: [Douglas Wightman](douglas.wightman@evernym.com) +- Authors: [Douglas Wightman](mailto:douglas.wightman@evernym.com) - Status: [DEMONSTRATED](/README.md#demonstrated) - Since: 2019-07-05 - Start Date: 2019-02-07 diff --git a/features/0114-predefined-identities/README.md b/features/0114-predefined-identities/README.md index 3f4851889..6d3ac98c5 100644 --- a/features/0114-predefined-identities/README.md +++ b/features/0114-predefined-identities/README.md @@ -1,9 +1,9 @@ # Aries RFC 0114: Predefined Identities - Authors: Daniel Hardman -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-07-10 -- Status Note: (explanation of current status; if adopted, links to impls or derivative ideas; if superseded, link to replacement) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Start Date: 2019-07-10 - Tags: [feature](/tags.md#feature) diff --git a/features/0116-evidence-exchange/README.md b/features/0116-evidence-exchange/README.md index f477f50a2..3b29fd35d 100644 --- a/features/0116-evidence-exchange/README.md +++ b/features/0116-evidence-exchange/README.md @@ -1,9 +1,9 @@ # Aries RFC 0116: Evidence Exchange Protocol 0.9 - Authors: [Dan Gisolfi](mailto:dan.gisolfi@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-07-26 -- Status Note: Revised to address both physical and digital identity proofing methods and NIST assurance levels. +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Start Date: 2019-07-05 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) diff --git a/features/0124-did-resolution-protocol/README.md b/features/0124-did-resolution-protocol/README.md index bfb98b9cd..77bf03ec7 100644 --- a/features/0124-did-resolution-protocol/README.md +++ b/features/0124-did-resolution-protocol/README.md @@ -1,7 +1,6 @@ # Aries RFC 0124: DID Resolution Protocol 0.9 -- Authors: [Markus Sabadello](markus@danubetech.com), - [Luis Gómez Alonso](luis.gomezalonso@sicpa.com) +- Authors: [Markus Sabadello](mailto:markus@danubetech.com), [Luis Gómez Alonso](mailto:luis.gomezalonso@sicpa.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-07-13 - Status Note: Not implemented, but has been discussed as part of the [Aries DID Resolution](https://github.com/hyperledger/aries-rfcs/issues/101) work. diff --git a/features/0160-connection-protocol/README.md b/features/0160-connection-protocol/README.md index 39ce74196..1fdf072ac 100644 --- a/features/0160-connection-protocol/README.md +++ b/features/0160-connection-protocol/README.md @@ -1,6 +1,6 @@ # 0160: Connection Protocol -- Authors: [Ryan West](ryan.west@sovrin.org), [Daniel Bluhm](daniel.bluhm@sovrin.org), Matthew Hailstone, Stephen Curran, [Sam Curren](sam@sovrin.org) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Ryan West](mailto:ryan.west@sovrin.org), [Daniel Bluhm](mailto:daniel.bluhm@sovrin.org), Matthew Hailstone, Stephen Curran, [Sam Curren](mailto:sam@sovrin.org) +- Status: [ADOPTED](/README.md#adopted) (But should move to deprecated) - Since: 2019-08-06 - Status Note: This is the protocol with existing uses. It is expected that [RFC 0023 DID Exchange](../../features/0023-did-exchange/README.md) will replace this protocol. - Supersedes: [HIPE 0031 - Connection Protocol](https://github.com/hyperledger/indy-hipe/tree/main/text/0031-connection-protocol) @@ -107,6 +107,8 @@ The *invitee* sends the *inviter* an ack or any other message that confirms the [0-invitation]: #0-invitation +> Note: This Invitation message is deprecated, and should use an invitation message from the [Out Of Band Protocol](../0434-outofband/README.md) + An invitation to connect may be transferred using any method that can reliably transmit text. The result must be the essential data necessary to initiate a [Connection Request](#1-connection-request) message. A connection invitation is an agent message with agent plaintext format, but is an **out-of-band communication** and therefore not communicated using wire level encoding or encryption. The necessary data that an invitation to connect must result in is: - suggested label @@ -399,7 +401,7 @@ The above message is required to be signed as described in [RFC 0234 Signature D "@type": "https://didcomm.org/signature/1.0/ed25519Sha512_single", "signature": "", "sig_data": "", - "signers": "" + "signer": "" } } ``` @@ -502,4 +504,4 @@ Name / Link | Implementation Notes [Aries Cloud Agent - Python](https://github.com/hyperledger/aries-cloudagent-python) | ported from VON codebase that passed agent connectathon tests, Feb 2019; [MISSING test results](/tags.md#test-anomaly) [Aries Static Agent - Python](https://github.com/hyperledger/aries-staticagent-python) | implemented July 2019; [MISSING test results](/tags.md#test-anomaly) [Aries Protocol Test Suite](https://github.com/hyperledger/aries-protocol-test-suite) | ported from Indy Agent codebase that provided agent connectathon tests, Feb 2019; [MISSING test results](/tags.md#test-anomaly) -[Indy Cloud Agent - Python](https://github.com/hyperledger/indy-agent/python) | passed agent connectathon tests, Feb 2019; [MISSING test results](/tags.md#test-anomaly) \ No newline at end of file +[Indy Cloud Agent - Python](https://github.com/hyperledger/indy-agent/python) | passed agent connectathon tests, Feb 2019; [MISSING test results](/tags.md#test-anomaly) diff --git a/features/0183-revocation-notification/README.md b/features/0183-revocation-notification/README.md index 76910410f..dab004c3b 100644 --- a/features/0183-revocation-notification/README.md +++ b/features/0183-revocation-notification/README.md @@ -1,7 +1,7 @@ # Aries RFC 0183: Revocation Notification 1.0 -- Authors: [Keith Smith] -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-08-12 +- Authors: Keith Smith +- Status: [ACCEPTED](/README.md#accepted) +- Since: 2024-05-01 - Status Note: Initial proposal after discussion on rocketchat - Supersedes: - Start Date: 2018-08-12 @@ -11,6 +11,10 @@ This RFC defines the message format which an issuer uses to notify a holder that a previously issued credential has been revoked. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + ## Motivation We need a standard protocol for an issuer to notify a holder that a previously issued credential has been revoked. @@ -42,7 +46,6 @@ The `revoke` message sent by the `issuer` to the `holder` is as follows: { "@type": "https://didcomm.org/revocation_notification/1.0/revoke", "@id": "", - "~please_ack": ["RECEIPT","OUTCOME"], "thread_id": "", "comment": "Some comment" } @@ -50,8 +53,6 @@ The `revoke` message sent by the `issuer` to the `holder` is as follows: Description of fields: -* `~please_ack` (optional) -- as described by the [Please ACK Decorator RFC](https://github.com/hyperledger/aries-rfcs/tree/main/features/0317-please-ack). If `OUTCOME` is specified, the `holder` should send an ack when the holder's agent has successfully notified the holder of the revocation. - * `thread_id` (required) -- the [thread ID](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0008-message-id-and-threading#thread-id-thid) of the [issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2) protocol which was used to issue one or more credentials that have been revoked by the issuer. If multiple credentials were issued, each credential has a different credential format but contains the same claims as described [here](https://github.com/hyperledger/aries-rfcs/tree/b982c24b9083dd5dddff6343dbf534cd1cfe36a6/features/0453-issue-credential-v2#message-attachments); therefore, this message notifies the holder that all of these credentials have been revoked. * `comment` (optional) -- a field that provides some human readable information about the revocation notification. This is typically the reason for the revocation as deemed appropriate by the issuer. diff --git a/features/0193-coin-flip/README.md b/features/0193-coin-flip/README.md index 49f70dd46..ebe7ea29f 100644 --- a/features/0193-coin-flip/README.md +++ b/features/0193-coin-flip/README.md @@ -1,9 +1,9 @@ # Aries RFC 0193: Coin Flip Protocol 1.0 -- Authors: [Daniel Hardman](daniel.hardman@gmail.com), [Patrick Stürmlinger](patrick@mindf.org) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-08-19 -- Status Note: minor update in late 2020 +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com), [Patrick Stürmlinger](mailto:patrick@mindf.org) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Start Date: 2019-08-19 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) @@ -11,6 +11,10 @@ Specifies a safe way for two parties who are remote from one another and who do not trust one another to pick a random, binary outcome that neither can manipulate. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + ## Motivation To guarantee fairness, it is often important to pick one party in a protocol to make a choice about what to do next. We need a way to do this that it more or less mirrors the randomness of flipping a coin. @@ -129,7 +133,6 @@ This message is sent from Recorder to Caller, and embodies Step 4 of [the algori "salt": "01bf7abd-aa80-4389-bf8c-dba0f250bb1b", "winner": "caller", "comment": "You win.", - "~please_ack": {}, "~thread": { "thid": "518be002-de8e-456e-b3d5-8fe472477a86", "sender_order": 1 @@ -145,8 +148,6 @@ The Caller should validate this message as follows: Having validated the message thus far, Caller determines the winner by checking if the self computed hash of `win` equals the given hash at the `propose` message at the position chosen with the `call` message or not. If yes, then the value of the `winner` field must be `caller`; if not, then it must be `recorder`. The `winner` field must be present in the message, and its value must be correct, for the `reveal` message to be deemed fully valid. This confirms that both parties understand the outcome, and it prevents a Recorder from asserting a false outcome that is accepted by careless validation logic on the Caller side. -The [`~please_ack` decorator](../0317-please-ack/README.md) is optional. If a superprotocol specifies the next step after a Coin Flip with sufficient precision, it may be unnecessary. However, it should be supported by implementations. The resulting `ack` message, if sent, is hereby [adopted into the Coin Flip protocol](../0015-acks/README.md#adopting-acks). - The [`~timing.expires_time` decorator](../0032-message-timing/README.md#tutorial) may be used to impose a time limit on the processing of this message. If used, the protocol must restart if the subsequent `ack` or the next message in the superprotocol is not received before the time limit. ## Drawbacks diff --git a/features/0211-route-coordination/README.md b/features/0211-route-coordination/README.md index 0741aa7ac..d4dc29dca 100644 --- a/features/0211-route-coordination/README.md +++ b/features/0211-route-coordination/README.md @@ -1,7 +1,7 @@ # 0211: Mediator Coordination Protocol -- Authors: [Sam Curren](telegramsam@gmail.com), [Daniel Bluhm](daniel@indicio.tech), [Adam Burdett](burdettadam@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-03-15 +- Authors: [Sam Curren](mailto:telegramsam@gmail.com), [Daniel Bluhm](mailto:daniel@indicio.tech), [Adam Burdett](mailto:burdettadam@gmail.com) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Discussed and implemented and part of AIP 2.0. - Start Date: 2019-09-03 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol), [test-anomaly](/tags.md#test-anomaly) @@ -162,7 +162,7 @@ Response to key list query, containing retrieved keys. { "recipient_key": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" } - ] + ], "pagination": { "count": 30, "offset": 30, @@ -200,3 +200,4 @@ The following lists the implementations (if any) of this RFC. Please do a pull r Name / Link | Implementation Notes --- | --- [Aries Cloud Agent - Python](https://github.com/hyperledger/aries-cloudagent-python/blob/main/Mediation.md) | Added in ACA-Py 0.6.0 [MISSING test results](/tags.md#test-anomaly)**** +[DIDComm mediator](https://github.com/Sirius-social/didcomm-mediator) | Open source cloud-based mediator. diff --git a/features/0212-pickup/README.md b/features/0212-pickup/README.md index 63f753fd6..3c8fd18a0 100644 --- a/features/0212-pickup/README.md +++ b/features/0212-pickup/README.md @@ -1,5 +1,6 @@ # 0212: Pickup Protocol -- Authors: [Sam Curren](telegramsam@gmail.com) + +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-09-03 - Status Note: Initial version @@ -32,41 +33,52 @@ batch retrieval can be executed when many messages ... ## Reference ### StatusRequest + Sent by the _recipient_ to the _message_holder_ to request a `status` message. -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/messagepickup/1.0/status-request" + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/1.0/status-request" } ``` + ### Status + Status details about pending messages -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/messagepickup/1.0/status", - "message_count": 7, - "duration_waited": 3600, - "last_added_time": "2019-05-01 12:00:00Z", - "last_delivered_time": "2019-05-01 12:00:01Z", - "last_removed_time": "2019-05-01 12:00:01Z", - "total_size": 8096 + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/1.0/status", + "message_count": 7, + "duration_waited": 3600, + "last_added_time": "2019-05-01 12:00:00Z", + "last_delivered_time": "2019-05-01 12:00:01Z", + "last_removed_time": "2019-05-01 12:00:01Z", + "total_size": 8096 } ``` + `message_count` is the only required attribute. The others may be present if offered by the _message_holder_. + ### Batch Pickup + A request to have multiple waiting messages sent inside a `batch` message. -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/messagepickup/1.0/batch-pickup", - "batch_size": 10 + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/1.0/batch-pickup", + "batch_size": 10 } ``` ### Batch + A message that contains multiple waiting messages. -```json= + +```json { "@id": "123456781", "@type": "https://didcomm.org/messagepickup/1.0/batch", @@ -87,22 +99,29 @@ A message that contains multiple waiting messages. ] } ``` + ### Message Query With Message Id List + A request to read single or multiple messages with a message message id array. -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/messagepickup/1.0/list-pickup", - "message_ids": [ - "06ca25f6-d3c5-48ac-8eee-1a9e29120c31", - "344a51cf-379f-40ab-ab2c-711dab3f53a9a" - ] + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/1.0/list-pickup", + "message_ids": [ + "06ca25f6-d3c5-48ac-8eee-1a9e29120c31", + "344a51cf-379f-40ab-ab2c-711dab3f53a9a" + ] } ``` + `message_ids` message id array for picking up messages. Any message id in `message_ids` could be delivered via several ways to the recipient (Push notification or with an envoloped message). + ### Message List Query Response + A response to query with message id list. -```json= + +```json { "@type": "https://didcomm.org/messagepickup/1.0/list-response", "messages~attach": [ @@ -121,16 +140,18 @@ A response to query with message id list. ] } ``` + ### Noop + Used to receive another message implicitly. This message has no expected behavior when received. -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/messagepickup/1.0/noop" + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/1.0/noop" } ``` - ## Prior art Concepts here borrow heavily from a [document](https://hackmd.io/@8VtAqKThQ6mKa9T7JgzIaw/SJw9Ead2N?type=view) written by Andrew Whitehead of BCGov. @@ -143,6 +164,6 @@ Concepts here borrow heavily from a [document](https://hackmd.io/@8VtAqKThQ6mKa9 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 ---- | --- - | | +| Name / Link | Implementation Notes | +| ----------- | -------------------- | +| | diff --git a/features/0213-transfer-policy/README.md b/features/0213-transfer-policy/README.md index 366ae5c31..6e440b147 100644 --- a/features/0213-transfer-policy/README.md +++ b/features/0213-transfer-policy/README.md @@ -1,8 +1,9 @@ # 0213: Transfer Policy Protocol -- Authors: [Sam Curren](telegramsam@gmail.com) + +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-09-03 -- Status Note: Initial version +- Status Note: Initial version - Start Date: 2019-09-03 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) @@ -24,65 +25,70 @@ Explicit Policy Enables clear expectations. ## Reference ### Policy Publish + Used to share current policy by policy holder. This can be sent unsolicited or in response to a `policy_share_request`. -```json= + +```json { - "@id": "123456781", - "@type": "https://didcomm.org/transferpolicy/1.0/policy", - "queue_max_duration": 86400, - "message_count_limit": 1000, - "message_size_limit": 65536, - "queue_size_limit": 65536000, - "pickup_allowed": true, - "delivery_retry_count_limit":5, - "delivery_retry_count_seconds":86400, - "delivery_retry_backoff": "exponential" + "@id": "123456781", + "@type": "https://didcomm.org/transferpolicy/1.0/policy", + "queue_max_duration": 86400, + "message_count_limit": 1000, + "message_size_limit": 65536, + "queue_size_limit": 65536000, + "pickup_allowed": true, + "delivery_retry_count_limit": 5, + "delivery_retry_count_seconds": 86400, + "delivery_retry_backoff": "exponential" } ``` + ### Policy Share Request + Used to ask for a `policy` message to be sent. -```json= +```json { - "@id": "123456781", - "@type": "https://didcomm.org/transferpolicy/1.0/policy_share_request" + "@id": "123456781", + "@type": "https://didcomm.org/transferpolicy/1.0/policy_share_request" } ``` ### Policy Change Request -Sent to request a policy change. The expected response is a `policy` message. -```json= +Sent to request a policy change. The expected response is a `policy` message. +```json { - "@id": "123456781", - "@type": "https://didcomm.org/transferpolicy/1.0/policy_change_request", - "queue_max_duration": 86400, - "message_count_limit": 1000, - "message_size_limit": 65536, - "queue_size_limit": 65536000, - "pickup_allowed": true, - "delivery_retry_count_limit":5, - "delivery_retry_count_seconds":86400, - "delivery_retry_backoff": "exponential" + "@id": "123456781", + "@type": "https://didcomm.org/transferpolicy/1.0/policy_change_request", + "queue_max_duration": 86400, + "message_count_limit": 1000, + "message_size_limit": 65536, + "queue_size_limit": 65536000, + "pickup_allowed": true, + "delivery_retry_count_limit": 5, + "delivery_retry_count_seconds": 86400, + "delivery_retry_backoff": "exponential" } ``` -Only attributes that you desire to change need to be included. +Only attributes that you desire to change need to be included. ## Prior art + Concepts here borrow heavily from a [document](https://hackmd.io/@8VtAqKThQ6mKa9T7JgzIaw/SJw9Ead2N?type=view) written by Andrew Whitehead of BCGov. ## Unresolved questions - Is the attribute list too extensive for a first pass? - Which policy attributes should be required? Which optional? - + ## 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 ---- | --- - | | +| Name / Link | Implementation Notes | +| ----------- | -------------------- | +| | diff --git a/features/0214-help-me-discover/README.md b/features/0214-help-me-discover/README.md index e59fbe6f7..322e39bee 100644 --- a/features/0214-help-me-discover/README.md +++ b/features/0214-help-me-discover/README.md @@ -1,8 +1,8 @@ # Aries RFC 0214: "Help Me Discover" Protocol -- Authors: [George Aristy](george.aristy@securekey.com), [Daniel Hardman](daniel.hardman@gmail.com) +- Authors: [George Aristy](mailto:george.aristy@securekey.com), [Daniel Hardman](mailto:daniel.hardman@gmail.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-09-10 -- Status Note: implementation is being explored by SecureKey +- Status Note: implementation is being explored by SecureKey - Start Date: 2018-08-20 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) diff --git a/features/0234-signature-decorator/README.md b/features/0234-signature-decorator/README.md index 0a3e4ce7c..6c8345ab3 100644 --- a/features/0234-signature-decorator/README.md +++ b/features/0234-signature-decorator/README.md @@ -1,5 +1,5 @@ # Aries RFC 0234: Signature Decorator -- Authors: [Kyle Den Hartog](kyle.denhartog@evernym.com) +- Authors: [Kyle Den Hartog](mailto:kyle.denhartog@evernym.com) - Status: [RETIRED](/README.md#retired) - Since: 2020-10-14 - Status Note: This decorator is retired, replaced with the use of the signed form of the attachment decorator diff --git a/features/0249-rich-schema-contexts/README.md b/features/0249-rich-schema-contexts/README.md index 46ec918d3..6b7719957 100644 --- a/features/0249-rich-schema-contexts/README.md +++ b/features/0249-rich-schema-contexts/README.md @@ -1,8 +1,8 @@ # Aries RFC 0249: Aries Rich Schema Contexts - Authors: [Brent Zundel](mailto:brent.zundel@evernym.com), [Ken Ebert](mailto:ken@sovrin.org), [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-10-08 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-06-07 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0281-rich-schemas/README.md b/features/0281-rich-schemas/README.md index b14c3e034..e91d923da 100644 --- a/features/0281-rich-schemas/README.md +++ b/features/0281-rich-schemas/README.md @@ -1,8 +1,8 @@ # Aries RFC 0281: Aries Rich Schemas - Authors: [Brent Zundel](mailto:brent.zundel@evernym.com), [Ken Ebert](mailto:ken@sovrin.org), [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-10-30 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-06-07 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0309-didauthz/README.md b/features/0309-didauthz/README.md index 84b5f1aa9..86a981c60 100644 --- a/features/0309-didauthz/README.md +++ b/features/0309-didauthz/README.md @@ -1,8 +1,8 @@ # Aries RFC 0309: DIDAuthZ -- Authors: [George Aristy](george.aristy@gmail.com) SecureKey Technologies -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-11-14 -- Status Note: This RFC is under development. +- Authors: [George Aristy](mailto:george.aristy@gmail.com) SecureKey Technologies +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-09-27 - Tags: [feature](/tags.md#feature), [credentials](/tags.md#credentials) diff --git a/features/0317-please-ack/README.md b/features/0317-please-ack/README.md index b0882919a..26d238cf2 100644 --- a/features/0317-please-ack/README.md +++ b/features/0317-please-ack/README.md @@ -1,12 +1,30 @@ # Aries RFC 0317: Please ACK Decorator -- Authors: [Daniel Hardman](daniel.hardman@gmail.com), [Timo Glastra](mailto:timo@animo.id) -- Status: [PROPOSED](/README.md#proposed) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com), [Timo Glastra](mailto:timo@animo.id) +- Status: [RETIRED](/README.md#retired) - Since: 2019-12-26 -- Status Note: Separated from the ACK protocol. A lot of complex features were removed for inclusion in AIP 2.0 (see note at bottom) +- Status Note: Attempts at implementation demonstrate that a general purpose `~please_ack` capability is not practical, and needs to be implemented on a per protocol basis, for protocols where the functionality makes sense. - Start Date: 2018-12-26 - Tags: [feature](/tags.md#feature), [decorator](/tags.md#decorator) +## Retirement of `~please_ack` + +The `please_ack` decorator was initially added to [Aries Interop Protocol 2.0]. However, this was done prior to attempts at an implementation. When such an attempt was made, it was found that the decorator is not practical as a general purpose mechanism. The capability assumed that the feature would be general purpose and could be applied outside of the protocols with which it was used. That assumption proved impossible to implement. The inclusion of the `~please_ack` decorator cannot be implemented without altering any protocol with which it is used, and so it is not practical. Instead, any protocols that can benefit from such a feature can be extended to explicitly support the feature. + +For the `"on": ["OUTCOME"]` type of ACK, the problem manifests in two ways. First, the definition of `OUTCOME` is protocol (and in fact, protocol message) specific. The definition of "complete" for each message is specific to each message, so there is no "general purpose" way to know when an `OUTCOME` ACK is to be sent. Second, the addition of a `~please_ack` decorator changes the protocol state machine for a given protocol, introducing additional states, and hence, additional state handling. Supporting `"on": ["OUTCOME"]` processing requires making changes to all protocols, which would be better handled on a per protocol basis, and where useful (which, it was found, is rare), adding messages and states. For example, what is the point of an extra `ACK` message on an `OUTCOME` in the middle of a protocol that itself results in the sending of the response message? + +Our experimentation found that it would be easier to achieve a general purpose `"on": ["RECEIPT"]` capability, but even then there were problems. Most notably, the capability is most useful when added to the last message of a protocol, where the message sender would like confirmation that the recipient got the message. However, it is precisely that use of the feature that also introduces breaking changes to the protocol state machine for the protocols to which it applies, requiring per protocol updates. So while the feature would be marginally useful in some cases, the complexity cost of the capability -- and the lack of demand for its creation -- led us to retire the entire RFC. + +For more details on the great work done by [Alexander Sukhachev @alexsdsr](https://github.com/alexsdsr), please see these pull requests, including both the changes proposed in the PRs, and the subsequent conversations about the features. + +- [Aries Cloud Agent Python PR 2540 - PleaseAck.md document](https://github.com/hyperledger/aries-cloudagent-python/pull/2540) +- [Aries Cloud Agent Python PR 2546 - DRAFT: please_ack support PoC for the 0453-issue-credential-v2 protocol](https://github.com/hyperledger/aries-cloudagent-python/pull/2546) +- [Aries RFCs - Update the 'unresolved questions' section of the 0317-please-ack RFC](https://github.com/hyperledger/aries-rfcs/pull/801) + +Much thanks for Alexander for the effort he put into trying to implement this capability. + +[Aries Interop Protocol 2.0]: https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0302-aries-interop-profile#aries-interop-profile-version-20 + ## Summary Explains how one party can request an acknowledgment to and clarify the status of processes. @@ -137,6 +155,6 @@ None specified. 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 ---- | --- - | +| Name / Link | Implementation Notes | +| ----------- | -------------------- | +| | diff --git a/features/0327-crypto-service/README.md b/features/0327-crypto-service/README.md index d147944b3..b47f77cd8 100644 --- a/features/0327-crypto-service/README.md +++ b/features/0327-crypto-service/README.md @@ -1,9 +1,9 @@ # Aries RFC 0327: Crypto service Protocol 1.0 - Authors: Robert Mitwicki, Wolfgang Lamot -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-11-20 (date you submit your PR) -- Status Note: RFC under development +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-11-01 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) diff --git a/features/0334-jwe-envelope/README.md b/features/0334-jwe-envelope/README.md index 76e43bde5..fbe2cba41 100644 --- a/features/0334-jwe-envelope/README.md +++ b/features/0334-jwe-envelope/README.md @@ -1,9 +1,9 @@ # Aries RFC 0334: JWE envelope 1.0 - Authors: [Baha A. Shaaban](mailto:baha.shaaban@securekey.com) (SecureKey Technologies Inc.), [Troy Ronda](mailto:troy.ronda@securekey.com) (SecureKey Technologies Inc.) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-11-28 -- Status Note: RFC under development +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-11-01 - Tags: [feature](/tags.md#feature) diff --git a/features/0335-http-over-didcomm/README.md b/features/0335-http-over-didcomm/README.md index c35e2ab3e..61928ddac 100644 --- a/features/0335-http-over-didcomm/README.md +++ b/features/0335-http-over-didcomm/README.md @@ -1,8 +1,8 @@ # 0335: HTTP Over DIDComm -- Authors: [Filip Burlacu](filip.burlacu@securekey.com) (SecureKey) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-12-03 -- Status Note: implementation is being explored by SecureKey +- Authors: [Filip Burlacu](mailto:filip.burlacu@securekey.com) (SecureKey) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-11-26 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) diff --git a/features/0347-proof-negotiation/README.md b/features/0347-proof-negotiation/README.md index 5bca2e518..575e9ce3d 100644 --- a/features/0347-proof-negotiation/README.md +++ b/features/0347-proof-negotiation/README.md @@ -1,6 +1,6 @@ # Aries RFC 0347: Proof Negotiation -- Authors: [Philipp Rieblinger](p.rieblinger@esatus.com), [Sebastian Weidenbach](s.weidenbach@esatus.com) +- Authors: [Philipp Rieblinger](mailto:p.rieblinger@esatus.com), [Sebastian Weidenbach](mailto:s.weidenbach@esatus.com) - Status: [PROPOSED](/README.md#proposed) - Since: 2019-12-13 - Status Note: Initial proposal after discussion on rocketchat diff --git a/features/0348-transition-msg-type-to-https/README.md b/features/0348-transition-msg-type-to-https/README.md index d52f2bf95..2efec08de 100644 --- a/features/0348-transition-msg-type-to-https/README.md +++ b/features/0348-transition-msg-type-to-https/README.md @@ -1,7 +1,7 @@ # Aries RFC 0348: Transition Message Type to HTTPs - Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca) -- Status: [ADOPTED](/README.md#adopted) +- Status: [RETIRED](/README.md#retired) - Since: 2020-08-26 - Status Note: In step 2 - community is updating implementations to send new formats. **Target Completion Date: 2020.10.15** - Supersedes: diff --git a/features/0351-purpose-decorator/README.md b/features/0351-purpose-decorator/README.md index 70618d188..30e647976 100644 --- a/features/0351-purpose-decorator/README.md +++ b/features/0351-purpose-decorator/README.md @@ -1,8 +1,8 @@ # Aries RFC 0351: Purpose Decorator -- Authors: [Filip Burlacu](filip.burlacu@securekey.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2019-12-16 -- Status Note: implementation is being explored by SecureKey +- Authors: [Filip Burlacu](mailto:filip.burlacu@securekey.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-12-05 - Tags: [feature](/tags.md#feature), [decorator](/tags.md#decorator) diff --git a/features/0360-use-did-key/README.md b/features/0360-use-did-key/README.md index c927fe001..b7fac14ca 100644 --- a/features/0360-use-did-key/README.md +++ b/features/0360-use-did-key/README.md @@ -1,8 +1,8 @@ # Aries RFC 0360: did:key Usage -- Authors: [Tobias Looker](tobias.looker@mattr.global), [Stephen Curran](mailto:swcurran@cloudcompass.ca) -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-04-15 +- Authors: [Tobias Looker](mailto:tobias.looker@mattr.global), [Stephen Curran](mailto:swcurran@cloudcompass.ca) +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Referenced in a number of Aries RFCs and formalized as part of [AIP 2.0](../../concepts/0302-aries-interop-profile/README.md) did:key method is a [W3C CCG work item](https://w3c-ccg.github.io/community/work_items.html) - Start Date: 2019-12-17 - Tags: [feature](/tags.md#feature) diff --git a/features/0418-rich-schema-encoding/README.md b/features/0418-rich-schema-encoding/README.md index 98cd5e14f..3dcee7ccc 100644 --- a/features/0418-rich-schema-encoding/README.md +++ b/features/0418-rich-schema-encoding/README.md @@ -1,8 +1,8 @@ # Aries RFC 0418: Aries Rich Schema Encoding Objects - Author: [Ken Ebert](mailto:ken@sovrin.org), [Mike Lodder](mailto:mike@sovrin.org), [Brent Zundel](mailto:brent.zundel@evernym.com), [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-02-10 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-03-19 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0428-prepare-issue-rich-credential/README.md b/features/0428-prepare-issue-rich-credential/README.md index af09b64c2..472dda37d 100644 --- a/features/0428-prepare-issue-rich-credential/README.md +++ b/features/0428-prepare-issue-rich-credential/README.md @@ -1,8 +1,8 @@ # 0428: Prerequisites to Issue Rich Credential -- Authors: [Brent Zundel](), [Ken Ebert]() -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-02-20 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Authors: [Brent Zundel](mailto:brent.zundel@evernym.com), [Ken Ebert](mailto:ken@sovrin.org) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2020-02-19 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0429-prepare-req-rich-pres/README.md b/features/0429-prepare-req-rich-pres/README.md index 558e55dcf..6c22f6b39 100644 --- a/features/0429-prepare-req-rich-pres/README.md +++ b/features/0429-prepare-req-rich-pres/README.md @@ -1,8 +1,8 @@ # 0429: Prerequisites to Request Rich Presentation -- Authors: [Brent Zundel](), [Ken Ebert]() -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-02-21 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Authors: [Brent Zundel](mailto:brent.zundel@evernym.com), [Ken Ebert](mailto:ken@sovrin.org) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2020-02-19 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0434-outofband/ExampleQRCode.png b/features/0434-outofband/ExampleQRCode.png index 7330ccbad..f96415ae7 100644 Binary files a/features/0434-outofband/ExampleQRCode.png and b/features/0434-outofband/ExampleQRCode.png differ diff --git a/features/0434-outofband/README.md b/features/0434-outofband/README.md index 7b33d2306..01f90d316 100644 --- a/features/0434-outofband/README.md +++ b/features/0434-outofband/README.md @@ -1,7 +1,7 @@ # Aries RFC 0434: Out-of-Band Protocol 1.1 -- Authors: [Ryan West](ryan.west@sovrin.org), [Daniel Bluhm](daniel.bluhm@sovrin.org), Matthew Hailstone, [Stephen Curran](swcurran@cloudcompass.ca), [Sam Curren](sam@sovrin.org), [George Aristy](george.aristy@securekey.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Ryan West](mailto:ryan.west@sovrin.org), [Daniel Bluhm](mailto:daniel.bluhm@sovrin.org), Matthew Hailstone, [Stephen Curran](mailto:swcurran@cloudcompass.ca), [Sam Curren](mailto:sam@sovrin.org), [George Aristy](mailto:george.aristy@securekey.com) +- Status: [ADOPTED](/README.md#adopted) - Since: 2020-03-01 - Status Note: This RFC extracts the `invitation` messages from the [DID Exchange](../../features/0023-did-exchange/README.md) protocol (and perhaps [Connection](../../features/0160-connection-protocol/README.md)), and replaces the combined `present_proof/1.0/request` combined with the `~service` decorator to define an ephemeral (connection-less) challenge. - Supersedes: Invitation Message in [0160-Connections](https://github.com/hyperledger/aries-rfcs/blob/9b0aaa39df7e8bd434126c4b33c097aae78d65bf/features/0160-connection-protocol/README.md#0-invitation-to-connect) and Invitation Message in [0023-DID-Exchange](https://github.com/hyperledger/aries-rfcs/blob/9b0aaa39df7e8bd434126c4b33c097aae78d65bf/features/0023-did-exchange/README.md#0-invitation-to-exchange). @@ -141,9 +141,9 @@ While the _receiver_ is expected to respond with an initiating message from a `h If a message has a service block instead of a DID in the `services` list, you may enable reuse by encoding the key and endpoint of the service block in a [Peer DID numalgo 2](https://identity.foundation/peer-did-method-spec/#generation-method) and using that DID instead of a service block. -If the receiver desires to reuse the existing connection and a `requests~attach` message is present, the receiver **SHOULD** respond to the attached message using the existing connection. +If the receiver desires to reuse the existing connection and a `requests~attach` item is included in the message, the receiver **SHOULD** respond to one of the attached messages using the existing connection. -If the receiver desires to reuse the existing connection and no `requests~attach` message is present, the receiver **SHOULD** attempt to do so with the `reuse` and `reuse-accepted` messages. This will notify the _inviter_ that the existing connection should be used, along with the context that can be used for follow-on interactions. +If the receiver desires to reuse the existing connection and no `requests~attach` item is included in the message, the receiver **SHOULD** attempt to do so with the `reuse` and `reuse-accepted` messages. This will notify the _inviter_ that the existing connection should be used, along with the context that can be used for follow-on interactions. While the `invitation` message is passed unencrypted and out-of-band, both the `handshake-reuse` and `handshake-reuse-accepted` messages **MUST** be encrypted and transmitted as normal DIDComm messages. @@ -348,7 +348,11 @@ The handling of the response is specified by the protocol used. Using a standard out-of-band message encoding allows for easier interoperability between multiple projects and software platforms. Using a URL for that standard encoding provides a built in fallback flow for users who are unable to automatically process the message. Those new users will load the URL in a browser as a default behavior, and may be presented with instructions on how to install software capable of processing the message. Already onboarded users will be able to process the message without loading in a browser via mobile app URL capture, or via capability detection after being loaded in a browser. -The standard out-of-band message format is a URL with a Base64URLEncoded json object as a query parameter. +The standard out-of-band message format is a URL with a **Base64Url** encoded json object as a query parameter. + +Please note the difference between [Base64Url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) and [Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) encoding. + +The Base64URL encoded JSON object **SHOULD NOT** use padding, but the decoding implementation used **MUST** correctly decode padded and unpadded Base64URL encoded data. The URL format is as follows, with some elements described below: @@ -360,13 +364,13 @@ https:///?oob= > To do: We need to rationalize this approach `https://` approach with the use of a special protocol (e.g. `didcomm://`) that will enable handling of the URL on mobile devices to automatically invoke an installed app on both Android and iOS. A user must be able to process the out-of-band message on the device of the agent (e.g. when the mobile device can't scan the QR code because it is on a web page on device). -The `` is an agent plaintext message (not a DIDComm message) that has been base64 url encoded. +The `` is an agent plaintext message (not a DIDComm message) that has been Base64Url encoded such that the resulting string can be safely used in a URL. ```javascript -outofband_message = b64urlencode() +outofband_message = base64UrlEncode() ``` -During encoding, whitespace from the JSON string **SHOULD** be eliminated to keep the resulting out-of-band message string as short as possible. +During Base64Url encoding, whitespace from the JSON string **SHOULD** be eliminated to keep the resulting out-of-band message string as short as possible. #### Example Out-of-Band Message Encoding @@ -390,16 +394,16 @@ Whitespace removed: {"@type":"https://didcomm.org/out-of-band/1.0/invitation","@id":"69212a3a-d068-4f9d-a2dd-4741bca89af3","label":"Faber College","goal_code":"issue-vc","goal":"To issue a Faber College Graduate credential","handshake_protocols":["https://didcomm.org/didexchange/1.0","https://didcomm.org/connections/1.0"],"services":["did:sov:LjgpST2rjsoxYegQDRm7EL"]} ``` -Base 64 URL Encoded: +Base64Url encoded: ```text -eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCAiZ29hbF9jb2RlIjoiaXNzdWUtdmMiLCJnb2FsIjoiVG8gaXNzdWUgYSBGYWJlciBDb2xsZWdlIEdyYWR1YXRlIGNyZWRlbnRpYWwiLCJoYW5kc2hha2VfcHJvdG9jb2xzIjpbImh0dHBzOi8vZGlkY29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIiwiaHR0cHM6Ly9kaWRjb21tLm9yZy9jb25uZWN0aW9ucy8xLjAiXSwic2VydmljZSI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 +eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 ``` -Example URL: +Example URL with Base64Url encoded message: ```text -http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCAiZ29hbF9jb2RlIjoiaXNzdWUtdmMiLCJnb2FsIjoiVG8gaXNzdWUgYSBGYWJlciBDb2xsZWdlIEdyYWR1YXRlIGNyZWRlbnRpYWwiLCJoYW5kc2hha2VfcHJvdG9jb2xzIjpbImh0dHBzOi8vZGlkY29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIiwiaHR0cHM6Ly9kaWRjb21tLm9yZy9jb25uZWN0aW9ucy8xLjAiXSwic2VydmljZSI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 +http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 ``` Out-of-band message URLs can be transferred via any method that can send text, including an email, SMS, posting on a website, or QR Code. @@ -417,9 +421,9 @@ Subject: Your request to connect and receive your graduate verifiable credential Dear Alice, -To receive your Faber College graduation certificate, click here to [connect](http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCAiZ29hbF9jb2RlIjoiaXNzdWUtdmMiLCJnb2FsIjoiVG8gaXNzdWUgYSBGYWJlciBDb2xsZWdlIEdyYWR1YXRlIGNyZWRlbnRpYWwiLCJoYW5kc2hha2VfcHJvdG9jb2xzIjpbImh0dHBzOi8vZGlkY29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIiwiaHR0cHM6Ly9kaWRjb21tLm9yZy9jb25uZWN0aW9ucy8xLjAiXSwic2VydmljZSI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0) with us, or paste the following into your browser: +To receive your Faber College graduation certificate, click here to [connect](http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0) with us, or paste the following into your browser: -http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCAiZ29hbF9jb2RlIjoiaXNzdWUtdmMiLCJnb2FsIjoiVG8gaXNzdWUgYSBGYWJlciBDb2xsZWdlIEdyYWR1YXRlIGNyZWRlbnRpYWwiLCJoYW5kc2hha2VfcHJvdG9jb2xzIjpbImh0dHBzOi8vZGlkY29tbS5vcmcvZGlkZXhjaGFuZ2UvMS4wIiwiaHR0cHM6Ly9kaWRjb21tLm9yZy9jb25uZWN0aW9ucy8xLjAiXSwic2VydmljZSI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 +http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 If you don't have an identity agent for holding credentials, you will be given instructions on how you can get one. @@ -440,24 +444,33 @@ It seems inevitable that the length of some out-of-band message will be too long - `https://example.com/8E6nEcJ26TTE` - `https://example.com/sky/event/8DcnUW2h8m4jcfPdQ2uMN7/work-laptop-bag/s/u` - On receipt of this form of message, the agent **MUST** perform an HTTP GET to retrieve the associated out-of-band message. The agent **SHOULD** include an `Accept` header requesting the `application/json` MIME type. -- The sender **MAY** include a `Content-Type` header specifying `application/json; charset=utf-8`. If so, the sender **MUST** return the invitation in JSON format. - - A sender may decide to wait to generate the full invitation until the redirection event of the shortened URL to the full length form dynamic, so that a single QR code can be used for distinct out-of-band messages. -- The sender **MAY** respond with a `status_code` of `301` or `302` and a `Location` header specifying the long out-of-band message URL. +- The sender **MAY** include a `Content-Type` header specifying `application/json; charset=utf-8`, and in the case where the agent included an `Accept` header for the `application/json` MIME type, the sender **MUST** include the header. If so, the sender **MUST** return the invitation in JSON format in the response body with a `status_code` of `200`. +- The sender **MAY** respond with a `status_code` of `301` or `302` and include a `Location` header specifying the long out-of-band message URL. - This redirect option operates like many commercial URL shorteners. - The sender **MUST** invalidate the URL after message retrieval or after an expiration time to prevent unintended parties from retrieving a copy of the message. - A sender **MUST NOT** use a commercial URL shortener unless it supports invalidating the URL. A usable QR code will always be able to be generated from the shortened form of the URL. + +#### URL Shortening Caveats + +Some HTTP libraries don't support stopping redirects from occuring on reception of a `301` or `302`, in this instance the redirect is automatically followed and will result in a response that **MAY** have a status of `200` and **MAY** contain a URL that can be processed as a normal `Out-of-Band` message. + +If the agent performs a HTTP GET with the `Accept` header requesting `application/json` MIME type the response can either contain the message in `json` or result in a redirect, processing of the response should attempt to determine which response type is received and process the message accordingly. + #### Out-of-Band Message Publishing The _sender_ will publish or transmit the out-of-band message URL in a manner available to the intended _receiver_. After publishing, the sender is in the _await-response_ state, will the receiver is in the _prepare-response_ state. #### Out-of-Band Message Processing -When they receiver receives the out-of-band message URL, there are two possible user flows, depending on whether the individual has an Aries agent. If the individual is new to Aries, they will likely load the URL in a browser. The resulting page **SHOULD** contain instructions on how to get started by installing an Aries agent. That install flow will transfer the out-of-band message to the newly installed software. +If the receiver receives an `out-of-band` message in the form of a QR code, the receiver should attempt to decode the QR code to an out-of-band message URL for processing. + +When the receiver receives the out-of-band message URL, there are two possible user flows, depending on whether the individual has an Aries agent. If the individual is new to Aries, they will likely load the URL in a browser. The resulting page **SHOULD** contain instructions on how to get started by installing an Aries agent. That install flow will transfer the out-of-band message to the newly installed software. + +A user that already has those steps accomplished will have the URL received by software directly. That software will attempt to base64URL decode the string and can read the out-of-band message directly out of the `oob` query parameter, without loading the URL. If this process fails then the software should attempt the steps to [process a shortened URL](#url-shortening). -A user that already has those steps accomplished will have the URL received by software directly. That software will base64URL decode the string and can read the out-of-band message directly out of the `oob` query parameter, without loading the URL. > **NOTE**: In receiving the out-of-band message, the base64url decode implementation used **MUST** > correctly decode padded and unpadded base64URL encoded data. @@ -537,4 +550,4 @@ The following lists the implementations (if any) of this RFC. Please do a pull r Name / Link | Implementation Notes --- | --- - | \ No newline at end of file + | diff --git a/features/0445-rich-schema-mapping/README.md b/features/0445-rich-schema-mapping/README.md index bb4640077..8abfbbd61 100644 --- a/features/0445-rich-schema-mapping/README.md +++ b/features/0445-rich-schema-mapping/README.md @@ -1,8 +1,8 @@ # Aries RFC 0445: Aries Rich Schema Mapping - Author: [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com), [Ken Ebert](mailto:ken@sovrin.org), [Brent Zundel](mailto:brent.zundel@evernym.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-03-16 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-03-16 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0446-rich-schema-cred-def/README.md b/features/0446-rich-schema-cred-def/README.md index 6aeab7609..81fe80854 100644 --- a/features/0446-rich-schema-cred-def/README.md +++ b/features/0446-rich-schema-cred-def/README.md @@ -1,8 +1,8 @@ # Aries RFC 0446: Aries Rich Schema Credential Definition - Author: [Alexander Shcherbakov](mailto:alexander.shcherbakov@evernym.com), [Ken Ebert](mailto:ken@sovrin.org), [Brent Zundel](mailto:brent.zundel@evernym.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-03-16 -- Status Note: Part of proposed Rich Schema capabilities for credentials +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Supersedes: - Start Date: 2019-03-16 - Tags: [feature](/tags.md#feature), [rich-schemas](/tags.md#rich-schemas) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index 7c975e53d..1a8494a17 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -1,14 +1,35 @@ # Aries RFC 0453: Issue Credential Protocol 2.0 - Authors: Nikita Khateev, Stephen Klump, Stephen Curran -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-04-15 - Status Note: See [RFC 0454](../0454-present-proof-v2/README.md) for the presentation part of using credentials. - Supersedes: [RFC 0036 Issue Credential v1.x](../0036-issue-credential/README.md) - Start Date: 2020-03-23 - Tags: [feature](/tags.md#feature), [decorator](/tags.md#decorator), [protocol](/tags.md#protocol), [credentials](/tags.md#credentials), [test-anomaly](/tags.md#test-anomaly) -## Version Change Log +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. +- 20240313: Version 2.0 is the current version +- 20240311: Removed references to payments in the protocol to clarify to those new to the protocol that they have not been implemented by anyone. + +For a period of time, versions 2.1 and 2.2 where defined in this RFC. Those +definitions were added prior to any implementations, and to date, there are no +known implementations available or planned. An attempt at [implementing version 2.1] +was not merged into the main branch of [Aries Cloud Agent Python], deemed +overly complicated and not worth the effort for what amounts to an edge case +(issuing multiple credentials of the same type in a single protocol instance). +Further, there is a [version 3.0] of this protocol that has been specified and implemented that +does not include these capabilities. Thus, a decision was made that versions 2.1 and 2.2 be removed +as being not accepted by the community and overly complicated to both implement +and migrate from. Those interested in seeing how those capabilities were +specified can look at this [protocol before they were removed]. + +[implementing version 2.1]: https://github.com/hyperledger/aries-cloudagent-python/pull/2088 +[protocol before they were removed]: https://github.com/hyperledger/aries-rfcs/tree/00487467f42528a2490bcf9c303b9469ed0da5bb/features/0453-issue-credential-v2 +[Aries Cloud Agent Python]: https://github.com/hyperledger/aries-cloudagent-python +[version 3.0]: https://github.com/decentralized-identity/waci-didcomm/tree/main/issue_credential ### 2.0/propose-credential and identifiers @@ -29,6 +50,10 @@ We need a standard protocol for issuing credentials. This is the basis of intero ## Tutorial +### Name and Version + +`issue-credential`, version 2.0 + ### Roles There are two roles in this protocol: Issuer and Holder. Technically, the latter role is only potential until the protocol completes; that is, the second party becomes a Holder of a credential by completing the protocol. However, we will use the term Holder throughout, to keep things simple. @@ -37,7 +62,7 @@ There are two roles in this protocol: Issuer and Holder. Technically, the latter ### Goals -When the goals of each role are not available because of context, goal codes may be specifically included in protocol messages. This is particularly helpful to differentiate between credentials passed between the same parties for several different reasons. A goal code included should be considered to apply to the entire thread and is not necessary to be repeated on each message. Changing the goal code may be done by including the new code in a message. All goal codes are optional, and without default. +When the goals of each role are not available because of context, goal codes may be specifically included in protocol messages. This is particularly helpful to differentiate between credentials passed between the same parties for several different reasons. A goal code included should be considered to apply to the entire thread and is not necessary to be repeated on each message. Changing the goal code may be done by including the new code in a message. All goal codes are optional, and without default. ### States @@ -45,19 +70,19 @@ The choreography diagram [below](#choreography-diagram) details how state evolve #### Issuer States -* proposal-received -* offer-sent -* request-received -* credential-issued -* done +- proposal-received +- offer-sent +- request-received +- credential-issued +- done #### Holder States -* proposal-sent -* offer-received -* request-sent -* credential-received -* done +- proposal-sent +- offer-received +- request-sent +- credential-received +- done Errors might occur in various places. For example, an Issuer might offer a credential for a price that the Holder is unwilling to pay. All errors are modeled with a `problem-report` message. Easy-to-anticipate errors reset the flow as shown in the diagrams, and use the code `issuance-abandoned`; more exotic errors (e.g., server crashed at Issuer headquarters in the middle of a workflow) may have different codes but still cause the flow to be abandoned in the same way. That is, in this version of the protocol, all errors cause the state of both parties (the sender and the receiver of the `problem-report`) to revert to `null` (meaning it is no longer engaged in the protocol at all). Future versions of the protocol may allow more granular choices (e.g., requesting and receiving a (re-)send of the `issue-credential` message if the Holder times out while waiting in the `request-sent` state). @@ -67,10 +92,10 @@ The state table outlines the protocol states and transitions. The Issue Credential protocol consists of these messages: -* `propose-credential` - potential Holder to Issuer (optional). Tells what the Holder hopes to receive. -* `offer-credential` - Issuer to potential Holder (optional for some credential implementations; required for Hyperledger Indy). Tells what the Issuer intends to issue, and possibly, the price the Issuer expects to be paid. -* `request-credential` - potential Holder to Issuer. If neither of the previous message types is used, this is the message that begins the protocol. -* `issue-credential` - Issuer to new Holder. Attachment payload contains the actual credential. +- `propose-credential` - potential Holder to Issuer (optional). Tells what the Holder hopes to receive. +- `offer-credential` - Issuer to potential Holder (optional for some credential implementations; required for Hyperledger Indy). Tells what the Issuer intends to issue, and possibly, the price the Issuer expects to be paid. +- `request-credential` - potential Holder to Issuer. If neither of the previous message types is used, this is the message that begins the protocol. +- `issue-credential` - Issuer to new Holder. Attachment payload contains the actual credential. In addition, the [`ack`](../0015-acks/README.md) and [`problem-report`](../0035-report-problem/README.md) messages are adopted into the protocol for confirmation and error handling. @@ -86,14 +111,12 @@ Any of the [0017-attachments RFC](../../concepts/0017-attachments/README.md#json #### Choreography Diagram -
-Note: This diagram was made in draw.io. To make changes: - -- upload the drawing HTML from this folder to the [draw.io](https://draw.io) site (Import From...GitHub), -- make changes, -- export the picture and HTML to your local copy of this repo, and -- submit a pull request. -
+> Note: This diagram was made in draw.io. To make changes: +> +> - upload the drawing HTML from this folder to the [draw.io](https://draw.io) site (Import From...GitHub), +> - make changes, +> - export the picture and HTML to your local copy of this repo, and +> - submit a pull request. The protocol has 3 alternative beginnings: @@ -142,19 +165,20 @@ Message format: Description of attributes: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `comment` -- an optional field that provides human readable information about this Credential Proposal, so the proposal can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). -* `credential_preview` -- an optional JSON-LD object that represents the credential data that Prover wants to receive. It matches the schema of [Credential Preview](#preview-credential). -* `formats` -- contains an entry for each `filters~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. -* `filters~attach` -- an array of attachments that further define the credential being proposed. This might be used to clarify which formats or format versions are wanted. +- `goal_code` -- optional field that indicates the goal of the message sender. +- `comment` -- an optional field that provides human readable information about this Credential Proposal, so the proposal can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). +- `credential_preview` -- an optional JSON-LD object that represents the credential data that Prover wants to receive. It matches the schema of [Credential Preview](#preview-credential). +- `formats` -- contains an entry for each `filters~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. +- `filters~attach` -- an array of attachments that further define the credential being proposed. This might be used to clarify which formats or format versions are wanted. ##### Propose Attachment Registry Credential Format | Format Value | Link to Attachment Format | Comment | ---- | --- | --- | --- | -DIF Credential Manifest | `dif/credential-manifest@v1.0` | [`propose-credential` attachment format](../0511-dif-cred-manifest-attach/README.md#propose-credential-attachment-format) | -Linked Data Proof VC Detail | `aries/ld-proof-vc-detail@v1.0` | [`ld-proof-vc-detail` attachment format](../0593-json-ld-cred-attach/README.md#ld-proof-vc-detail-attachment-format) | -Hyperledger Indy Credential Abstract | `hlindy/cred-filter@v2.0` | [`cred filter` format](../0592-indy-attachments/README.md#cred-filter-format)| +--- | --- | --- | --- | +DIF Credential Manifest | `dif/credential-manifest@v1.0` | [`propose-credential` attachment format](../0511-dif-cred-manifest-attach/README.md#propose-credential-attachment-format) | | +Linked Data Proof VC Detail | `aries/ld-proof-vc-detail@v1.0` | [`ld-proof-vc-detail` attachment format](../0593-json-ld-cred-attach/README.md#ld-proof-vc-detail-attachment-format) | | +Hyperledger Indy Credential Filter | `hlindy/cred-filter@v2.0` | [`cred filter` format](../0592-indy-attachments/README.md#cred-filter-format)| | +Hyperledger AnonCreds Credential Filter | `anoncreds/credential-filter@v1.0` | [`Credential Filter` format](../0771-anoncreds-attachments/README.md#credential-filter-format)| | #### Offer Credential @@ -190,14 +214,12 @@ Message Format: Description of fields: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `replacement_id` -- an optional field to help coordinate credential replacement. When this is present and matches the `replacement_id` of a previously issued credential, it may be used to inform the recipient that the offered credential is considered to be a replacement to the previous credential. This value is unique to the issuer. It must not be used in a credential presentation. -* `comment` -- an optional field that provides human readable information about this Credential Offer, so the offer can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). -* `credential_preview` -- a JSON-LD object that represents the credential data that Issuer is willing to issue. It matches the schema of [Credential Preview](#preview-credential); -* `formats` -- contains an entry for each `offers~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. -* `offers~attach` -- an array of attachments that further define the credential being offered. This might be used to clarify which formats or format versions will be issued. - -The Issuer may add a [`~payment-request` decorator](../0075-payment-decorators/README.md#payment_request) to this message to convey the need for payment before issuance. See the [payment section below](#payments-during-credential-exchange) for more details. +- `goal_code` -- optional field that indicates the goal of the message sender. +- `replacement_id` -- an optional field to help coordinate credential replacement. When this is present and matches the `replacement_id` of a previously issued credential, it may be used to inform the recipient that the offered credential is considered to be a replacement to the previous credential. This value is unique to the issuer. It must not be used in a credential presentation. +- `comment` -- an optional field that provides human readable information about this Credential Offer, so the offer can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). +- `credential_preview` -- a JSON-LD object that represents the credential data that Issuer is willing to issue. It matches the schema of [Credential Preview](#preview-credential); +- `formats` -- contains an entry for each `offers~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. +- `offers~attach` -- an array of attachments that further define the credential being offered. This might be used to clarify which formats or format versions will be issued. It is possible for an Issuer to add a [`~timing.expires_time` decorator](../0032-message-timing/README.md#tutorial) to this message to convey the idea that the offer will expire at a particular point in the future. Such behavior is not a special part of this protocol, and support for it is not a requirement of conforming implementations; the `~timing` decorator is simply a general possibility for any DIDComm message. We mention it here just to note that the protocol can be enriched in composable ways. @@ -208,10 +230,12 @@ Credential Format | Format Value | Link to Attachment Format | Comment | DIF Credential Manifest | `dif/credential-manifest@v1.0` | [`offer-credential` attachment format](../0511-dif-cred-manifest-attach/README.md#offer-credential-attachment-format) | Hyperledger Indy Credential Abstract | `hlindy/cred-abstract@v2.0` | [`cred abstract` format](../0592-indy-attachments/README.md#cred-abstract-format)| Linked Data Proof VC Detail | `aries/ld-proof-vc-detail@v1.0` | [`ld-proof-vc-detail` attachment format](../0593-json-ld-cred-attach/README.md#ld-proof-vc-detail-attachment-format) | +Hyperledger AnonCreds Credential Offer | `anoncreds/credential-offer@v1.0` | [`Credential Offer` format](../0771-anoncreds-attachments/README.md#credential-offer-format)| +W3C VC - Data Integrity Proof Credential Offer | `didcomm/w3c-di-vc-offer@v0.1` | [`Credential Offer` format](../0809-w3c-data-integrity-credential-attachment/README.md#credential-offer-attachment-format)| #### Request Credential -This is a message sent by the potential Holder to the Issuer, to request the issuance of a credential. Where circumstances do not require a preceding Offer Credential message (e.g., there is no cost to issuance that the Issuer needs to explain in advance, and there is no need for cryptographic negotiation), this message initiates the protocol. In Hyperledger Indy, this message can only be sent in response to an `offer-credential` message. +This is a message sent by the potential Holder to the Issuer, to request the issuance of a credential. Where circumstances do not require a preceding Offer Credential message (e.g., there is no cost to issuance that the Issuer needs to explain in advance, and there is no need for cryptographic negotiation), this message initiates the protocol. When using the Hyperledger Indy AnonCreds verifiable credential format, this message can only be sent in response to an `offer-credential` message. Message Format: @@ -241,12 +265,10 @@ Message Format: Description of Fields: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `comment` -- an optional field that provides human readable information about this Credential Request, so it can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). -* `formats` -- contains an entry for each `requests~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. -* `requests~attach` -- an array of [attachments](../../concepts/0017-attachments/README.md) defining the requested formats for the credential. - -This message may have a [`~payment-receipt` decorator](../0075-payment-decorators/README.md#payment_receipt) to prove to the Issuer that the potential Holder has satisfied a payment requirement. See the [payment section below](#payments-during-credential-exchange). +- `goal_code` -- optional field that indicates the goal of the message sender. +- `comment` -- an optional field that provides human readable information about this Credential Request, so it can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). +- `formats` -- contains an entry for each `requests~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. +- `requests~attach` -- an array of [attachments](../../concepts/0017-attachments/README.md) defining the requested formats for the credential. ##### Request Attachment Registry @@ -255,10 +277,12 @@ Credential Format | Format Value | Link to Attachment Format | Comment | DIF Credential Manifest | `dif/credential-manifest@v1.0` | [`request-credential` attachment format](../0511-dif-cred-manifest-attach/README.md#request-credential-attachment-format) | Hyperledger Indy Credential Request | `hlindy/cred-req@v2.0` | [`cred request` format](../0592-indy-attachments/README.md#cred-request-format)| Linked Data Proof VC Detail | `aries/ld-proof-vc-detail@v1.0` | [`ld-proof-vc-detail` attachment format](../0593-json-ld-cred-attach/README.md#ld-proof-vc-detail-attachment-format) | +Hyperledger AnonCreds Credential Request | `anoncreds/credential-request@v1.0` | [`Credential Request` format](../0771-anoncreds-attachments/README.md#credential-request-format)| +W3C VC - Data Integrity Proof Credential Request | `didcomm/w3c-di-vc-request@v0.1` | [`Credential Request` format](../0809-w3c-data-integrity-credential-attachment/README.md#credential-request-attachment-format)| #### Issue Credential -This message contains as an [attached payload](../../concepts/0017-attachments/README.md) the credential being issued. It is sent in response to a valid Request Credential message. +This message contains a verifiable credential being issued as an [attached payload](../../concepts/0017-attachments/README.md). It is sent in response to a valid Request Credential message. Message Format: @@ -289,12 +313,11 @@ Message Format: Description of fields: -* `replacement_id` -- an optional field that provides an identifier used to manage credential replacement. When this value is present and matches the `replacement_id` of a previously issued credential, this credential may be considered as a replacement for that credential. This value is unique to the issuer. It must not be used in a credential presentation. -* `comment` -- an optional field that provides human readable information about the issued credential, so it can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). -* `formats` -- contains an entry for each `credentials~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. -* `credentials~attach` -- an array of attachments containing the issued credentials. +- `replacement_id` -- an optional field that provides an identifier used to manage credential replacement. When this value is present and matches the `replacement_id` of a previously issued credential, this credential may be considered as a replacement for that credential. This value is unique to the issuer. It must not be used in a credential presentation. +- `comment` -- an optional field that provides human readable information about the issued credential, so it can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). +- `formats` -- contains an entry for each `credentials~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. +- `credentials~attach` -- an array of attachments containing the issued credentials. -If the issuer wants an acknowledgement that he issued credential was accepted, this message must be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. Outcome in the context of this protocol means the acceptance of the credential in whole, i.e. the credential is verified and the contents of the credential are acknowledged. Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Holder to respond with an explicit `ack` message as described in the please ack decorator RFC. ##### Credentials Attachment Registry @@ -302,6 +325,12 @@ Credential Format | Format Value | Link to Attachment Format | Comment | --- | --- | --- | --- | Linked Data Proof VC | `aries/ld-proof-vc@v1.0` | [`ld-proof-vc` attachment format](../0593-json-ld-cred-attach/README.md#ld-proof-vc-attachment-format) | Hyperledger Indy Credential | `hlindy/cred@v2.0` | [credential format](../0592-indy-attachments/README.md#credential-format)| +Hyperledger AnonCreds Credential| `anoncreds/credential@v1.0` | [`Credential` format](../0771-anoncreds-attachments/README.md#credential-format)| +W3C VC - Data Integrity Proof Credential | `didcomm/w3c-di-vc@v0.1` | [`Credential` format](../0809-w3c-data-integrity-credential-attachment/README.md#credential-attachment-format)| + +#### Adopted Problem Report + +The [problem-report message is adopted](../0035-report-problem/README.md) by this protocol. `problem-report` messages can be used by either party to indicate an error in the protocol. #### Preview Credential @@ -333,8 +362,8 @@ The optional `mime-type` advises the issuer how to render a binary attribute, to The mandatory `value` holds the attribute value: -* if `mime-type` is missing (null), then `value` is a string. In other words, implementations interpret it the same as any other key+value pair in JSON -* if `mime-type` is not null, then `value` is always a base64url-encoded string that represents a binary BLOB, and `mime-type` tells how to interpret the BLOB after base64url-decoding. +- if `mime-type` is missing (null), then `value` is a string. In other words, implementations interpret it the same as any other key+value pair in JSON +- if `mime-type` is not null, then `value` is always a base64url-encoded string that represents a binary BLOB, and `mime-type` tells how to interpret the BLOB after base64url-decoding. ## Threading @@ -342,20 +371,6 @@ Threading can be used to initiate a [sub-protocol](../../concepts/0003-protocols If threading were added to all of the above messages, a `~thread` decorator would be present, and later messages in the flow would reference the `@id` of earlier messages to stitch the flow into a single coherent sequence. Details about threading can be found in the [0008: Message ID and Threading](../../concepts/0008-message-id-and-threading/README.md) RFC. -## Payments during credential exchange - -Credentialing ecosystems may wish to associate credential issuance with payments by fiat currency or tokens. This is common with non-digital credentials today; we pay a fee when we apply for a passport or purchase a plane ticket. Instead or in addition, some circumstances may fit a mode where payment is made each time a credential is *used*, as when a Verifier pays a Prover for verifiable medical data to be used in research, or when a Prover pays a Verifier as part of a workflow that applies for admittance to a university. For maximum flexibility, we mention payment possibilities here as well as in the sister [0037: Present Proof](../0037-present-proof/README.md) RFC. - -### Payment decorators - -Wherever they happen and whoever they involve, payments are accomplished with optional payment decorators. See [0075: Payment Decorators](../0075-payment-decorators/README.md). - -### Payment flow - -A `~payment-request` may decorate a Credential Offer from Issuer to Holder. When they do, a corresponding `~payment-receipt` should be provided on the Credential Request returned to the Issuer. - -During credential presentation, the Verifier may pay the Holder as compensation for Holder for disclosing data. This would require a `~payment-request` in a Presentation Proposal message, and a corresponding `~payment-receipt` in the subsequent Presentation Request. If such a workflow begins with the Presentation Request, the Prover may sending back a Presentation (counter-)Proposal with appropriate decorator inside it. - ### Limitations Smart contracts may be missed in ecosystem, so operation "issue credential after payment received" is not atomic. It’s possible case that malicious issuer will charge first and then will not issue credential in fact. But this situation should be easily detected and appropriate penalty should be applied in such type of networks. @@ -379,13 +394,12 @@ See [RFC 0036 Issue Credential, v1.x](../0036-issue-credential/README.md). ## Unresolved questions -- References to the expected Ack and Problem Report messages should be added. - We might need to propose a new MIME type for credential (the same way as .docx is not processed as generic xml). See [this issue](https://github.com/w3c/vc-data-model/issues/421) against the W3C/vc-data-model. ## 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 ---- | --- +Name / Link | Implementation Notes | +--- | --- | | | diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index 9ac19ebdc..420d9bd4c 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -1,19 +1,35 @@ # Aries RFC 0454: Present Proof Protocol 2.0 - Authors: Nikita Khateev, Stephen Curran -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-04-15 - Status Note: See [RFC 0453](../0453-issue-credential-v2/README.md) for the corresponding issue credential protocol. - Supersedes: [RFC 0037](../0037-present-proof/README.md) - Start Date: 2020-05-27 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol), [credentials](/tags.md#credentials), [test-anomaly](/tags.md#test-anomaly) -## Version Change Log - -### 2.1 - Add ability to request multiple presentations - -A minor update to add mechanism for a Verifier to request the Prover submit multiple presentations in the "presentation" message(s), each presentation sourced from different credentials that satisfy the presentation request. -An example use of this capability is an employer (Verifier) requesting multiple "proof of employment" presentations from a job application (Prover), each satisfying the one presentation request. +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. +- 20240311: Version 2.0 is the current version + +For a period of time, versions 2.1 and 2.2 where defined in this RFC. Those +definitions were added prior to any implementations, and to date, there are no +known implementations available or planned. An attempt at [implementing version 2.1] +of the associated "issue multiple credentials" was not merged into the main branch of +[Aries Cloud Agent Python], deemed overly complicated and not worth the effort +for what amounts to an edge case (presenting multiple presentations of the same type +in a single protocol instance). Further, there is a [version 3.0] of this +protocol that has been specified and implemented that does not include these +capabilities. Thus, a decision was made that versions 2.1 and 2.2 be removed as +being not accepted by the community and overly complicated to both implement and +migrate from. Those interested in seeing how those capabilities were specified +can look at this [protocol before they were removed]. + +[implementing version 2.1]: https://github.com/hyperledger/aries-cloudagent-python/pull/2088 +[protocol before they were removed]: https://github.com/hyperledger/aries-rfcs/tree/00487467f42528a2490bcf9c303b9469ed0da5bb/features/0454-present-proof-v2 +[Aries Cloud Agent Python]: https://github.com/hyperledger/aries-cloudagent-python +[version 3.0]: https://github.com/decentralized-identity/waci-didcomm/blob/main/present_proof/present-proof-v3.md ### 2.0 - Alignment with [RFC 0453 Issue Credential](../0453-issue-credential-v2/README.md) @@ -33,7 +49,7 @@ We need a standard protocol for a verifier to request a presentation from a prov ### Name and Version -`present-proof`, version 2.1 +`present-proof`, version 2.0 ### Key Concepts @@ -52,7 +68,7 @@ The roles are `verifier` and `prover`. The `verifier` requests the presentation ### Goals -When the goals of each role are not available because of context, goal codes may be specifically included in protocol messages. This is particularly helpful to differentiate between credentials passed between the same parties for several different reasons. A goal code included should be considered to apply to the entire thread and is not necessary to be repeated on each message. Changing the goal code may be done by including the new code in a message. All goal codes are optional, and without default. +When the goals of each role are not available because of context, goal codes may be specifically included in protocol messages. This is particularly helpful to differentiate between credentials passed between the same parties for several different reasons. A goal code included should be considered to apply to the entire thread and is not necessary to be repeated on each message. Changing the goal code may be done by including the new code in a message. All goal codes are optional, and without default. ### States @@ -60,36 +76,33 @@ The following states are defined and included in the state transition table belo #### States for Verifier -* request-sent -* proposal-received -* presentation-received -* abandoned -* done +- request-sent +- proposal-received +- presentation-received +- abandoned +- done #### States for Prover -* request-received -* proposal-sent -* presentation-sent -* abandoned -* done +- request-received +- proposal-sent +- presentation-sent +- abandoned +- done [![state machine matrix](present-proof-states.png)](https://docs.google.com/spreadsheets/d/1XThILA0_ZiH3voBv5M8-GIt1We9t_Rlg0xaY5jmNVIA/edit) For the most part, these states map onto the transitions shown in both the state transition table above, and in the choreography diagram ([below](#choreography-diagram)) in obvious ways. However, a few subtleties are worth highlighting: -* The Verifier may indicate in the `request-presentation` message that the Prover may provide multiple Presentations (in one or more `presentation` messages). In that case, the Verifier stays in the `request-state` if the Prover indicates in `presentation` messages that additional -`presentation` messages will be sent. See the messages (below) for how the Verifier and Prover indicate how multiple presentations are to be handled. - -* The final states for both the prover and verifier are `done` or `abandoned`, and once reached, no further updates to the protocol instance are expected. +- The final states for both the prover and verifier are `done` or `abandoned`, and once reached, no further updates to the protocol instance are expected. -* The `ack-presentation` is sent or not based on the value of `will_confirm` in the `request-presentation`. A verifier may send an `ack-presentation` message in response to the prover including the `~please_ack` decorator in the `presentation` message. Whether an `ack-presentation` is expected or not determines whether the states `presentation-sent` and `presentation-received` are used at all in a protocol instance. +- The `ack-presentation` is sent or not based on the value of `will_confirm` in the `request-presentation`. Whether an `ack-presentation` is expected or not determines whether the states `presentation-sent` and `presentation-received` are used at all in a protocol instance. -* The `ack-presentation` message should reflect the business validation of the proof (does the proof satisfy the business need?) not just the cryptographic verification. Ideally, those are as tightly aligned as possible. +- The `ack-presentation` message should reflect the business validation of the proof (does the proof satisfy the business need?) not just the cryptographic verification. Ideally, those are as tightly aligned as possible. -* When a Prover makes a (counter-)proposal, it transitions to the `proposal-sent` state. This state is only present by implication in the choreography diagram; it essentially equates to the null or begin state in that the Prover does nothing until a presentation request arrives, triggering the leftmost transition for the Prover. +- When a Prover makes a (counter-)proposal, it transitions to the `proposal-sent` state. This state is only present by implication in the choreography diagram; it essentially equates to the null or begin state in that the Prover does nothing until a presentation request arrives, triggering the leftmost transition for the Prover. -* Errors might occur in various places. For example, a Prover might decide not to respond to a `presentation-request` or a verifier may time out waiting for the Prover to supply a `presentation`. Errors should trigger a `problem-report`. In this version of the protocol, all errors cause the state of both parties (the sender and the receiver of the `problem-report`) to transition to the terminal `abandoned` state (meaning it is no longer engaged in the protocol at all). +- Errors might occur in various places. For example, a Prover might decide not to respond to a `presentation-request` or a verifier may time out waiting for the Prover to supply a `presentation`. Errors should trigger a `problem-report`. In this version of the protocol, all errors cause the state of both parties (the sender and the receiver of the `problem-report`) to transition to the terminal `abandoned` state (meaning it is no longer engaged in the protocol at all). ### Choreography Diagram @@ -99,9 +112,9 @@ For the most part, these states map onto the transitions shown in both the state The present proof protocol consists of these messages: -* `propose-presentation` - Prover to Verifier (optional) - propose a presentation or send a counter-proposal in response to a `request-presentation` message -* `request-presentation` - Verifier to Prover - request a presentation -* `presentation` - Prover to Verifier - provide a presentation(s) in response to a request +- `propose-presentation` - Prover to Verifier (optional) - propose a presentation or send a counter-proposal in response to a `request-presentation` message +- `request-presentation` - Verifier to Prover - request a presentation +- `presentation` - Prover to Verifier - provide a presentation in response to a request In addition, the [`ack`](../0015-acks/README.md) and [`problem-report`](../0035-report-problem/README.md) messages are adopted into the protocol for confirmation and error handling. @@ -139,10 +152,10 @@ An optional message sent by the prover to the verifier to initiate a proof prese Description of fields: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `comment` -- a field that provides some human readable information about the proposed presentation. -* `formats` -- contains an entry for each `filter~attach` array entry, including an optional value of the attachment `@id` (if attachments are present) and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. -* `proposals~attach` -- an optional array of attachments that further define the presentation request being proposed. This might be used to clarify which formats or format versions are wanted. +- `goal_code` -- optional field that indicates the goal of the message sender. +- `comment` -- a field that provides some human readable information about the proposed presentation. +- `formats` -- contains an entry for each `filter~attach` array entry, including an optional value of the attachment `@id` (if attachments are present) and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. +- `proposals~attach` -- an optional array of attachments that further define the presentation request being proposed. This might be used to clarify which formats or format versions are wanted. If the `proposals~attach` is not provided, the `attach_id` item in the `formats` array should not be provided. That form of the `propose-presentation` message is to indicate the presentation formats supported by the prover, independent of the verifiable presentation request content. @@ -153,9 +166,10 @@ Negotiation prior to the delivery of the presentation can be done using the `pro #### Propose Attachment Registry Presentation Format | Format Value | Link to Attachment Format | Comment | ---- | --- | --- | --- | -Hyperledger Indy Proof Req| hlindy/proof-req@v2.0 | [proof request format](../0592-indy-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. -DIF Presentation Exchange | `dif/presentation-exchange/definitions@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#propose-presentation-attachment-format) | +--- | --- | --- | --- | +Hyperledger Indy Proof Req | `hlindy/proof-req@v2.0` | [proof request format](../0592-indy-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. | +DIF Presentation Exchange | `dif/presentation-exchange/definitions@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#propose-presentation-attachment-format) | | +Hyperledger AnonCreds Proof Request | `anoncreds/proof-request@v1.0` | [`Proof Request` format](../0771-anoncreds-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. | ### Request Presentation @@ -168,7 +182,6 @@ From a verifier to a prover, the `request-presentation` message describes values "goal_code": "", "comment": "some comment", "will_confirm": true, - "present_multiple": false, "formats" : [ { "attach_id" : "", @@ -189,24 +202,19 @@ From a verifier to a prover, the `request-presentation` message describes values Description of fields: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `comment` -- a field that provides some human readable information about this request for a presentation. -* `will_confirm` -- an optional field that defaults to `false` to indicate that the Verifier will or will not send a post-presentation confirmation `ack` message. -* `present_multiple` -- an optional field that defaults to `false` to indicate that the Verifier would like the Prover to send multiple presentations that satisfy the presentation request from different verifiable credentials. -* `formats` -- contains an entry for each `request_presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation request format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. -* `request_presentations~attach` -- an array of attachments containing the acceptable verifiable presentation requests. - -While the `present_multiple` value can be set to true in any instance of the protocol, Verifiers are recommended to use the capability with care -if the `presentation-request` includes presenting claims from multiple verifiable credential types. Such scenarios can get overly complicated for the Prover -if they hold multiple instances of each of the requested credential. For example, an employer asking for multiple presentations for a single request for claims -from both employment and education verifiable credentials held by the Prover. +- `goal_code` -- optional field that indicates the goal of the message sender. +- `comment` -- a field that provides some human readable information about this request for a presentation. +- `will_confirm` -- an optional field that defaults to `false` to indicate that the verifier will or will not send a post-presentation confirmation `ack` message +- `formats` -- contains an entry for each `request_presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation request format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. +- `request_presentations~attach` -- an array of attachments containing the acceptable verifiable presentation requests. #### Presentation Request Attachment Registry Presentation Format | Format Value | Link to Attachment Format | Comment | ---- | --- | --- | --- | -Hyperledger Indy Proof Req| hlindy/proof-req@v2.0 | [proof request format](../0592-indy-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. -DIF Presentation Exchange | `dif/presentation-exchange/definitions@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#request-presentation-attachment-format) | +--- | --- | --- | --- | +Hyperledger Indy Proof Req| `hlindy/proof-req@v2.0` | [proof request format](../0592-indy-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. | +DIF Presentation Exchange | `dif/presentation-exchange/definitions@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#request-presentation-attachment-format) | | +Hyperledger AnonCreds Proof Request | `anoncreds/proof-request@v1.0` | [`Proof Request` format](../0771-anoncreds-attachments/README.md#proof-request-format) | Used to propose as well as request proofs. | ### Presentation @@ -218,7 +226,6 @@ This message is a response to a Presentation Request message and contains signed "@id": "", "goal_code": "", "comment": "some comment", - "last_presentation": true, "formats" : [ { "attach_id" : "", @@ -240,26 +247,24 @@ This message is a response to a Presentation Request message and contains signed Description of fields: -* `goal_code` -- optional field that indicates the goal of the message sender. -* `comment` -- a field that provides some human readable information about this presentation. -* `last_presentation` -- an optional field that defaults to `true` to indicate this is the last presentation message to be sent in satisfying the presentation request. If the value is `false`, the Prover MUST send another presentation message with an additional presentation(s). The Prover's last `presentation` message MUST have a `last_presentation` value of `false` (explicitly or by default). If the `present_multiple` field is absent or `false` in the `request_presentation` message from the Verifier, the `last_presentation` field on the first/only `presentation` message MUST be true (explicitly or by default). -* `formats` -- contains an entry for each `presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. -* `presentations~attach` -- an array of attachments containing the presentation in the requested format(s). If the `present_multiple` field is `true` in the `request_presentation` message from the Verifier, the Prover MAY include multiple presentations of the same format that satisfy the Presentation request from the Verifier. - -If the `last_presentation` field is `false`, the Verifier's state SHOULD remain in the `request-sent` state (barring an error), with the expectation that additional `presentation` messages will be coming from the prover. If the `last_presentation` value is `true` (explicitly or by default) the Verifier MUST transition to their next appropriate state. +- `comment` -- a field that provides some human readable information about this presentation. +- `goal_code` -- optional field that indicates the goal of the message sender. +- `formats` -- contains an entry for each `presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. +- `presentations~attach` -- an array of attachments containing the presentation in the requested format(s). -If the Prover wants an acknowledgement that the presentation was accepted, this message may be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. This is not necessary if the Verifier has indicated it will send an `ack-presentation` using the `will_confirm` property. Outcome in the context of this protocol is the definition of "successful" as described in [Ack Presentation](#ack-presentation). Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Verifier to respond with an explicit `ack` message as described in the please ack decorator RFC. +If the prover wants an acknowledgement that the presentation was accepted, this message may be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. This is not necessary if the verifier has indicated it will send an `ack-presentation` using the `will_confirm` property. Outcome in the context of this protocol is the definition of "successful" as described in [Ack Presentation](#ack-presentation). Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Verifier to respond with an explicit `ack` message as described in the please ack decorator RFC. #### Presentations Attachment Registry Presentation Format | Format Value | Link to Attachment Format | Comment | ---- | --- | --- | --- | -Hyperledger Indy Proof | hlindy/proof@v2.0 | [proof format](../0592-indy-attachments/README.md#proof-format) | -DIF Presentation Exchange | `dif/presentation-exchange/submission@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#presentation-attachment-format) | +--- | --- | --- | --- | +Hyperledger Indy Proof | `hlindy/proof@v2.0` | [proof format](../0592-indy-attachments/README.md#proof-format) | | +DIF Presentation Exchange | `dif/presentation-exchange/submission@v1.0` | [`propose-presentation` attachment format](../0510-dif-pres-exch-attach/README.md#presentation-attachment-format) | | +Hyperledger AnonCreds Proof | `anoncreds/proof@v1.0` | [`Proof` format](../0771-anoncreds-attachments/README.md#proof-format) | | ### Ack Presentation -A message from the verifier to the prover that the `Present Proof` protocol was completed successfully and is now in the `done` state. The message is an adopted `ack` from the [RFC 0015 acks protocol](../0015-acks/README.md). The definition of "successful" in this protocol means the acceptance of the presentation in whole, i.e. the proof is verified and the contents of the proof are acknowledged. The `ack` message MUST NOT be sent until a `last_presentation` value is `true` (explicitly or by default) in the `presentation` message from the Prover. +A message from the verifier to the prover that the `Present Proof` protocol was completed successfully and is now in the `done` state. The message is an adopted `ack` from the [RFC 0015 acks protocol](../0015-acks/README.md). The definition of "successful" in this protocol means the acceptance of the presentation in whole, i.e. the proof is verified and the contents of the proof are acknowledged. ### Problem Report @@ -273,7 +278,9 @@ Details are covered in the [Tutorial](#tutorial) section. ## Drawbacks -- None currently noted +The Indy format of the proposal attachment as proposed above does not allow nesting of logic along the lines of "A and either B or C if D, otherwise A and B", nor cross-credential options such as proposing a legal name issued by either (for example) a specific financial institution or government entity. + +The verifiable presentation standardization work being conducted in parallel to this in DIF and the W3C Credentials Community Group (CCG) should be included in at least the `Registry` tables of this document, and ideally used to eliminate the need for presentation format-specific options. ## Rationale and alternatives @@ -289,6 +296,6 @@ The previous major version of this protocol is [RFC 0037 Present Proof](../0037- 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 ---- | --- - | +Name / Link | Implementation Notes | +--- | --- | + | | diff --git a/features/0482-coprotocol-protocol/README.md b/features/0482-coprotocol-protocol/README.md index d10243186..17810775a 100644 --- a/features/0482-coprotocol-protocol/README.md +++ b/features/0482-coprotocol-protocol/README.md @@ -1,8 +1,8 @@ # Aries RFC 0482: Coprotocol Protocol 0.5 -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [PROPOSED](/README.md#proposed) -- Since: 2020-05-19 -- Status Note: Sister to [Aries RFC 0478](../../concepts/0478-coprotocols/README.md), which explains background concepts. Socialized on Aries community call in Feb 2020, using [these slides](https://docs.google.com/presentation/d/17hk6QqLW5M9E4TBPZwXIUBu9eEinMNXReceyZTF4LpA/edit). Discussed again in May 2020. Source files for graphics are either checked in or are published at https://j.mp/2XgyjH3. +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [STALLED](/README.md#stalled) +- Since: 2024-04-03 +- Status Note: No implementations have been created. - Start Date: 2020-02-03 - Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) diff --git a/features/0496-transition-to-oob-and-did-exchange/README.md b/features/0496-transition-to-oob-and-did-exchange/README.md index 5a1028531..e2544f3e1 100644 --- a/features/0496-transition-to-oob-and-did-exchange/README.md +++ b/features/0496-transition-to-oob-and-did-exchange/README.md @@ -1,9 +1,9 @@ -# Aries RFC 0496: Transition to the Out of Band and DID Exchange Protocols +# Aries RFC 0496: Transition to the Out of Band Protocol - Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca) -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-11-24 -- Status Note: In step 1 - update all implementations to accept Connection and OOB Invitations. **Target Completion Date: 2021.12.31** +- Status Note: In step 2 - All systems using OOB. **Target Completion Date: 2024-07-02** - Supersedes: - Start Date: 2020-06-07 - Tags: [feature](/tags.md#feature), [community-update](/tags.md#community-update), [test-anomaly](/tags.md#test-anomaly) @@ -28,10 +28,10 @@ The transition from the old to new messages will occur in four steps: - See the section below on [Step 1 out-of-band messages](#step-1-out-of-band-messages) - During Step 1, all agents should continue to send the current invitation and connection-less protocol messages. - Each agent builder SHOULD notify the community they have completed Step 1 by submitting a PR to update their entry in the [implementations](#implementations) section of this RFC. -- **Step 2**: Agent builders update all agent code bases and deployments to send out out-of-band invitations equivalent to the current invitation and connection-less protocol messages, and Agent builders add full out-of-band and did-exchange ([RFC 0023](../0023-did-exchange/README.md)) protocol support to all agent code bases and deployments. +- **Step 2**: Agent builders update all agent code bases and deployments to send out out-of-band invitations equivalent to the current invitation and connection-less protocol messages, and Agent builders add full out-of-band protocol support to all agent code bases and deployments. - Messages from existing RFCs being replaced by the out-of-band protocol are marked as `deprecated`. - Full out-of-band support is **NOT** required—just support for the out-of-band equivalents of the old `invitation` messages. - - When sending or receiving `did:peer` DIDs, the DIDs MUST conform to [RFC 627 Static Peer DIDs](../0627-static-peer-dids/README.md). + - When sending or receiving `did:peer` DIDs, the DIDs MUST conform to the [Peer DID Specification](https://identity.foundation/peer-did-method-spec/). - Each agent builder SHOULD notify the community they have completed Step 2 by submitting a PR to update their entry in the [implementations](#implementations) section. - **Step 3**: Support for the current invitation and connection-less protocol messages can be removed from all implementations and deployments, and all out-of-band `invitation` capabilities that align with the then current Aries Interop Profile (AIP) may be offered. diff --git a/features/0510-dif-pres-exch-attach/README.md b/features/0510-dif-pres-exch-attach/README.md index bd6e06456..14a4598b5 100644 --- a/features/0510-dif-pres-exch-attach/README.md +++ b/features/0510-dif-pres-exch-attach/README.md @@ -1,7 +1,7 @@ # Aries RFC 0510: Presentation-Exchange Attachment format for requesting and presenting proofs - Authors: George Aristy (SecureKey Technologies) -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2020-07-21 - Status Note: - Supersedes: @@ -59,7 +59,7 @@ The Prover responds with a `presentation` message containing a ### `propose-presentation` attachment format -Format identifier: `dif/presentation-exchange/definition@v1.0` +Format identifier: `dif/presentation-exchange/definitions@v1.0` #### Examples: propose-presentation @@ -72,7 +72,7 @@ Format identifier: `dif/presentation-exchange/definition@v1.0` "comment": "some comment", "formats" : [{ "attach_id" : "143c458d-1b1c-40c7-ab85-4d16808ddf0a", - "format" : "dif/presentation-exchange/definition@v1.0" + "format" : "dif/presentation-exchange/definitions@v1.0" }], "proposal~attach": [{ "@id": "143c458d-1b1c-40c7-ab85-4d16808ddf0a", @@ -106,7 +106,9 @@ Format identifier: `dif/presentation-exchange/definition@v1.0` ### `request-presentation` attachment format -Format identifier: `dif/presentation-exchange/definition@v1.0` +Format identifier: `dif/presentation-exchange/definitions@v1.0` + +Since the format identifier defined above is the same as the one used in the `propose-presentation` message, it's recommended to consider both the message `@type` and the `format` to accuarately understand the contents of the attachment. The contents of the attachment is a JSON object containing the Verifier's presentation definition and an _options_ object with proof options: @@ -145,7 +147,7 @@ Name|Status|Description "comment": "some comment", "formats" : [{ "attach_id" : "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947", - "format" : "dif/presentation-exchange/definition@v1.0" + "format" : "dif/presentation-exchange/definitions@v1.0" }], "request_presentations~attach": [{ "@id": "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947", @@ -196,7 +198,7 @@ Name|Status|Description "comment": "some comment", "formats" : [{ "attach_id" : "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947", - "format" : "dif/presentation-exchange/definition@v1.0" + "format" : "dif/presentation-exchange/definitions@v1.0" }], "request_presentations~attach": [{ "@id": "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947", diff --git a/features/0557-discover-features-v2/README.md b/features/0557-discover-features-v2/README.md index d72f20111..b6def52c4 100644 --- a/features/0557-discover-features-v2/README.md +++ b/features/0557-discover-features-v2/README.md @@ -1,8 +1,8 @@ # Aries RFC 0557: Discover Features Protocol v2.x - Authors: Daniel Hardman -- Status: [ACCEPTED](/README.md#accepted) -- Since: 2021-04-15 +- Status: [ADOPTED](/README.md#adopted) +- Since: 2024-05-01 - Status Note: Update to version 2.0 proposed in conjunction with DIDComm v2 efforts at DIF, where it became clear that we need to discover more than just protocol support of other agents. Included in [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md). - Supersedes: [version 1.0 of this protocol in RFC 0031](../0031-discover-features/README.md), which was widely referenced in the Aries eocsystem in 2018 and 2019. - Start Date: 2018-12-17 diff --git a/features/0587-encryption-envelope-v2/README.md b/features/0587-encryption-envelope-v2/README.md index adc3b5015..9340671a6 100644 --- a/features/0587-encryption-envelope-v2/README.md +++ b/features/0587-encryption-envelope-v2/README.md @@ -145,7 +145,7 @@ The media type of the envelope MUST be set in the `typ` [property](https://tools As discussed in [RFC 0434](../0434-outofband/README.md) and [RFC 0067](../0067-didcomm-diddoc-conventions/README.md), the `accept` property is used to advertise supported media types. The `accept` property may contain an envelope media type or a combination of the envelope media type and the content media type. In cases where the content media type is not present, the expectation is that the appropriate content media type can be inferred. -For example, `application/didcomm-enc-env` indicates both Envelope v1 and DIDComm v1 and `application/didcomm-encrypted+json` indicates both Envelope v2 and DIDComm v2. +For example, `application/didcomm-envelope-enc` indicates both Envelope v1 and DIDComm v1 and `application/didcomm-encrypted+json` indicates both Envelope v2 and DIDComm v2. However, some agents may choose to support Envelope v2 with a DIDComm v1 message payload. In case the `accept` property is set in both the DID service block and the out-of-band message, the out-of-band property takes precedence. diff --git a/features/0592-indy-attachments/README.md b/features/0592-indy-attachments/README.md index 0d92aa6b2..c8351c483 100644 --- a/features/0592-indy-attachments/README.md +++ b/features/0592-indy-attachments/README.md @@ -1,7 +1,7 @@ # Aries RFC 0592: Indy Attachment Formats for Requesting and Presenting Credentials - Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-04-15 - Status Note: Formalizes the Indy AnonCreds attachments for issuing credentials and presenting proofs. A part of the Indy AnonCreds subtarget of [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md). - Supersedes: less formally documented Indy attachment formats documented in [Aries RFC 0036](../0036-issue-credential/README.md), [Aries RFC 0037](../0037-present-proof/README.md), etc. @@ -163,6 +163,8 @@ A concrete, issued Indy credential may be transmitted over many protocols, but i This is a credential that's designed to be _held_ but not _shared directly_. It is stored in the holder's wallet and used to [derive a novel ZKP](https://youtu.be/bnbNtjsKb4k?t=1280) or [W3C-compatible verifiable presentation](https://docs.google.com/document/d/1ntLZGMah8iJ_TWQdbrNNW9OVwPbIWkkCMiid7Be1PrA/edit#heading=h.vw0mboesl528) just in time for each sharing of credential material. +The encoded values of the credential MUST follow the encoding algorithm as described in [Encoding Claims](#encoding-claims). + This is the format emitted by libindy's [indy_issuer_create_credential()](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L383) function. It is JSON-based and might look like this: ```jsonc @@ -212,6 +214,8 @@ Here is a sample proof request that embodies the following: "Using a government- This is the format of an Indy-style ZKP. It plays the same role as a W3C-style verifiable presentation (VP) and can be [mapped to one](https://docs.google.com/document/d/1ntLZGMah8iJ_TWQdbrNNW9OVwPbIWkkCMiid7Be1PrA/edit#heading=h.vw0mboesl528). +The raw values encoded in the presentation SHOULD be verified against the encoded values using the encoding algorithm as described below in [Encoding Claims](#encoding-claims). + The identifier for this format is `hlindy/proof@v2.0`. It is a version of the (JSON-based) data emitted by libindy's [indy_prover_create_proof()](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L1404)) function. A proof that responds to the [previous proof request sample](#proof-request-format) looks like this: ```jsonc @@ -323,6 +327,48 @@ The identifier for this format is `hlindy/proof@v2.0`. It is a version of the (J } ``` +### Unrevealed Attributes + +AnonCreds supports a holder responding to a proof request with some of the +requested claims included in an `unrevealed_attrs` array, as seen in the example +above, with `attr2_referent`. Assuming the rest of the proof is valid, AnonCreds +will indicate that a proof with unrevealed attributes has been successfully +verified. It is the responsibility of the verifier to determine if the purpose +of the verification has been met if some of the attributes are not revealed. + +There are at least a few valid use cases for this approach: + +- A verifier may ask for, but not require, that a prover provide all of the + requested attributes. +- A verifier may ask for claims from several credentials, expecting holders to + only have some of the credentials. The holders respond with claims from the + credentials they have, and leave the other attributes unrevealed. + - For example, a verifier may ask for a national identity card and an resident + card, knowing that most holders will have one or the other. + +### Encoding Claims + +Claims in AnonCreds-based verifiable credentials are put into the credential in two forms, `raw` and `encoded`. `raw` is the actual data value, and `encoded` is the (possibly derived) integer value that is used in presentations. At this time, AnonCreds does not take an opinion on the method used for encoding the raw value. + +AnonCreds issuers and verifiers must agree on the encoding method so that the verifier can check that the `raw` value returned in a presentation corresponds to the proven `encoded` value. The following is the encoding algorithm that MUST be used by Issuers when creating credentials and SHOULD be verified by Verifiers receiving presentations: + +- keep any 32-bit integer as is +- convert any string integer (e.g. `"1234"`) to be a 32-bit integer (e.g. `1234`) +- for data of any other type: + - convert to string (use string "None" for null) + - encode via utf-8 to bytes + - apply SHA-256 to digest the bytes + - convert the resulting digest bytes, big-endian, to integer + - stringify the integer as a decimal. + +An example implementation in Python can be found [here](https://github.com/hyperledger/aries-cloudagent-python/blob/0000f924a50b6ac5e6342bff90e64864672ee935/aries_cloudagent/messaging/util.py#L106). + +A gist of test value pairs can be found [here](https://gist.github.com/swcurran/78e5a9e8d11236f003f6a6263c6619a6). + +#### Notes on Encoding Claims + +- In converting any string integer to an integer, leading 0s in the string are (by definition) not part of the integer. The leading 0's remain in the (untouched) `raw` value. +- The use of AnonCreds predicates, such as proving "older than 21" based on a date of birth claim without sharing the date of birth, is based on an expression involving the `encoded` value. Thus, only `raw` integers or string integers can be used in AnonCreds predicates. ## Implementations diff --git a/features/0593-json-ld-cred-attach/README.md b/features/0593-json-ld-cred-attach/README.md index 918d8dc0f..4f3fda5d1 100644 --- a/features/0593-json-ld-cred-attach/README.md +++ b/features/0593-json-ld-cred-attach/README.md @@ -1,7 +1,7 @@ # Aries RFC 0593: JSON-LD Credential Attachment format for requesting and issuing credentials - Authors: Timo Glastra (Animo Solutions), George Aristy (SecureKey Technologies) -- Status: [ACCEPTED](/README.md#accepted) +- Status: [ADOPTED](/README.md#adopted) - Since: 2021-04-15 - Status Note: Included as part of the JSON-LD verifiable credentials subtarget of [AIP v2.0](../../concepts/0302-aries-interop-profile/README.md). - Supersedes: diff --git a/features/0627-static-peer-dids/README.md b/features/0627-static-peer-dids/README.md index 518750d90..aea840735 100644 --- a/features/0627-static-peer-dids/README.md +++ b/features/0627-static-peer-dids/README.md @@ -1,6 +1,6 @@ # Aries RFC 0627: Static Peer DIDs -- Authors: [Daniel Hardman](daniel.hardman@gmail.com) -- Status: [ACCEPTED](/README.md#accepted) +- Authors: [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [RETIRED](/README.md#retired) - Since: 2021-04-07 - Status Note: formally freezes a set of features that have been relatively stable for about 18 months - Start Date: 2021-03-24 diff --git a/features/0685-pickup-v2/README.md b/features/0685-pickup-v2/README.md new file mode 100644 index 000000000..4e7948c83 --- /dev/null +++ b/features/0685-pickup-v2/README.md @@ -0,0 +1,239 @@ +# 0685: Pickup Protocol 2.0 + +- Authors: [Sam Curren](mailto:telegramsam@gmail.com), [James Ebert](mailto:james.ebert@indicio.tech) +- Status: [ACCEPTED](/README.md#accepted) +- Since: 2024-05-01 +- Status Note: Initial version +- Start Date: 2020-12-22 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +## Summary + +A protocol to facilitate an agent picking up messages held at a mediator. + +## Motivation + +Messages can be picked up simply by sending a message to the _Mediator_ with a `return_route` decorator specified. This mechanism is implicit, and lacks some desired behavior made possible by more explicit messages. + +This protocol is the explicit companion to the implicit method of picking up messages. + +## Tutorial + +### Roles + +**Mediator** - The agent that has messages waiting for pickup by the _Recipient_. + +**Recipient** - The agent who is picking up messages. + +### Flow + +The `status-request` message is sent by the _Recipient_ to the _Mediator_ to query how many messages are pending. + +The `status` message is the response to `status-request` to communicate the state of the message queue. + +The `delivery-request` message is sent by the _Recipient_ to request delivery of pending messages. + +The `message-received` message is sent by the _Recipient_ to confirm receipt of delivered messages, +prompting the _Mediator_ to clear messages from the queue. + +The `live-delivery-change` message is used to set the state of `live_delivery`. + +- When Live Mode is enabled, messages that arrive when an existing connection exists are delivered over the connection immediately, +rather than being pushed to the queue. See [Live Mode](#live-mode) for more details. + +## Reference + +Each message sent MUST use the `~transport` decorator as follows, which has been adopted from [RFC 0092 transport return route](/features/0092-transport-return-route/README.md) protocol. This has been omitted from the examples for brevity. + +```json +"~transport": { + "return_route": "all" +} +``` + +## Message Types + +### Status Request + +Sent by the _Recipient_ to the _Mediator_ to request a `status` message. +#### Example: + +```json +{ + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/2.0/status-request", + "recipient_key": "" +} +``` + +`recipient_key` is optional. When specified, the _Mediator_ MUST only return status related to that recipient key. This allows the _Recipient_ to discover if any messages are in the queue that were sent to a specific key. You can find more details about `recipient_key` and how it's managed in [0211-route-coordination](https://github.com/hyperledger/aries-rfcs/blob/master/features/0211-route-coordination/README.md). + +### Status + +Status details about waiting messages. + +#### Example: + +```json +{ + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/2.0/status", + "recipient_key": "", + "message_count": 7, + "longest_waited_seconds": 3600, + "newest_received_time": "2019-05-01 12:00:00Z", + "oldest_received_time": "2019-05-01 12:00:01Z", + "total_bytes": 8096, + "live_delivery": false +} +``` + +`message_count` is the only REQUIRED attribute. The others MAY be present if offered by the _Mediator_. + +`longest_waited_seconds` is in seconds, and is the longest delay of any message in the queue. + +`total_bytes` represents the total size of all messages. + +If a `recipient_key` was specified in the `status-request` message, the matching value MUST be specified +in the `recipient_key` attribute of the status message. + +`live_delivery` state is also indicated in the status message. + +> Note: due to the potential for confusing what the actual state of the message queue +> is, a status message MUST NOT be put on the pending message queue and MUST only +> be sent when the _Recipient_ is actively connected (HTTP request awaiting +> response, WebSocket, etc.). + +### Delivery Request + +A request from the _Recipient_ to the _Mediator_ to have pending messages delivered. + +#### Examples: + +```json +{ + "@id": "123456781", + "@type": "https://didcomm.org/messagepickup/2.0/delivery-request", + "limit": 10, + "recipient_key": "" +} +``` + +```json +{ + "@type": "https://didcomm.org/messagepickup/2.0/delivery-request", + "limit": 1 +} +``` + + +`limit` is a REQUIRED attribute, and after receipt of this message, the _Mediator_ SHOULD deliver up to the `limit` indicated. + +`recipient_key` is optional. When [specified](), the _Mediator_ MUST only return messages sent to that recipient key. + +If no messages are available to be sent, a `status` message MUST be sent immediately. + +Delivered messages MUST NOT be deleted until delivery is acknowledged by a `messages-received` message. + +### Message Delivery + +Messages delivered from the queue must be delivered in a batch `delivery` message as attachments. The ID of each attachment is used to confirm receipt. The ID is an opaque value, and the _Recipient_ should not infer anything from the value. + +The ONLY valid type of attachment for this message is a DIDComm Message in encrypted form. + +The `recipient_key` attribute is only included when responding to a `delivery-request` message that indicates a `recipient_key`. + +```json +{ + "@id": "123456781", + "~thread": { + "thid": "" + }, + "@type": "https://didcomm.org/messagepickup/2.0/delivery", + "recipient_key": "", + "~attach": [{ + "@id": "", + "data": { + "base64": "" + } + }] +} +``` + +This method of delivery does incur an encoding cost, but is much simpler to implement and a more robust interaction. + +### Messages Received +After receiving messages, the _Recipient_ sends an ack message indiciating +which messages are safe to clear from the queue. + +#### Example: + +```json +{ + "@type": "https://didcomm.org/messagepickup/2.0/messages-received", + "message_id_list": ["123","456"] +} +``` + +`message_id_list` is a list of ids of each message received. The id of each message is present in the attachment descriptor of each attached message of a `delivery` message. + +Upon receipt of this message, the _Mediator_ knows which messages have been received, and can remove them from the collection of queued messages with confidence. The mediator SHOULD send an updated `status` message reflecting the changes to the queue. + +### Multiple Recipients + +If a message arrives at a _Mediator_ addressed to multiple _Recipients_, the message MUST be queued for each _Recipient_ independently. If one of the addressed _Recipients_ retrieves a message and indicates it has been received, that message MUST still be held and then removed by the other addressed _Recipients_. + +## Live Mode +Live mode is the practice of delivering newly arriving messages directly to a connected _Recipient_. It is disabled by default and only activated by the _Recipient_. Messages that arrive when Live Mode is off MUST be stored in the queue for retrieval as described above. If Live Mode is active, and the connection is broken, a new inbound connection starts with Live Mode disabled. + +Messages already in the queue are not affected by Live Mode - they must still be requested with `delivery-request` messages. + +Live mode MUST only be enabled when a persistent transport is used, such as WebSockets. + +_Recipients_ have three modes of possible operation for message delivery with various abilities and level of development complexity: + +1. Never activate live mode. Poll for new messages with a `status_request` message, and retrieve them when available. +2. Retrieve all messages from queue, and then activate Live Mode. This simplifies message processing logic in the _Recipient_. +3. Activate Live Mode immediately upon connecting to the _Mediator_. Retrieve messages from the queue as possible. When receiving a message delivered live, the queue may be queried for any waiting messages delivered to the same key for processing. + +### Live Mode Change +Live Mode is changed with a `live-delivery-change` message. + +#### Example: + +```json +{ + "@type": "https://didcomm.org/messagepickup/2.0/live-delivery-change", + "live_delivery": true +} +``` + +Upon receiving the `live_delivery_change` message, the _Mediator_ MUST respond with a `status` message. + +If sent with `live_delivery` set to `true` on a connection incapable of live delivery, a `problem_report` SHOULD be sent as follows: + +```json +{ + "@type": "https://didcomm.org/notification/1.0/problem-report", + "~thread": { + "pthid": "" + }, + "description": "Connection does not support Live Delivery" +} +``` + +## Prior art + +Version 1.0 of this protocol served as the main inspiration for this version. Version 1.0 suffered from not being very explicit, and an incomplete model of message delivery signaling. + +## Alternatives + +- An alternative to deriving a message ID is to wrap each message in a delivery wrapper. This would enable the mediator to include a mediator managed id and metadata along with the message itself, but carries the downside of double encrypting messages and extra processing. + +## 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 +--- | --- + | | diff --git a/features/0693-credential-representation/README.md b/features/0693-credential-representation/README.md new file mode 100644 index 000000000..ce0eaf3ff --- /dev/null +++ b/features/0693-credential-representation/README.md @@ -0,0 +1,59 @@ +# 0693: Cross-Platform Credential Representation + +- Authors: [Horacio Nunez](mailto:horacio.nunez@kiva.org) (Kiva Protocol) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2021-07-06 +- Status Note: +- Supersedes: +- Start Date: 2021-02-10 +- Tags: [feature](/tags.md#feature) + +## Summary +Aries Agent developers currently build end user products without a standard method of rendering credentials. +This RFC proposes how the Aries community can reuse available open technologies to build such a rendering method. + +Key results include: +- Feasibility of cross platform rendering. +- Enable branding of credentials. + +This RFC also enumerate the specific challenges that by using this method could be tackled next. + +## Motivation +The human computer interaction between agents and their users will always gravitate around credentials. +This interaction is more useful for users when their representation resembles that of their conventional +(physical) counterparts. + +Achieving effortless semiotic parity with analog credentials doesn't come easy or cheap. +In fact, when reviewing new Aries-base projects, is always the case that the rendering of +credentials with any form of branding is a demanding portion of the roadmap. + +Since the work required here is never declarative the work never stops feeling sysyphean. +Indeed, the cost of writing code of representing a credential remains constant over time, no +matter how many times we do it. + +Imagine if we achieve declarative while empowering branding. + +### Entering SVG + +The solution we propose is to adopt SVG as the default format to describe how to represent SSI credentials, and to +introduce a convention to ensure that credentials values could be embedded in the final user interface. +The following images illustrates how this can work: + +![SVG + Credential Values](https://i.imgur.com/3ssaQUB.png "SVG + Credential Values") + +### SVG + Credential Values + +We propose a notation of the form `{{credential.values.[AttributeName]}}` and `{{credential.names.[AttributeName]}}`. +This way both values and attributes names can be used in branding activities. + +#### Cross Platform + +Since SVG is a web standard based on XML there isn't a shortage of existing tools to power brand and engineering needs +right away. Indeed, any implementation will be powered by native SVG renderer and XML parser. + +## Future work + +* (RFC) A default credential representation to serves as community baseline +* (RFC) How to communicate the designated credential representation among agents. +* (RFC) Expand metadata available to include Revocation status. +* (Dev Tool) Standalone desktop tool to help design/brand a credential stored in an agent. diff --git a/features/0699-push-notifications-apns/README.md b/features/0699-push-notifications-apns/README.md new file mode 100644 index 000000000..ce9172380 --- /dev/null +++ b/features/0699-push-notifications-apns/README.md @@ -0,0 +1,153 @@ +# Aries RFC 0699: Push Notifications apns Protocol 1.0 + +- Authors: [Timo Glastra](mailto:timo@animo.id) (Animo Solutions) & [Berend Sliedrecht](mailto:berend@animo.id) (Animo Solutions) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2021-10-07 +- Status Note: Initial version +- Start Date: 2021-05-05 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +> Note: This protocol is currently written to support native push notifications for iOS via [Apple Push Notification Service](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns/). +> For the implementation for Android (using fcm), please refer to [0734: Push Notifications fcm](../0734-push-notifications-fcm/README.md) + +## Summary + +A protocol to coordinate a push notification configuration between two agents. + +## Motivation + +This protocol would give an agent enough information to send push notifications about specific events to an iOS device. This would be of great benefit for mobile wallets, as a holder can be notified when new messages are pending at the mediator. Mobile applications, such as wallets, are often killed and can not receive messages from the mediator anymore. Push notifications would resolve this problem. + +## Tutorial + +### Name and Version + +URI: `https://didcomm.org/push-notifications-apns/1.0` + +Protocol Identifier: `push-notifications-apns` + +Version: `1.0` + +Since apns only supports iOS, no `-ios` or `-android` is required as it is implicit. + +### Key Concepts + +When an agent would like to receive push notifications at record event changes, e.g. incoming credential offer, incoming connection request, etc., the agent could initiate the protocol by sending a message to the other agent. + +This protocol only defines how an agent would get the token which is necessary for push notifications. + +Each platform is has its own protocol so that we can easily use [0031: Discover Features 1.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0031-discover-features/README.md) and [0557: Discover Features 2.X](https://github.com/hyperledger/aries-rfcs/blob/main/features/0557-discover-features-v2/README.md) to see which specific services are supported by the other agent. + +### Roles + +**notification-sender** + +**notification-receiver** + +The **notification-sender** is an agent who will send the **notification-receiver** notifications. The **notification-receiver** can get and set their push notification configuration at the **notification-sender**. + +### Services + +This RFC focusses on configuring the data necessary for pushing notifications to iOS, via [apns](https://developer.apple.com/notifications/). + +In order to implement this protocol, the [set-device-info](#set-device-info) and [get-device-info](#get-device-info) messages MUST be implemented by the **notification-sender** and [device-info](#device-info) message MUST be implemented by the **notification-receiver**. + +#### Supported Services + +The protocol currently supports the following push notification services + +- [apns](https://developer.apple.com/notifications/) for iOS devices + +### Messages + +When a notification-receiver wants to receive push notifications from the notification-sender, the notification-receiver has to send the following message: + +#### Set Device Info + +Message to set the device info using the native iOS device token for push notifications. + +```json +{ + "@type": "https://didcomm.org/push-notifications-apns/1.0/set-device-info", + "@id": "", + "device_token": "" +} +``` + +Description of the fields: + +- `device_token` -- The token that is required by the notification provider (string, null) + +It is important to note that the set device info message can be used to set, update and remove the device info. To set, and update, these values the normal messages as stated above can be used. To remove yourself from receiving push notifications, you can send the same message where all values MUST be `null`. If either value is `null` a `problem-report` MAY be sent back with `missing-value`. + +#### Get Device Info + +When a notification-receiver wants to get their push-notification configuration, they can send the following message: + +```json +{ + "@type": "https://didcomm.org/push-notifications-apns/1.0/get-device-info", + "@id": "" +} +``` + +#### Device Info + +Response to the get device info: + +```json +{ + "@type": "https://didcomm.org/push-notifications-apns/1.0/device-info", + "device_token": "", + "~thread": { + "thid": "" + } +} +``` + +This message can be used by the notification-receiver to receive their device info, e.g. `device_token`. If the notification-sender does not have this field for that connection, a `problem-report` MAY be used as a response with `not-registered-for-push-notifications`. + +#### Adopted messages + +In addition, the [`ack`](https://github.com/hyperledger/aries-rfcs/blob/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0015-acks/README.md) message is adopted into the protocol for confirmation by the notification-sender. The ack message SHOULD be sent in response to any of the set-device-info messages. + +### Sending Push Notifications + +When an agent wants to send a push notification to another agent, the payload of the push notifications MUST include the `@type` property, and COULD include the `message_tag` property, to indicate the message is sent by the notification-sender. Guidelines on notification messages are not defined. + +```json +{ + "@type": "https://didcomm.org/push-notifications-apns", + "message_tag": "", + "message_id": "", + ... +} +``` + +Description of the fields: + +- `@type` -- Indicator of what kind of notification it is. (This could help the notification-receiver with parsing if a notification comes from another agent, for example) +- `message_tag` -- Optional field to connect the push notification to a DIDcomm message. As defined in [0334: jwe-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0334-jwe-envelope) or [0019: encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0019-encryption-envelope). +- `message_id` -- Optional field to pickup the message from the mediator that the notification was linked to. As defined in [0685: Pickup Protocol 2.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0685-pickup-v2/README.md). + +## Drawbacks + +Each service requires a considerable amount of domain knowledge. The RFC can be extended with new services over time. + +The `@type` property in the push notification payload currently doesn't indicate which agent the push notification came from. In e.g. the instance of using multiple mediators, this means the notification-receiver does not know which mediator to retrieve the message from. + +## Prior art + +- This RFC is based on the implementation of the [`AddDeviceInfoMessage`](https://github.com/hyperledger/aries-framework-dotnet/blob/9bc6346a21da263083bbac8dd8227cc941c95ea9/src/Hyperledger.Aries.Routing/AddDeviceInfoMessage.cs) in Aries Framework .NET + +## Unresolved questions + +None + +## 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 | +| ----------- | -------------------- | +| | | diff --git a/features/0721-revocation-notification-v2/README.md b/features/0721-revocation-notification-v2/README.md new file mode 100644 index 000000000..3b3af4e2d --- /dev/null +++ b/features/0721-revocation-notification-v2/README.md @@ -0,0 +1,128 @@ +# Aries RFC 0721: Revocation Notification 2.0 +- Authors: Keith Smith, Daniel Bluhm, James Ebert +- Status: [ACCEPTED](/README.md#accepted) +- Since: 2024-05-01 +- Status Note: Updates the credential identifiers format after discussions while implementing [RFC 0183 Revocation Notification](../0183-revocation-notification/README.md) +- Supersedes: [RFC 0183 Revocation Notification](../0183-revocation-notification/README.md) +- Start Date: 2021-11-01 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +## Summary + +This RFC defines the message format which an issuer uses to notify a holder that a previously issued credential has been revoked. + +## Change Log + +- 20240320: Clarification removing references to retired `~please_ack` decorator and RFC. + +## Motivation + +We need a standard protocol for an issuer to notify a holder that a previously issued credential has been revoked or unrevoked. + +For example, suppose a passport agency revokes Alice's passport. +The passport agency (an issuer) may want to notify Alice (a holder) that her passport has been revoked so that she +knows that she will be unable to use her passport to travel. + +## Tutorial + +The Revocation Notification protocol is a very simple protocol consisting of two messages: + +* Revoke - issuer to holder +* Unrevoke - issuer to holder + +This simple protocol allows an issuer to choose to notify a holder that a previously issued credential has been revoked or unrevoked. + +It is the issuer's prerogative whether or not to notify the holder that a credential has been (un)revoked. It is not a security risk if the issuer does not notify the holder that the credential has been (un)revoked, nor if the message is lost. The holder will still be unable to use a revoked credential without this notification. + +### Roles + +There are two parties involved in a Revocation Notification: `issuer` and `holder`. +The `issuer` sends the `revoke` or `unrevoke` message to the `holder`. + +### Messages + +#### Revoke + +The `revoke` message sent by the `issuer` to the `holder`. The holder should verify that the `revoke` message came from the connection that was originally used to issue the credential. + +Message format: + +```JSON +{ + "@type": "https://didcomm.org/revocation_notification/2.1/revoke", + "@id": "", + "revocation_format": "", + "credential_id": "", + "comment": "Some comment" +} +``` + +Description of fields: + +* `revocation_format` (required) -- the format of the credential revocation. Accepted values for the revocation format are provided in the "Revocation Credential Identification Formats" section immediately below. + +* `credential_id` (required) -- the individual credential identifier of a credential issued using the [issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2) protocol that has been revoked by the issuer. Accepted values for the credential id format are provided in the "Revocation Credential Identification Formats" section immediately below. + +* `comment` (optional) -- a field that provides some human readable information about the revocation notification. This is typically the reason for the revocation as deemed appropriate by the issuer. + +#### Unrevoke + +The `unrevoke` message sent by the `issuer` to the `holder`. The holder should verify that the `unrevoke` message came from the connection that was originally used to issue the credential. + +Message format: + +```JSON +{ + "@type": "https://didcomm.org/revocation_notification/2.1/unrevoke", + "@id": "", + "revocation_format": "", + "credential_id": "", + "comment": "Some comment" +} +``` + +Description of fields: + +* `revocation_format` (required) -- the format of the credential revocation. Accepted values for the revocation format are provided in the "Revocation Credential Identification Formats" section immediately below. + +* `credential_id` (required) -- the individual credential identifier of a credential issued using the [issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2) protocol that has been revoked by the issuer. Accepted values for the credential id format are provided in the "Revocation Credential Identification Formats" section immediately below. + +* `comment` (optional) -- a field that provides some human readable information about the revocation notification. This is typically the reason for the revocation as deemed appropriate by the issuer. + +#### Revocation Credential Identification Formats + +In order to support multiple credential revocation formats, the following dictates the format of revocation formats and their credential ids. As additional credential revocation formats are determined their credential id formats should be added. + +Revocation Format | Credential Identifier Format | Example | +--- | --- | --- | +`indy-anoncreds` | `::` | `AsB27X6KRrJFsqZ3unNAH6:4:AsB27X6KRrJFsqZ3unNAH6:3:cl:48187:default:CL_ACCUM:3b24a9b0-a979-41e0-9964-2292f2b1b7e9::1` | +`anoncreds` | `::` | `did:indy:sovrin:5nDyJVP1NrcPAttP3xwMB9/anoncreds/v0/REV_REG_DEF/56495/npdb/TAG1::1` | + +## Reference + +* See the [issue-credential-v2](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2) protocol. +* See the [Please ACK Decorator RFC](https://github.com/hyperledger/aries-rfcs/tree/main/features/0317-please-ack). + +## Drawbacks + +If we later added support for more general event subscription and notification message flows, this would be redundant. + +## Rationale and alternatives + +- Why is this design the best in the space of possible designs? It is simple. +- What other designs have been considered and what is the rationale for not +choosing them? A more general event subscription and notification mechanism was considered but chose to keep this simple for the same reasons that the basic message was kept simple. +- What is the impact of not doing this? There is no standard way of sending a revocation notification which is a common scenario. + +## Prior art + +## Unresolved questions + +## 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 +--- | --- + | | + diff --git a/features/0728-device-binding-attachments/README.md b/features/0728-device-binding-attachments/README.md new file mode 100644 index 000000000..e127cba1e --- /dev/null +++ b/features/0728-device-binding-attachments/README.md @@ -0,0 +1,270 @@ +# Aries RFC 0728 : Device Binding Attachments + +- Authors: [Paul Bastian](mailto:paul.bastian@bdr.de), [Sebastian Bickerle](mailto:sebastian.bickerle@main-incubator.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2022-04-07 +- Status Note: This is an initial draft +- Start Date: 2022-01-01 +- Tags: [feature](/tags.md#feature) + +## Summary + +Extends existing present-proof protocols to allow proofing the control of a hardware bound key embedded within a verfiable credential. + +## Motivation + +To enable use-cases which require a high level of assurance a verifier must reach a high degree of confidence that a verifiable credential (VC) can only be used by the person it was issued for. One way to enforce this requirement is that the issuer additionally binds the VC to a hardware bound public key and therefore binding the credential to the device, as discussed in the [DIF Wallet Security WG](https://github.com/decentralized-identity/wallet-security). The issaunce process, including the attestation of the wallet and the hardware bound key is off-scope for this Aries RFC. A valid presentation of the VC then requires an additional challenge which proofs that the presenter is in control of the corresponding private key. Since the proof of control must be part of legitimate presentation it makes sense to extend all current `present-proof` protocols. + +Note: The focus so far has been on AnonCreds, we will also look into device binding of W3C VC, however this is currently lacking in the examples. + +Warning: **This concept is primarily meant for regulated, high-security usecases**. Please review the drawbacks before considering using this. + +## Tutorial + +To proof the control of a hardware bound key the holder must answer a challenge for one or more public keys embedded within verifiable credentials. + +### Challenge + +The following challenge object must be provided by the verifier. + +#### device-binding-challenge + +```json +{ + "@type": "https://didcomm.org/device-binding/%ver/device-binding-challenge", + "@id": "", + "nonce": "", // recommend at least 128-bit unsigned integer + "requests": [ + { + "id": "libindy-request-presentation-0", + "path": "$.requested_attributes.attr2_referent.names.hardwareDid" + } + ] +} +``` + +Description of attributes: + +- `nonce` -- a nonce which has to be signed by the holder to proof control +- `requests` -- an array of referenced presentation requests + - `id` -- reference to an attached presentation request of `request-presentation` message (e.g. libindy request) + - `path` -- JsonPath to a requested attribute which represents a public key of a hardware bound key pair - represented as did:key + +The `device-binding-challenge` must be attached to the `request-presentations~attach` array of the `request-presentation` message defined by [RFC-0037](https://github.com/hyperledger/aries-rfcs/blob/main/features/0037-present-proof/README.md#request-presentation) and [RFC-0454](https://github.com/hyperledger/aries-rfcs/tree/main/features/0454-present-proof-v2#request-presentation). + +#### Example request-presentation messages + +The following represents a request-presentation message with an attached libindy presentation request and a corresponding device-binding-challenge. + +**Present Proof v1** + +```json +{ + "@type": "https://didcomm.org/present-proof/1.0/request-presentation", + "@id": "", + "comment": "some comment", + "request_presentations~attach": [ + { + "@id": "libindy-request-presentation-0", + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ], + "device_binding~attach": [ + { + "@id": "device-binding-challenge-0" + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ] +} +``` + +**Present Proof v2** + +```json +{ + "@type": "https://didcomm.org/present-proof/2.0/request-presentation", + "@id": "", + "goal_code": "", + "comment": "some comment", + "will_confirm": true, + "present_multiple": false, + "formats" : [ + { + "attach_id" : "libindy-request-presentation-0", + "format" : "hlindy/proof-req@v2.0", + } + ], + "request_presentations~attach": [ + { + "@id": "libindy-request-presentation-0", + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ], + "device_binding~attach": [ + { + "@id": "device-binding-challenge-0" + "mime-type": "application/json", + "data": { + "base64": "" // inner object + } + } + ] +} +``` + +### Response + +The following response must be generated by the holder of the VC. + +#### device-binding-reponse + +```json +{ + "@type": "https://didcomm.org/device-binding/%ver/device-binding-response", + "@id": "", + "proofs": [ + { + "id": "libindy-presentation-0", + "path": "$.requested_proof.revealed_attrs.attr1_referent.raw" + } + ] +} +``` + +Description of attributes: + +- `proofs` -- an array of proofs for different hardware keys which must match the `requests` array from the [device-binding-challenge](#device-binding-challenge) + - `id` -- reference to presentation of VC with an embeded hardware bound key + - `path` -- JsonPath to raw value of hardware bound public key within the attached presentation of the VC represented as did:key + +The `device-binding-response` must be attached to the `device_binding~attach` array of a `presentation` message defined by [RFC-0037](https://github.com/hyperledger/aries-rfcs/blob/main/features/0037-present-proof/README.md#presentation) or [RFC-0454](https://github.com/hyperledger/aries-rfcs/tree/main/features/0454-present-proof-v2#presentation). + +- `jws` -- Nonce from [device-binding-challenge](#device-binding-challenge) signed with the corresponding private key as a Json Web Signature object, acording to Aries [RFC-0017](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0017-attachments#signing-attachments). + +### Example presentation messages + +The following represents a presentation message with an attached libindy presentation and a corresponding device-binding-response. + +**Present Proof v1** + +```json +{ + "@type": "https://didcomm.org/present-proof/1.0/presentation", + "@id": "", + "comment": "some comment", + "presentations~attach": [ + { + "@id": "libindy-presentation-0", + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ], + "device_binding~attach": [ + { + "@id": "device-binding-response-0", + "mime-type": "application/json", + "data": { + "base64": "", + "jws": { + "header": { + "kid": "did:key:z6MkmjY8GnV5i9YTDtPETC2uUAW6ejw3nk5mXF5yci5ab7th" + }, + "protected": "eyJhbGciOiJFZERTQSIsImlhdCI6MTU4Mzg4... (bytes omitted)", + "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)" + } + } + } + ] +} +``` + +**Present Proof v2** + +```json +{ + "@type": "https://didcomm.org/present-proof/%VER/presentation", + "@id": "", + "goal_code": "", + "comment": "some comment", + "last_presentation": true, + "formats" : [ + { + "attach_id" : "libindy-presentation-0", + "format" : "hlindy/proof-req@v2.0", + } + ], + "presentations~attach": [ + { + "@id": "libindy-presentation-0", + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ], + "device_binding~attach": [ + { + "@id": "device-binding-response-0" + "mime-type": "application/json", + "data": { + "base64": "", + "jws": { + "header": { + "kid": "did:key:z6MkmjY8GnV5i9YTDtPETC2uUAW6ejw3nk5mXF5yci5ab7th" + }, + "protected": "eyJhbGciOiJFZERTQSIsImlhdCI6MTU4Mzg4... (bytes omitted)", + "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)" + } + } + } + ] +} +``` + +## Reference + +- [DIF Wallet Security Github Page](https://github.com/decentralized-identity/wallet-security) + +## Drawbacks + +Including a hardware-bound public key (as an attribute) into a Verifiable Credential/AnonCred is necessary for this concept but introduces a globally unique and therefore trackable identifier. As this public key is revealed to the verifier, there is a higher risk of correlation. The Issuer must always use a hardware-bound key for a single credential and the Wallet should enforce to never reuse the key. Additionally, the holder should ideally be informed about the increased correlation risk by the wallet UX. + +## Rationale and alternatives + +The rationale behind this proposal is to formalize the way a holder wallet can proof the control of a (hardware-bound) key. + +This proposal tries to extend existing protocols to reduce the implementation effort for existing solutions. It might be reasonable to include this only in a new version of the present proof protocol (e.g. present-proof v3). + +## Prior art + +None to our knowledge. + +## Unresolved questions + +- What is the best way to reference hardware bound keys within VCs and presentations? + - Do we need a standardised attribute name for the hardware backed public key (e.g. "HardwareDid") + - Can we just reference the hardware key within the request object? + - Is it required to explicitly define the accepted signing algorithm within the `device-binding-challenge` object? +- What kind of key encoding do we choose? + - did:key, base64-encoded JWK and did:jwk in discussion + +## 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](/README.md#accepted). + +| Name / Link | Implementation Notes | +| ----------- | -------------------- | +| | diff --git a/features/0734-push-notifications-fcm/README.md b/features/0734-push-notifications-fcm/README.md new file mode 100644 index 000000000..4d4380e89 --- /dev/null +++ b/features/0734-push-notifications-fcm/README.md @@ -0,0 +1,154 @@ +# Aries RFC 0734: Push Notifications fcm Protocol 1.0 + +- Authors: [Timo Glastra](mailto:timo@animo.id) (Animo Solutions) & [Berend Sliedrecht](mailto:berend@animo.id) (Animo Solutions) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2022-05-12 +- Status Note: Initial version +- Start Date: 2022-05-12 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +> Note: This protocol is currently written to support native push notifications using fcm. +> For the implementation for iOS (via apns), please refer to [0699: Push Notifications apns](../0699-push-notifications-apns/README.md) + +## Summary + +A protocol to coordinate a push notification configuration between two agents. + +## Motivation + +This protocol would give an agent enough information to send push notifications about specific events to a device that supports fcm. This would be of great benefit for mobile wallets, as a holder can be notified when new messages are pending at the mediator. Mobile applications, such as wallets, are often killed and can not receive messages from the mediator anymore. Push notifications would resolve this problem. + +## Tutorial + +### Name and Version + +URI: `https://didcomm.org/push-notifications-fcm/1.0` + +Protocol Identifier: `push-notifications-fcm` + +Version: `1.0` + +### Key Concepts + +When an agent would like to receive push notifications at record event changes, e.g. incoming credential offer, incoming connection request, etc., the agent could initiate the protocol by sending a message to the other agent. + +This protocol only defines how an agent would get the token and platform that is necessary for push notifications. + +Each platform has its own protocol so that we can easily use [0031: Discover Features 1.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0031-discover-features/README.md) and [0557: Discover Features 2.X](https://github.com/hyperledger/aries-rfcs/blob/main/features/0557-discover-features-v2/README.md) to see which specific services are supported by the other agent. + +### Roles + +**notification-sender** + +**notification-receiver** + +The **notification-sender** is an agent who will send the **notification-receiver** notifications. The **notification-receiver** can get and set their push notification configuration at the **notification-sender**. + +### Services + +This RFC focuses on configuring the data necessary for pushing notifications via [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging). + +In order to implement this protocol, the [set-device-info](#set-device-info) and [get-device-info](#get-device-info) messages MUST be implemented by the **notification-sender** and [device-info](#device-info) message MUST be implemented by the **notification-receiver**. + +#### Supported Services + +The protocol currently supports the following push notification services + +- [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) + +### Messages + +When a notification-receiver wants to receive push notifications from the notification-sender, the notification-receiver has to send the following message: + +#### Set Device Info + +Message to set the device info using the fcm device token and device platform for push notifications. + +```json +{ + "@type": "https://didcomm.org/push-notifications-fcm/1.0/set-device-info", + "@id": "", + "device_token": "", + "device_platform": "" +} +``` + +Description of the fields: + +- `device_token` -- The token that is required by the notification provider (string, null) +- `device_platform` -- The platform used by the sender, e.g. Android / iOS / Linux / etc. (string, null) + +It is important to note that the set device info message can be used to set, update and remove the device info. To set, and update, these values the normal messages as stated above can be used. To remove yourself from receiving push notifications, you can send the same message where all values MUST be `null`. If either value is `null`, a `problem-report` MAY be sent back with `missing-value`. + +#### Get Device Info + +When a notification-receiver wants to get their push-notification configuration, they can send the following message: + +```json +{ + "@type": "https://didcomm.org/push-notifications-fcm/1.0/get-device-info", + "@id": "" +} +``` + +#### Device Info + +Response to the get device info: + +```json +{ + "@type": "https://didcomm.org/push-notifications-fcm/1.0/device-info", + "device_token": "", + "device_platform": "", + "~thread": { + "thid": "" + } +} +``` + +This message can be used by the notification-receiver to receive their device info, e.g. `device_token` and `device_platform`. If the notification-sender does not have this field for that connection, a `problem-report` MAY be used as a response with `not-registered-for-push-notifications`. + +#### Adopted messages + +In addition, the [`ack`](https://github.com/hyperledger/aries-rfcs/blob/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0015-acks/README.md) message is adopted into the protocol for confirmation by the notification-sender. The ack message SHOULD be sent in response to any of the set-device-info messages. + +### Sending Push Notifications + +When an agent wants to send a push notification to another agent, the payload of the push notifications MUST include the `@type` property, and COULD include the `message_tags` property, to indicate the message is sent by the notification-sender. Guidelines on notification messages are not defined. + +```json +{ + "@type": "https://didcomm.org/push-notifications-fcm", + "message_tags": [""], + "message_ids": [""], + ... +} +``` + +Description of the fields: + +- `@type` -- Indicator of what kind of notification it is. (This could help the notification-receiver with parsing if a notification comes from another agent, for example) +- `message_tag` -- Optional list field to connect the push notification to a DIDcomm message, this can be used for batching multiple messages to a single notification. As defined in [0334: jwe-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0334-jwe-envelope) or [0019: encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0019-encryption-envelope). +- `message_ids` -- Optional list field to pickup the message from the mediator that the notification was linked to, this can be used for batching multiple messages to a single notification. As defined in [0685: Pickup Protocol 2.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0685-pickup-v2/README.md). + +## Drawbacks + +Each service requires a considerable amount of domain knowledge. The RFC can be extended with new services over time. + +The `@type` property in the push notification payload currently doesn't indicate which agent the push notification came from. In e.g. the instance of using multiple mediators, this means the notification-receiver does not know which mediator to retrieve the message from. + +## Prior art + +- This RFC is based on the implementation of the [`AddDeviceInfoMessage`](https://github.com/hyperledger/aries-framework-dotnet/blob/9bc6346a21da263083bbac8dd8227cc941c95ea9/src/Hyperledger.Aries.Routing/AddDeviceInfoMessage.cs) in Aries Framework .NET + +## Unresolved questions + +None + +## 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 | +| ----------- | -------------------- | +| | | diff --git a/features/0745-push-notifications-expo/README.md b/features/0745-push-notifications-expo/README.md new file mode 100644 index 000000000..f3f3140ba --- /dev/null +++ b/features/0745-push-notifications-expo/README.md @@ -0,0 +1,142 @@ +# Aries RFC 0745: Push Notifications Expo Protocol 1.0 + +- Authors: [Timo Glastra](mailto:timo@animo.id) (Animo Solutions) & [Berend Sliedrecht](mailto:berend@animo.id) (Animo Solutions) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2022-07-26 +- Status Note: Initial version +- Start Date: 2022-07-15 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +> Note: This protocol is currently written to support sending push notifications through [Expo's push notification service](https://docs.expo.dev/push-notifications/overview/). For sending push notification directly using APNS or FCM see the respective RFCs; [0734: Push Notifications fcm](../0734-push-notifications-fcm/README.md) and [0699: Push Notifications apns](../0699-push-notifications-apns/README.md). + +## Summary + +[Expo](https://expo.dev) provides tools and services on top of [React Native](https://reactnative.dev/). This RFC defines a protocol to coordinate expo push notification configuration between two agents, allowing the **notification-sender** to send push notifications through Expo's push notification service to the **notification-receiver**. + +## Motivation + +When mobile edge agents are offline and messages are received at the mediator, it is desired that the mediator can inform the mobile agent of pending messages. A protocol to set the push notification device info at another agent allows the mediator to send updates to the mobile agent. + +## Tutorial + +### Name and Version + +URI: `https://didcomm.org/push-notifications-expo/1.0` + +Protocol Identifier: `push-notifications-expo` + +Version: `1.0` + +### Key Concepts + +When an agent would like to receive push notifications of pending messages, e.g. when a forward message is received at the mediator, the **notification-receiver** can register for push notifications at the **notification-sender** using the `set-device-info` message. + +This protocol only defines how an agent would get the token which is necessary for push notifications. + +Each platform is has its own protocol so that we can easily use [0031: Discover Features 1.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0031-discover-features/README.md) and [0557: Discover Features 2.X](https://github.com/hyperledger/aries-rfcs/blob/main/features/0557-discover-features-v2/README.md) to see which specific services are supported by the other agent. + +### Roles + +**notification-sender** + +**notification-receiver** + +The **notification-sender** is an agent who will send the **notification-receiver** notifications. The **notification-receiver** can get and set their push notification configuration at the **notification-sender**. + +### Services + +This RFC focusses on configuring the data necessary for pushing notifications to iOS and Android, via [Expo's Push API](https://docs.expo.dev/push-notifications/sending-notifications/) + +### Messages + +When a notification-receiver wants to receive push notifications from the notification-sender, the notification-receiver has to send the following message: + +#### Set Device Info + +Message to set the device info using the [Expo Push Token](https://docs.expo.dev/versions/latest/sdk/notifications/#getexpopushtokenasyncoptions-expotokenoptions-expopushtoken) for push notifications. + +```json +{ + "@type": "https://didcomm.org/push-notifications-expo/1.0/set-device-info", + "@id": "", + "device_token": "" +} +``` + +Description of the fields: + +- `device_token` -- The token that is required by the notification provider. Usually has the format of `ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]` (string, null) + +It is important to note that the set device info message can be used to set, update and remove the device info. To set, and update, these values the normal messages as stated above can be used. To remove yourself from receiving push notifications, you can send the same message where the `device_token` value is `null`. + +#### Get Device Info + +When a notification-receiver wants to get their push-notification configuration, they can send the following message: + +```json +{ + "@type": "https://didcomm.org/push-notifications-expo/1.0/get-device-info", + "@id": "" +} +``` + +#### Device Info + +Response to the get device info: + +```json +{ + "@type": "https://didcomm.org/push-notifications-expo/1.0/device-info", + "device_token": "", + "~thread": { + "thid": "" + } +} +``` + +This message can be used by the notification-receiver to receive their device info, e.g. `device_token`. If the notification-sender does not have this field for that connection, a `problem-report` MAY be used as a response with `not-registered-for-push-notifications`. + +#### Adopted messages + +In addition, the [`ack`](https://github.com/hyperledger/aries-rfcs/blob/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0015-acks/README.md) message is adopted into the protocol for confirmation by the notification-sender. The ack message MUST be sent in response to any of the set-device-info messages. + +### Sending Push Notifications + +When an agent wants to send a push notification to another agent, the payload of the push notifications MUST include the `@type` property, and COULD include the `message_tag` property, to indicate the message is sent by the notification-sender. Guidelines on notification messages are not defined. + +```json +{ + "@type": "https://didcomm.org/push-notifications-expo", + "message_tag": "", + "message_id": "", + ... +} +``` + +Description of the fields: + +- `@type` -- Indicator of what kind of notification it is. (This could help the notification-receiver with parsing if a notification comes from another agent, for example) +- `message_tag` -- Optional field to connect the push notification to a DIDcomm message. As defined in [0334: jwe-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0334-jwe-envelope) or [0019: encryption-envelope](https://github.com/hyperledger/aries-rfcs/tree/main/features/0019-encryption-envelope). +- `message_id` -- Optional field to pickup the message from the mediator that the notification was linked to. As defined in [0685: Pickup Protocol 2.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0685-pickup-v2/README.md). + +## Drawbacks + +Each service requires a considerable amount of domain knowledge. The RFC can be extended with new services over time. + +The `@type` property in the push notification payload currently doesn't indicate which agent the push notification came from. In e.g. the instance of using multiple mediators, this means the notification-receiver does not know which mediator to retrieve the message from. + +## Prior art + +- This RFC is based on the implementation of the [`AddDeviceInfoMessage`](https://github.com/hyperledger/aries-framework-dotnet/blob/9bc6346a21da263083bbac8dd8227cc941c95ea9/src/Hyperledger.Aries.Routing/AddDeviceInfoMessage.cs) in Aries Framework .NET + +## Unresolved questions + +None + +## 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 | +| ----------- | -------------------- | +| | | diff --git a/features/0748-n-wise-did-exchange/README.md b/features/0748-n-wise-did-exchange/README.md new file mode 100644 index 000000000..f5ecafb9f --- /dev/null +++ b/features/0748-n-wise-did-exchange/README.md @@ -0,0 +1,380 @@ +# Aries RFC 0748: N-wise DID Exchange Protocol 1.0 + +- Authors: [Mikhail Lytaev](mailto:mikelytaev@gmail.com), [Pavel Minenkov](mailto:minikspb@gmail.com) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2022-08-03 +- Status Note: Under research +- Supersedes: +- Start Date: 2022-06-03 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) +- URI: https://didcomm.org/n-wise/1.0 + +## Summary + +This RFC defines a protocol for creating and managing relationships within a group of SSI subjects. In a certain sense, this RFC is a generalization of the pairwise concept and protocols [0160-connection-protocol](https://github.com/hyperledger/aries-rfcs/tree/main/features/0160-connection-protocol) and [0023-did-exchange](https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange) for an arbitrary number of parties (n-wise). + +## Motivation + +SSI subjects and [agents](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0004-agents) representing them must have a way to establish relationships with each other in a trustful manner. In the simplest case, when only two participants are involved, this goal is achieved using [0023-did-exchange](https://github.com/hyperledger/aries-rfcs/blob/main/features/0023-did-exchange/README.md) protocol by creating and securely sharing their DID Documents directly between agents. However, it is often desirable to organize an interaction involving more than two paries. The number of parties of such an interaction may change over time, and most of the agents may be mobile ones. The simplest and most frequently used example of such interaction is a group chat in instant messenger. The trusted nature of SSI technology makes it possible to use group relationships for holding legally significant unions, such as board of directors, territorial community or dissertation councils. + +## Tutorial + +### Name and Version + +n-wise, version 1.0 + +URI: https://didcomm.org/n-wise/1.0 + +### Registry of n-wise states + +The current state of n-wise is an up-to-date list of the parties' DID Documents. In pairwise relation the state is stored by the participants and updated by a direct notification of the other party. When there are more than two participants, the problem of synchronizing the state of this n-wise (i.e. [consensus](https://en.wikipedia.org/wiki/Consensus_(computer_science))) arising. It should be borne in mind that the state may change occasionally: users may be added or deleted, DID Documents may be modified (when keys are rotated or endpoints are changed). + +In principle, any trusted repository can act as a registry of n-wise states. The following options for storing the n-wise state can be distinguished: + +- #### Directly on the agent's side (Edge chain) + + - This approach is the closest to [0023-did-exchange](https://github.com/hyperledger/aries-rfcs/blob/main/features/0023-did-exchange/README.md) protocol. However since there are more than two participants, an additional consensus procedure is required to correctly account for changes in the n-wise state. This option is suitable if the participants are represented by cloud agents which are (almost) always online. In this case, a consensus can be established between them using the well-known algorithms (RAFT, Paxos, BFT). However, if most of the agents are mobile and are online only occasionally, the mentioned consensus algorithms are not applicable. So it is preferable to use external solutions for storing and updating the n-wise states. + +- #### Public or private distributed ledger + + - In this case, the task of recording and storing the state is taken over by a third-party distributed network. The network can verify incoming transactions by executing a smart contract, or accept all incoming transactions, so transaction validation takes place only on the participating agents. + +- #### Centralized storage + + - This case is applicable when security requirements allow participants to trust a centralized solution. + +The concept of pluggable consensus implies choosing the most appropriate way to maintain a registry of states, depending on the needs. + +N-wise state update is performed by committing the corresponding transaction to the registry of n-wise states. To get the current n-wise state, the agent receives a list of transactions from the registry of states, verifies them and applies sequentially, starting with the `genesisTx`. Incorrect transactions (without a proper signature or missing the required fields) are ignored. Thus, n-wise can be considered as a replicated state machine, which is executed on each participant. + +The specifics of recording and receiving transactions depend on the particular method of maintaining the n-wise registry and on a particular ledger. This RFC DOES NOT DEFINE specific n-wise registry implementations. + +### Roles + +- ##### User + + - The party of n-wise. Has the right to: + + - Modify its DID Document; + - Remove himself from n-wise; + - Invite new parties. + +- ##### Owner + - In addition to user's rights, has the right to: + - Remove other users from n-wise; + - Modify n-wise meta information; + - Transfer its role to another user. + + - There can be only one owner in n-wise at a time. + +- ##### Creator + + - Creator of the n-wise and the author of `genesisTx`. + - The creator automatically becomes the owner of n-wise after creation. + +- ##### Inviter + + - The n-wise participant who initiates the invitation of a new one. + +- ##### Invitee + + - The participant accepting the invitation and connecting to n-wise. If successful, the participant becomes a user of n-wise. + +### Actions + +#### N-wise creation + +The creation begins with the initialization of the n-wise registry. This RFC DOES NOT SPECIFY the procedure for n-wise registry creation. After creating the registry, the creator commits the `genesisTx` transaction. The creator automatically obtains the role of owner. The creator MUST generate a unique DID and DID Document for n-wise. + +#### Invitation of a new party + +Any n-wise party can create an invitation to join n-wise. First, inviter generates a pair of public and private invitation keys according to Ed25519. The public key of the invitation is pushed to the registry using the `invitationTx` transaction. Then the `Invitation` message with the invitation private key is sent out-of-band to the invitee. The invitation key pair is unique for each invitee and can be used only once. + +#### Accepting the invitation + +Once `Invitation` received, the invite generates a unique DID and DID Document for the n-wise and commits `AddParticipantTx` transaction to the registry. +It is NOT ALLOWED to reuse DID from other relationships. + +The process of adding a new participant is shown in the figure below + +![](add_participant.png) + +#### Updating DID Document + +Updating the user's DID Document is required for the key rotation or endpoint updating. To update the associated DID Document, user commits the `updateParticipantTx` transaction to the registry. + +#### Removing a party form n-wise + +Removing is performed using the `removeParticipantTx` transaction. +The user can delete itself (the corresponding transaction is signed by the user's public key). The owner can delete any user (the corresponding transaction is signed by the owner's public key). + +#### Updating n-wise meta information + +Meta information can be updated by the owner using the `updateMetadataTx` transaction. + +#### Transferring the owner role to other user + +The owner can transfer control of the n-wise to other user. The old owner loses the corresponding privileges and becomes a regular user. The operation is performed using the `NewOwnerTx` transaction. + +#### Notification on n-wise state update + +Just after committing the transaction to the n-wise registry, the participant MUST send the `ledger-update-notify` message to all other parties. +The participant who received `ledger-update-notify` SHOULD fetch updates from the n-wise registry. + +### DIDComm messaging within n-wise + +It is allowed to exchange DIDComm messages of any type within n-wise. +The belonging of the sender to a certain n-wise is determined by the sender's verkey. + +This RFC DOES NOT DEFINE a procedure of exchanging messages within n-wise. In the simplest case, this can be implemented as sending a message to each participant in turn. In case of a large number of parties, it is advisable to consider using a centralized coordinator who would be responsible for the ordering and guaranteed sending of messages from the sender to the rest of parties. + +## Reference + +### N-wise registry transactions + +N-wise state is modified using transactions in the following form + +```json +{ + "type": "transaction type", + ... + "proof" { + "type": "JcsEd25519Signature2020", + "verificationMethod": "did:alice#key1", + "signatureValue": "..." + + } +} +``` + +#### Attributes +* `type` - required attribute, type of transaction; +* `proof` - required attribute, transaction signature in [JSON-LD Proof](https://w3c-ccg.github.io/data-integrity-spec/) format; +* `verificationMethod` - required attribute, depends on the specific type of transaction and is defined below. + +### GenesisTx + +'GenesisTx' is a mandatory initial transaction that defines the basic properties of the n-wise. + +```json +{ + "type": "genesisTx", + "label": "Council", + "creatorNickname": "Alice", + "creatorDid": "did:alice", + "creatorDidDoc": { + .. + }, + "ledgerType": "iota@1.0", + "metaInfo" { + ... + } +} +``` + +#### Attributes +* `label` - required attribute, n-wise name; +* `creatorNickname` - required attribute, creator nickname; +* `creatorDid` - required attribute, DID of the creator; +* `creatorDidDoc` - required attribute, DID Document of the creator; +* `ledgerType` - required attribute, n-wise registry type; +* `metaInfo` - optional attribute, additional n-wise meta information; the format is determined by a particular n-wise state implementation; + +The `genesisTx` transaction MUST be signed by the creator's public key defined in his DID Document. + +### InvitationTx + +This transaction adds the invitation public keys to the n-wise registry. + +```json +{ + "type": "invitationTx", + "publicKey": [ + { + "id": "invitationVerkeyForBob", + "type": "Ed25519VerificationKey2018", + "publicKeyBase58": "arekhj893yh3489qh" + } + ] +} + +``` +#### Attributes +* `publicKey` - required attribute, array of invitation public keys; +* `id` - required attribute, invitation public key ID; +* `type` - required attribute, key type; +* `publicKeyBase58` - required attribute, base58 encoded public key. + +invitationTx` MUST be signed by the user's public key defined in it's DID Document. + +### Invitation message + +The message is intended to invite a new participant. It is sent via an arbitrary communication channel (pairwise, QR code, e-mail, etc.). + +```json +{ + "@id": "5678876542345", + "@type": "https://didcomm.org/n-wise/1.0/invitation", + "label": "Invitaion to join n-wise", + "invitationKeyId": "invitationVerkeyForBob", + "invitationPrivateKeyBase58": "qAue25rghuFRhrue....", + "ledgerType": "iota@1.0", + "ledger~attach": [ + { + "@id": "attachment id", + "mime-type": "application/json", + "data": { + "base64": "" + } + } + ] +} + +``` +#### Attributes +* `label` - optional attribute, human readable invitation text; +* `invitationKeyId` - required attribute, invitation key ID; +* `invitationPrivateKeyBase58`- required attribute, base58 encoded invitation private key; +* `ledgerType` - required attribute, n-wise registry type; +* `ledger~attach` - optional attribute, attachment with meta information, required for connection to n-wise registry; defined by a particular registry implementation. + +### AddParticipantTx + +The transaction is designed to add a new user to n-wise. + +```json +{ + "id": "addParticipantTx", + "nickname": "Bob", + "did": "did:bob", + "didDoc": { + ... + } + +} + +``` +#### Attributes +* `nickname` - required attribute, user nickname; +* `did` - required attribute, user's DID; +* `didDoc` - required attribute, user's DID Document. + +`AddParticipantTx` transaction MUST be signed by the invitation private key (`invitationPrivateKeyBase58`), received in `Invitation` message. As committing the `AddParticipantTx` transaction, the corresponding invitation key pair is considered deactivated (other invitations cannot be signed by it). + +The transaction executor MUST verify if the invitation key was indeed previously added. Execution of the transaction entails the addition of a new party to n-wise. + +### UpdateParticipantTx + +The transaction is intended to update information about the participant. + +```json +{ + "type": "updateParticipantTx", + "did": "did:bob", + "nickname": "Updated Bob", + "didDoc" { + ... + } +} + +``` +#### Attributes +* `did` - requred attribute, DID of the updating user; +* `nickname` - optional attribute, new nickname; +* `didDoc` - optional attribute, new DID document. + +Transaction MUST be signed by the public key of the user being updated. The specified public key MUST be defined in the previous version of the DID Document. + +Execution of the transaction entails updating information about the participant. + +### RemoveParticipantTx + +The transaction is designed to remove a party from n-wise. + +```json +{ + "type": "removeParticipantTx", + "did": "did:bob" +} +``` +#### Attributes +* `did` - requred attribute, DID of the removing user; + +The execution of the transaction entails the removal of the user and his DID Document from the list of n-wise parties. + +The transaction MUST be signed by the public key of the user who is going to be removed from n-wise, or with the public key of the owner. + +### UpdateMetadataTx + +The transaction is intended to update the meta-information about n-wise. + +```json +{ + "type": "updateMetadataTx", + "label": "Updated Council" + "metaInfo": { + ... + } +} +``` + +#### Attributes +* `label` - optional attribute, new n-wise name; +* `metaInfo` - optional attribute, new n-wise meta-information. + +The transaction MUST be signed by the owner's public key. + +### NewOwnerTx + +The transaction is intended to transfer the owner role to another user. The old owner simultaneously becomes a regular user. + +```json +{ + "type": "newOwnerTx", + "did": "did:bob" +} +``` + +#### Attributes +* `did` required attribute, new owner's DID. + +The transaction MUST be signed by the owner's public key. + +### ledger-update-notify + +The message is intended to notify participants about the modifications of the n-wise state. + +```json +{ + "@id": "4287428424", + "@type": "https://didcomm.org/n-wise/1.0/ledger-update-notify" +} +``` + +## Drawbacks + +- External DLT is required; +- The user hierarchy is quite primitive. + +## Rationale and alternatives +Public DID methods use blockchain networks or other public storages for its DID Documents. [Peer DID](https://identity.foundation/peer-did-method-spec/) rejects the use of external storage, which is absolutely justified for a pairwise relationship, since a DID Document can be stored by the other participant. If there are more than two participants, consensus on the list of DID Documents is required. N-wise is somewhat of a middle ground between a Peer DID (DID document is stored only by a partner) and a public DID (DID document is available to everyone in the internet). So, the concept of n-wise state registry was introduced in this RFC, and its specific implementations (consensus between participants or a third-party trusted registry) remain at the discretion of the n-wise creator. The concept of [microledger](https://github.com/the-human-colossus-foundation/microledger-spec/blob/main/microledger.md) is also considerable to use for the n-wise state registry. + +One more promising high-level concept for building n-wise protocols is +[Gossyp](https://github.com/dhh1128/didcomm.org/tree/gossyp/gossyp). + +## Prior art + +The term of n-wise was proposed in [Peer DID](https://identity.foundation/peer-did-method-spec/) specification, and previously discussed in [document](https://docs.google.com/document/d/1BjYdivGQ9GxIz9CJ2ymNvMA68uHZm8bFOTyCHDmziOU/edit#). However, no strict formalization of this process was proposed, as well as the need for consensus between the participants was not noted. + +## Unresolved questions + +* Who should be responsible for the order of transactions? +* How to define specific n-wise state registry implementations (separate RFCs?) +* How to make a flexible user hierarchy? + +## 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 +--- | --- +[Sirius SDK Java](https://github.com/Sirius-social/sirius-sdk-java/) | [IOTA Ledger](https://www.iota.org/) based implementation ([IOTA n-wise registry spec](https://github.com/Sirius-social/docs/blob/main/specs/iota-n-wise-registry.md)). See a detailed [example](https://github.com/Sirius-social/Notebooks/blob/main/notebooks/NwiseJava.ipynb) in Jupyter notebook. diff --git a/features/0748-n-wise-did-exchange/add_participant.png b/features/0748-n-wise-did-exchange/add_participant.png new file mode 100644 index 000000000..2fca39cff Binary files /dev/null and b/features/0748-n-wise-did-exchange/add_participant.png differ diff --git a/features/0755-oca-for-aries/OCA4Aries.xlsx b/features/0755-oca-for-aries/OCA4Aries.xlsx new file mode 100644 index 000000000..28b6fc184 Binary files /dev/null and b/features/0755-oca-for-aries/OCA4Aries.xlsx differ diff --git a/features/0755-oca-for-aries/OCA4AriesBundle.json b/features/0755-oca-for-aries/OCA4AriesBundle.json new file mode 100644 index 000000000..27d1ac295 --- /dev/null +++ b/features/0755-oca-for-aries/OCA4AriesBundle.json @@ -0,0 +1,231 @@ +[ + { + "capture_base": { + "attributes": { + "birthdate_dateint": "DateTime", + "country": "Text", + "expiry_date_dateint": "DateTime", + "family_name": "Text", + "given_names": "Text", + "issuing_jurisdiction": "Text", + "locality": "Text", + "picture": "Binary", + "postal_code": "Text", + "region": "Text", + "street_address": "Text" + }, + "classification": "", + "digest": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "flagged_attributes": [ + "given_names", + "family_name", + "birthdate_dateint", + "street_address", + "locality", + "region", + "postal_code", + "country", + "picture", + "expiry_date_dateint" + ], + "type": "spec/capture_base/1.0" + }, + "overlays": [ + { + "attribute_character_encoding": { + "birthdate_dateint": "utf-8", + "country": "utf-8", + "expiry_date_dateint": "utf-8", + "family_name": "utf-8", + "given_names": "utf-8", + "issuing_jurisdiction": "utf-8", + "locality": "utf-8", + "picture": "base64", + "postal_code": "utf-8", + "region": "utf-8", + "street_address": "utf-8" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "default_character_encoding": "utf-8", + "digest": "Ek-rB1QH1LWWFp21WtxjO-eaCzIHm1jL3QTXqTc5CYiQ", + "type": "spec/overlays/character_encoding/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date of Birth", + "country": "Country", + "expiry_date_dateint": "Expiry Date", + "family_name": "Family Name", + "given_names": "Given Names", + "issuing_jurisdiction": "Issuing Jurisdiction", + "locality": "Locality", + "picture": "Photo (if issued)", + "postal_code": "Postal Code", + "region": "Region", + "street_address": "Street Address" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "EZlM7u7Waz53UZQqWnbK1t11PC_sLBaV03esGRg9EvP8", + "language": "en-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "The date of birth of the person", + "country": "The country code of the person's address", + "expiry_date_dateint": "The expiry date of this [credential / ID]", + "family_name": "The legal family name of the person", + "given_names": "The legal first name(s) of the person", + "issuing_jurisdiction": "The jurisdiction (province, territory, or federal) that issued this [credential / ID]", + "locality": "The city name or locality name of the person's address", + "picture": "A verified photo of the person (if issued)", + "postal_code": "The postal code of the person's address", + "region": "For Canadian addresses, the province or territory of the person's address. For other countries, the regional code of the person's address.", + "street_address": "The full address of the person, excluding locality, region, and postal code" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EgbEwEyKPpfkzJyb4TKHUfRKUpY-EuvJEQxDPSIg-PeU", + "language": "en-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date de naissance", + "country": "Pays", + "expiry_date_dateint": "Date d'expiration", + "family_name": "Nom de famille", + "given_names": "Prénoms", + "issuing_jurisdiction": "Autorité de délivrance", + "locality": "Localité", + "picture": "Photo (si délivrée)", + "postal_code": "Code postal", + "region": "Région", + "street_address": "Adresse municipale" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "E-8GcJ-wUUkea3cYV-7jzVNYV2Lb9gkAbfmQzmxCPyQU", + "language": "fr-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "La date de naissance de la personne", + "country": "Le code du pays de l'adresse de la personne", + "expiry_date_dateint": "La date d'expiration de ce/cette [justificatif / pièce d'identité].", + "family_name": "Le nom de famille légal de la personne", + "given_names": "Le ou les prénoms légaux de la personne", + "issuing_jurisdiction": "L'autorité (province, territoire ou fédéral) qui a délivré ce/cette [justificatif / pièce d'identité]", + "locality": "Le nom de la ville ou de la localité de l'adresse de la personne", + "picture": "Une photo vérifiée de la personne (si délivrée)", + "postal_code": "Le code postal de l'adresse de la personne", + "region": "Pour les adresses canadiennes, la province ou le territoire de l'adresse de la personne. Pour les autres pays, l’indicatif régional de l'adresse de la personne", + "street_address": "L'adresse complète de la personne, sans la localité, la région et le code postal" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EPukcZklEiGw87fzn2WD6o7mgDcM-wVvTs327JMLnT_s", + "language": "fr-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_formats": { + "birthdate_dateint": "YYYYMMDD", + "expiry_date_dateint": "YYYYMMDD", + "picture": "image/jpeg" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EbDQxonRzsXsZxMeflemhNSbaV3FZon6C114U4jdPc24", + "type": "spec/overlays/format/1.0" + }, + { + "attribute_standards": { + "birthdate_dateint": "urn:iso:std:iso:1989", + "expiry_date_dateint": "urn:iso:std:iso:1989" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "ExyElGOmvaHOBtZhOTnNlpblsqpDUcb3xE_qxWgO-GCc", + "type": "spec/overlays/standard/1.0" + }, + { + "attribute_entry_codes": { + "issuing_jurisdiction": [ + "BC", + "ON", + "QC" + ] + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "E8C3mJfLUPM0tasawt7FeuhiTvxQ7QDPaGBRCEpKfvJU", + "type": "spec/overlays/entry_code/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "Colombie-Britannique", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EDeOfI580ee7MDfRriE9FxMoY0VDOOvsRyXEafw_yL0Y", + "language": "fr-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "British Columbia", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "Ej5eE3PhtzglfUMIO9-cmPWYnZcgk7Q9kQG4RuqPY4I8", + "language": "en-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Example credential help text.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "A Canadian schema used for the identity of a person", + "digest": "EhGmnV8_T-Gw646j8r8kI2RHRVv6Znx8XrOPFKoLnRR8", + "issuer": "Government of British Columbia", + "issuer_description": "Government of British Columbia", + "issuer_url": "https://www.gov.bc.ca/", + "language": "en-CA", + "name": "Person Credential", + "type": "spec/overlays/meta/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Exemple de texte d'aide sur les informations d'identification.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "Schéma canadien utilisé pour l'identité d'une personne", + "digest": "EboSiMc4qQKjoRKkQuBiBZbDoZxnP4XLn7yaY6NDHOGA", + "issuer": "Gouvernement de la Colombie-Britannique", + "issuer_description": "Gouvernement de la Colombie-Britannique", + "issuer_url": "https://www.gov.bc.ca/", + "language": "fr-CA", + "name": "Informations d'identification de la personne", + "type": "spec/overlays/meta/1.0" + }, + { + "logo": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/0755-oca-for-aries/best-bc-logo.png", + "background_image_slice": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/best-bc-background-image-slice.png", + "background_image": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/best-bc-background-image.png", + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "description": "", + "digest": "EBQbQEV6qSEGDzGLj1CqT4e6yzESjPimF-Swmyltw5jU", + "expiry_date_attribute": "expiry_date_dateint", + "name": "", + "primary_attribute": "family_name", + "secondary_attribute": "given_names", + "type": "aries/overlays/branding/1.0" + } + ] + } +] diff --git a/features/0755-oca-for-aries/OCA4AriesExcel.json b/features/0755-oca-for-aries/OCA4AriesExcel.json new file mode 100644 index 000000000..512b04b57 --- /dev/null +++ b/features/0755-oca-for-aries/OCA4AriesExcel.json @@ -0,0 +1,218 @@ +[ + { + "capture_base": { + "attributes": { + "birthdate_dateint": "DateTime", + "country": "Text", + "expiry_date_dateint": "DateTime", + "family_name": "Text", + "given_names": "Text", + "issuing_jurisdiction": "Text", + "locality": "Text", + "picture": "Binary", + "postal_code": "Text", + "region": "Text", + "street_address": "Text" + }, + "classification": "", + "digest": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "flagged_attributes": [ + "given_names", + "family_name", + "birthdate_dateint", + "street_address", + "locality", + "region", + "postal_code", + "country", + "picture", + "expiry_date_dateint" + ], + "type": "spec/capture_base/1.0" + }, + "overlays": [ + { + "attribute_character_encoding": { + "birthdate_dateint": "utf-8", + "country": "utf-8", + "expiry_date_dateint": "utf-8", + "family_name": "utf-8", + "given_names": "utf-8", + "issuing_jurisdiction": "utf-8", + "locality": "utf-8", + "picture": "base64", + "postal_code": "utf-8", + "region": "utf-8", + "street_address": "utf-8" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "default_character_encoding": "utf-8", + "digest": "Ek-rB1QH1LWWFp21WtxjO-eaCzIHm1jL3QTXqTc5CYiQ", + "type": "spec/overlays/character_encoding/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date of Birth", + "country": "Country", + "expiry_date_dateint": "Expiry Date", + "family_name": "Family Name", + "given_names": "Given Names", + "issuing_jurisdiction": "Issuing Jurisdiction", + "locality": "Locality", + "picture": "Photo (if issued)", + "postal_code": "Postal Code", + "region": "Region", + "street_address": "Street Address" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "EZlM7u7Waz53UZQqWnbK1t11PC_sLBaV03esGRg9EvP8", + "language": "en-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "The date of birth of the person", + "country": "The country code of the person's address", + "expiry_date_dateint": "The expiry date of this [credential / ID]", + "family_name": "The legal family name of the person", + "given_names": "The legal first name(s) of the person", + "issuing_jurisdiction": "The jurisdiction (province, territory, or federal) that issued this [credential / ID]", + "locality": "The city name or locality name of the person's address", + "picture": "A verified photo of the person (if issued)", + "postal_code": "The postal code of the person's address", + "region": "For Canadian addresses, the province or territory of the person's address. For other countries, the regional code of the person's address.", + "street_address": "The full address of the person, excluding locality, region, and postal code" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EgbEwEyKPpfkzJyb4TKHUfRKUpY-EuvJEQxDPSIg-PeU", + "language": "en-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date de naissance", + "country": "Pays", + "expiry_date_dateint": "Date d'expiration", + "family_name": "Nom de famille", + "given_names": "Prénoms", + "issuing_jurisdiction": "Autorité de délivrance", + "locality": "Localité", + "picture": "Photo (si délivrée)", + "postal_code": "Code postal", + "region": "Région", + "street_address": "Adresse municipale" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "E-8GcJ-wUUkea3cYV-7jzVNYV2Lb9gkAbfmQzmxCPyQU", + "language": "fr-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "La date de naissance de la personne", + "country": "Le code du pays de l'adresse de la personne", + "expiry_date_dateint": "La date d'expiration de ce/cette [justificatif / pièce d'identité].", + "family_name": "Le nom de famille légal de la personne", + "given_names": "Le ou les prénoms légaux de la personne", + "issuing_jurisdiction": "L'autorité (province, territoire ou fédéral) qui a délivré ce/cette [justificatif / pièce d'identité]", + "locality": "Le nom de la ville ou de la localité de l'adresse de la personne", + "picture": "Une photo vérifiée de la personne (si délivrée)", + "postal_code": "Le code postal de l'adresse de la personne", + "region": "Pour les adresses canadiennes, la province ou le territoire de l'adresse de la personne. Pour les autres pays, l’indicatif régional de l'adresse de la personne", + "street_address": "L'adresse complète de la personne, sans la localité, la région et le code postal" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EPukcZklEiGw87fzn2WD6o7mgDcM-wVvTs327JMLnT_s", + "language": "fr-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_formats": { + "birthdate_dateint": "YYYYMMDD", + "expiry_date_dateint": "YYYYMMDD", + "picture": "image/jpeg" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EbDQxonRzsXsZxMeflemhNSbaV3FZon6C114U4jdPc24", + "type": "spec/overlays/format/1.0" + }, + { + "attribute_standards": { + "birthdate_dateint": "urn:iso:std:iso:1989", + "expiry_date_dateint": "urn:iso:std:iso:1989" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "ExyElGOmvaHOBtZhOTnNlpblsqpDUcb3xE_qxWgO-GCc", + "type": "spec/overlays/standard/1.0" + }, + { + "attribute_entry_codes": { + "issuing_jurisdiction": [ + "BC", + "ON", + "QC" + ] + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "E8C3mJfLUPM0tasawt7FeuhiTvxQ7QDPaGBRCEpKfvJU", + "type": "spec/overlays/entry_code/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "Colombie-Britannique", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EDeOfI580ee7MDfRriE9FxMoY0VDOOvsRyXEafw_yL0Y", + "language": "fr-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "British Columbia", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "Ej5eE3PhtzglfUMIO9-cmPWYnZcgk7Q9kQG4RuqPY4I8", + "language": "en-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Example credential help text.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "A Canadian schema used for the identity of a person", + "digest": "EhGmnV8_T-Gw646j8r8kI2RHRVv6Znx8XrOPFKoLnRR8", + "issuer": "Government of British Columbia", + "issuer_description": "Government of British Columbia", + "issuer_url": "https://www.gov.bc.ca/", + "language": "en-CA", + "name": "Person Credential", + "type": "spec/overlays/meta/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Exemple de texte d'aide sur les informations d'identification.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "Schéma canadien utilisé pour l'identité d'une personne", + "digest": "EboSiMc4qQKjoRKkQuBiBZbDoZxnP4XLn7yaY6NDHOGA", + "issuer": "Gouvernement de la Colombie-Britannique", + "issuer_description": "Gouvernement de la Colombie-Britannique", + "issuer_url": "https://www.gov.bc.ca/", + "language": "fr-CA", + "name": "Informations d'identification de la personne", + "type": "spec/overlays/meta/1.0" + } + ] + } +] diff --git a/features/0755-oca-for-aries/README.md b/features/0755-oca-for-aries/README.md new file mode 100644 index 000000000..9b2cbc0e6 --- /dev/null +++ b/features/0755-oca-for-aries/README.md @@ -0,0 +1,688 @@ +# 0755: Overlays Capture Architecture (OCA) For Aries + +- Authors: [Stephen Curran](mailto:swcurran@gmail.com) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2024-03-02 +- Status Note: Implemented in the [Bifold Wallet](https://github.com/openwallet-foundation/bifold-wallet) +- Start Date: 2022-09-25 +- Version: 1.0 +- Tags: [feature](/tags.md#feature) + +## Summary + +[Overlays Capture Architecture](https://oca.colossi.network/) (OCA) is, per the +[OCA specification], a "standardized global solution for data capture and +exchange." Given a data structure (such as a verifiable credential), OCA allows +for the creation of purpose-specific overlays of information about that data +structure. Each overlay provides some knowledge (human and machine-readable) +about the overall data structure or the individual attributes within it. The +information in the overlays makes it possible to create useful software for +capturing data, displaying it and exchanging it. While the [OCA +website](https://oca.colossi.network/) and [OCA specification] can be reviewed +for a detailed background of OCA and its various purposes, in this RFC we'll +focus on its purpose in Aries, which is quite constrained and pragmatic--a +mechanism for an issuer to provide information about a verifiable credential to +allow holder and verifier software to display the credential in a human-friendly +way, including using the viewers preferred language, and the issuer's preferred +branding. The image below shows an Aries mobile Wallet displaying the same +credential without and with OCA overlays applied in two languages. All of the +differences in the latter two screenshots from the first come from +issuer-supplied OCA data. + +[OCA Specification]: https://oca.colossi.network/specification/ +[RFC0756 OCA for Aries Style Guide]: ../../features/0756-oca-for-aries-style-guide/README.md + +![Example: Using OCA in Aries Bifold](assets/bifold-oca-example.jpg) + +This RFC formalizes how Aries verifiable credential issuers can make a JSON [OCA +Bundle] (a set of related OCA overlays about a base data structure) available to +holders and verifiers that includes the following information for each type of +credential they issue. + +- Metadata about the credential, such as the Classification system upon which + the credential is based. +- Metadata about the credential in multiple languages, such as its name, + description, the name and description of the issuer and so on. +- Type, format, encoding, standard and units information about the credential's raw + attribute data. +- Metadata about the attributes within the credential in multiple languages, + such as a label and help text. +- A set of branding elements (logo, background image, color and so on) that + holder and verifier software are expected to use in displaying the credential. + +The standard flow of data between participants is as follows: + +- An issuer creates an OCA Bundle for each type of verifiable credential it +issues. +- During credential issuance using [RFC 0453 Issue Credential V2 v2.2 (or later) +protocol] the issuer MAY include in the protocol's `credential-offer` or +`credential` messages the OCA Bundle for the credential type as an `oca-bundle` +[issue credential supplement]. +- When provided, the holder software has full access to the OCA information +published by that issuer and can use the OCA data to render the credential for +its user(s) in the language of their choice, with credential branding from +the issuer, based on the [RFC0756 OCA for Aries Style Guide]. +- The holder MAY share the OCA Bundle with a verifier by using [RFC 0453 Issue +Credential V2 v2.2 (or later) protocol] to add the `oca-bundle` credential +supplement received from the issuer. +- On receipt, the verifier software has full access to the OCA information +published by that issuer and can use the OCA data to render the credential for +its user(s) in the language of their choice, with credential branding from +the issuer, based on the [RFC0756 OCA for Aries Style Guide]. + +[RFC 0453 Issue Credential V2 v2.2 (or later) +protocol]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2#22---addition-of-supplements +[issue credential supplement]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2#supplements +[OCA Bundle]: https://oca.colossi.network/specification/#bundle + +While the issuer providing the OCA Bundle for a credential type using the +credential supplement mechanism is the typical flow (as detailed in this RFC), +other flows, outside of the scope of this RFC are possible. See the [rationale +and alternatives section of this RFC for some +examples](#rationale-and-alternatives). + +## Motivation + +The core data models for verifiable credentials are more concerned about the +correct cryptographic processing of the credentials than about general +processing of the attribute data, and the user experience of those using +credentials. An AnonCreds verifiable credential contains the bare minimum of +metadata about a credential--basically, just the developer-style names for the +type of credential and the attributes within it. JSON-LD-based verifiable +credentials has the capacity to add more information about the attributes in a +credential, but the data is not easily accessed and is provided to enable +machine processing rather than improving user experience. + +OCA allows credential issuers to declare information about the verifiable +credential types it issues to improve the handling of those credentials by +holder and verifier Aries agents, and to improve the on-screen display of the +credentials, through the application of issuer-specified branding elements. + +## Tutorial + +The tutorial section of this RFC defines the coordination necessary for an +the creation, publishing, retrieval and use of an OCA Bundle for a given +type of verifiable credential. + +``` Note + +In this overview, we assume the the use of OCA specifically for verifiable +credentials, and further, specifically for AnonCreds verifiable credentials. OCA +can also be used be applied to any data structure, not just verifiable +credentials, and for other verifiable credential models, such as those based on +the JSON-LD- or JWT-style verifiable credentials. As the Aries +community applies OCA to other styles of verifiable credential, we +will extend this RFC. + +``` + +### Issuer Activities + +The use of OCA as defined in this RFC begins with an issuer preparing an [OCA +Bundle] for each type of credential they issue. An OCA Bundle is a JSON data +structure consisting of the [Capture Base], and some additional overlays of +different types (listed in the [next section](#oca-specification-overlays)). + +While an OCA Bundle can be manually maintained in an OCA Bundle JSON file, a +common method of maintaining OCA source data is to use a spreadsheet, and +generating the OCA Bundle from the Excel source. See the section of this RFC +called [OCA Tooling](#oca-issuer-tools) for a link to an OCA Source spreadsheet, +and information on tools available for managing the OCA Source data and +generating a corresponding OCA Bundle. + +The creation of the OCA Bundle and the configuration of the issuer's Aries +Framework to deliver the OCA Bundle during credential issuance should be all +that a specific issuer needs to do in using OCA for Aries. An Aries Framework +that supports OCA for Aries should handle the rest of the technical +requirements. + +#### OCA Specification Overlays + +All OCA data is based on a [Capture Base], which defines the data structure +described in the overlays. For AnonCreds, the Capture Base attributes MUST be +the list of attributes in the AnonCreds schema for the given credential type. +The Capture Base also MUST contain: + +- the type of each attribute, based on an enumerated list of [types defined in + the OCA + specification](https://oca.colossi.network/v1.1.0-rc.html#attribute-type) +- a list of the base attributes that will hold Personally Identifiable +Information (PII) in an issued credential. An issuer SHOULD use the [Kantara +Initiative's Blinding Identity +Taxonomy](https://docs.kantarainitiative.org/Blinding-Identity-Taxonomy-Report-Version-1.0.html) +to identify the attributes to flag as being PII. + +With the Capture Base defined, the following additional overlay types MAY be +created by the Issuer and SHOULD be expected by holders and verifiers. +Overlay types flagged "multilingual" may have multiple instances of the overlay, +one for each issuer-supported language (e.g en for English, fr French, SP +Spanish, etc.) or country-language (e.g., en-CA for Canadian English, fr-CA for +Canadian French), as defined in the [OCA Specification about +languages](https://oca.colossi.network/specification/#language). + +An OCA Bundle that contains overlay types that a holder or verifier does not +expect MUST be processed, with the unexpected overlays ignored. + +- The **[Character Encoding Overlay]** contains the encoding for each attribute +in the capture base. +- The **[Format Overlay]** provides +the input structure for each data attribute. The format may be useful to the +holder (or verifier) in displaying the data in a style expected by the user, +such as knowing that a given field of `type` binary is an image in `image/jpeg` +format. +- The multilingual **[Label Overlay]** provides a label to be used for each +attribute for a given language. The label overlay also includes labels for +attributes with enumerated values (called categories in the OCA specification). +For example, a data attribute containing the codes "EN", "FR", "SP" could have a +category entries that indicate the codes correspond to "English", "French" and +"Spanish", respectively. +- The multilingual **[Information Overlay]** provides a description or help text +about each attribute for a given language. There will be one overlay per +issuer-supported language. +- The multilingual **[Meta Overlay]** contains information about the credential +itself. For Aries, the meta overlay SHOULD include the following additional +name/value pairs, specific to the OCA for Aries use case: + - `name` - the name of the credential. + - `description` - a description of the credential. + - `issuer` - the name of the issuer of the credential. + - `issuer_description` - a description for the issuer of the credential. + - `issuer_url` - a URL for the issuer of the credential. + - `credential_help_text` - help text about the credential + - `credential_support_url` - a URL for a service providing support in the use of the credential. +- The **[Unit Overlay]** + allows the issuer to declare the units of measurement for the attributes in + the overlay. +- The **[Standard Overlay]** indicates that some or all of the attributes use + specific data standards populating the attribute in a credential. This might + be used, for example, for defining the standard applied in populating a data + attribute with a date or date/time. +- The **[Entry Code Overlay]** contains a list of enumerated values for each + data attribute that uses enumerated values. An example might be a list of + regional jurisdiction (such as provinces or states) short forms that will be + placed in an attribute (e.g., NY, ND, AL, CA, etc.). The attributes in the + credential are expected to be populated with one of the enumerated values. +- The **[Entry Overlay]** contains a language-specific list of the meanings for + each enumerated value for each data attribute that uses enumerated values. For + our example of short forms of jurisdictions, the "meanings" would be the + expanded list per language supported (English, French, Spanish, etc.) of + jurisdictions (e.g., New York, North Dakota, Alabama, California, etc.). + +[Capture Base]: https://oca.colossi.network/v1.1.0-rc.html#capture-base +[Character Encoding Overlay]: https://oca.colossi.network/v1.1.0-rc.html#character-encoding-overlay +[Format Overlay]: https://oca.colossi.network/v1.1.0-rc.html#format-overlay +[Label Overlay]: https://oca.colossi.network/v1.1.0-rc.html#label-overlay +[Information Overlay]: https://oca.colossi.network/v1.1.0-rc.html#information-overlay +[Meta Overlay]: https://oca.colossi.network/v1.1.0-rc.html#meta-overlay +[Unit Overlay]: https://oca.colossi.network/specification/#unit-overlay +[Standard Overlay]: https://oca.colossi.network/specification/#standard-overlay +[Entry Code Overlay]: https://oca.colossi.network/specification/#entry-code-overlay +[Entry Overlay]: https://oca.colossi.network/specification/#entry-overlay + +#### Aries-Specific Dates in the OCA Format Overlay + +In AnonCreds, zero-knowledge proof (ZKP) predicates (used, for example, to prove +older than a given age based on date of birth without sharing the actual date of +birth) must be based on **integers**. In the AnonCreds/Aries community, common +ways for representing dates and date/times as integers so that they can be used +in ZKP predicates are the `dateint` and `Unix Time` formats, respectively. + +- "`dateint`" is a credential attribute that uses the Aries `dateint` +specification as described in [Aries RFC +0592](../0592-indy-attachments/README.md). Briefly, `dateint` is a date +(YYYYMMDD) provided in a credential attribute as an integer (for example +`September 29, 2022` is the integer `20220929` or `20,220,929`). `dateint` is +also part of [ISO standard 1989 for COBOL Programming +Interfaces](https://www.iso.org/standard/74527.html), described [here in an IBM +document](https://www.ibm.com/docs/en/cobol-zos/6.3?topic=sf-format-arguments-return-values-date-time-intrinsic-functions#INFFORM__stand_date). + +- "`Unix Time`" is a credential attribute that is a date/time timestamp +constructed according to the `Unix Time` [Unix/POSIX data +standard](https://en.wikipedia.org/wiki/Unix_time). Briefly, `Unix Time` is a +date/time represented as the number of seconds since January 1, 1970 UTC. + +In an OCA for Aries OCA Bundle, a `dateint` and `Unix Time` attributes MUST +have the following values in the indicated overlays: + +- `dateint` + - datatype `DateTime` in the [Capture Base] + - standard `urn:iso:std:iso:1989` in the [Standard Overlay] + - character encoding `utf-8` in the [Character Encoding Overlay] + - format `YYYYMMDD` in the [Format Overlay] + - Example: `20230114` for "January 14, 2023" +- `Unix Time` + - datatype `DateTime` in the [Capture Base] + - standard `urn:unix:unix-time` in the [Standard Overlay] + - character encoding `utf-8` in the [Character Encoding Overlay] + - format `epoch` in the [Format Overlay] + - Example: `1673715495` for "Sat Jan 14 2023 16:58:15 GMT+0000" + +A recipient of an OCA Bundle with the combination of overlay values referenced +above for `dateint` and `Unix Time` SHOULD convert the integer attribute data +into a date or date/time (respectively) and display the information as +appropriate for the user. For example, a mobile app should display the data as a +date or date/time based on the user's language/country setting and timezone, +possibly combined with an app setting for showing the data in [short, medium, +long or full +form](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). + +#### Aries Specific "branding" Overlay + +In addition to the core OCA Overlays listed earlier, Aries issuers MAY include +an additional Aries-specific extension overlay, the **"branding" overlay**, that +gives the issuer a way to provide a set of data elements about the branding that +they would like to see applied to a given type of credential. The `branding +overlay` is similar to the multilanguage Meta overlay (e.g. ones for English, +French and Spanish), with a specified set of name/value pairs. Holders (and +verifiers) use the branding values from the issuer when rendering a credential +of that type according the [RFC0756 OCA for Aries Style Guide]. + +An example of the use of the branding overlay is as follows, along with a +definition of the name/value pair elements, and a sample image of how the +elements are to be used. The sample is provide only to convey the concept of the +branding overlay and how it is to be used. Issuers, holders and verifiers should +refer to [RFC0756 OCA for Aries Style Guide] for details on how the elements are to +be provided and used in displaying credentials. + +``` +{ + "type": "aries/overlays/branding/1.0" + "digest": "EBQbQEV6qSEGDzGLj1CqT4e6yzESjPimF-Swmyltw5jU", + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "logo": "https://raw.githubusercontent.com/hyperledger/aries-rfcs/oca4aries/features/0755-oca-for-aries/best-bc-logo.png", + "background_image": "https://raw.githubusercontent.com/hyperledger/aries-rfcs/oca4aries/features/best-bc-background-image.png", + "background_image_slice": "https://raw.githubusercontent.com/hyperledger/aries-rfcs/oca4aries/features/best-bc-background-image-slice.png", + "primary_background_color": "#003366", + "secondary_background_color": "#003366", + "secondary_attribute": "given_names", + "primary_attribute": "family_name", + "secondary_attribute": "given_names", + "issued_date_attribute": "", + "expiry_date_attribute": "expiry_date_dateint", +} +``` + +![Sample: Using the Branding Overlay, from the Aries Credential Branding Style +Guide](assets/Sample-use-of-Branding-Overlay.png) + +[hashlink]: https://datatracker.ietf.org/doc/html/draft-sporny-hashlink +[Data URL Scheme]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs + +- OCA Overlay-related items: + - `type` - a the type of the overlay, using the `aries` namespace. + - `digest` - the self-addressing identifier (SAID) for the overlay. Note that in this example, the SAID is not accurate for the data in the example. + - `capture_base` - the self-addressing identifier (SAID) for the capture base to which this overlay applies. +- `logo` - a URI for a logo to display on the credential in some contexts. +The URI can be an HTTP URL, a [hashlink] or, to support inline images, a data +URL (e.g.: `data:image/png;base64,...`) as defined by the [Data URL Scheme]. The +logo MUST adhere to the logo properties defined in [RFC0756 OCA for Aries Style Guide]. +- `background_image` - a URI for a background image to display with the +credential in some contexts. The URI could be an HTTP URL, a [hashlink] or, to +support inline images, a data URL (e.g.: `data:image/png;base64,...`) as defined +by the [Data URL Scheme]. The image MUST adhere to the background image +properties defined in [RFC0756 OCA for Aries Style Guide]. +- `background_image_slice` - a URI for a background image slice to display +with the credential in some contexts. The URI could be a HTTP URL, a [hashlink] +or, to support inline images, a data URL (e.g.: `data:image/png;base64,...`) as +defined by the [Data URL Scheme]. The image MUST adhere to the background image slice +properties defined in [RFC0756 OCA for Aries Style Guide]. +- `primary_background_color` - hex color code for the primary background color of the + credential to be used in some contexts. +- `secondary_background_color` - hex color code for the secondary background color of the + credential to be used in some contexts. +- `primary_attribute` - the name of a capture base attribute to be displayed on + the credential in some contexts. +- `secondary_attribute` - the name of a capture base attribute to be displayed on + the credential in some contexts. +- `issued_date_attribute` - the name of a capture base attribute that is the date + of issuance of the credential. If there is no such attribute, leave blank. +- `expiry_date_attribute` - the name of a capture base attribute that is the + expiry date of the credential. If there is no such attribute, leave blank. + +It is deliberate that the credential branding defined in this RFC does **not** +attempt to achieve pixel-perfect on screen rendering of the equivalent paper +credential. There are two reasons for this: + +- First, studies have shown that issuers do not want people to think that the +digital credentials they have in their mobile wallet can be used as literal +replacements for paper during person-to-person (non-digital) verifications by +the holder showing their mobile device screen to the verifier. By showing +verifiers their screen, the holder may be oversharing their personal data. As +well, digital credentials are even easier to forge than paper credentials when +they are to be verified by a human, and we want to discourage using digital +credentials in that way. +- Second, having each issuer provide pixel-perfect layout guidance to Aries agents +that supports a responsive user interface on a wide range of devices (laptops, +tablets and thousands of mobile phones) is extraordinarily complex. Further, a +wallet wanting to provide a consistent, helpful user experience will be severely +hampered by displaying credentials with many (perhaps hundreds) of completely +different credential layouts and styles. + +Instead, the guidance in this RFC and the [RFC0756 OCA for Aries Style Guide] +gives the issuer a few ways to brand their credentials, and holder/verifier apps +information on how to use those issuer-provided elements in a manner consistent +for all issuers and all credentials. + +#### OCA Issuer Tools + +An Aries OCA Bundle can be managed as pure JSON as found in this [sample OCA for +Aries OCA Bundle]. However, managing such multilingual content in JSON is not +easy, particularly if the language translations come from team members not +comfortable with working in JSON. An easier way to manage the data is to use an +OCA source spreadsheet for most of the data, some in a source JSON file, and to +use a converter to create the OCA Bundle JSON from the two sources. We recommend +that an issuer maintain the spreadsheet file and source JSON in version control +and use a pipeline action to generate the OCA Bundle when the source files are +updated. + +The OCA Source Spreadsheet, an [example of which is attached to this +RFC](OCA4Aries.xlsx), contains the following: + +- An introductory tab about the OCA content in the spreadsheet. +- A tab with instructions on using the spreadsheet. +- A "Main" tab with the "Capture Base" data, along with data for other, non-multilingual overlays. +- A language or country-language code tab per country-language to be supported by the issuer + containing the source data for all multilingual overlays. + +The JSON Source file contains the [Aries-specific Branding +Overlay](#aries-specific-branding-overlay). Attached to this RFC is an [example +Branding Overlay JSON file](branding.json) that issuers can use to start. + +The following is how to create an OCA Source spreadsheet and from that, generate +an OCA Bundle. Over time, we expect that this part of the RFC will be clarified +as the tooling evolves. + +- Creating/Maintaining the Excel File + - Make a copy of the latest [OCA Template] from the [Human Colossus Foundation]. + - Fill in the "Main" tab with the attributes from the schema, completing the + relevant columns for each attribute. Current columns to complete: + - CB-CL: Classification + - CB-AN: Attribute Name + - CB-AT: Attribute Type + - CB-FA: Flagged Attribute + - OL-CH: Character Encoding + - OL-FT: Format + - OL-ST: Standard + - OL-EC: Entry Codes + - OL-UT: Unit + - As needed, populate the columns for "dateint" and "Unix Time" attributes as indicated in the [Aries Specific Dates in the OCA Formats Overlay](#aries-specific-dates-in-the-oca-format-overlay) section of this document. + - Rename the sample language tab (`en`) to one of the language or language-country that as an issuer, you want to support. + - Fill in the data in columns other than C (which is automatically populated from the `Main` tab) for the first language as appropriate. + - Populate column A and B as follows: + - In column A (`OL-MN: Meta [Attribute Name]`), add the values: + - "name" + - "description" + - "issuer" + - "issuer_description" + - "issuer_url" + - "credential_help_text" + - "credential_support_url" + - "watermark" + - The "watermark" is used to mark non-production credentials, as described in the ["non-production watermark" section of RFC0756 OCA for Aries Style Guide](../../features/0756-oca-for-aries-style-guide/README.md#non-production-watermark) + - Complete column B (`OL-MV: Meta [Attribute Value]`) as appropriate for each column A name (listed above). + - Duplicate and rename the initial language tab for each language or language-country that as an issuer, you want to support. + - Update each additional language tab. +- Creating/Maintaining the Branding JSON file + - Make a copy of the attached example [branding JSON file](branding.json), and update the values for the credential you are issuing. +- Generating the OCA Bundle from the OCA for Aries Source files: + - Use the open source [OCA Parser from the Human Colossus Foundation] to convert the + spreadsheet to JSON. The current command to use is `parser parse oca --path > ` + - Use the open source [jq utility](https://stedolan.github.io/jq/) to add the `branding.json` file to the JSON Excel output to produce the OCA Bundle with the following command, replacing the file names in the command with the ones for your use: + - `jq ".[].overlays += $(cat BRANDING-JSON-FILE)" OCA-EXCEL-FILE > OCA-BUNDLE-JSON-FILE` + - From a command line in this folder, the following command can be run to generate the OCA Bundle JSON to standard output: + - `jq ".[].overlays += $(cat branding.json)" OCA4AriesExcel.json` + +> NOTE: The `capture_base` and `digest` fields in the branding overlay of the resulting OCA Bundle JSON file will **not** be updated to be proper self-addressing identifiers (SAIDs) as required by the [OCA Specification]. We are looking into how to automate the updating of those data elements. + +[OCA Template]: https://github.com/THCLab/oca-ecosystem/raw/main/examples/template.xlsx + +Scripting the generation process should be relatively simple, and our expectation is that +the community will evolve the [Parser from the Human Colossus Foundation] to +simplify the process further. + +[sample OCA for Aries OCA Bundle]: ./sample_oca_for_aries_oca_bundle.json +[OCA Parser from the Human Colossus Foundation]: https://github.com/THCLab/oca-rust + +Over time, we expect to see other tooling become available--notably, a tool for +issuers to see what credentials will look like when their OCA Bundle is applied. + +#### Issuing A Credential + +> This section of the specification remains under consideration. The use of the +> `credential supplement` as currently described here is somewhat problematic +> for a number of reasons. +> +> - The issuer has no way to update the OCA Bundle for a given holder after +> issueance. We see this as a likely use case to enable, for example, an +> issuer supporting additional languages over time. +> - The "External Attachments" risk, as described in [this section of this +> RFC](#warning-external-attachments). +> - The complicated way for a verifier to get an OCA Bundle when needed after a +> presentation. +> +> We are currently investigating if an OCA Bundle can be published to the same +> VDR as holds an AnonCreds Schema or Credential Definition. We think that would +> overcome each of those concerns and make it easier to both publish and +> retrieve OCA Bundles. + +The currently preferred mechanism for an issuer to provide an OCA Bundle to a +holder is when issuing a credential using +[RFC0453 Issue Credential](../0453-issue-credential-v2/README.md), version 2.2 or later, the issuer +provides, in the [credential offer +message](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2/README.md#offer-credential), +an OCA Bundle as a [credential +supplement](https://github.com/hyperledger/aries-rfcs/tree/main/features/0453-issue-credential-v2/README.md#supplements). + +- The supplement type MUST be `oca-bundle`. +- The OCA Bundle MUST be in the JSON form of an OCA Bundle, not the ZIP format. +- The attachment MUST be +[signed](../../concepts/0017-attachments/README.md#signing-attachments) by the +issuer, and may be of [type +`base64url`](../../concepts/0017-attachments/README.md#base64url), meaning the +OCA Bundle is embedded in the message, or of [type +`link`](../../concepts/0017-attachments/README.md#links). + +The reason OCA Bundle attachment must be signed by the issuer so that if the holder +passes the OCA Bundle on to the verifier, the verifier can be certain that the +issuer provided the OCA Bundle, and that it was not created by a malicious holder. + +Issuers should be aware that to ensure that the signature on a linked OCA Bundle +(using the attachment [type `link`](../../concepts/0017-attachments/README.md#links)) +remains verifiable, the content resolved by the link must not change over time. +For example, an Issuer might publish their OCA Bundles in a public GitHub +repository, and send a link to the OCA Bundle during issuance. In that case the +Issuer is advised to send a commit-based GitHub URL, rather than a branch-based +reference. The Issuer may update the OCA Bundle sent to different holders over +time, but once issued, each OCA Bundle MUST remain accessible. + +#### Warning: External Attachments + +The use of an attachment of type `link` for the OCA Bundle itself, or the use of +external references to the images in the +[branding Overlay](#aries-specific-branding-overlay) could provide malicious issuers with +a mechanism for tracking the use of a holder's verifiable credential. +Specifically, the issuer could: + +- Make any or all of the OCA bundle external references a unique identifier for + the holder. +- When the holder retrieves the OCA bundle, the issuer does not learn anything + useful as they already know they have issued a credential to that holder. +- If the holder passes the OCA bundle to verifiers and the verifiers resolve the + external references, the malicious issuer would learn that the holder has used + their verifiable credential in a presentation, and perhaps, with what verifier. + +A holder MAY choose not to attach an OCA Bundle to a verifier if it contains any +external references. Non-malicious issuers are encouraged to **not** use +external references in their OCA Bundles and as such, to minimize the inlined +images in the branding overlay. + +### Holder Activities + +Before processing a credential and an associated OCA Bundle, the holder SHOULD +determine if the issuer is known in an ecosystem and has a sufficiently positive +reputation. For example, the holder might determine if the issuer is in a suitable [Trust Registry] +or request a presentation from the issuer about their identity. + +[Trust Registry]: https://wiki.trustoverip.org/display/HOME/ToIP+Trust+Registry+Protocol+Specification + +On receipt of a credential with an OCA Bundle supplement, the holder SHOULD +retrieve the OCA Bundle attachment, verify the signature is from the issuer's +public DID, verify the signature, and verify that the [OCA Capture Base] is for +the credential being offered or issued to the holder. If verified, the holder +should associate the OCA Bundle with the credential, including the signature. + +The holder SHOULD take appropriate security precautions in handling the +remainder of the OCA data, especially the images as they could contain a +malicious payload. The security risk is comparable to a browser receiving a web +page containing images. + +Holder software should be implemented to use the OCA Bundle when processing +and displaying the credential as noted in the list below. Developers of holder +software should be familiar with the overlays the issuer is likely to provide +(see list [here](#oca-specification-overlays)) and how to use them according to +[RFC0756 OCA for Aries Style Guide]. + +- Check the country and language settings of the current user and use the +appropriate multilingual overlays to respect those settings in displaying +credential metadata and attributes (labels, etc.). +- Consider adding multilingual informational popups in your app using the per + attribute data in the "information" overlay. +- Consider using the PII flag in the Capture Base to provide guidance to the + user about the sharing of PII. +- Use the branding overlay and [RFC0756 OCA for Aries Style Guide] in + displaying the credential in various contexts (e.g., in a credential offer + prompt, in a list, selected from a list, alone on a page, etc.). +- Process the attribute data using the `type`, `character encoding`, `format`, + `unit` and `standard` overlays and display tha attributes appropriately for a + given user. For example, display dates in a form suitable for the language and + country settings of the user. +- Where enumerated names are used for credential attributes, retrieve and use + the name-value pairs in the [Entry Code Overlay] and [Entry Overlay] to display the data. +- Use the OCA-provide metadata about the credential, such as the + name/description of the issuer, name/description of the credential type. + +A recommended tactic when adding OCA support to a holder is when a credential is +issued without an associated OCA Bundle, generate an OCA Bundle for the +credential using the information available about the type of the credential, +default images, and randomly generated colors. That allows for the creation of +screens that assume an OCA Bundle is available. The [RFC0756 OCA for Aries Style +Guide] contains guidelines for doing that. + +#### Adding OCA Bundles to Present Proof Messages + +Once a holder has an OCA Bundle that was issued with the credential, it MAY pass +the OCA Bundle to a verifier when a presenting a proof that includes claims from +that credential. This can be done via the [present proof credential supplements] +approach, similar to what used when the credential was issued to the holder. +When constructing the `present_proof` message to hold a proof, the holder would +iterate through the credentials in the proof, and if there is an issuer-supplied +OCA Bundle for the credentials, add the OCA Bundle as a supplement to the +message. The signature from the Issuer MUST be included with the supplement. + +A holder SHOULD NOT send an OCA Bundle to a verifier if the OCA Bundle is a +link, or if any of the data items in the OCA Bundle are links, as noted in the +in the [warning about external attachments in OCA +Bundles](#warning-external-attachments). + +[present proof credential supplements]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0454-present-proof-v2#22---addition-of-supplements + +### Verifier Activities + +On receipt of a presentation with OCA Bundle supplements, the verifier SHOULD +retrieve the OCA Bundle attachments, verify the signatures are from the +credential issuers' public DIDs, verify the signatures, and verify that the [OCA +Capture Base] is for the credentials being presented to the verifier. If +verified, the verifier should associate the OCA Bundle with the source +credential from the presentation. + +On receipt of a presentation with OCA Bundle supplements, the verifier MAY +process the OCA Bundle attachment and verify the issuer's signature. If it +verifies, the verifier should associate the OCA Bundle with the source +credential from the presentation. The verifier SHOULD take appropriate security +precautions in handling the data, especially the images. The holder software +should be implemented to use the OCA Bundle when processing and displaying the +credential as noted in the list below. + +Developers of verifier software should be familiar with the overlays the issuer +is likely to provide (see list [here](#oca-specification-overlays)) and how to +use them according to [RFC0756 OCA for Aries Style Guide]. The list of [how to +use the OCA Bundle as a holder](#holder-activities) applies equally to +verifiers. + +## Reference + +- The [OCA Specification] +- [RFC0756 OCA for Aries Style Guide] + +## Drawbacks + +- The use of credential supplements might not be the best way to publish OCA + Bundles. The Aries community is currently investigating if OCA Bundles can be + published to the Verifiable Data Registry upon which the schema and credential + definition are published. +- As noted in this [warning](#warning-external-attachments), the use of links + either for OCA Bundles or for the images that are embedded in OCA Bundles are + both extremely useful and problematic. It would be nice to be able to allow + links for/in the OCA Bundles without the potential of being used to track the + holder. +- If the OCA Bundle is passed to the holder as a link, the issuer must continue + to make that content available for as long as the holder might retain the + credential. Putting the OCA Bundle on a verifiable data registry (such as a + ledger/blockchain) might be a good way to publish such data. +- The processing of an OCA Bundle, and particularly the processing of images in + the branding overlay, provide an attack vector for malicious issuers. + Developers of holder software SHOULD take precautions in handling and + displaying the data. + +## Rationale and alternatives + +- The OCA architecture seems well suited to the Aries verifiable credential +use case, supporting the important capabilities of data formats, accessibility +support, multilingual support and the desire for issuers to brand their +credentials. +- The use of JSON-LD could provide some of the required capabilities covered by +OCA (such as multilingual labels), but that solution requires adding +considerable overhead and far more complicated processing to achieve a minimum +of the capabilities available through OCA. +- The current situation of having almost no metadata about credentials is +extremely limiting. + - Extracting best available metadata from the Schema and Credential Definition + objects, converting developer attribute/credential names of human friendly + (e.g. "given_name" to Given Name, or "ssn" to "Ssn") and using that for the + display of a credential. + - The random generation of a background color for a given credential for use + when displaying a credential. +- There are other flows that could be used to get an OCA Bundle to holders and +verifiers. + - A publisher of a schema might also publish an OCA Bundle based on the +schema, for anyone to use. + - An Aries agent vendor (such as the creator of an Aries mobile wallet) might +create a repository of OCA Bundles of common credential types for deployments of +their agent. + - When using such alternatives, agents retrieving an OCA Bundle should have a +way to verify the source of the OCA Bundle, such as having a cryptographic +signature over the OCA Bundle from the designated publisher. + +## Prior art + +None, as far as we are aware. + +## Unresolved questions + +- Are there better ways for issuers to publish OCA Bundles for consumption by + holders/verifiers? +- How do we balance the prevention of possible tracking by issuers, and the use + of links to OCA Bundles or assets within OCA Bundles. + +## 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](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | diff --git a/features/0755-oca-for-aries/assets/Sample-use-of-Branding-Overlay.png b/features/0755-oca-for-aries/assets/Sample-use-of-Branding-Overlay.png new file mode 100644 index 000000000..d1242b65b Binary files /dev/null and b/features/0755-oca-for-aries/assets/Sample-use-of-Branding-Overlay.png differ diff --git a/features/0755-oca-for-aries/assets/bifold-oca-example.jpg b/features/0755-oca-for-aries/assets/bifold-oca-example.jpg new file mode 100644 index 000000000..a2020578b Binary files /dev/null and b/features/0755-oca-for-aries/assets/bifold-oca-example.jpg differ diff --git a/features/0755-oca-for-aries/best-bc-background-image-slice.png b/features/0755-oca-for-aries/best-bc-background-image-slice.png new file mode 100644 index 000000000..babf3ec3b Binary files /dev/null and b/features/0755-oca-for-aries/best-bc-background-image-slice.png differ diff --git a/features/0755-oca-for-aries/best-bc-background-image.jpg b/features/0755-oca-for-aries/best-bc-background-image.jpg new file mode 100644 index 000000000..1a7c484fc Binary files /dev/null and b/features/0755-oca-for-aries/best-bc-background-image.jpg differ diff --git a/features/0755-oca-for-aries/best-bc-logo.png b/features/0755-oca-for-aries/best-bc-logo.png new file mode 100644 index 000000000..883a43412 Binary files /dev/null and b/features/0755-oca-for-aries/best-bc-logo.png differ diff --git a/features/0755-oca-for-aries/branding.json b/features/0755-oca-for-aries/branding.json new file mode 100644 index 000000000..c2e06b409 --- /dev/null +++ b/features/0755-oca-for-aries/branding.json @@ -0,0 +1,15 @@ +[ + { + "logo": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/0755-oca-for-aries/best-bc-logo.png", + "background_image_slice": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/best-bc-background-image-slice.png", + "background_image": "https://raw.githubusercontent.com/swcurran/aries-rfcs/oca4aries/features/best-bc-background-image.png", + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "description": "", + "digest": "EBQbQEV6qSEGDzGLj1CqT4e6yzESjPimF-Swmyltw5jU", + "expiry_date_attribute": "expiry_date_dateint", + "name": "", + "primary_attribute": "family_name", + "secondary_attribute": "given_names", + "type": "aries/overlays/branding/1.0" + } +] \ No newline at end of file diff --git a/features/0755-oca-for-aries/sample_oca_for_aries_oca_bundle.json b/features/0755-oca-for-aries/sample_oca_for_aries_oca_bundle.json new file mode 100644 index 000000000..940ad9870 --- /dev/null +++ b/features/0755-oca-for-aries/sample_oca_for_aries_oca_bundle.json @@ -0,0 +1,223 @@ +[ + { + "capture_base": { + "attributes": { + "birthdate_dateint": "DateTime", + "country": "Text", + "expiry_date_dateint": "DateTime", + "family_name": "Text", + "given_names": "Text", + "issuing_jurisdiction": "Text", + "locality": "Text", + "picture": "Binary", + "postal_code": "Text", + "region": "Text", + "street_address": "Text" + }, + "classification": "", + "digest": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "flagged_attributes": [ + "given_names", + "family_name", + "birthdate_dateint", + "street_address", + "locality", + "region", + "postal_code", + "country", + "picture", + "expiry_date_dateint" + ], + "type": "spec/capture_base/1.0" + }, + "overlays": [ + { + "attribute_character_encoding": { + "birthdate_dateint": "utf-8", + "country": "utf-8", + "expiry_date_dateint": "utf-8", + "family_name": "utf-8", + "given_names": "utf-8", + "issuing_jurisdiction": "utf-8", + "locality": "utf-8", + "picture": "base64", + "postal_code": "utf-8", + "region": "utf-8", + "street_address": "utf-8" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "default_character_encoding": "utf-8", + "digest": "Ek-rB1QH1LWWFp21WtxjO-eaCzIHm1jL3QTXqTc5CYiQ", + "type": "spec/overlays/character_encoding/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date de naissance", + "country": "Pays", + "expiry_date_dateint": "Date d'expiration", + "family_name": "Nom de famille", + "given_names": "Prénoms", + "issuing_jurisdiction": "Autorité de délivrance", + "locality": "Localité", + "picture": "Photo (si délivrée)", + "postal_code": "Code postal", + "region": "Région", + "street_address": "Adresse municipale" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "E-8GcJ-wUUkea3cYV-7jzVNYV2Lb9gkAbfmQzmxCPyQU", + "language": "fr-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "La date de naissance de la personne", + "country": "Le code du pays de l'adresse de la personne", + "expiry_date_dateint": "La date d'expiration de ce/cette [justificatif / pièce d'identité].", + "family_name": "Le nom de famille légal de la personne", + "given_names": "Le ou les prénoms légaux de la personne", + "issuing_jurisdiction": "L'autorité (province, territoire ou fédéral) qui a délivré ce/cette [justificatif / pièce d'identité]", + "locality": "Le nom de la ville ou de la localité de l'adresse de la personne", + "picture": "Une photo vérifiée de la personne (si délivrée)", + "postal_code": "Le code postal de l'adresse de la personne", + "region": "Pour les adresses canadiennes, la province ou le territoire de l'adresse de la personne. Pour les autres pays, l’indicatif régional de l'adresse de la personne", + "street_address": "L'adresse complète de la personne, sans la localité, la région et le code postal" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EPukcZklEiGw87fzn2WD6o7mgDcM-wVvTs327JMLnT_s", + "language": "fr-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_categories": [], + "attribute_labels": { + "birthdate_dateint": "Date of Birth", + "country": "Country", + "expiry_date_dateint": "Expiry Date", + "family_name": "Family Name", + "given_names": "Given Names", + "issuing_jurisdiction": "Issuing Jurisdiction", + "locality": "Locality", + "picture": "Photo (if issued)", + "postal_code": "Postal Code", + "region": "Region", + "street_address": "Street Address" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "category_labels": {}, + "digest": "EZlM7u7Waz53UZQqWnbK1t11PC_sLBaV03esGRg9EvP8", + "language": "en-CA", + "type": "spec/overlays/label/1.0" + }, + { + "attribute_information": { + "birthdate_dateint": "The date of birth of the person", + "country": "The country code of the person's address", + "expiry_date_dateint": "The expiry date of this [credential / ID]", + "family_name": "The legal family name of the person", + "given_names": "The legal first name(s) of the person", + "issuing_jurisdiction": "The jurisdiction (province, territory, or federal) that issued this [credential / ID]", + "locality": "The city name or locality name of the person's address", + "picture": "A verified photo of the person (if issued)", + "postal_code": "The postal code of the person's address", + "region": "For Canadian addresses, the province or territory of the person's address. For other countries, the regional code of the person's address.", + "street_address": "The full address of the person, excluding locality, region, and postal code" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EgbEwEyKPpfkzJyb4TKHUfRKUpY-EuvJEQxDPSIg-PeU", + "language": "en-CA", + "type": "spec/overlays/information/1.0" + }, + { + "attribute_formats": { + "birthdate_dateint": "dateint", + "expiry_date_dateint": "dateint", + "picture": "image/jpeg" + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EpLFl6BPqESrirpFvZD4WmWs12B0nktGH5haGY68lGYY", + "type": "spec/overlays/format/1.0" + }, + { + "attribute_entry_codes": { + "issuing_jurisdiction": [ + "BC", + "ON", + "QC" + ] + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "E8C3mJfLUPM0tasawt7FeuhiTvxQ7QDPaGBRCEpKfvJU", + "type": "spec/overlays/entry_code/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "Colombie-Britannique", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "EDeOfI580ee7MDfRriE9FxMoY0VDOOvsRyXEafw_yL0Y", + "language": "fr-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "attribute_entries": { + "issuing_jurisdiction": { + "BC": "British Columbia", + "ON": "Ontario", + "QC": "Québec" + } + }, + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "digest": "Ej5eE3PhtzglfUMIO9-cmPWYnZcgk7Q9kQG4RuqPY4I8", + "language": "en-CA", + "type": "spec/overlays/entry/1.0" + }, + { + "background_image": "data:image/png;base64,iVBORw...", + "background_image_slide": "data:image/png;base64,iVBORw...", + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "description": "", + "digest": "E1nQd76Qx7LLbmqG0ZO--0IccL5xozK4_-J5oYLvSpNA", + "logo": "data:image/png;base64,iVBORw...", + "name": "", + "primary_attribute": "family_name", + "primary_background_color": "#2E86C1", + "secondary_attribute": "given_name", + "secondary_background_color": "#2E86C1", + "type": "aries/overlays/branding/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Exemple de texte d'aide sur les informations d'identification.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "Schéma canadien utilisé pour l'identité d'une personne", + "digest": "EboSiMc4qQKjoRKkQuBiBZbDoZxnP4XLn7yaY6NDHOGA", + "issuer": "Gouvernement de la Colombie-Britannique", + "issuer_description": "Gouvernement de la Colombie-Britannique", + "issuer_url": "https://www.gov.bc.ca/", + "language": "fr-CA", + "name": "Informations d'identification de la personne", + "type": "spec/overlays/meta/1.0" + }, + { + "capture_base": "EKpcSmz06sJs0b4g24e0Jc7OerbJrGN2iMVEnwLYKBS8", + "credential_help_text": "Example credential help text.", + "credential_support_url": "https://www.gov.bc.ca/", + "description": "A Canadian schema used for the identity of a person", + "digest": "EhGmnV8_T-Gw646j8r8kI2RHRVv6Znx8XrOPFKoLnRR8", + "issuer": "Government of British Columbia", + "issuer_description": "Government of British Columbia", + "issuer_url": "https://www.gov.bc.ca/", + "language": "en-CA", + "name": "Person Credential", + "type": "spec/overlays/meta/1.0" + } + ] + } +] \ No newline at end of file diff --git a/features/0756-oca-for-aries-style-guide/README.md b/features/0756-oca-for-aries-style-guide/README.md new file mode 100644 index 000000000..dc1dc2e07 --- /dev/null +++ b/features/0756-oca-for-aries-style-guide/README.md @@ -0,0 +1,585 @@ +# 0756: OCA for Aries Style Guide + +- Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2023-01-05 +- Status Note: Implemented in the [Bifold Wallet](https://github.com/openwallet-foundation/bifold-wallet) +- Supersedes: N/A +- Start Date: 2022-11-15 +- Version: 1.0 +- Tags: [feature](/tags.md#feature) + +[RFC0755 OCA for Aries]: ../0755-oca-for-aries/README.md + +## Summary + +Support for credential branding in Aries agents is provided by information +provided from the issuer of a given credential type using Overlays Capture +Architecture (OCA) overlays. Aries agents (software) use the issuer-provided OCA +data when displaying (rendering) the issuer’s credential on screens. This style +guide is for issuers to know what information to include in the OCA overlays and +how those elements will be used by holders and verifiers. The style guide is +also for Aries holder and verifier software makers about how to use the OCA data +provided from issuers for a given credential type. It is up to the software +makers to use OCA data provided by the issuers as outlined in this guide. + +For more information about the use of OCA in Aries, please see [RFC0755 OCA for +Aries] + +## Motivation + +OCA Bundles is intended to be used by ALL Aries issuers and ALL Aries Holders. Some +Aries verifiers might also use OCA Bundles. This Style Guide provides guidance for +issuers about what overlays to populate and with what information, and guidance +for holders (and verifiers) about how to use the OCA Bundle data provided by the +issuers when rendering Credentials on screen. + +* Issuers **SHOULD** follow this Style Guide in preparing an OCA Bundle for each + credential type they issue. Holders (and verifiers) **expect** issuers to follow + the guidance provided in this RFC. +* Holder creators (and verifiers) **SHOULD** follow this Style Guide in + rendering credentials for users. Issuers **expect** holders (and verifiers) to + follow the guidance provided in this RFC. + +Issuers, holders and verifiers expect other issuers, holders and verifiers to +follow this Style Guide. Issuers, holders and verifiers not following this Style +Guide will likely cause end users to see unpredictable and potential +"unfriendly" results when credentials are displayed. + +It is in the best interest of the Aries community as a whole for those writing +Aries agent software to use OCA Bundles and to follow this Style Guide in +displaying credentials. + +## Tutorial + +Before reviewing this Style Guide, please review and be familiar with [RFC0755 +OCA for Aries]. It provides the technical details about OCA, the issuer role in +creating an OCA Bundle and delivering to holders (and optionally, from holders +to verifiers) and the holders role in extracting information from the OCA Bundle +about a held credential. This Style Guide provides the details about what each +participant is expected to do in creating OCA Bundles and using the data in OCA +Bundles to render credentials on screen. + + + + + + + + + + +## OCA for Aries Style Guide + +A Credential User Interface (UI) pulls from a issuer-provided OCA Bundle the following elements: + + + +* **Meta Overlays (multilingual):** + * Credential name + * Issuer name + * Issuer description + * Issuer URL + * Credential help text + * Credential support URL + * Non-Production watermark +* **“branding” Overlay:** + * **_logo_** - a URI for an inline or external logo image to display with the credential. See details below about the use and requirements for the image. + * **_background_image_** - a URI for an inline or external background image to display with the credential. See details below about the use and requirements for the image. + * **_background_image_slice_** - a URI for an inline or external background image slice to display with the credential. See details below about the use and requirements for the image. + * **_primary_background_color_** - an RGB color code for the credential background + * **_secondary_background_color_** - an RGB color code for the credential background highlight background color. + * **_primary_attribute_** - the name of the primary capture base attribute to display \ +on the credential. + * **_secondary_attribute_** - the name of the secondary capture base attribute to \ +display on the credential. + * **_issued_date_attribute_** - the name of a capture base attribute that is the date of issuance of the credential. If there is no such attribute, leave it blank. + * **_expiry_date_attribute_** - the name of a capture base attribute that is the expiry date of the credential. If there is no such attribute, leave it blank. + + +### Credential Layouts + +This style guide defines three layouts for credentials, the credential list layout, the stacked list layout, and the single credential layout. Holders and verifiers SHOULD display credentials using only these layouts in the context of a screen containing either a list of credentials or a single credential, respectively. Holders and verifiers MAY display other relevant information on the page along with one of the layouts. + +The stacked list is the same as the credential layout, with the credentials that are stacked cutoff between elements 6 and 7. Examples of the stacked layout can be seen in the [Stacking](#heading=h.27voxgccn7kf) section of this document. In the Stacked layout, one of the credentials in the stack may be displayed using the full credential list layout. + + + + + + + + + + + +
+alt_text + + +alt_text + +
Credential List Layout + Single Credential Layout +
+ + +**_Figure: Credential Layouts_** + +The numbered items in the layouts are as follows. In the list, the OCA data element(s) is provided first, and, where the needed data element(s) is not available through an OCA Bundle, a calculation for a fallback is defined. It is good practice to have code that populates a per credential data structure with data from the credential’s OCA Bundle if available, and if not, populated by the fallbacks. That way, the credentials are displayed in the same way with or without an OCA Bundle per credential. Unless noted, all of the data elements come from the “branding” overlay. Items 10 and 11 are not included in the layouts but are included to document the fallbacks for those values. + + + +1. `logo` + * Fallback: First letter of the alias of the DIDComm connection +2. `background_image_slice` if present, else `secondary_background_color` + * Fallback: Black overlay at 24% opacity +3. `primary_background_color` + * Fallback: Randomly generated color +4. Credential Status derived from revocation status and expiry date (if available) + * Fallback: Empty +5. Meta overlay item `issuer_name` + * Fallback: Alias of the DIDComm connection +6. Meta overlay item `name` + * Fallback: The AnonCreds Credential Definition `tag`, unless the value is either `credential` or `default`, otherwise the AnonCreds `schema_name` attribute from the AnonCreds schema +7. `primary_attribute` + * Fallback: Empty +8. `secondary_attribute` + * Fallback: Empty +9. `background_image` if present, else `secondary_background_color` + * Fallback: Black overlay at 24% opacity (default) +10. `issued_date_attribute` + * Fallback: If tracked, the date the credential was received by the Holder, else empty. +11. `expiry_date_attribute` + * Fallback: Empty + + +![alt_text](images/image3.png "image_tooltip") + + +**_Figure: Template layers_** + +The font color is either black or white, as determined by calculating contrast levels (following [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG2AA-Conformance)) against the background colors from either the OCA Bundle or the generated defaults. + + + + + + + +
+alt_text + + +alt_text + +
+ + +**_Figure: example of a credential with no override specifications_** + + +### Logo Image Specifications + +The image in the top left corner is a space for the issuer logo. This space should not be used for anything other than the issuer logo. The logo image may be masked to fit within a rounded square with varying corner radii. Thus, the logo must be a square image (aspect ratio 1:1), as noted in the table below. The background is default white, therefore logo files with a transparent background will overlay a white background. + +The following are the specifications for the credential logo for issuers. + +Images should be as small as possible to balance quality and download speed. To ensure image quality on all devices, it is recommended to use vector based file types such as SVG. + + + + + + + + + + + + + + + + + + + +
Preferred file type + SVG, JPG, PNG with transparent background, +
Aspect ratio + 1:1 +
Recommended image size + 240x240 px +
Color space + RGB +
+ + + +### Background Image Slice Specifications + +For issuers to better represent their brand, issuers may specify an image slice that will be used as outlined in the samples below. Note the use of the image in a long, narrow space and the dynamic height. The image slice will be top aligned, scaled (preserving aspect ratio) and cropped as needed to fill the space. + +Credential height is dependent on the content and can be unpredictable. Different languages (English, French, etc.) will add more length to names, OS level settings such as font changes or text enlargement will unpredictably change the height of the credential. The recommended image size below is suggested to accommodate for most situations. Note that since the image is top aligned, the top area of the image is certain to be displayed, while the bottom section of the image may not always be visible. + + +![alt_text](images/image6.jpg "image_tooltip") + + +**_Figure: Examples of the image slice behavior_** + +Types of images best used in this area are abstract images or graphical art. Do not use images that are difficult to interpret when cropped. + + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use an abstract image that can work even when cropped unexpectedly. +

Don’t +

+Use images that are hard to interpret when cropped. Avoid words +

+ + +**_Figure: Background image slice Do’s and Don’ts_** + + + + + + + + + + + + + + + + + + + +
Preferred file type + SVG, PNG, JPG +
Aspect ratio + 1:10 +
Recommended image size + 120x1200 px +
Color space + RGB +
+ + + +### Background Image Specifications + +The background image is to give issuers more opportunities to represent their brand and is used in some credential display screens. Avoid text in the background image. + + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use an image that represents your brand. +

Don’t +

+Use this image as a marketing platform. Avoid the use of text. +

+ + +**_Figure: Background image Do’s and Don’ts_** + + + + + + + + + + + + + + + + + + + +
Preferred file type + SVG, PNG, JPG +
Aspect ratio + 3:1 +
Recommended image size + 1080x360 px +
Color space + RGB +
+ + + +### Credential Status + +To reduce visual clutter, the issued date (if present), expiry date (if present), and revocation status (if applicable) may be interpreted by an icon at the top right corner when: + + + +* A new credential has been added, based on _issued_date_attribute_, if set, or for a holder agent/wallet, the date the credential was received. +* A credential is revoked, if the credential is revocable and is known to have been revoked. +* A credential is expiring soon or expired, based on _expiry_date_attribute_, if set. + + +![alt_text](images/image11.png "image_tooltip") + + +**_Figure: An example demonstrating how the revocation date, expiry date or issued date may be represented._** + +The interpretation of the issued date, expiry date and revocation status may be dependent on the holder software, such as a wallet. For example, the specific icons used may vary by wallet, or the full status data may be printed over the credential. + + +### Credential name and Issuer name guidelines + +Issuers should be mindful of the length of text on the credential as lengthy text will dynamically change the height of the credential. Expansive credentials risk reducing the number of fully visible credentials in a list. + + + +![alt_text](images/image12.png "image_tooltip") + + +**_Figure: An example demonstrating how lengthy credentials can limit the number of visible credentials._** + +Be mindful of other factors that may increase the length of text and hence, the height of the credential such as translated languages or the font size configured at the OS level. + + +![alt_text](images/image13.png "image_tooltip") + + +**_Figure: Examples showing the treatment of lengthy names_** + + +### Primary and Secondary Attribute Guidelines + +If issuers expect people to hold multiples of their credentials of the same type, they may want to specify a primary and secondary attribute to display on the card face. + +Note that wallet builders or holders may limit the visibility of the primary and secondary attributes on the card face to mitigate privacy concerns. Issuers can expect that these attributes may be fully visible, redacted, or hidden. + +To limit personal information from being displayed on a card face, only specify what is absolutely necessary for wallet holders to differentiate between credentials of the same type. Do not display private information such as medical related attributes. + + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use attributes that help users identify their credentials. Always consider if a primary and secondary attribute is absolutely necessary. +

Don’t +

+Display attributes that contain private information. +

+ + +**_Figure: Primary/secondary attribute Do’s and Don’ts_** + + +### Non-production watermark + +To identify non-production credentials, issuers can add a watermark to their credentials. The watermark is a simple line of text that can be customized depending on the issuer needs. The line of text will also appear as a prefix to the credential name. The line of text should be succinct to ensure legibility. This watermark is not intended to be used for any other purpose than to mark non-production credentials. Ensure proper localization to the watermark is present in all languages. + +Example text include: + + + +* DEMO +* SAMPLE +* NON-PRODUCTION +* TEST +* DEVELOPMENT +* DO NOT USE + + + + + + + + + + +
+ +alt_text + + +alt_text + +
Do +

+Use succinct words to describe the type of issued credential. This ensures legibility and does not increase the size of the credential unnecessarily. +

Don’t +

+Use long works or words that do not describe non-production credentials. +

+ + + +### Credential resizing + +Credential size depends on the content of the credential and the size of the device. Text areas are resized according to the width. + + +![alt_text](images/image18.png "image_tooltip") + + +**_Figure: Treatment of the credential template on different devices_** + + +![alt_text](images/image19.png "image_tooltip") + + +**_Figure: An example of credential on different devices_** + + +### Stacking + +Credentials may be stacked to overlap each other to increase the number of visible credentials in the viewport. The header remains unchanged. The issuer name, logo and credential name will always be visible but the primary and secondary attributes and the image slice will be obscured. + + +![alt_text](images/image20.png "image_tooltip") + + +**_Figure: An example of stacked credentials with default and enlarged text._** + + +### Accessibility + +The alt-tags for the logo and background images come from the multilingual OCA Meta Overlay for the issuer name and credential type name. + + +### More Variations + +To view more credential variations using this template, [view the Adobe XD file](https://xd.adobe.com/view/045a1969-719a-4aa5-848f-637ef1b7051a-5109/). + + + +## Drawbacks + +Defining and requesting adherence to a style guide is a lofty goal. With so many +independent issuers, holders and verifiers using Aries, it is a challenge +to get everyone to agree on a single way to display credentials for users. However, +the alternative of everyone "doing their own thing", perhaps in small groups, will +result in a poor experience for users, and be frustrating to both issuers trying +to convey their brand, and holders (and verifiers) trying to create a beautiful +experience for their users. + +## Rationale and alternatives + +In coming up with this Style Guide, we consider how much control to give +issuers, ultimately deciding that given them too much control (e.g., pixel +precise layout of their credential) creates a usage/privacy risk (people using +their credentials by showing them on screen, with all private data showing), is +technical extremely difficult given the variations of holder devices, and likely +to result in a very poor user experience. + +A user experience group in Canada came up with the core design, and the Aries +Working Group reviewed and approved of the Style Guide. + +## Prior art + +The basic concept of giving issuers a small set of parameters that they could +control in branding of their data is used in many applications and communities. +Relevant to the credential use case is the application of this concept in the +Apple Wallet and Google Wallet. Core to this is the setting of expectations of +all of the participants of how their data will be used, and how to use the data +provided. In the Aries holder (and verifier) case, unlike that of the Apple +Wallet and Google Wallet, is that there is not just one holder that is using the +data from many issuers to render the data on screen, but many holders that are +expected to adhere to this Style Guide. + +## Unresolved questions + +- A challenge will be in evolving this Style Guide based on new input from those +that use it over time. We expect the Aries RFC version process to be sufficient. +However, this is the first time that this process has been applied to a user +experience "protocol", as opposed to a technical, messaging protocol. + +## 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](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | diff --git a/features/0756-oca-for-aries-style-guide/images/image1.png b/features/0756-oca-for-aries-style-guide/images/image1.png new file mode 100644 index 000000000..073dfea64 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image10.png b/features/0756-oca-for-aries-style-guide/images/image10.png new file mode 100644 index 000000000..da6c3f5f8 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image10.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image11.png b/features/0756-oca-for-aries-style-guide/images/image11.png new file mode 100644 index 000000000..ddcbbae39 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image11.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image12.png b/features/0756-oca-for-aries-style-guide/images/image12.png new file mode 100644 index 000000000..eff7f3e98 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image12.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image13.png b/features/0756-oca-for-aries-style-guide/images/image13.png new file mode 100644 index 000000000..ddbedd9e9 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image13.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image14.png b/features/0756-oca-for-aries-style-guide/images/image14.png new file mode 100644 index 000000000..26169aeb7 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image14.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image15.png b/features/0756-oca-for-aries-style-guide/images/image15.png new file mode 100644 index 000000000..5376619d4 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image15.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image16.png b/features/0756-oca-for-aries-style-guide/images/image16.png new file mode 100644 index 000000000..b6f6e9319 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image16.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image17.png b/features/0756-oca-for-aries-style-guide/images/image17.png new file mode 100644 index 000000000..f28f00725 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image17.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image18.png b/features/0756-oca-for-aries-style-guide/images/image18.png new file mode 100644 index 000000000..72cd9dc4c Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image18.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image19.png b/features/0756-oca-for-aries-style-guide/images/image19.png new file mode 100644 index 000000000..945c8b919 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image19.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image2.png b/features/0756-oca-for-aries-style-guide/images/image2.png new file mode 100644 index 000000000..6e8d5c746 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image2.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image20.png b/features/0756-oca-for-aries-style-guide/images/image20.png new file mode 100644 index 000000000..ab86d9219 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image20.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image3.png b/features/0756-oca-for-aries-style-guide/images/image3.png new file mode 100644 index 000000000..d1242b65b Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image3.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image4.png b/features/0756-oca-for-aries-style-guide/images/image4.png new file mode 100644 index 000000000..38b7378a9 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image4.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image5.png b/features/0756-oca-for-aries-style-guide/images/image5.png new file mode 100644 index 000000000..bc440e866 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image5.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image6.jpg b/features/0756-oca-for-aries-style-guide/images/image6.jpg new file mode 100644 index 000000000..6d215de9d Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image6.jpg differ diff --git a/features/0756-oca-for-aries-style-guide/images/image7.png b/features/0756-oca-for-aries-style-guide/images/image7.png new file mode 100644 index 000000000..aa863ba6e Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image7.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image8.png b/features/0756-oca-for-aries-style-guide/images/image8.png new file mode 100644 index 000000000..f7270510b Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image8.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image9.png b/features/0756-oca-for-aries-style-guide/images/image9.png new file mode 100644 index 000000000..10dff8021 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image9.png differ diff --git a/features/0771-anoncreds-attachments/README.md b/features/0771-anoncreds-attachments/README.md new file mode 100644 index 000000000..ea3318964 --- /dev/null +++ b/features/0771-anoncreds-attachments/README.md @@ -0,0 +1,341 @@ +# Aries RFC 0771: AnonCreds Attachment Formats for Requesting and Presenting Credentials + +- Authors: [Timo Glastra](mailto:timo@animo.id), [Daniel Hardman](mailto:daniel.hardman@gmail.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2023-02-24 +- Status Note: Formalizes the AnonCreds attachments for issuing credentials and presenting proofs over DIDComm. +- Supersedes: Hyperledger Indy specific AnonCreds attachment formats documented in [Aries RFC 0592](../0592-indy-attachments/README.md). +- Start Date: 2023-02-24 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol), [credentials](/tags.md#credentials), [test-anomaly](/tags.md#test-anomaly) + +## Summary + +This RFC registers attachment formats used with [Hyperledger AnonCreds](https://hyperledger.github.io/anoncreds-spec/) ZKP-oriented credentials in the [Issue Credential Protocol 2.0](../0453-issue-credential-v2/README.md) and [Present Proof Protocol 2.0](../0454-present-proof-v2/README.md). If not specified otherwise, this follows the rules as defined in the [AnonCreds Specification](https://hyperledger.github.io/anoncreds-spec/). + +## Motivation + +Allows AnonCreds credentials to be used with credential-related protocols that take pluggable formats as payloads. + +## Reference + +### Credential Filter format + +The potential holder uses this format to propose criteria for a potential credential for the issuer to offer. The format defined here is not part of the AnonCreds spec, but is a Hyperledger Aries-specific message. + +The identifier for this format is `anoncreds/credential-filter@v1.0`. The data structure allows specifying zero or more criteria from the following structure: + +```jsonc +{ + "schema_issuer_id": "", + "schema_name": "", + "schema_version": "", + "schema_id": "", + "issuer_id": "", + "cred_def_id": "" +} +``` + +The potential holder may not know, and need not specify, all of these criteria. For example, the holder might only know the schema name and the (credential) issuer id. Recall that the potential holder may specify target attribute values and MIME types in the [credential preview](../0453-issue-credential-v2/README.md#preview-credential). + +For example, the JSON structure might look like this: + +```json +{ + "schema_issuer_id": "did:sov:4RW6QK2HZhHxa2tg7t1jqt", + "schema_name": "bcgov-mines-act-permit.bcgov-mines-permitting", + "issuer_id": "did:sov:4RW6QK2HZhHxa2tg7t1jqt" +} +``` + +A complete [`propose-credential` message from the Issue Credential protocol 2.0](../0453-issue-credential-v2/README.md#propose-credential) embeds this format as an attachment in the `filters~attach` array: + +```json +{ + "@id": "", + "@type": "https://didcomm.org/issue-credential/%VER/propose-credential", + "comment": "", + "formats": [ + { + "attach_id": "", + "format": "anoncreds/credential-filter@v1.0" + } + ], + "filters~attach": [ + { + "@id": "", + "mime-type": "application/json", + "data": { + "base64": "ewogICAgInNjaGVtYV9pc3N1ZXJfZGlkIjogImRpZDpzb3Y... (clipped)... LMkhaaEh4YTJ0Zzd0MWpxdCIKfQ==" + } + } + ] +} +``` + +### Credential Offer format + +This format is used to clarify the structure and semantics (but not the concrete data values) of a potential credential, in offers sent from issuer to potential holder. + +The identifier for this format is `anoncreds/credential-offer@v1.0`. It must follow the [structure of a Credential Offer](https://hyperledger.github.io/anoncreds-spec/#credential-offer) as defined in the AnonCreds specification. + +The JSON structure might look like this: + +```json +{ + "schema_id": "4RW6QK2HZhHxa2tg7t1jqt:2:bcgov-mines-act-permit.bcgov-mines-permitting:0.2.0", + "cred_def_id": "4RW6QK2HZhHxa2tg7t1jqt:3:CL:58160:default", + "nonce": "57a62300-fbe2-4f08-ace0-6c329c5210e1", + "key_correctness_proof" : +} +``` + +A complete [`offer-credential` message from the Issue Credential protocol 2.0](../0453-issue-credential-v2/README.md#offer-credential) embeds this format as an attachment in the `offers~attach` array: + +```json +{ + "@type": "https://didcomm.org/issue-credential/%VER/offer-credential", + "@id": "", + "replacement_id": "", + "comment": "", + "credential_preview": , + "formats" : [ + { + "attach_id" : "", + "format": "anoncreds/credential-offer@v1.0" + } + ], + "offers~attach": [ + { + "@id": "", + "mime-type": "application/json", + "data": { + "base64": "ewogICAgInNjaGVtYV9pZCI6ICI0Ulc2UUsySFpoS... (clipped)... jb3JyZWN0bmVzc19wcm9vZj4KfQ==" + } + } + ] +} +``` + +### Credential Request format + +This format is used to formally request a credential. It differs from the Credential Offer above in that it contains a cryptographic commitment to a link secret; an issuer can therefore use it to bind a concrete instance of an issued credential to the appropriate holder. (In contrast, the credential offer describes the schema and cred definition, but not enough information to actually issue to a specific holder.) + +The identifier for this format is `anoncreds/credential-request@v1.0`. It must follow the [structure of a Credential Request](https://hyperledger.github.io/anoncreds-spec/#credential-request) as defined in the AnonCreds specification. + +The JSON structure might look like this: + +```jsonc +{ + "entropy" : "e7bc23ad-1ac8-4dbc-92dd-292ec80c7b77", + "cred_def_id" : "4RW6QK2HZhHxa2tg7t1jqt:3:CL:58160:default", + // Fields below can depend on Cred Def type + "blinded_ms" : , + "blinded_ms_correctness_proof" : , + "nonce": "fbe22300-57a6-4f08-ace0-9c5210e16c32" +} +``` + +A complete [`request-credential` message from the Issue Credential protocol 2.0](../0453-issue-credential-v2/README.md#request-credential) embeds this format as an attachment in the `requests~attach` array: + +```json +{ + "@id": "cf3a9301-6d4a-430f-ae02-b4a79ddc9706", + "@type": "https://didcomm.org/issue-credential/%VER/request-credential", + "comment": "", + "formats": [ + { + "attach_id": "7cd11894-838a-45c0-a9ec-13e2d9d125a1", + "format": "anoncreds/credential-request@v1.0" + } + ], + "requests~attach": [ + { + "@id": "7cd11894-838a-45c0-a9ec-13e2d9d125a1", + "mime-type": "application/json", + "data": { + "base64": "ewogICAgInByb3Zlcl9kaWQiIDogImRpZDpzb3Y6YWJjeHl.. (clipped)... DAtNTdhNi00ZjA4LWFjZTAtOWM1MjEwZTE2YzMyIgp9" + } + } + ] +} +``` + +### Credential format + +A concrete, issued AnonCreds credential may be transmitted over many protocols, but is specifically expected as the final message in [Issuance Protocol 2.0](../0453-issue-credential-v2/README.md). The identifier for this format is `anoncreds/credential@v1.0`. + +This is a credential that's designed to be _held_ but not _shared directly_. It is stored in the holder's wallet and used to [derive a novel ZKP](https://youtu.be/bnbNtjsKb4k?t=1280) or [W3C-compatible verifiable presentation](https://docs.google.com/document/d/1ntLZGMah8iJ_TWQdbrNNW9OVwPbIWkkCMiid7Be1PrA/edit#heading=h.vw0mboesl528) just in time for each sharing of credential material. + +The encoded values of the credential MUST follow the encoding algorithm as described in [Encoding Attribute Data](https://hyperledger.github.io/anoncreds-spec/#encoding-attribute-data). It must follow the [structure of a Credential](https://hyperledger.github.io/anoncreds-spec/#constructing-a-credential) as defined in the AnonCreds specification. + +The JSON structure might look like this: + +```jsonc +{ + "schema_id": "4RW6QK2HZhHxa2tg7t1jqt:2:bcgov-mines-act-permit.bcgov-mines-permitting:0.2.0", + "cred_def_id": "4RW6QK2HZhHxa2tg7t1jqt:3:CL:58160:default", + "rev_reg_id", "EyN78DDGHyok8qw6W96UBY:4:EyN78DDGHyok8qw6W96UBY:3:CL:56389:CardossierOrgPerson:CL_ACCUM:1-1000", + "values": { + "attr1" : {"raw": "value1", "encoded": "value1_as_int" }, + "attr2" : {"raw": "value2", "encoded": "value2_as_int" } + }, + // Fields below can depend on Cred Def type + "signature": , + "signature_correctness_proof": + "rev_reg": + "witness": +} +``` + +An exhaustive description of the format is out of scope here; it is more completely documented in the [AnonCreds Specification](https://hyperledger.github.io/anoncreds-spec). + +### Proof Request format + +This format is used to formally request a verifiable presenation (proof) derived from an AnonCreds-style ZKP-oriented credential. + +The format can also be used to _propose_ a presentation, in this case the `nonce` field MUST NOT be provided. The `nonce` field is required when the proof request is used to request a proof. + +The identifier for this format is `anoncreds/proof-request@v1.0`. It must follow the [structure of a Proof](https://hyperledger.github.io/anoncreds-spec/#create-presentation-request) as defined in the AnonCreds specification. + +Here is a sample proof request that embodies the following: "Using a government-issued ID, disclose the credential holder’s name and height, hide the credential holder’s sex, get them to self-attest their phone number, and prove that their age is at least 18": + +```jsonc +{ + "nonce": "2934823091873049823740198370q23984710239847", + "name":"proof_req_1", + "version":"0.1", + "requested_attributes":{ + "attr1_referent": {"name":"sex"}, + "attr2_referent": {"name":"phone"}, + "attr3_referent": {"names": ["name", "height"], "restrictions": } + }, + "requested_predicates":{ + "predicate1_referent":{"name":"age","p_type":">=","p_value":18} + } +} +``` + +### Proof format + +This is the format of an AnonCreds-style ZKP. The raw values encoded in the presentation MUST be verified against the encoded values using the encoding algorithm as described in [Encoding Attribute Data](https://hyperledger.github.io/anoncreds-spec/#encoding-attribute-data) + +The identifier for this format is `anoncreds/proof@v1.0`. It must follow the [structure of a Presentation](https://hyperledger.github.io/anoncreds-spec/#generate-presentation) as defined in the AnonCreds specification. + +A proof that responds to the [previous proof request sample](#proof-request-format) looks like this: + +```jsonc +{ + "proof":{ + "proofs":[ + { + "primary_proof":{ + "eq_proof":{ + "revealed_attrs":{ + "height":"175", + "name":"1139481716457488690172217916278103335" + }, + "a_prime":"5817705...096889", + "e":"1270938...756380", + "v":"1138...39984052", + "m":{ + "master_secret":"375275...0939395", + "sex":"3511483...897083518", + "age":"13430...63372249" + }, + "m2":"1444497...2278453" + }, + "ge_proofs":[ + { + "u":{ + "1":"152500...3999140", + "2":"147748...2005753", + "0":"8806...77968", + "3":"10403...8538260" + }, + "r":{ + "2":"15706...781609", + "3":"343...4378642", + "0":"59003...702140", + "DELTA":"9607...28201020", + "1":"180097...96766" + }, + "mj":"134300...249", + "alpha":"827896...52261", + "t":{ + "2":"7132...47794", + "3":"38051...27372", + "DELTA":"68025...508719", + "1":"32924...41082", + "0":"74906...07857" + }, + "predicate":{ + "attr_name":"age", + "p_type":"GE", + "value":18 + } + } + ] + }, + "non_revoc_proof":null + } + ], + "aggregated_proof":{ + "c_hash":"108743...92564", + "c_list":[ 6 arrays of 257 numbers between 0 and 255] + } + }, + "requested_proof":{ + "revealed_attrs":{ + "attr1_referent":{ + "sub_proof_index":0, + "raw":"Alex", + "encoded":"1139481716457488690172217916278103335" + } + }, + "revealed_attr_groups":{ + "attr4_referent":{ + "sub_proof_index":0, + "values":{ + "name":{ + "raw":"Alex", + "encoded":"1139481716457488690172217916278103335" + }, + "height":{ + "raw":"175", + "encoded":"175" + } + } + } + }, + "self_attested_attrs":{ + "attr3_referent":"8-800-300" + }, + "unrevealed_attrs":{ + "attr2_referent":{ + "sub_proof_index":0 + } + }, + "predicates":{ + "predicate1_referent":{ + "sub_proof_index":0 + } + } + }, + "identifiers":[ + { + "schema_id":"NcYxiDXkpYi6ov5FcYDi1e:2:gvt:1.0", + "cred_def_id":"NcYxi...cYDi1e:2:gvt:1.0:TAG_1", + "rev_reg_id":null, + "timestamp":null + } + ] +} +``` + +## 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 | +| ----------- | -------------------- | +| | diff --git a/features/0780-data-urls-images/README.md b/features/0780-data-urls-images/README.md new file mode 100644 index 000000000..b0d307528 --- /dev/null +++ b/features/0780-data-urls-images/README.md @@ -0,0 +1,185 @@ +# RFC 0780: Use Data URLs for Images and More in Credential Attributes + +- Authors: [Stephen Curran](mailto:swcurran@cloudcompass.ca), [Clecio Varjao](mailto:clecio.varjao@gov.bc.ca) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2024-03-02 +- Status Note: Implemented in the [Bifold Wallet](https://github.com/openwallet-foundation/bifold-wallet) +- Supersedes: None +- Start Date: 2023-03-31 +- Tags: [feature](/tags.md#feature) + +## Summary + +Some credentials include attributes that are not simple strings or numbers, such +as images or JSON data structures. When complex data is put in an attribute +the issuer **SHOULD** issue the attribute as a Data URL, as defined in [IETF RFC 2397], and whose use +is described in this [Mozilla Developer Documentation] article. + +[IETF RFC 2397]: https://datatracker.ietf.org/doc/rfc2397/ +[Mozilla Developer Documentation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs + +On receipt of all credentials and presentations, holders and verifiers +**SHOULD** check all string attributes to determine if they are Data URLs. If +so, they **SHOULD** securely process the data according to the metadata +information in the Data URL, including: + +- the [MIME type] of the data (such as `image/png` or `application/json`) +- whether the data is [base64 encoded]. + +[base64 encoded]: https://datatracker.ietf.org/doc/rfc4648/ +[MIME type]: https://www.ucolick.org/~sla/fits/mime/inetstds.html + +This allows, for example, an Aries Mobile Wallet to detect that a data element +is an image and how it is encoded, and display it for the user as an image, +not as a long (long) string of gibberish. + +## Motivation + +Holders and verifiers want to enable a delightful user experience when an issuer +issues attributes that contain other than strings or numbers, such as an +image or a JSON data structure. In such cases, the holder and +verifiers need a way to know the format of the data so it can be processed +appropriately and displayed usefully. While the Aries community encourages the +use of the [Overlays Capture Architecture specification] as outlined +in [RFC 0755 OCA for Aries] for such information, there will be times where an +OCA Bundle is not available for a given credential. In the absence of an OCA Bundle, the holders and verifiers of +such attributes need data type information for processing and displaying the attributes. + +[Overlays Capture Architecture specification]: https://oca.colossi.network/specification/ +[RFC 0755 OCA for Aries]: https://github.com/swcurran/aries-rfcs/blob/oca4aries/features/0755-oca-for-aries/README.md + +## Tutorial + +An issuer wants to issue a verifiable credential that contains an image, such as +a photo of the holder to which the credential is issued. Issuing such an +attribute is typically done by converting the image to a base64 string. This is +handled by the various verifiable credential formats supported by Aries issuers. +The challenge is to convey to the holder and verifiers that the attribute is not +"just another string" that can be displayed on screen to the user. By making the +attribute a Data URL, the holder and verifiers can detect the type and encoding +of the attribute, process it, and display it correctly. + +For example, this image (from the IETF 2793 specification): + +![](photo.png) + +can be issued as the attribute `photo` in a verifiable credential with its value a Data URL as follows: + +```json +{ +"photo": "data:image/png;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAwAAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFzByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSpa/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJlZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uisF81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PHhhx4dbgYKAAA7" +} +``` + +The syntax of a Data URL is described in [IETF RFC 2397]. The \ version is: + +- `data:` -- hardcoded. +- `` -- optional, the [MIME type] of the data. +- `;base64` -- optional, if present, the data is [base64 encoded]. +- `,` -- hardcoded separator. +- `` -- the attribute data in the specified encoding. + +A holder or verifier receiving a credential or presentation **MUST** check +each attribute is a string, and if so, if it is a Data URL (likely by using a +regular expression). If it is a Data URL it should be securely processed +accordingly. + +Aries Data URL verifiable credential attributes **MUST** include the ``. + +### Image Size + +A separate issue from the use of Data URLs is how large an image (or other data +type) can be put into an attribute and issued as a verifiable credential. That +is an issue that is dependent on the verifiable credential implementation and +other factors. For AnonCreds credentials, the attribute will be treated as a +string, a hash will be calculated over the string, and the resulting number will +be signed--just as for any string. The size of the image does not matter. +However, there may be other components in your deployment that might impact how +big an attribute in a credential can be. Many in the community have successfully +experimented with the use of images in credentials, so consulting others on the +question might be helpful. + +For the purpose of this RFC, the amount of data in the attribute is not +relevant. + +### Security + +As noted in this [Mozilla Developer Documentation] and this [Mozilla Security +Blog Post about Data URLs], Data URLs are blocked from being used in the Address +Bar of all major browsers. That is because Data URLs may contain HTML that can +contain anything, including HTML forms that collect data from users. Since Aries +holder and verifier agents are not general purpose content presentation engines +(as are browsers) the use of Data URLs are less of a security risk. Regardless, +holders and verifiers **MUST** limit their processing of attributes containing +Data URLs to displaying the data, and not executing the data. Further, Aries +holders and verifiers **MUST** stay up on dependency vulnerabilities, such as +images constructed to exploit vulnerabilities in libraries that display images. + +[Mozilla Security Blog Post about Data URLs]: https://blog.mozilla.org/security/2017/11/27/blocking-top-level-navigations-data-urls-firefox-59/ + +## Reference + +References for implementing this RFC are: + +- [IETF RFC 2397] +- [Mozilla Developer Documentation] +- [Stack Overflow Article on a Data URL Regex](https://stackoverflow.com/questions/5714281/regex-to-parse-image-data-uri) +- [A GitHub Gist of JavaScript to detect a data URL](https://gist.github.com/bgrins/6194623) + +## Drawbacks + +The Aries community is moving to the use of the [Overlay Capture Architecture +Specification] to provide a more generalized way to accomplish the same thing +(understanding the meaning, format and encoding of attributes), so this RFC is +duplicating a part of that capability. That said, it is easier and faster for +issuers to start using, and for holders and verifiers to detect and use. + +Issuers may choose to issue Data URLs with MIME types not commonly known to +Aries holder and verifier components. In such cases, the holder or verifier +**MUST NOT** display the data. + +Even if the MIME type of the data is known to the holders and verifiers, it may +not be obvious how to present the data on screen in a useful way. For example, +an attribute holding a JSON data structure with an array of values may not +easily be displayed. + +## Rationale and alternatives + +We considered using the same approach as is used in [RFC 0441 Present Proof Best +Practices](../../concepts/0441-present-proof-best-practices/README.md#dates-and-predicates) +of a special suffix (`_img`) for the attribute name in a credential to indicate that +the attribute held an image. However, that provides far less information than this +approach (e.g., what type of image?), and its use is limited to images. This RFC +defines a far more complete, standard, and useful approach. + +As noted in the drawbacks section, this same functionality can (and should) be +achieved with the broad deployment of [Overlay Capture Architecture +Specification] and [RFC 0755 OCA for Aries]. However, the full deployment of +[RFC 0755 OCA for Aries] will take some time, and in the meantime, this is a +"quick and easy" alternate solution that is useful alongside OCA for Aries. + +## Prior art + +In the use cases of which we are aware of issuers putting images and JSON +structures into attributes, there was no indicator of the attribute content, and +the holders and verifiers were assumed to either "know" about the data content +based on the type of credential, or they just displayed the data as a string. + +## Unresolved questions + +Should this RFC define a list (or the location of a list) of MIME types that +Aries issuers can use in credential attributes? + +For supported MIME types that do not have obvious display methods (such as +JSON), should there be a convention for how to display the data? + +## 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](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | + diff --git a/features/0780-data-urls-images/photo.png b/features/0780-data-urls-images/photo.png new file mode 100644 index 000000000..3dc4fc65f Binary files /dev/null and b/features/0780-data-urls-images/photo.png differ diff --git a/features/0793-unqualfied-dids-transition/README.md b/features/0793-unqualfied-dids-transition/README.md new file mode 100644 index 000000000..c5a772413 --- /dev/null +++ b/features/0793-unqualfied-dids-transition/README.md @@ -0,0 +1,105 @@ +# Aries RFC 0793: Unqualified DID Transition + +- Authors: [Sam Curren](mailto:swcurran@cloudcompass.ca) +- Status: [ACCEPTED](/README.md#accepted) +- Since: 2023-07-11 +- Status Note: In Step 1 - **Target Deployment Date: 2024-07-02** +- Supersedes: +- Start Date: 2023-07-11 +- Tags: [feature](/tags.md#feature), [community-update](/tags.md#community-update) + +## Summary + +Historically, Aries use of the Indy SDK's wallet included the use of 'unqualified DIDs' or DIDs without a did: prefix and method. +This transition documents the process of migrating any such DIDs still in use to fully qualified DIDs. + +This process involves the adoption of the Rotate DID protocol and algorithm 4 of the Peer DID Method, then the rotation from the unqualified DIDs to any fully qualified DID, with preference for did:peer:4. + +The adoption of these specs will further prepare the Aries community for adoption of DIDComm v2 by providing an avenue for adding DIDComm v2 compatible endpoints. + +Codebases that do not use unqualified DIDs MUST still adopt DID Rotation and did:peer:4 as part of this process, even if no unqualified DIDs must be rotated. + +This RFC follows the guidance in [RFC +0345](../../concepts/0345-community-coordinated-update/README.md) about +community-coordinated updates to (try to) ensure that independently deployed, +interoperable agents remain interoperable throughout this transition. + +The transition from the unqualified to qualified DIDs will occur in four steps: + +- **Pre-work**: where we agree on the transition plan outlined in this RFC. + - Finalize did:peer:4 details, including feature discovery support of did:peer:4. + - Verify transisiton plan and code. +- **Step 1**: Agent builders MUST update all agent code bases and deployments to support DID Rotation and did:peer:4. + - Each agent builder SHOULD notify the community they have completed Step 1 by submitting a PR to update their entry in the [implementations](#implementations) accordingly. + - Target Date for code update: 2024-05-01 + - Target Date for deployment update: 2024-07-02 +- **Step 2**: Agent builders using unqualified DIDs MUST no longer use new unqualified DIDs, and MUST use DID Rotation to rotate to a fully qualified DID. + - Each agent builder SHOULD notify the community they have completed Step 2 by submitting a PR to update their entry in the [implementations](#implementations) accordingly. + - Target Date for finishing step 2: 2024-11-01 +- **Step 3**: Agent builders SHOULD update their deployments to remove all support for receiving unqualified DIDs from other agents. + +The community coordination triggers between the steps above will be as follows: + +- **Pre-work to Step 1** - a PR to this RFC is merged that sets the RFC status to [ACCEPTED](/README.md#accepted). + - The [ACCEPTED](/README.md#accepted) version of this RFC is included in the current [Aries Interop Profile](/concepts/0302-aries-interop-profile/README.md) version. +- **Step 1 to Step 2** - the community agrees that the majority of the deployed agents have completed Step 1. A PR to this RFC is merged that sets the RFC status to [ADOPTED](/README.md#adopted). + - Agent builders indicate completion of Step 1 by updating the [Implementations](#implementations) section of this RFC. + - All other RFCs in this repo are updated to use the new message type format. + - The [ADOPTED](/README.md#adopted) version of this RFC is included in the current [Aries Interop Profile](/concepts/0302-aries-interop-profile/README.md) version. +- **Step 2 to Step 3** - the community agrees that the majority of the deployed agents have completed Step 2. A PR to this RFC is merged that sets the RFC status to [RETIRED](/README.md#retired). + - Agent builders indicate completion of Step 2 by updating the [Implementations](#implementations) section of this RFC. + +## Motivation + +To enable agent builders to independently update their code bases and deployed agents while maintaining interoperability. + +## Tutorial + +The general mechanism for this type of transition is documented in [RFC 0345](../../concepts/0345-community-coordinated-update/README.md) about +community-coordinated updates. + +The specific sequence of events to make this particular transition is outlined in the [summary](#summary) section of this RFC. + +## Reference + +See the [summary](#summary) section of this RFC for the details of this transition. + +## Drawbacks + +None identified. + +## Rationale and alternatives + +This approach balances the speed of adoption with the need for independent deployment and interoperability. + +## Prior art + +The approach outlined in [RFC +0345](../../concepts/0345-community-coordinated-update/README.md) about +community-coordinated updates is a well-known pattern for using deprecation to +make breaking changes in an ecosystem. That said, this is the first attempt to +use this approach in Aries. Adjustments to the transition plan will be made as needed, and RFC 0345 will be updated based on lessons learned in executing this plan. + +## Unresolved questions + +- Are any changes to existing RFCs needed before starting Step 1? + +## Implementations + +The following table lists the status of various agent code bases and deployments with respect to the steps of this transition. Agent builders MUST update this table as they complete steps of the transition. + +Name / Link | Implementation Notes +--- | --- +[Aries Protocol Test Suite](https://github.com/hyperledger/aries-protocol-test-suite) | No steps completed +[Aries Framework - .NET](https://github.com/hyperledger/aries-framework-dotnet) | No steps completed +[Trinsic.id](https://trinsic.id/) | No steps completed +[Aries Cloud Agent - Python](https://github.com/hyperledger/aries-cloudagent-python) | No steps completed +[Aries Static Agent - Python](https://github.com/hyperledger/aries-staticagent-python) | No steps completed +[Aries Framework - Go](https://github.com/hyperledger/aries-framework-go) | No steps completed +[Connect.Me](https://www.evernym.com/blog/connect-me-sovrin-digital-wallet/) | No steps completed +[Verity](https://www.evernym.com/products/) | No steps completed +[Pico Labs](http://picolabs.io/) | No steps completed +[IBM](https://github.com/IBM-Blockchain-Identity/unknown) | No steps completed +IBM Agent | No steps completed +[Aries Cloud Agent - Pico](https://github.com/Picolab/aries-cloudagent-pico) | No steps completed +[Aries Framework JavaScript](https://github.com/hyperledger/aries-framework-javascript) | No steps completed \ No newline at end of file diff --git a/features/0794-did-rotate/README.md b/features/0794-did-rotate/README.md new file mode 100644 index 000000000..0218fdae2 --- /dev/null +++ b/features/0794-did-rotate/README.md @@ -0,0 +1,147 @@ +# Aries RFC 0794: DID Rotate 1.0 + +- Authors: [Sam Curren](mailto:telegramsam@gmail.com) +- Status: [ACCEPTED](/README.md#accepted) +- Since: 2024-03-02 +- Status Note: Implemented in the [Aries Cloud Agent Python](https://github.com/hyperledger/aries-cloudagent-python) +- Start Date: 2023-08-18 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) +- URI: https://didcomm.org/did-rotate/1.0 + +## Summary + +This protocol signals the change of DID in use between parties. + +This protocol is only applicable to DIDComm v1 - in DIDComm v2 use the more efficient DID Rotation header. + +## Motivation + +This mechanism allows a party in a relationship to change the DID they use to identify themselves in that relationship. This may be used to switch DID methods, +but also to switch to a new DID within the same DID method. For non-updatable DID methods, this allows updating DID Doc attributes such as service endpoints. Inspired by (but different from) the DID rotation feature of the DIDComm Messaging (DIDComm v2) spec. + +## Implications for Software Implementations + +Implementations will need to consider how data (public keys, DIDs and the ID for the relationship) related to the relationship is managed. If the relationship DIDs are used as identifiers, those identifiers may need to be updated during the rotation to maintain data integrity. For example, both parties might have to retain and be able to use as identifiers for the relationship the existing DID and the rotated to DID, and their related keys for a period of time until the rotation is complete. + +## Tutorial + +### Name and Version + +DID Rotate 1.0 + +URI: https://didcomm.org/did-rotate/1.0/ + +### Roles + +**rotating_party**: this party is rotating the DID in use for this relationship. They send the `rotate` message. + +**observing_party**: this party is notified of the DID rotation + +### Messages + +#### Rotate + +Message Type URI: https://didcomm.org/did-rotate/1.0/rotate + +`to_did`: The new DID to be used to identify the **rotating_party** + +```json +{ + "@id": "123456780", + "@type": "https://didcomm.org/did-rotate/1.0/rotate", + "to_did": "did:example:newdid", + +} +``` + +The **rotating_party** is expected to receive messages on both the existing and new DIDs and their associated keys for a reasonable period that MUST extend at least until the following `ack` message has been received. + +This message MUST be sent using AuthCrypt or as a signed message in order to establish the provenance of the new DID. In Aries implementations, messages sent within the context of a relationship are by default sent using AuthCrypt. Proper provenance prevents injection attacks that seek to take over a relationship. Any rotate message received without being authcrypted or signed MUST be discarded and not processed. + +DIDComm v1 uses public keys as the outer message identifiers. This means that rotation to a new DID using the same public key will not result in a change for new inbound messages. The **observing_party** must not assume that the new DID uses the same keys as the existing relationship. + +#### Ack + +Message Type URI: https://didcomm.org/did-rotate/1.0/ack + +This message has been adopted from [the `ack` protocol] +(https://github.com/hyperledger/aries-rfcs/tree/main/features/0015-acks). + +This message is still sent to the prior DID to acknowledge the receipt of the rotation. Following messages will be sent to the new DID. + +In order to correctly process out of order messages, the The **observing_party** may choose to receive messages from the old DID for a reasonable period. This allows messages sent before rotation but received after rotation in the case of out of order message delivery. + +In this message, the `thid` (Thread ID) MUST be included to allow the `rotating_party` to correlate it with the sent `rotate` message. + +```json +{ + "@id": "123456780", + "@type": "https://didcomm.org/did-rotate/1.0/ack", + "~thread" : { + "thid": "" + }, + +} +``` + +#### Problem Report + +Message Type URI: https://didcomm.org/did-rotate/1.0/problem-report + +This message has been adopted from [the `report-problem` protocol] +(https://github.com/hyperledger/aries-rfcs/blob/main/features/0035-report-problem/README.md). + +If the **observing_party** receives a `rotate` message with a DID that they cannot resolve, they MUST return a problem-report message. + +The `description` `code` must be set to one of the following: +- **e.did.unresolvable** - used for a DID who's method is supported, but will not resolve +- **e.did.method_unsupported** - used for a DID method for which the `observing_party` does not support resolution. +- **e.did.doc_unsupported** - used for a DID for which the `observing_party` does not find information sufficient for a DIDComm connection in the resolved DID Document. This would include compatible key types and a DIDComm capable service endpoint. + + +Upon receiving this message, the `rotating_party` must not complete the rotation and resolve the issue. Further rotation attempts must happen in a new thread. + +```json +{ + "@type" : "https://didcomm.org/did-rotate/1.0/problem-report", + "@id" : "an identifier that can be used to discuss this error message", + "~thread" : { + "pthid": "" + }, + "description" : { "en": "DID Unresolvable", "code": "e.did.unresolvable" }, + "problem_items" : [ {"did": ""} ], +} +``` + +#### Hangup + +Message Type URI: https://didcomm.org/did-rotate/1.0/hangup + +This message is sent by the **rotating_party** to inform the **observing_party** that they are done with the relationship and will no longer be responding. + +There is no response message. + +Use of this message does not require or indicate that all data has been deleted by either party, just that interaction has ceased. + +```json +{ + "@id": "123456780", + "@type": "https://didcomm.org/did-rotate/1.0/hangup" +} +``` + +## Prior art + +This protocol is inspired by the rotation feature of DIDComm Messaging (DIDComm v2). The implementation differs in important ways. +The DIDComm v2 method is a _post rotate_ operation: the first message sent AFTER the rotation contains the prior DID and a signature authorizing the rotation. This is efficient, but requires the use of a message header and a higher level of integration with message processing. +This protocol is a _pre rotate_ operation: notifying the other party of the new DID in advance is a less efficient but simpler approach. This was done to minimize adoption pain. The pending move to DIDComm v2 will provide the efficiency. + +## 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](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | diff --git a/features/0804-didcomm-rpc/README.md b/features/0804-didcomm-rpc/README.md new file mode 100644 index 000000000..ea9ed8388 --- /dev/null +++ b/features/0804-didcomm-rpc/README.md @@ -0,0 +1,420 @@ +# 0804: DIDComm Remote Procedure Call (DRPC) + +- Authors: [Clecio Varjao](mailto:clecio.varjao@gov.bc.ca) (BC Gov), [Stephen Curran](mailto:swcurran@cloudcompass.ca) (BC Gov), [Akiff Manji](mailto:amanji@petridish.dev) (BC Gov) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2024-03-02 +- Status Note: Implemented in an [Aries Cloud Agent Python plugin](https://github.com/hyperledger/aries-acapy-plugins), and [Credo TS](https://github.com/openwallet-foundation/credo-ts) +- Supersedes: +- Start Date: 2023-11-29 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol) + +## Summary + +The DIDComm Remote Procedure Call (DRPC) protocol enables a [JSON-RPC]-based +request-response interaction to be carried out across a DIDComm channel. The +protocol is designed to enable custom interactions between connected agents, and +to allow for the rapid prototyping of experimental DIDComm protocols. An agent +sends a DIDComm message to request a [JSON-RPC] service be invoked by another +agent, and gets back the [JSON-RPC]-format response in subsequent DIDComm +message. The protocol enables any request to be conveyed that the other agent +understands. Out of scope of this protocol is how the requesting agent discovers +the services available from the responding agent, and how the two agents know +the semantics of the specified [JSON-RPC] requests and responses. By using +DIDComm between the requesting and responding agents, the security and privacy +benefits of DIDComm are accomplished, and the generic parameters of the requests +allow for flexibility in how and where the protocol can be used. + +[JSON-RPC]: https://www.jsonrpc.org/specification + +## Motivation + +There are several use cases that are driving the initial need for this protocol. + +### App Attestation + +A mobile wallet needs to get an [app attestation] verifiable credential from +the wallet publisher. To do that, the wallet and publisher need to exchange +information specific to to the attestation process with the Google and Apple +stores. The sequence is as follows: + +- The wallet decides (for some reason) it needs an App Attestation credential + from its publisher. +- If not already available, a DIDComm connection between the wallet and the + attestation service is created. +- The wallet uses the DRPC protocol to request a nonce from the service to be + used in the attestation. The service responds with the nonce. +- The wallet uses a new instance of the DRPC protocol to request the attestation + be performed. The service responds with the status of the attestation process. +- The service completes the business process by initiating an Issue Credential + process to issue an attestation verifiable credential. + +The wallet and service are using instances of three protocols (two DRPC and one +Issue Credential) to carry out a full business process. Each participant must +have knowledge of the full business process--there is nothing inherent in the +DRPC protocol about this process, or how it is being used. The DRPC protocol is +included to provide a generic request-response mechanism that alleviates the +need for formalizing special purpose protocols. + +> App attestation is a likely candidate for a having its own DIDComm protocol. +> This use of DRPC is ideal for developing and experimenting with the necessary +> agent interactions before deciding on if a use-specific protocol is needed and +> its semantics. + +[app attestation]: https://developer.apple.com/documentation/devicecheck + +### Video Verification Service + +A second example is using the DRPC protocol is to implement a custom video +verification service that is used by a specific mobile wallet implementation and +a proprietary backend service prior to issuing a credential to the wallet. Since +the interactions are to a proprietary service, so an open specification does not +make sense, but the use of DIDComm is valuable. In this example, the wallet +communicates over DIDComm to a Credential Issuer agent that (during +verification) proxies the requests/responses to a backend ("behind the +firewall") service. The wallet is implemented to use DRPC protocol instances to +initiate the verification and receive the actions needed to carry out the steps +of the verification (take picture, take video, instruct movements, etc.), +sending to the Issuer agent the necessary data. The Issuer conveys the requests +to the verification service and the responses back to the mobile wallet. At the +end of the process, the Issuer can see the result of the process, and decide on +the next actions between it and the mobile wallet, such as issuing a credential. + +Again, after using the DRPC protocol for developing and experimenting with the +implementation, the creators of the protocol can decide to formalize their own +custom, end-to-end protocol, or continue to use the DRPC protocol instances. +Important is that they can begin development without doing any Aries frameworks +customizations or plugins by using DRPC. + +## Tutorial + +### Name and Version + +This is the DRPC protocol. It is uniquely identified by the URI: + + "https://didcomm.org/drpc/1.0" + +### Key Concepts + +> This RFC assumes that you are familiar with [DID communication]. + +[DID communication]: /concepts/0005-didcomm/README.md + +The protocol consists of a DIDComm `request` message carrying an arbitrary +[JSON-RPC] request to a responding agent, and a second message that carries the +result of processing the request back to the client of the first message. The +interpretation of the request, how to carry out the request, the content of the +response, and the interpretation of the response, are all up to the business +logic (controllers) of the participating agents. There is no discovery of remote +services offered by agents--it is assumed that the two participants are aware of +the DRPC capabilities of one another through some other means. For example, from +the [App Attestation use case](#app-attestation), functionality to carry out the +app attestation process, and the service to use it is built into the mobile wallet. + +Those unfamiliar with [JSON-RPC], the `` is that it is a very simple +request response protocol using JSON where the only data shared is: + +- a `method` that defines what needs to be done, +- some `params` in JSON that are up to the requester/server to agree on, and +- an (optional) `id` to connect the response to the request. + +The response is likewise simple: + +- a `result` item if the invocation completed successful containing the return results, +- an `error` item if the invocation failed, containing details about the failure, and +- the `id` from the request. + +An example of a simple [JSON-RPC] request/response pair from the specification is: + +```json +--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1} +<-- {"jsonrpc": "2.0", "result": 19, "id": 1} +``` + +A [JSON-RPC] request may be a batch of requests, each with a different `id` value, +and the response a similar array, with an entry for each of the requests. + +[JSON-RPC] follows a similar "parameters defined by the message type" pattern as +DIDComm. As a result, in this protocol we do not need to add any special +handling around the `params` such as Base64 encoding, signing, headers and so +on, as the parties interacting with the protocol by definition must have a +shared understanding of the content of the `params` and can define any special +handling needed amongst themselves. + +It is expected (although not required) that an Aries Framework receiving a DRPC +message will simply pass to its associated "business logic" (controller) the +request from the client, and wait on the controller to provide the response +content to be sent back to the original client. Apart from the messaging processing +applied to all inbound and outbound messages, the Aries Framework will not +perform any of the actual processing of the request. + +### Roles + +There are two roles, adopted from the [JSON-RPC] specification, in the protocol +`client` and `server`: + +- The `client` initiates the protocol, sending a request to the `server`. +- The `server` carries out the request however they see fit. The `server` + may process the request themselves, or might invoke another service to process + the request. The `server` might be unable or unwilling to carry out the + request. +- The `server` returns the response from the request in a message to the `client`. + +### States + +#### Client States + +The `client` agent goes through the following states: + +- request-sent +- completed + +The state transition table for the `client` is: + +| State / Events | Send Request | Receive Response | +| ----------------------- | ---------------------------------- | ------------------------------- | +| *Start* | Transition to
**request-sent** | | +| request-sent | | Transition to
**complete** | +| completed | | | +| problem-report received | | Transition to
**abandoned** | +| abandoned | | | + +#### Server States + +The `server` agent goes through the following states: + +- request-received +- completed + +The state transition table for the `server` is: + +| State / Events | Receive Request | Send Response or Problem Report | +| ---------------- | -------------------------------------- | ------------------------------- | +| *Start* | Transition to
**request-received** | | +| request-received | | Transition to
**complete** | +| completed | | | + +### Messages + +The following are the messages in the DRPC protocol. The `response` message +handles all positive responses, so the `ack` ([RFC 0015 ACKs]) message is +**NOT** adopted by this protocol. The [RFC 0035 Report Problem] is adopted by +this protocol in the event that a `request` is not recognizable as a [JSON-RPC] +message and as such, a [JSON-RPC] response message cannot be created. See the +details below in the [Problem Report Message](#problem-report-message) section. + +[RFC 0015 ACKs]: ../features/0015-acks/README.md +[RFC 0035 Report Problem]: ../features/0035-report-problem/README.md + +#### Request Message + +The `request` message is sent by the `client` to initiate the protocol. The +message contains the [JSON-RPC] information necessary for the `server` to +process the request, prepare the response, and send the response message back to +the `client`. It is assumed the `client` knows what types of requests the +`server` is prepared to receive and process. If the `server` does not know how +to process the error, [JSON-RPC] has a standard response, outlined in the +[response message](#response-message) section below. How the `client` and +`server` coordinate that understanding is out of scope of this protocol. + +The `request` message uses the same JSON items as [JSON-RPC], skipping the +`id` in favor of the existing DIDComm `@id` and thread handling. + +```jsonc + { + "@type": "https://didcomm.org/drpc/1.0/request", + "@id": "2a0ec6db-471d-42ed-84ee-f9544db9da4b", + "request" : {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1} + } +``` + +The items in the message are as follows: + +- `@type` -- required, must be as above +- `@id` -- required, must be as defined in [RFC 0005 DIDComm] +- `request` -- **required**, an item containing a [JSON-RPC] request JSON structure. + - `request` **MUST** be either a single [JSON-RPC] request, or an array of [JSON-RPC] requests. + - Each [JSON-RPC] request **MUST** have the `jsonrpc` and `method` items. + - Each [JSON-RPC] request **MAY** have the `params` and `id` items. + - See the details below about the handling of `notification` [JSON-RPC] requests, requests where the `id` field is omitted. + - See the [JSON-RPC] specification for details about the `jsonrpc`, `method`, `params` and `id` JSON items. + +Per the [JSON-RPC] specification, if the `id` field of a [JSON-RPC] request is omitted, the `server` should not respond. In this DRPC DIDComm protocol, the `server` is always expected to send a `response`, but **MUST NOT** include +a [JSON-RPC] response for any [JSON-RPC] request for which the `id` is omitted. This is covered further +in the [response message](#response-message) section (below). + +#### Response Message + +A `response` message is sent by the `server` to following the +processing of the request to convey the output of the processing to the +`client`. As with the `request` the format mostly exactly that of a +[JSON-RPC] response. + +If the `request` is unrecognizable as a [JSON-RPC] message such that a +[JSON-RPC] message cannot be generated, the `server` SHOULD send a [RFC 0035 +Report Problem] message to the `client`. + +It is assumed the `client` understands what the contents of the +`response` message means in the context of the protocol instance. How the +`client` and `server` coordinate that understanding is out of scope of this +protocol. + +```jsonc + + { + "@type": "https://didcomm.org/drpc/1.0/response", + "@id": "63d6f6cf-b723-4eaf-874b-ae13f3e3e5c5", + "response": {"jsonrpc": "2.0", "result": 19, "id": 1} + } +``` + +The items in the message are as follows: + +- `@type` -- required, must be as above +- `@id` -- required, must be as defined in [RFC 0005 DIDComm] +- `response` -- **required**, an item containing a [JSON-RPC] response JSON structure. + - `response` **MUST** be either single (possibly empty) [JSON-RPC] response, + or an array of [JSON-RPC] responses. + - If all of the [JSON-RPC] requests in the `request` message are + *notifications* (e.g., the `id` item is omitted), the DIDComm `response` + message **MUST** be sent back with the value: `"response" : {}`. + - Each [JSON-RPC] response **MUST** have the `jsonrpc` and `id` items, and either a `result` or `error` item. + - See the [JSON-RPC] specification for details about the `jsonrpc`, `id`, `result` and `error` JSON items. + +As with all DIDComm messages that are not the first in a protocol instance, a +`~thread` decorator **MUST** be included in the `response` message. + +The special handling of the "all [JSON-RPC] requests are notifications" +described above is to simplify the DRPC handling to know when a DRPC protocol +instance is complete. If a `response` message is not always required, the DRPC +handler would have to inspect the `request` message to look for `id`s to +determine when the protocol completes. + +If the `server` does not understand how to process a given [JSON-RPC] request, a +`response` error **SHOULD** be returned (as per the [JSON-RPC] specification) with: + +- `error.code` value `-32601`, +- `error.message` set to `Method not found`, and +- no `error.data` item. + +#### Problem Report Message + +A [RFC 0035 Report Problem] message **SHOULD** be sent by the `server` instead +of a `response` message only if the `request` is unrecognizable as a [JSON-RPC] message. +An [JSON-RPC] errors **MUST** be provided to the `client` by the `server` via the +`response` message, not a `problem-report`. The `client` **MUST NOT** +respond to a `response` message, even if the `response` message is not a valid +[JSON-RPC] response. This is because once the `server` sends the `response`, the +protocol is in the `completed` state (from the `server`'s perspective) and so +is subject to deletion. As such, a follow up `problem-report` message would have +an invalid `thid` (thread ID) and (at best) be thrown away by the `server`. + +### Constraints + +The primary constraint with this protocol is that the two parties using the +protocol must understand one another--what [JSON-RPC] request(s) to use, what +parameters to provide, how to process the those requests, what the `response` +means, and so on. It is not a protocol to be used between arbitrary parties, but +rather one where the parties have knowledge outside of DIDComm of one another +and their mutual capabilities. + +On the other hand, that constraint enables great flexibility for explicitly +collaborating agents (such as a mobile wallet and the agent of its manufacturer) +to accomplish request-response transactions over DIDComm without +needing to define additional DIDComm protocols. More complex interactions can be +accomplished by carrying out a sequence of DRPC protocol instances between +agents. + +The flexibility the DRPC protocol allows for experimenting with specific +interactions between agents that could later evolve into formal DIDComm "fit for +purpose" protocols. + +## Reference + +### Codes Catalog + +A [JSON-RPC] request codes catalog *could* be developed over time and be +included in this part of the RFC. This might an intermediate step in transitioning +a given interaction implemented using DRPC into formally specified interaction. +On the other hand, simply defining a full DIDComm protocol will often be a far +better approach. + +At this time, there are no codes to be cataloged. + +## Drawbacks + +Anything that can be done by using the DRPC protocol can be accomplished by a +formally defined protocol specific to the task to be accomplished. The advantage +of the DRPC protocol is that pairs of agent instances that are explicitly +collaborating can use this protocol without having to first define a +task-specific protocol. + +## Rationale and alternatives + +We considered not supporting the *notification* and *batch* forms of the +[JSON-RPC] specification, and decided it made sense to allow for the full +support of the [JSON-RPC] specification, including requests of those forms. That +said, we also found that the concept of **not** having a DRPC `response` message +in some (likely, rare) cases based on the contents of the `request` JSON item +(e.g., when all of the `id`s are omitted from the [JSON-RPC] requests) would +unnecessarily complicate the DIDComm protocol instance handling about when it is +complete. As a result, a DRPC `response` message is always required. + +This design builds on the experience of implementations of this kind of feature +using [RFC 0095 Basic Message] and [RFC 0335 HTTP Over DIDComm]. This design +tries to build off the learnings gained from both of those implementations. + +Based on feedback to an original version of the RFC, we looked as well at +using [gRPC] as the core of this protocol, versus [JSON-RPC]. Our assessment +was that [gRPC] was a much heavier weight mechanism that required more effort +between parties to define and implement what will often be a very simple +request-response transaction -- at the level of defining a DIDComm protocol. + +[gRPC]: https://grpc.io/ + +The use of `params` and leaving the content and semantics of the params up to +the `client` and `server` means that they can define the appropriate handling of +the parameters. This eliminates the need for the protocol to define, for +example, that some data needs to be Base64 encoding for transmission, or if some +values need to be cryptographically signed. Such details are left to the +participants and how they are using the protocol. + +## Prior art + +This protocol has similar goals to the [RFC 0335 HTTP Over DIDComm] protocol, +but takes a lighter weight, more flexible approach. We expect that implementing +HTTP over DIDComm using this protocol will be as easy as using [RFC 0335 HTTP +Over DIDComm], where the [JSON-RPC] request's `params` data structure holds the +`headers` and `body` elements for the HTTP request. On the other hand, using the +explicit [RFC 0335 HTTP Over DIDComm] is might be a better choice if it is +available and exactly what is needed. + +[RFC 0335 HTTP Over DIDComm]: /features/0335-http-over-didcomm/README.md + +One of the example use cases for this protocol has been implemented by "hijacking" the +[RFC 0095 Basic Message] protocol to carry out the needed request/response actions. This +approach is less than ideal in that: + +- That is not the intended use of [RFC 0095 Basic Message], which is to send a + basic, human consumable message to the other agent. +- The request method and parameters have to be encoded into the basic message. +- The [RFC 0095 Basic Message] protocol is a single message protocols, so each + request-response interaction requires two instances of the protocol, and for + the controllers to manage connecting the interactions together. + +[RFC 0095 Basic Message]: /features/0095-basic-message/README.md + +## Unresolved questions + +- Should we include the idea of a `request` having a goal code ([RFC 0519 Goal Codes])? + +[RFC 0519 Goal Codes]: /concepts/0519-goal-codes/README.md + +## 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](README.md). + +Name / Link | Implementation Notes +--- | --- + | diff --git a/features/0809-w3c-data-integrity-credential-attachment/README.md b/features/0809-w3c-data-integrity-credential-attachment/README.md new file mode 100644 index 000000000..3b6acab82 --- /dev/null +++ b/features/0809-w3c-data-integrity-credential-attachment/README.md @@ -0,0 +1,321 @@ +# Aries RFC 0809: W3C Verifiable Credential Data Integrity Attachment format for requesting and issuing credentials + +- Authors: Timo Glastra (Animo Solutions) +- Status: [DEMONSTRATED](/README.md#demonstrated) +- Since: 2024-01-10 +- Status Note: Implemented in [Aries Cloud Agent Python](https://github.com/hyperledger/aries-cloudagent-python) and [Credo](https://github.com/openwallet-foundation/credo-ts) +- Supersedes: [Aries RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md) +- Start Date: 2023-12-18 +- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol), [credentials](/tags.md#credentials), [test-anomaly](/tags.md#test-anomaly) + +## Summary + +This RFC registers an attachment format for use in the [issue-credential V2](../0453-issue-credential-v2/README.md) protocol based on W3C Verifiable Credentials with [Data Integrity Proofs](https://www.w3.org/TR/vc-data-integrity/) from the [VC Data Model](https://www.w3.org/TR/vc-data-model/#linked-data-proofs). + +## Motivation + +The Issue Credential protocol needs an attachment format to be able to exchange W3C verifiable credentials. It is desirable to make use of specifications developed in an open standards body, such as the [Credential Manifest](https://identity.foundation/credential-manifest/) for which the attachment format is described in [RFC 0511: Credential-Manifest Attachment format](../0511-dif-cred-manifest-attach/README.md). However, the _Credential Manifest_ is not finished and ready yet, and therefore there is a need to bridge the gap between standards. + +## Tutorial + +Complete examples of messages are provided in the [reference section](#reference). + +## Reference + +### Credential Offer Attachment Format + +Format identifier: `didcomm/w3c-di-vc-offer@v0.1` + +```json +{ + "data_model_versions_supported": ["1.1", "2.0"], + "binding_required": true, + "binding_method": { + "anoncreds_link_secret": { + "nonce": "1234", + "cred_def_id": "did:key:z6MkwXG2WjeQnNxSoynSGYU8V9j3QzP3JSqhdmkHc6SaVWoT/credential-definition", + "key_correctness_proof": "" + }, + "didcomm_signed_attachment": { + "algs_supported": ["EdDSA"], + "did_methods_supported": ["key", "web"], + "nonce": "1234" + } + }, + "credential": { + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/security/data-integrity/v2", + { + "@vocab": "https://www.w3.org/ns/credentials/issuer-dependent#" + } + ], + "type": ["VerifiableCredential"], + "issuer": "did:key:z6MkwXG2WjeQnNxSoynSGYU8V9j3QzP3JSqhdmkHc6SaVWoT", + "issuanceDate": "2024-01-10T04:44:29.563418Z", + "credentialSubject": { + "height": 175, + "age": 28, + "name": "Alex", + "sex": "male" + } + } +} +``` + +- `data_model_versions_supported` - Required. List of strings indicating the supported VC Data Model versions. The list MUST contain at least one value. The values MUST be a valid data model version. Current supported values include `1.1` and `2.0`. +- `binding_required` - Optional. Boolean indicating whether the credential MUST be bound to the holder. If omitted, the credential is not required to be bound to the holder. If set to `true`, the credential MUST be bound to the holder using at least one of the binding methods defined in `binding_method`. +- `binding_method` - Required if `binding_required` is true. Object containing key-value pairs of binding methods supported by the issuer to bind the credential to a holder. If the value is omitted, this indicates the issuer does not support any binding methods for issuance of the credential. See [Binding Methods](#binding-methods) for a registry of default binding methods supported as part of this RFC. +- `credential` - Required. The credential to be issued. The credential MUST be compliant with the **first** `data_model_versions_supported` entry version of VC Data Model, except for the omission of a set required keys that may only be known at the time of issuance. See [Credential Offer Exceptions](#credential-offer-exceptions) for a list of exceptions. The credential MUST NOT contain any proofs. Some properties MAY be omitted if they will only be available at time of issuance, such as `issuanceDate`, `issuer`, `credentialSubject.id`, `credentialStatus`, `credentialStatus.id`. + +#### Credential Offer Exceptions + +To allow for validation of the `credential` according to the corresponding VC Data Model version, the `credential` in the offer MUST be conformant to the corresponding VC Data Model version, except for the exceptions listed below. This still allows the credential to be validated, knowing which deviations are possible. + +The list of exception is as follows: + +- `issuanceDate` (v1.1) or `validFrom` (v2.0) can be omitted, or set to a placeholder value. +- `issuer` (or `issuer.id` if issuer is an object) can be omitted +- `credentialSubject.id` can be omitted +- `credentialStatus` + - Either the whole `credentialStatus` can be omitted + - OR the `credentialStatus.type` can be present, but other required fields that are dynamic can be omitted (such as the `statusListIndex` and `statusListCredential` in case of [Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/)) + +### Credential Request Attachment Format + +Format identifier: `didcomm/w3c-di-vc-request@v0.1` + +This format is used to request a verifiable credential. The JSON structure might look like this: + +```json +{ + "data_model_version": "2.0", + "binding_proof": { + "anoncreds_link_secret": { + "entropy": "", + "cred_def_id": "did:key:z6MkwXG2WjeQnNxSoynSGYU8V9j3QzP3JSqhdmkHc6SaVWoT/credential-definition", + "blinded_ms": {}, + "blinded_ms_corectness_proof": {}, + "nonce": "" + }, + "didcomm_signed_attachment": { + "attachment_id": "<@id of the attachment>" + } + } +} +``` + +- `data_model_version` - Required. The data model version of the credential to be issued. The value MUST be a valid data model version and match one of the values from the `data_model_versions_supported` offer. +- `binding_proof` - Required if `binding_required` is `true` in the offer. Object containing key-value pairs of proofs for the binding to the holder. The keys MUST match keys of the `binding_method` object from the offer. See [Binding Methods](#binding-methods) for a registry of default binding methods supported as part of this RFC. + +### Credential Attachment Format + +Format identifier: `didcomm/w3c-di-vc@v0.1` + +This format is used to transmit a verifiable credential. The JSON structure might look like this: + +```json +{ + "credential": { + // vc with proof object or array + } +} +``` + +- `credential` - The signed credential. MUST be a valid verifiable credential object with one or more proofs and MUST conform to VC Data Model version as defined in the `data_model_version` of the request. + +It is up to the issuer to the pick an appropriate cryptographic suite to sign the credential. The issuer may use the cryptographic binding material provided by the holder to select the cryptographic suite. For example, when the `anoncreds_link_secret` binding method is used, the issuer should use an `DataIntegrityProof` with the `anoncredsvc-2023` cryptographic suite. When a holder provides a signed attachment as part of the binding proof using the `EdDSA` JWA alg, the issuer could use a `DateIntegrityProof` with the `eddsa-rdfc-2022` cryptographic suite. However, it is not required for the cryptographic suite used for the signature on the credential to be in any way related to the cryptographic suite used for the binding proof, unless the binding method explicitly requires this (for example the `anoncreds_link_secret` binding method). + +A complete [`issue-credential` message from the Issue Credential protocol 2.0](../0453-issue-credential-v2/README.md#issue-credential) might look like this: + +```json +{ + "@id": "284d3996-ba85-45d9-964b-9fd5805517b6", + "@type": "https://didcomm.org/issue-credential/2.0/issue-credential", + "comment": "", + "formats": [ + { + "attach_id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8", + "format": "didcomm/w3c-di-vc@v0.1" + } + ], + "credentials~attach": [ + { + "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8", + "mime-type": "application/json", + "data": { + "base64": "ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=" + } + } + ] +} +``` + +### Binding Methods + +The attachment format supports different methods to bind the credential to the receiver of the credential. In the offer message the issuer can indicate which binding methods are supported in the `binding_methods` object. Each key represents the id of the supported binding method. + +This section defines a set of binding methods supported by this attachment format, but other binding methods may be used. Based on the binding method, the request needs to include a `binding_proof` object where the key matches the key of the binding method from the offer. + +#### AnonCreds Link Secret + +Identifier: `anoncreds_link_secret` + +This binding method is intended to be used in combination with a credential containing an AnonCreds proof. + +##### Binding Method in Offer + +The structure of the binding method in the offer MUST match the structure of the [Credential Offer](https://hyperledger.github.io/anoncreds-spec/#credential-offer) as defiend in the AonCreds specification, with the exclusion of the `schema_id` key. + +```jsonc +{ + "nonce": "1234", + "cred_def_id": "did:key:z6MkwXG2WjeQnNxSoynSGYU8V9j3QzP3JSqhdmkHc6SaVWoT/credential-definition", + "key_correctness_proof": { + /* key correctness proof object */ + } +} +``` + +##### Binding Proof in Request + +The structure of the binding proof in the request MUST match the structure of the [Credential Request](https://hyperledger.github.io/anoncreds-spec/#credential-request) as defined in the AnonCreds specification. + +```jsonc +{ + "anoncreds_link_secret": { + "entropy": "", + "blinded_ms": { + /* blinded ms object */ + }, + "blinded_ms_corectness_proof": { + /* blinded ms correctness proof object */ + }, + "nonce": "" + } +} +``` + +##### Binding in Credential + +The issued credential should be bound to the holder by including the blinded link secret in the credential as defined in the [Issue Credential section](https://hyperledger.github.io/anoncreds-spec/#issue-credential) of the AnonCreds specification. Credential bound using the AnonCreds link secret binding method MUST contain an proof with `proof.type` value of `DataIntegrityProof` and `cryptosuite` value of `anoncredsvc-2023`, and conform to the [AnonCreds W3C Verifiable Credential Representation](https://hyperledger.github.io/anoncreds-spec/#w3c-verifiable-credentials-representation). + +#### DIDComm Signed Attachment + +Identifier: `didcomm_signed_attachment` + +This binding method leverages [DIDComm signed attachments](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0017-attachments/README.md#signing-attachments) to bind a credential to a specific key and/or identifier. + +##### Binding Method in Offer + +```jsonc +{ + "didcomm_signed_attachment": { + "algs_supported": ["EdDSA"], + "did_methods_supported": ["key"], + "nonce": "b19439b0-4dc9-4c28-b796-99d17034fb5c" + } +} +``` + +- `algs_supported` - Required. List of strings indicating the Json Web Algorithms supported by the issuer for verifying the signed attachment. The list MUST contain at least one value. The values MUST be a valid algorithm identifier as defined in the [JSON Web Signature and Encryption Algorithms](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) registry. +- `did_methods_supported` - Required. List of strings indicating which did methods are supported by the issuer for binding the credential to the holder. The list MUST contain at least one value. Values should ONLY include the method identifier of the did method. Examples values include `key` or `web`. +- `nonce` - Required. Nonce to be used in the request to prevent replay attacks of the signed attachment. + +##### Binding Proof in Request + +The binding proof in the request points to an appended attachment containing the signed attachment. + +```json +{ + "didcomm_signed_attachment": { + "attachment_id": "<@id of the attachment>" + } +} +``` + +- `attachment_id` - The id of the appended attachment included in the request message that contains the signed attachment. + +###### Signed Attachment Content + +The attachment MUST be signed by including a signature in the `jws` field of the attachment. The data MUST be a JSON document encoded in the `base64` field of the attachment. The structure of the signed attachment is described below. + +**JWS Payload** + +```json +{ + "nonce": "", +} +``` + +- `nonce` - Required. The `nonce` from the `didcomm_signed_attachment` object within `binding_method` from the credential offer + +**Protected Header** + +```json +{ + "alg": "EdDSA", + "kid": "did:key:z6MkkwiqX7BvkBbi37aNx2vJkCEYSKgHd2Jcgh4AUhi4YY1u#z6MkkwiqX7BvkBbi37aNx2vJkCEYSKgHd2Jcgh4AUhi4YY1u" +} +``` + +- `alg`: REQUIRED. A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. MUST NOT be none or an identifier for a symmetric algorithm (MAC). MUST match one of the `algs_supported` entries from the offer `binding_method` object. +- `kid`: REQUIRED. JOSE Header containing the DID URL pointing to a specific key in a did document. The did method of the DID URL MUST match with one of the `did_methods_supported` from the offer `binding_method` object. + +A signed binding request attachment appended to a request message might look like this: + +```json +{ + "@id": "284d3996-ba85-45d9-964b-9fd5805517b6", + "@type": "https://didcomm.org/issue-credential/2.0/request-credential", + "comment": "", + "formats": [ + { + "attach_id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8", + "format": "didcomm/w3c-di-vc-request@v0.1" + } + ], + "~attach": [ + { + "@id": "123", + "mime-type": "application/json", + "data": { + "base64": "", + "jws": { + "protected": "eyJhbGciOiJFZERTQSIsImlhdCI6MTU4Mzg4... (bytes omitted)", + "signature": "3dZWsuru7QAVFUCtTd0s7uc1peYEijx4eyt5... (bytes omitted)" + } + } + } + ], + "credentials~attach": [ + { + "@id": "5b38af88-d36f-4f77-bb7a-2f04ab806eb8", + "mime-type": "application/json", + "data": { + "base64": "ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=" + } + } + ] +} +``` + +##### Binding in Credential + +The issued credential should be bound to the holder by including the did in the credential as `credentialSubject.id` or `holder`. + +## Drawbacks + +- While it has a similar setup and structure compared to OpenID for Verifiable Credential Issuance, this attachment format only focuses on issuance of W3C Verifiable Credentials. Therefore another (but probably quite similar) attachment format needs to be defined to support issuance of non-W3C VCs +- There is currently no way for an issuer or holder to indicate which cryptographic suites they support for the signature of the credential. Currently it's at the discretion of the issuer to decide which cryptographic suite to use. In a future (minor) version we can add an optional way for a) the issuer to indicate which cryptographic suites they support, and b) the holder to indicate which cryptographic suites they support. +- There is currently no attachment format defined for a credential proposal. This makes it impossible for a holder to initiate the issuance of a credential using this attachment format. In a future (minor) version the proposal attachment format can be added. + +## Rationale and alternatives + +[RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md), [W3C VC API](https://w3c-ccg.github.io/vc-api/) allows issuance of credentials using only linked data signatures, while [RFC 0592: Indy Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0592-indy-attachments/README.md) supports issuance of AnonCreds credentials. This attachment format aims to support issuance of both previous attachment formats (while for AnonCreds it now being in the W3C model), as well as supporting additional features such as issuance W3C JWT VCs, credentials with multiple proofs, and cryptographic binding of the credential to the holder. + +## Prior art + +The attachment format in this RFC is heavily inspired by [RFC 0593: JSON-LD Credential Attachment](https://github.com/hyperledger/aries-rfcs/blob/main/features/0593-json-ld-cred-attach/README.md), [W3C VC API](https://w3c-ccg.github.io/vc-api/) and [OpenID for Verifiable Credential Issuance](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html). + +## Unresolved questions diff --git a/index.md b/index.md index 345d695db..227bd313f 100644 --- a/index.md +++ b/index.md @@ -1,121 +1,141 @@ # Aries RFCs by Status ## [ADOPTED](README.md#adopted) -* [0348: Transition Message Type to HTTPs](features/0348-transition-msg-type-to-https/README.md) (2020-08-26, [14 impls](features/0348-transition-msg-type-to-https/README.md#implementations) — [`feature`](/tags.md#feature) [`community-update`](/tags.md#community-update)) - -## [ACCEPTED](README.md#accepted) * [0003: Protocols](concepts/0003-protocols/README.md) (2019-04-01, [10 impls](concepts/0003-protocols/README.md#implementations) — [`concept`](/tags.md#concept)) -* [0004: Agents](concepts/0004-agents/README.md) (2019-01-15, [10 impls](concepts/0004-agents/README.md#implementations) — [`concept`](/tags.md#concept)) * [0005: DID Communication](concepts/0005-didcomm/README.md) (2019-11-21, [10 impls](concepts/0005-didcomm/README.md#implementations) — [`concept`](/tags.md#concept)) -* [0006: SSI Notation](concepts/0006-ssi-notation/README.md) (2018-09-01, [1 impl](concepts/0006-ssi-notation/README.md#implementations) — [`concept`](/tags.md#concept)) * [0008: Message ID and Threading](concepts/0008-message-id-and-threading/README.md) (2018-10-01, [5 impls](concepts/0008-message-id-and-threading/README.md#implementations) — [`concept`](/tags.md#concept)) * [0011: Decorators](concepts/0011-decorators/README.md) (2019-01-31, [10 impls](concepts/0011-decorators/README.md#implementations) — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) -* [0015: ACKs](features/0015-acks/README.md) (2021-04-15, [4 impls](features/0015-acks/README.md#implementations) — [`feature`](/tags.md#feature)) -* [0017: Attachments](concepts/0017-attachments/README.md) (2019-01-31, [2 impls](concepts/0017-attachments/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0015: ACKs](features/0015-acks/README.md) (2024-05-01, [4 impls](features/0015-acks/README.md#implementations) — [`feature`](/tags.md#feature)) +* [0017: Attachments](concepts/0017-attachments/README.md) (2024-05-01, [2 impls](concepts/0017-attachments/README.md#implementations) — [`concept`](/tags.md#concept)) * [0019: Encryption Envelope](features/0019-encryption-envelope/README.md) (2019-05-04, [7 impls](features/0019-encryption-envelope/README.md#implementations) — [`feature`](/tags.md#feature)) * [0020: Message Types](concepts/0020-message-types/README.md) (2019-05-24, [8 impls](concepts/0020-message-types/README.md#implementations) — [`concept`](/tags.md#concept)) -* [0023: DID Exchange Protocol 1.0](features/0023-did-exchange/README.md) (2021-04-15, [1 impl](features/0023-did-exchange/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) +* [0021: DIDComm Message Anatomy](concepts/0021-didcomm-message-anatomy/README.md) (2019-05-25 — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) +* [0023: DID Exchange v1](features/0023-did-exchange/README.md) (2021-04-15, [1 impl](features/0023-did-exchange/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) * [0025: DIDComm Transports](features/0025-didcomm-transports/README.md) (2019-12-05 — [`feature`](/tags.md#feature)) * [0031: Discover Features Protocol 1.0](features/0031-discover-features/README.md) (2019-05-01, [2 impls](features/0031-discover-features/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0035: Report Problem Protocol 1.0](features/0035-report-problem/README.md) (2021-03-15, [3 impls](features/0035-report-problem/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) +* [0035: Report Problem Protocol 1.0](features/0035-report-problem/README.md) (2024-05-01, [3 impls](features/0035-report-problem/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) * [0036: Issue Credential Protocol 1.0](features/0036-issue-credential/README.md) (2019-05-28, [1 impl](features/0036-issue-credential/README.md#implementations) — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) * [0037: Present Proof Protocol 1.0](features/0037-present-proof/README.md) (2019-05-28, [1 impl](features/0037-present-proof/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) -* [0044: DIDComm File and MIME Types](features/0044-didcomm-file-and-mime-types/README.md) (2021-04-15 — [`feature`](/tags.md#feature)) -* [0046: Mediators and Relays](concepts/0046-mediators-and-relays/README.md) (2019-02-01, [2 impls](concepts/0046-mediators-and-relays/README.md#implementations) — [`concept`](/tags.md#concept)) -* [0047: JSON-LD Compatibility](concepts/0047-json-ld-compatibility/README.md) (2019-02-20 — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) * [0048: Trust Ping Protocol 1.0](features/0048-trust-ping/README.md) (2019-02-01, [6 impls](features/0048-trust-ping/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0049: Repudiation](concepts/0049-repudiation/README.md) (2019-03-01 — [`concept`](/tags.md#concept)) -* [0050: Wallets](concepts/0050-wallets/README.md) (2018-07-01, [1 impl](concepts/0050-wallets/README.md#implementations) — [`concept`](/tags.md#concept)) -* [0092: Transports Return Route](features/0092-transport-return-route/README.md) (2019-12-06, [2 impls](features/0092-transport-return-route/README.md#implementations) — [`feature`](/tags.md#feature)) -* [0094: Cross-Domain Messaging](concepts/0094-cross-domain-messaging/README.md) (2018-10-29 — [`concept`](/tags.md#concept)) +* [0092: Transports Return Route](features/0092-transport-return-route/README.md) (2024-05-01, [2 impls](features/0092-transport-return-route/README.md#implementations) — [`feature`](/tags.md#feature)) +* [0094: Cross-Domain Messaging](concepts/0094-cross-domain-messaging/README.md) (2024-05-01 — [`concept`](/tags.md#concept)) * [0095: Basic Message Protocol 1.0](features/0095-basic-message/README.md) (2019-08-06, [6 impls](features/0095-basic-message/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0160: Connection Protocol](features/0160-connection-protocol/README.md) (2019-08-06, [5 impls](features/0160-connection-protocol/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0211: Mediator Coordination Protocol](features/0211-route-coordination/README.md) (2021-03-15, [1 impl](features/0211-route-coordination/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0250: Rich Schema Objects](concepts/0250-rich-schemas/README.md) (2019-10-08 — [`concept`](/tags.md#concept) [`rich-schemas`](/tags.md#rich-schemas)) +* [0160: Connection Protocol](features/0160-connection-protocol/README.md) (2019-08-06, [6 impls](features/0160-connection-protocol/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) +* [0211: Mediator Coordination Protocol](features/0211-route-coordination/README.md) (2024-05-01, [2 impls](features/0211-route-coordination/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) * [0302: Aries Interop Profile](concepts/0302-aries-interop-profile/README.md) (2021-01-06 — [`concept`](/tags.md#concept)) -* [0360: did:key Usage](features/0360-use-did-key/README.md) (2021-04-15 — [`feature`](/tags.md#feature)) -* [0434: Out-of-Band Protocol 1.1](features/0434-outofband/README.md) (2020-03-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0441: Prover and Verifier Best Practices for Proof Presentation](concepts/0441-present-proof-best-practices/README.md) (2021-04-15 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) +* [0360: did:key Usage](features/0360-use-did-key/README.md) (2024-05-01 — [`feature`](/tags.md#feature)) +* [0434: Out-of-Band Protocol 1.1](features/0434-outofband/README.md) (2020-03-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) +* [0441: Prover and Verifier Best Practices for Proof Presentation](concepts/0441-present-proof-best-practices/README.md) (2024-05-01 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) * [0453: Issue Credential Protocol 2.0](features/0453-issue-credential-v2/README.md) (2021-04-15 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) * [0454: Present Proof Protocol 2.0](features/0454-present-proof-v2/README.md) (2021-04-15 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) +* [0496: Transition to the Out of Band Protocol](features/0496-transition-to-oob-and-did-exchange/README.md) (2021-11-24 — [`feature`](/tags.md#feature) [`community-update`](/tags.md#community-update) [`test-anomaly`](/tags.md#test-anomaly)) * [0510: Presentation-Exchange Attachment format for requesting and presenting proofs](features/0510-dif-pres-exch-attach/README.md) (2020-07-21 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) -* [0519: Goal Codes](concepts/0519-goal-codes/README.md) (2021-04-15 — [`concept`](/tags.md#concept)) -* [0557: Discover Features Protocol v2.x](features/0557-discover-features-v2/README.md) (2021-04-15 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) -* [0587: Encryption Envelope v2](features/0587-encryption-envelope-v2/README.md) (2021-04-15 — [`feature`](/tags.md#feature)) +* [0557: Discover Features Protocol v2.x](features/0557-discover-features-v2/README.md) (2024-05-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`test-anomaly`](/tags.md#test-anomaly)) * [0592: Indy Attachment Formats for Requesting and Presenting Credentials](features/0592-indy-attachments/README.md) (2021-04-15 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) * [0593: JSON-LD Credential Attachment format for requesting and issuing credentials](features/0593-json-ld-cred-attach/README.md) (2021-04-15 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) -* [0627: Static Peer DIDs](features/0627-static-peer-dids/README.md) (2021-04-07 — [`feature`](/tags.md#feature)) + +## [ACCEPTED](README.md#accepted) +* [0004: Agents](concepts/0004-agents/README.md) (2019-01-15, [11 impls](concepts/0004-agents/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0006: SSI Notation](concepts/0006-ssi-notation/README.md) (2018-09-01, [1 impl](concepts/0006-ssi-notation/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0044: DIDComm File and MIME Types](features/0044-didcomm-file-and-mime-types/README.md) (2021-04-15 — [`feature`](/tags.md#feature)) +* [0046: Mediators and Relays](concepts/0046-mediators-and-relays/README.md) (2019-02-01, [3 impls](concepts/0046-mediators-and-relays/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0047: JSON-LD Compatibility](concepts/0047-json-ld-compatibility/README.md) (2019-02-20 — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) +* [0049: Repudiation](concepts/0049-repudiation/README.md) (2019-03-01 — [`concept`](/tags.md#concept)) +* [0050: Wallets](concepts/0050-wallets/README.md) (2018-07-01, [1 impl](concepts/0050-wallets/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0183: Revocation Notification 1.0](features/0183-revocation-notification/README.md) (2024-05-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0519: Goal Codes](concepts/0519-goal-codes/README.md) (2021-04-15 — [`concept`](/tags.md#concept)) +* [0587: Encryption Envelope v2](features/0587-encryption-envelope-v2/README.md) (2021-04-15 — [`feature`](/tags.md#feature)) * [0646: W3C Credential Exchange using BBS+ Signatures](features/0646-bbs-credentials/README.md) (2021-04-28 — [`feature`](/tags.md#feature)) +* [0685: Pickup Protocol 2.0](features/0685-pickup-v2/README.md) (2024-05-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0721: Revocation Notification 2.0](features/0721-revocation-notification-v2/README.md) (2024-05-01 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0793: Unqualified DID Transition](features/0793-unqualfied-dids-transition/README.md) (2023-07-11, [12 impls](features/0793-unqualfied-dids-transition/README.md#implementations) — [`feature`](/tags.md#feature) [`community-update`](/tags.md#community-update)) +* [0794: DID Rotate 1.0](features/0794-did-rotate/README.md) (2024-03-02 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) ## [DEMONSTRATED](README.md#demonstrated) -* [0029: Message Trust Contexts](concepts/0029-message-trust-contexts/README.md) (2019-05-10, [3 impls](concepts/0029-message-trust-contexts/README.md#implementations) — [`concept`](/tags.md#concept)) * [0032: Message Timing](features/0032-message-timing/README.md) (2019-05-01, [1 impl](features/0032-message-timing/README.md#implementations) — [`feature`](/tags.md#feature)) * [0042: LOX -- A more secure pluggable framework for protecting wallet keys](features/0042-lox/README.md) (2019-05-30, [1 impl](features/0042-lox/README.md#implementations) — [`feature`](/tags.md#feature)) * [0043: l10n (Locali[s|z]ation)](features/0043-l10n/README.md) (2019-04-01, [4 impls](features/0043-l10n/README.md#implementations) — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) -* [0051: Decentralized Key Management](concepts/0051-dkms/README.md) (2019-03-29, [2 impls](concepts/0051-dkms/README.md#implementations) — [`concept`](/tags.md#concept)) * [0113: Question Answer Protocol 0.9](features/0113-question-answer/README.md) (2019-07-05, [2 impls](features/0113-question-answer/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0509: Action Menu Protocol](features/0509-action-menu/README.md) (2020-07-02 , [1 impl](features/0509-action-menu/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0748: N-wise DID Exchange Protocol 1.0](features/0748-n-wise-did-exchange/README.md) (2022-08-03, [1 impl](features/0748-n-wise-did-exchange/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0755: Overlays Capture Architecture (OCA) For Aries](features/0755-oca-for-aries/README.md) (2024-03-02 — [`feature`](/tags.md#feature)) +* [0756: OCA for Aries Style Guide](features/0756-oca-for-aries-style-guide/README.md) (2023-01-05 — [`feature`](/tags.md#feature)) +* [0780: Use Data URLs for Images and More in Credential Attributes](features/0780-data-urls-images/README.md) (2024-03-02 — [`feature`](/tags.md#feature)) +* [0804: DIDComm Remote Procedure Call (DRPC)](features/0804-didcomm-rpc/README.md) (2024-03-02 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0809: W3C Verifiable Credential Data Integrity Attachment format for requesting and issuing credentials](features/0809-w3c-data-integrity-credential-attachment/README.md) (2024-01-10 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) ## [PROPOSED](README.md#proposed) -* [0013: Overlays](concepts/0013-overlays/README.md) (2019-05-20 — [`concept`](/tags.md#concept)) -* [0021: DIDComm Message Anatomy](concepts/0021-didcomm-message-anatomy/README.md) (2019-05-25 — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) -* [0024: DIDComm over XMPP](features/0024-didcomm-over-xmpp/README.md) (2019-06-14 — [`feature`](/tags.md#feature)) * [0028: Introduce Protocol 1.0](features/0028-introduce/README.md) (2019-04-15 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0030: Sync Connection Protocol 1.0](features/0030-sync-connection/README.md) (2019-07-03 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator) [`protocol`](/tags.md#protocol)) * [0034: Message Tracing](features/0034-message-tracing/README.md) (2018-10-24 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) * [0056: Service Decorator](features/0056-service-decorator/README.md) (2019-06-03 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) * [0066: Non-Repudiable Signature for Cryptographic Envelope](features/0066-non-repudiable-cryptographic-envelope/README.md) (2019-04-15 — [`feature`](/tags.md#feature)) * [0067: DIDComm DID document conventions](features/0067-didcomm-diddoc-conventions/README.md) (2019-06-10 — [`feature`](/tags.md#feature)) * [0074: DIDComm Best Practices](concepts/0074-didcomm-best-practices/README.md) (2019-06-10 — [`concept`](/tags.md#concept)) -* [0075: Payment Decorators](features/0075-payment-decorators/README.md) (2019-06-11 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) * [0103: Indirect Identity Control](concepts/0103-indirect-identity-control/README.md) (2019-06-04 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) * [0104: Chained Credentials](concepts/0104-chained-credentials/README.md) (2019-09-09 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) -* [0114: Predefined Identities](features/0114-predefined-identities/README.md) (2019-07-10 — [`feature`](/tags.md#feature)) -* [0116: Evidence Exchange Protocol 0.9](features/0116-evidence-exchange/README.md) (2019-07-26 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0124: DID Resolution Protocol 0.9](features/0124-did-resolution-protocol/README.md) (2019-07-13 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0167: Data Consent Lifecycle](concepts/0167-data-consent-lifecycle/README.md) (2019-08-07 (updated 2019-03-16) — [`concept`](/tags.md#concept)) -* [0183: Revocation Notification 1.0](features/0183-revocation-notification/README.md) (2019-08-12 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0193: Coin Flip Protocol 1.0 ](features/0193-coin-flip/README.md) (2019-08-19 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0207: Credential Fraud Threat Model](concepts/0207-credential-fraud-threat-model/README.md) (2019-08-30 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) * [0212: Pickup Protocol](features/0212-pickup/README.md) (2019-09-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0213: Transfer Policy Protocol](features/0213-transfer-policy/README.md) (2019-09-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0214: "Help Me Discover" Protocol](features/0214-help-me-discover/README.md) (2019-09-10 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0217: Linkable Message Paths](concepts/0217-linkable-message-paths/README.md) (2019-09-10 — [`concept`](/tags.md#concept)) * [0231: Biometric Service Provider](concepts/0231-biometric-service-provider/README.md) (2019-09-24 — [`concept`](/tags.md#concept)) -* [0249: Aries Rich Schema Contexts](features/0249-rich-schema-contexts/README.md) (2019-10-08 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0257: Private Credential Issuance](concepts/0257-private-credential-issuance/README.md) (2019-10-16 — [`concept`](/tags.md#concept) [`protocol`](/tags.md#protocol)) -* [0268: Unified DIDCOMM Deeplinking](concepts/0268-unified-didcomm-agent-deeplinking/README.md) (2019-10-23 — [`concept`](/tags.md#concept)) +* [0268: Unified DIDCOMM Deeplinking](concepts/0268-unified-didcomm-agent-deeplinking/README.md) (2019-10-23 — [`concept`](/tags.md#concept)) * [0270: Interop Test Suite](concepts/0270-interop-test-suite/README.md) (2019-10-25 — [`concept`](/tags.md#concept)) -* [0281: Aries Rich Schemas](features/0281-rich-schemas/README.md) (2019-10-30 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0289: The Trust Over IP Stack](concepts/0289-toip-stack/README.md) (2019-11-04 — [`concept`](/tags.md#concept) [`stack`](/tags.md#stack) [`trust layer`](/tags.md#trust layer) [`governance framework`](/tags.md#governance framework)) -* [0309: DIDAuthZ](features/0309-didauthz/README.md) (2019-11-14 — [`feature`](/tags.md#feature) [`credentials`](/tags.md#credentials)) -* [0317: Please ACK Decorator](features/0317-please-ack/README.md) (2019-12-26 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) -* [0327: Crypto service Protocol 1.0](features/0327-crypto-service/README.md) (2019-11-20 (date you submit your PR) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0334: JWE envelope 1.0](features/0334-jwe-envelope/README.md) (2019-11-28 — [`feature`](/tags.md#feature)) -* [0335: HTTP Over DIDComm](features/0335-http-over-didcomm/README.md) (2019-12-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) * [0345: Community Coordinated Update](concepts/0345-community-coordinated-update/README.md) (2019-12-26 (date you submit your PR) — [`concept`](/tags.md#concept)) * [0346: DIDComm Between Two Mobile Agents Using Cloud Agent Mediator](concepts/0346-didcomm-between-two-mobile-agents/README.md) (2019-06-23 — [`concept`](/tags.md#concept)) * [0347: Proof Negotiation](features/0347-proof-negotiation/README.md) (2019-12-13 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0351: Purpose Decorator](features/0351-purpose-decorator/README.md) (2019-12-16 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) -* [0418: Aries Rich Schema Encoding Objects](features/0418-rich-schema-encoding/README.md) (2020-02-10 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0420: Rich Schema Objects Common](concepts/0420-rich-schemas-common/README.md) (2020-02-13 — [`concept`](/tags.md#concept) [`rich-schemas`](/tags.md#rich-schemas)) -* [0428: Prerequisites to Issue Rich Credential](features/0428-prepare-issue-rich-credential/README.md) (2020-02-20 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0429: Prerequisites to Request Rich Presentation](features/0429-prepare-req-rich-pres/README.md) (2020-02-21 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) * [0430: Machine-Readable Governance Frameworks](concepts/0430-machine-readable-governance-frameworks/README.md) (2020-02-24 — [`concept`](/tags.md#concept)) * [0440: KMS Architectures ](concepts/0440-kms-architectures/README.md) (2020-03-06 — [`concept`](/tags.md#concept)) -* [0445: Aries Rich Schema Mapping](features/0445-rich-schema-mapping/README.md) (2020-03-16 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0446: Aries Rich Schema Credential Definition](features/0446-rich-schema-cred-def/README.md) (2020-03-16 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) -* [0478: Coprotocols](concepts/0478-coprotocols/README.md) (2020-05-19 — [`concept`](/tags.md#concept) [`protocol`](/tags.md#protocol)) -* [0482: Coprotocol Protocol 0.5](features/0482-coprotocol-protocol/README.md) (2020-05-19 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) -* [0496: Transition to the Out of Band and DID Exchange Protocols](features/0496-transition-to-oob-and-did-exchange/README.md) (2020-09-30 — [`feature`](/tags.md#feature) [`community-update`](/tags.md#community-update)) * [0511: Credential-Manifest Attachment format for requesting and presenting credentials](features/0511-dif-cred-manifest-attach/README.md) (2020-07-22 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) * [0559: Privacy-Preserving Proof of Uniqueness](concepts/0559-pppu/README.md) (2020-10-21 — [`concept`](/tags.md#concept)) * [0566: Issuer-Hosted Custodial Agents](concepts/0566-issuer-hosted-custodidal-agents/README.md) (2020-11-16 — [`concept`](/tags.md#concept)) * [0641: Linking binary objects to credentials using hash based references](features/0641-linking-binary-objects-to-credentials/README.md) (2021-04-22 — [`feature`](/tags.md#feature) [`credentials`](/tags.md#credentials)) +* [0693: Cross-Platform Credential Representation](features/0693-credential-representation/README.md) (2021-07-06 — [`feature`](/tags.md#feature)) +* [0699: Push Notifications apns Protocol 1.0](features/0699-push-notifications-apns/README.md) (2021-10-07 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0700: Out-of-Band through redirect](concepts/0700-oob-through-redirect/README.md) (2021-10-08 — [`concept`](/tags.md#concept) [`decorator`](/tags.md#decorator)) +* [0728: Device Binding Attachments](features/0728-device-binding-attachments/README.md) (2022-04-07 — [`feature`](/tags.md#feature)) +* [0734: Push Notifications fcm Protocol 1.0](features/0734-push-notifications-fcm/README.md) (2022-05-12 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0757: Push Notification](concepts/0757-push-notification/README.md) (2022-11-02 — [`concept`](/tags.md#concept)) +* [0771: AnonCreds Attachment Formats for Requesting and Presenting Credentials](features/0771-anoncreds-attachments/README.md) (2023-02-24 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol) [`credentials`](/tags.md#credentials) [`test-anomaly`](/tags.md#test-anomaly)) +* [0799: Aries Long Term Support Releases](concepts/0799-long-term-support/README.md) (2023-11-07 — [`concept`](/tags.md#concept)) + +## [STALLED](README.md#stalled) +* [0024: DIDComm over XMPP](features/0024-didcomm-over-xmpp/README.md) (2024-04-03 — [`feature`](/tags.md#feature)) +* [0029: Message Trust Contexts](concepts/0029-message-trust-contexts/README.md) (2024-04-03, [3 impls](concepts/0029-message-trust-contexts/README.md#implementations) — [`concept`](/tags.md#concept)) +* [0030: Sync Connection Protocol 1.0](features/0030-sync-connection/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator) [`protocol`](/tags.md#protocol)) +* [0075: Payment Decorators](features/0075-payment-decorators/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) +* [0114: Predefined Identities](features/0114-predefined-identities/README.md) (2024-04-03 — [`feature`](/tags.md#feature)) +* [0116: Evidence Exchange Protocol 0.9](features/0116-evidence-exchange/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0193: Coin Flip Protocol 1.0 ](features/0193-coin-flip/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0207: Credential Fraud Threat Model](concepts/0207-credential-fraud-threat-model/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`credentials`](/tags.md#credentials)) +* [0217: Linkable Message Paths](concepts/0217-linkable-message-paths/README.md) (2024-04-03 — [`concept`](/tags.md#concept)) +* [0249: Aries Rich Schema Contexts](features/0249-rich-schema-contexts/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0250: Rich Schema Objects](concepts/0250-rich-schemas/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`rich-schemas`](/tags.md#rich-schemas)) +* [0257: Private Credential Issuance](concepts/0257-private-credential-issuance/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`protocol`](/tags.md#protocol)) +* [0281: Aries Rich Schemas](features/0281-rich-schemas/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0289: The Trust Over IP Stack](concepts/0289-toip-stack/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`stack`](/tags.md#stack) [`trust layer`](/tags.md#trust layer) [`governance framework`](/tags.md#governance framework)) +* [0309: DIDAuthZ](features/0309-didauthz/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`credentials`](/tags.md#credentials)) +* [0327: Crypto service Protocol 1.0](features/0327-crypto-service/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0334: JWE envelope 1.0](features/0334-jwe-envelope/README.md) (2024-04-03 — [`feature`](/tags.md#feature)) +* [0335: HTTP Over DIDComm](features/0335-http-over-didcomm/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0351: Purpose Decorator](features/0351-purpose-decorator/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) +* [0418: Aries Rich Schema Encoding Objects](features/0418-rich-schema-encoding/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0420: Rich Schema Objects Common](concepts/0420-rich-schemas-common/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`rich-schemas`](/tags.md#rich-schemas)) +* [0428: Prerequisites to Issue Rich Credential](features/0428-prepare-issue-rich-credential/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0429: Prerequisites to Request Rich Presentation](features/0429-prepare-req-rich-pres/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0445: Aries Rich Schema Mapping](features/0445-rich-schema-mapping/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0446: Aries Rich Schema Credential Definition](features/0446-rich-schema-cred-def/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`rich-schemas`](/tags.md#rich-schemas)) +* [0478: Coprotocols](concepts/0478-coprotocols/README.md) (2024-04-03 — [`concept`](/tags.md#concept) [`protocol`](/tags.md#protocol)) +* [0482: Coprotocol Protocol 0.5](features/0482-coprotocol-protocol/README.md) (2024-04-03 — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) ## [RETIRED](README.md#retired) +* [0013: Overlays](concepts/0013-overlays/README.md) (2023-01-15 — [`concept`](/tags.md#concept)) +* [0051: Decentralized Key Management](concepts/0051-dkms/README.md) (2024-04-03, [2 impls](concepts/0051-dkms/README.md#implementations) — [`concept`](/tags.md#concept)) * [0234: Signature Decorator](features/0234-signature-decorator/README.md) (2020-10-14, [3 impls](features/0234-signature-decorator/README.md#implementations) — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) * [0303: V0.1 Credential Exchange (Deprecated)](features/0303-v01-credential-exchange/README.md) (2019-11-12, [4 impls](features/0303-v01-credential-exchange/README.md#implementations) — [`feature`](/tags.md#feature) [`protocol`](/tags.md#protocol)) +* [0317: Please ACK Decorator](features/0317-please-ack/README.md) (2019-12-26 — [`feature`](/tags.md#feature) [`decorator`](/tags.md#decorator)) +* [0348: Transition Message Type to HTTPs](features/0348-transition-msg-type-to-https/README.md) (2020-08-26, [14 impls](features/0348-transition-msg-type-to-https/README.md#implementations) — [`feature`](/tags.md#feature) [`community-update`](/tags.md#community-update)) +* [0627: Static Peer DIDs](features/0627-static-peer-dids/README.md) (2021-04-07 — [`feature`](/tags.md#feature)) >(This file is machine-generated; see [code/generate_index.py](code/generate_index.py).) diff --git a/mkdocs-requirements.txt b/mkdocs-requirements.txt new file mode 100644 index 000000000..05cd7cb50 --- /dev/null +++ b/mkdocs-requirements.txt @@ -0,0 +1,3 @@ + +mkdocs-material==9.5.39 +mike==2.1.3 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..826526691 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,254 @@ +site_name: Hyperledger Aries Interoperability Profiles / RFCs +repo_name: hyperledger/aries-rfcs +repo_url: https://github.com/hyperledger/aries-rfcs +theme: + name: material + # custom_dir: overrides + logo: https://raw.githubusercontent.com/hyperledger/aries-rfcs/main/collateral/Hyperledger_Aries_Logo_White.png + favicon: https://raw.githubusercontent.com/hyperledger/aries-rfcs/main/collateral/favicon.ico + icon: + repo: fontawesome/brands/github + palette: + - primary: green + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.code.copy + - navigation.expand + - navigation.footer + - navigation.instant + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - toc.follow +# - toc.integrate +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde +plugins: + - search +# extra: +nav: +- Welcome: + - Welcome: README.md + - All RFCs by Status: RFCindex.md + - RFC Template: 0000-template.md + - Protocol RFC Template: 0000-template-protocol.md +- Governance: + - Maintainers: MAINTAINERS.md + - Contributing: contributing.md + - Submitting Issues: github-issues.md + - License: LICENSE.md + - Security: SECURITY.md +# RFCs by AIP and Status +- AIP 2.0: + - Aries RFC 0003 Protocols: aip2/0003-protocols/README.md + - Aries RFC 0004 Agents: aip2/0004-agents/README.md + - Aries RFC 0005 DID Communication: aip2/0005-didcomm/README.md + - Aries RFC 0008 Message ID and Threading: aip2/0008-message-id-and-threading/README.md + - Aries RFC 0011 Decorators: aip2/0011-decorators/README.md + - Aries RFC 0015 ACKs: aip2/0015-acks/README.md + - Aries RFC 0017 Attachments: aip2/0017-attachments/README.md + - Aries RFC 0019 Encryption Envelope: aip2/0019-encryption-envelope/README.md + - Aries RFC 0020 Message Types: aip2/0020-message-types/README.md + - Aries RFC 0023 DID Exchange Protocol 1.0: aip2/0023-did-exchange/README.md + - Aries RFC 0025 DIDComm Transports: aip2/0025-didcomm-transports/README.md + - Aries RFC 0035 Report Problem Protocol 1.0: aip2/0035-report-problem/README.md + - Aries RFC 0044 DIDComm File and MIME Types: aip2/0044-didcomm-file-and-mime-types/README.md + - Aries RFC 0046 Mediators and Relays: aip2/0046-mediators-and-relays/README.md + - Aries RFC 0047 JSON-LD Compatibility: aip2/0047-json-ld-compatibility/README.md + - Aries RFC 0048 Trust Ping Protocol 1.0: aip2/0048-trust-ping/README.md + - Aries RFC 0050 Wallets: aip2/0050-wallets/README.md + - Aries RFC 0092 Transports Return Route: aip2/0092-transport-return-route/README.md + - Aries RFC 0094 Cross-Domain Messaging: aip2/0094-cross-domain-messaging/README.md + - Aries RFC 0095 Basic Message Protocol 1.0: aip2/0095-basic-message/README.md + - Aries RFC 0183 Revocation Notification 1.0: aip2/0183-revocation-notification/README.md + - 0211 Mediator Coordination Protocol: aip2/0211-route-coordination/README.md + - Aries RFC 0360 did:key Usage: aip2/0360-use-did-key/README.md + - Aries RFC 0434 Out-of-Band Protocol 1.1: aip2/0434-outofband/README.md + - 0441 Prover and Verifier Best Practices for Proof Presentation: aip2/0441-present-proof-best-practices/README.md + - Aries RFC 0453 Issue Credential Protocol 2.0: aip2/0453-issue-credential-v2/README.md + - Aries RFC 0454 Present Proof Protocol 2.0: aip2/0454-present-proof-v2/README.md + - Aries RFC 0510 Presentation-Exchange Attachment format for requesting and presenting proofs: aip2/0510-dif-pres-exch-attach/README.md + - 0519 Goal Codes: aip2/0519-goal-codes/README.md + - Aries RFC 0557 Discover Features Protocol v2.x: aip2/0557-discover-features-v2/README.md + - Aries RFC 0592 Indy Attachment Formats for Requesting and Presenting Credentials: aip2/0592-indy-attachments/README.md + - Aries RFC 0593 JSON-LD Credential Attachment format for requesting and issuing credentials: aip2/0593-json-ld-cred-attach/README.md +- ADOPTED: + - 0003 Protocols: concepts/0003-protocols/README.md + - 0005 DID Communication: concepts/0005-didcomm/README.md + - 0008 Message ID and Threading: concepts/0008-message-id-and-threading/README.md + - 0011 Decorators: concepts/0011-decorators/README.md + - 0015 ACKs: features/0015-acks/README.md + - 0017 Attachments: concepts/0017-attachments/README.md + - 0019 Encryption Envelope: features/0019-encryption-envelope/README.md + - 0020 Message Types: concepts/0020-message-types/README.md + - 0021 DIDComm Message Anatomy: concepts/0021-didcomm-message-anatomy/README.md + - 0023 DID Exchange v1: features/0023-did-exchange/README.md + - 0025 DIDComm Transports: features/0025-didcomm-transports/README.md + - 0031 Discover Features Protocol 1.0: features/0031-discover-features/README.md + - 0035 Report Problem Protocol 1.0: features/0035-report-problem/README.md + - 0036 Issue Credential Protocol 1.0: features/0036-issue-credential/README.md + - 0037 Present Proof Protocol 1.0: features/0037-present-proof/README.md + - 0048 Trust Ping Protocol 1.0: features/0048-trust-ping/README.md + - 0092 Transports Return Route: features/0092-transport-return-route/README.md + - 0094 Cross-Domain Messaging: concepts/0094-cross-domain-messaging/README.md + - 0095 Basic Message Protocol 1.0: features/0095-basic-message/README.md + - 0160 Connection Protocol: features/0160-connection-protocol/README.md + - 0211 Mediator Coordination Protocol: features/0211-route-coordination/README.md + - 0302 Aries Interop Profile: concepts/0302-aries-interop-profile/README.md + - 0360 did:key Usage: features/0360-use-did-key/README.md + - 0434 Out-of-Band Protocol 1.1: features/0434-outofband/README.md + - 0441 Prover and Verifier Best Practices for Proof Presentation: concepts/0441-present-proof-best-practices/README.md + - 0453 Issue Credential Protocol 2.0: features/0453-issue-credential-v2/README.md + - 0454 Present Proof Protocol 2.0: features/0454-present-proof-v2/README.md + - 0496 Transition to the Out of Band Protocol: features/0496-transition-to-oob-and-did-exchange/README.md + - 0510 Presentation-Exchange Attachment format for requesting and presenting proofs: features/0510-dif-pres-exch-attach/README.md + - 0557 Discover Features Protocol v2.x: features/0557-discover-features-v2/README.md + - 0592 Indy Attachment Formats for Requesting and Presenting Credentials: features/0592-indy-attachments/README.md + - 0593 JSON-LD Credential Attachment format for requesting and issuing credentials: features/0593-json-ld-cred-attach/README.md +- ACCEPTED: + - 0004 Agents: concepts/0004-agents/README.md + - 0006 SSI Notation: concepts/0006-ssi-notation/README.md + - 0044 DIDComm File and MIME Types: features/0044-didcomm-file-and-mime-types/README.md + - 0046 Mediators and Relays: concepts/0046-mediators-and-relays/README.md + - 0047 JSON-LD Compatibility: concepts/0047-json-ld-compatibility/README.md + - 0049 Repudiation: concepts/0049-repudiation/README.md + - 0050 Wallets: concepts/0050-wallets/README.md + - 0183 Revocation Notification 1.0: features/0183-revocation-notification/README.md + - 0519 Goal Codes: concepts/0519-goal-codes/README.md + - 0587 Encryption Envelope v2: features/0587-encryption-envelope-v2/README.md + - 0646 W3C Credential Exchange using BBS+ Signatures: features/0646-bbs-credentials/README.md + - 0685 Pickup Protocol 2.0: features/0685-pickup-v2/README.md + - 0721 Revocation Notification 2.0: features/0721-revocation-notification-v2/README.md + - 0793 Unqualified DID Transition: features/0793-unqualfied-dids-transition/README.md + - 0794 DID Rotate 1.0: features/0794-did-rotate/README.md +- DEMONSTRATED: + - 0032 Message Timing: features/0032-message-timing/README.md + - 0042 LOX -- A more secure pluggable framework for protecting wallet keys: features/0042-lox/README.md + - 0043 l10n (Locali[s|z]ation): features/0043-l10n/README.md + - 0113 Question Answer Protocol 0.9: features/0113-question-answer/README.md + - 0509 Action Menu Protocol: features/0509-action-menu/README.md + - 0748 N-wise DID Exchange Protocol 1.0: features/0748-n-wise-did-exchange/README.md + - 0755 Overlays Capture Architecture (OCA) For Aries: features/0755-oca-for-aries/README.md + - 0756 OCA for Aries Style Guide: features/0756-oca-for-aries-style-guide/README.md + - 0780 Use Data URLs for Images and More in Credential Attributes: features/0780-data-urls-images/README.md + - 0804 DIDComm Remote Procedure Call (DRPC): features/0804-didcomm-rpc/README.md + - 0809 W3C Verifiable Credential Data Integrity Attachment format for requesting and issuing credentials: features/0809-w3c-data-integrity-credential-attachment/README.md +- PROPOSED: + - 0028 Introduce Protocol 1.0: features/0028-introduce/README.md + - 0034 Message Tracing: features/0034-message-tracing/README.md + - 0056 Service Decorator: features/0056-service-decorator/README.md + - 0066 Non-Repudiable Signature for Cryptographic Envelope: features/0066-non-repudiable-cryptographic-envelope/README.md + - 0067 DIDComm DID document conventions: features/0067-didcomm-diddoc-conventions/README.md + - 0074 DIDComm Best Practices: concepts/0074-didcomm-best-practices/README.md + - 0103 Indirect Identity Control: concepts/0103-indirect-identity-control/README.md + - 0104 Chained Credentials: concepts/0104-chained-credentials/README.md + - 0124 DID Resolution Protocol 0.9: features/0124-did-resolution-protocol/README.md + - 0167 Data Consent Lifecycle: concepts/0167-data-consent-lifecycle/README.md + - 0212 Pickup Protocol: features/0212-pickup/README.md + - 0213 Transfer Policy Protocol: features/0213-transfer-policy/README.md + - 0214 "Help Me Discover" Protocol: features/0214-help-me-discover/README.md + - 0231 Biometric Service Provider: concepts/0231-biometric-service-provider/README.md + - 0268 Unified DIDCOMM Deeplinking: concepts/0268-unified-didcomm-agent-deeplinking/README.md + - 0270 Interop Test Suite: concepts/0270-interop-test-suite/README.md + - 0345 Community Coordinated Update: concepts/0345-community-coordinated-update/README.md + - 0346 DIDComm Between Two Mobile Agents Using Cloud Agent Mediator: concepts/0346-didcomm-between-two-mobile-agents/README.md + - 0347 Proof Negotiation: features/0347-proof-negotiation/README.md + - 0430 Machine-Readable Governance Frameworks: concepts/0430-machine-readable-governance-frameworks/README.md + - 0440 KMS Architectures : concepts/0440-kms-architectures/README.md + - 0511 Credential-Manifest Attachment format for requesting and presenting credentials: features/0511-dif-cred-manifest-attach/README.md + - 0559 Privacy-Preserving Proof of Uniqueness: concepts/0559-pppu/README.md + - 0566 Issuer-Hosted Custodial Agents: concepts/0566-issuer-hosted-custodidal-agents/README.md + - 0641 Linking binary objects to credentials using hash based references: features/0641-linking-binary-objects-to-credentials/README.md + - 0693 Cross-Platform Credential Representation: features/0693-credential-representation/README.md + - 0699 Push Notifications apns Protocol 1.0: features/0699-push-notifications-apns/README.md + - 0700 Out-of-Band through redirect: concepts/0700-oob-through-redirect/README.md + - 0728 Device Binding Attachments: features/0728-device-binding-attachments/README.md + - 0734 Push Notifications fcm Protocol 1.0: features/0734-push-notifications-fcm/README.md + - 0757 Push Notification: concepts/0757-push-notification/README.md + - 0771 AnonCreds Attachment Formats for Requesting and Presenting Credentials: features/0771-anoncreds-attachments/README.md + - 0799 Aries Long Term Support Releases: concepts/0799-long-term-support/README.md +- STALLED: + - 0024 DIDComm over XMPP: features/0024-didcomm-over-xmpp/README.md + - 0029 Message Trust Contexts: concepts/0029-message-trust-contexts/README.md + - 0030 Sync Connection Protocol 1.0: features/0030-sync-connection/README.md + - 0075 Payment Decorators: features/0075-payment-decorators/README.md + - 0114 Predefined Identities: features/0114-predefined-identities/README.md + - 0116 Evidence Exchange Protocol 0.9: features/0116-evidence-exchange/README.md + - 0193 Coin Flip Protocol 1.0 : features/0193-coin-flip/README.md + - 0207 Credential Fraud Threat Model: concepts/0207-credential-fraud-threat-model/README.md + - 0217 Linkable Message Paths: concepts/0217-linkable-message-paths/README.md + - 0249 Aries Rich Schema Contexts: features/0249-rich-schema-contexts/README.md + - 0250 Rich Schema Objects: concepts/0250-rich-schemas/README.md + - 0257 Private Credential Issuance: concepts/0257-private-credential-issuance/README.md + - 0281 Aries Rich Schemas: features/0281-rich-schemas/README.md + - 0289 The Trust Over IP Stack: concepts/0289-toip-stack/README.md + - 0309 DIDAuthZ: features/0309-didauthz/README.md + - 0327 Crypto service Protocol 1.0: features/0327-crypto-service/README.md + - 0334 JWE envelope 1.0: features/0334-jwe-envelope/README.md + - 0335 HTTP Over DIDComm: features/0335-http-over-didcomm/README.md + - 0351 Purpose Decorator: features/0351-purpose-decorator/README.md + - 0418 Aries Rich Schema Encoding Objects: features/0418-rich-schema-encoding/README.md + - 0420 Rich Schema Objects Common: concepts/0420-rich-schemas-common/README.md + - 0428 Prerequisites to Issue Rich Credential: features/0428-prepare-issue-rich-credential/README.md + - 0429 Prerequisites to Request Rich Presentation: features/0429-prepare-req-rich-pres/README.md + - 0445 Aries Rich Schema Mapping: features/0445-rich-schema-mapping/README.md + - 0446 Aries Rich Schema Credential Definition: features/0446-rich-schema-cred-def/README.md + - 0478 Coprotocols: concepts/0478-coprotocols/README.md + - 0482 Coprotocol Protocol 0.5: features/0482-coprotocol-protocol/README.md +- RETIRED: + - 0013 Overlays: concepts/0013-overlays/README.md + - 0051 Decentralized Key Management: concepts/0051-dkms/README.md + - 0234 Signature Decorator: features/0234-signature-decorator/README.md + - 0303 V0.1 Credential Exchange (Deprecated): features/0303-v01-credential-exchange/README.md + - 0317 Please ACK Decorator: features/0317-please-ack/README.md + - 0348 Transition Message Type to HTTPs: features/0348-transition-msg-type-to-https/README.md + - 0627 Static Peer DIDs: features/0627-static-peer-dids/README.md \ No newline at end of file diff --git a/tags.md b/tags.md index 6ad75f24d..a146fa01e 100644 --- a/tags.md +++ b/tags.md @@ -15,8 +15,7 @@ Defines a specific, concrete feature that [agents](concepts/0004-agents/README.m Defines a general aspect of the Aries mental model, or a pattern that manifests in many different features. ### `community-update` -An RFC that tracks a community-coordinated update, as described in [RFC -0345](../../concepts/0345-community-coordinated-update/README.md). Such updates +An RFC that tracks a community-coordinated update, as described in [RFC 0345](concepts/0345-community-coordinated-update/README.md). Such updates enable independently deployed, interoperable agents to remain interoperable throughout the transition. @@ -24,7 +23,7 @@ throughout the transition. Relates to [verifiable credentials](https://www.w3.org/TR/vc-data-model/). ### `rich-schemas` -Relates to next-generation schemas, such as those used by [https://schema.org](schema.org), as used in verifiable credentials. +Relates to next-generation schemas, such as those used by [https://schema.org](https://schema.org), as used in verifiable credentials. ### `test-anomaly` Violates some aspect of our [policy on writing tests for protocols before allowing their status to progress beyond DEMONSTRATED](/README.md#accepted). RFCs should only carry this tag temporarily, to grandfather something where test improvements are happening in the background. When this tag is applied to an RFC, unit tests run by our CI/CD pipeline will emit a warning rather than an error about missing tests, IFF each implementation that lacks tests formats its notes about test results like this: