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/0535-email-access-governance-framework/README.md b/concepts/0535-email-access-governance-framework/README.md new file mode 100644 index 000000000..01f468e1e --- /dev/null +++ b/concepts/0535-email-access-governance-framework/README.md @@ -0,0 +1,90 @@ +# 0535: Email Access Governance Framework +- Authors: [Sam Curren](telegramsam@gmail.com) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2020-09-16 +- Status Note: Proposed, but in need of specifics to put into action. +- Start Date: 2020-07-14 +- Tags: feature, protocol + +## Summary + + +> Note: This RFC was created in advance of the [Credential Trust Establishment](https://identity.foundation/credential-trust-establishment/) spec work at the DIF. The concepts are good, but the governance mechanism should be updated to use this newer spec before action is taken. + +This Governance Framework is community managed. + +When making connections from one person to another over DIDComm, it is useful to be able to gain proof of something to verify that the connection is with the right person and has not been subject to a MITM attack. We expect this Governance Framework to be one of many used for the purpose of helping to verify identity attributes in the creation of trusted channels. + +This is an early attempt at the creation and use of of a practical governance framework. As Governance Framework technology improves, we expect this particular framework to be replaced. + +## Purpose + +To facilitate the verification of email access between two parties over DIDComm and related technologies. + +## Details + +### Goal Codes + +This Governance framework satisfies the following goal code(s): + +`aries.receive.verifiable.identifier` + +### Protocols + +`https://didcomm.org/present-proof/2.0/` + +### Roles + +**issuer**: Responsible for issuing credentials according to the requirements of this governance framework. + +### Schemas + +_TODO: schemas listed here_ + +### Issuers + +BCGov (DID?) + +### Issue Requirements + +Issuers must validate email ownership by sending an email to the email address in question. The email MUST contain a link for the user to click, or a code to be entered in a verification step. After verifying that the clicked link or entered code matches, the credential may be issued. + +Issued credentials should indicate an expiration date no longer than 6 months from the date of verification. + +### Revocation + +This framework does not currently use revocation, relying upon the expiration date to prevent widespread issues. + +### Allowable Verification Purposes + +Email addresses revealed in this manner may be used for the following purposes: + +- Displaying to recipient. +- Checking against address book. + +Use outside these purposes, including the following examples, violates the allowed uses as specified by this governance framework. + +- Sending email to the address without explicit additional approval of the user. +- Sharing email address with any other party. + +### Machine Readable Document + +Located [here](data.json). + +## Notes + +- The machine readable document is as simple as possible by design. As related technology improves, the document will be updated to reflect these changes. +- Code for the indy email verification service: https://github.com/bcgov/indy-email-verification that could be used as a basis for an issuer. + +## Unresolved questions + +- Which networks? +- Need Schemas and Issuers +## Uses + +The following libraries or applications use this Governance Framework. + +Name / Link | Implementation Notes +--- | --- + | + diff --git a/concepts/0535-email-access-governance-framework/data.json b/concepts/0535-email-access-governance-framework/data.json new file mode 100644 index 000000000..fbccd0166 --- /dev/null +++ b/concepts/0535-email-access-governance-framework/data.json @@ -0,0 +1,12 @@ +{ + "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"], + "name": "Email Access" + "version": "0.1", + "description": "Proof of email access, useful for proving a common identifier and/or validating an email address without performing a live loop-back test." + "last_updated": "2020-09-16", + "docs_uri": "http://github.com/hyperledger/aries-rfcs/blob/master/", + "data_uri": "", + "schemas": ["schemaidhere"], + "roles": ["issuer"], + "rules": [ {"when": {"id": "did:example:abc123"}, "thus": "issuer"} ] +} \ No newline at end of file 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/0812-compression-dictionary/README.md b/concepts/0812-compression-dictionary/README.md new file mode 100644 index 000000000..2f776977f --- /dev/null +++ b/concepts/0812-compression-dictionary/README.md @@ -0,0 +1,176 @@ +# 0812: Compressing DIDComm messages using dictionaries (Ex. 0000: RFC Topic) +- Authors: [Kim Ebert](kim@indicio.tech) +- Status: [PROPOSED](/README.md#proposed) +- Since: 2022- +- Status Note: Compression theory +- Supersedes: +- Start Date: 2022-03-10 +- Tags: [concept](/tags.md#concept) + +## Summary + +Using Dictionary Compression, higher compression rates can be achieved for small messages with known entries. + +## Motivation + +DIDComm messages contain well know values and are often short in size. Using dictionary based compression may reduce the overall size of messages that may be transmitted or stored. + +## Tutorial + +### Training + +The first step is to determine the type of data that needs to be provided for training, and generating a number of requests that meets that criteria. + +An example of creating such an invite using Aca-py and curl + +``` +curl -X POST "http://127.0.0.1:8150/out-of-band/create-invitation" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"alias\": \"\", \"attachments\": [ ], \"handshake_protocols\": [ \"did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/didexchange/1.0\" ], \"metadata\": {}, \"my_label\": \"\", \"use_public_did\": false}" +``` + +Result: + +``` +{"invitation_url": "https://localhost:443?oob=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9vdXQtb2YtYmFuZC8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiYTYwZDhlYTAtZDg1Zi00NDJkLTk0NTktZTk2NWEyYjg3Nzg1IiwgInNlcnZpY2VzIjogW3siaWQiOiAiI2lubGluZSIsICJ0eXBlIjogImRpZC1jb21tdW5pY2F0aW9uIiwgInJlY2lwaWVudEtleXMiOiBbImRpZDprZXk6ejZNa296SGNjNzI0ajlGOFJBR214bTFOY3hpVlhtOE10c0NMQ0paWktacWRwd0Z3Il0sICJyb3V0aW5nS2V5cyI6IFsiZGlkOmtleTp6Nk1rcTNycDg1cm1qTjRwdnN5WUpWTlZoVXZBNUJwTWFlNkd5MlBUUzVZaHdVelIiLCAiZGlkOmtleTp6Nk1rbnZwTmEzQXdWOHl6SHJaM0s3WXVDdU1adXBiSEt0ZDJwVDN4U3NzODRqenEiXSwgInNlcnZpY2VFbmRwb2ludCI6ICJodHRwczovL21lZGlhdG9yNC50ZXN0LmluZGljaW90ZWNoLmlvOjQ0MyJ9XSwgImhhbmRzaGFrZV9wcm90b2NvbHMiOiBbImRpZDpzb3Y6QnpDYnNOWWhNcmpIaXFaRFRVQVNIZztzcGVjL2RpZGV4Y2hhbmdlLzEuMCJdLCAibGFiZWwiOiAiTGFiIn0=", "invitation": {"@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/out-of-band/1.0/invitation", "@id": "a60d8ea0-d85f-442d-9459-e965a2b87785", "services": [{"id": "#inline", "type": "did-communication", "recipientKeys": ["did:key:z6MkozHcc724j9F8RAGmxm1NcxiVXm8MtsCLCJZZKZqdpwFw"], "routingKeys": ["did:key:z6Mkq3rp85rmjN4pvsyYJVNVhUvA5BpMae6Gy2PTS5YhwUzR", "did:key:z6MknvpNa3AwV8yzHrZ3K7YuCuMZupbHKtd2pT3xSss84jzq"], "serviceEndpoint": "https://localhost:443"}], "handshake_protocols": ["did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/didexchange/1.0"], "label": "Lab"}, "state": "initial", "trace": false, "invi_msg_id": "a60d8ea0-d85f-442d-9459-e965a2b87785"} +``` + +We then extract the data required for the invitation. + +``` +{"@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/out-of-band/1.0/invitation", "@id": "2dbf6f36-8dc0-4b35-9558-dab26e3ae3c3", "services": [{"id": "#inline", "type": "did-communication", "recipientKeys": ["did:key:z6MkqfRyf4ycr6HFpo4XyhQp8gBwdBW51Z2yXnxg11AuFZT6"], "routingKeys": ["did:key:z6Mkq3rp85rmjN4pvsyYJVNVhUvA5BpMae6Gy2PTS5YhwUzR", "did:key:z6MknvpNa3AwV8yzHrZ3K7YuCuMZupbHKtd2pT3xSss84jzq"], "serviceEndpoint": "https://localhost:443"}], "handshake_protocols": ["did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/didexchange/1.0"], "label": "Lab"} +``` + +Finally, we strip out the keys that are specific to the local agent, leaving content that can easily be compressed. + +``` +{"@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/out-of-band/1.0/invitation", "@id:": "", "services": [{"id": "#inline", "type": "did-communication", "recipientKeys": ["did:key:"], "routingKeys": ["did:key:", "did:key:"], "serviceEndpoint": "https://:443"}], "handshake_protocols": ["did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/didexchange/1.0"], "label": "Lab"} +``` + +We do this a hundred or so times, and include other configuration options of interest. ( Research into what should be included here could provide some value ) + +We then create the dictionary. + +``` +zstd --train ./data/* -o dict +``` + +This dictionary can now be used to compress the data before it is base64 encoded into the url. + +### The Compressed Out of Band Message + +Using a unique url parameter for compressed out of band messages, the client can determine the alternative behavior to follow. + +The coob message includes the following binary data. The first 4 bytes indicate the dictary to be used, perhaps as an unsiged long. Or alternatively we could use a d= parameter for the storage of the dictionary id. + +Dictionary IDs would be used to indicate which dictionary the client should use. Occassionally, ARIES may release a new dictionary. This new dictionary should not be used for limited time to allow all clients to get the latest dictionaries. These dictionaries could be auto-retrieved by the clients when connection to the internet is available. + +The rest of the coob data is the a compressed zstd binary output. After the binary data is combined together, the data is base64url encoded. + +``` +https://localhost:443?c=sztd&d=1&oob=KLUv_Wc3PnoBMAG1BgBijCwjEIfWAzs-1Bd8YPpweoDAqvElxVlFB2t_B0mLRHdVVVVVwQ1ZRjAL7yxb-TIysjm8Ed-yTeWLF1qo8MlxiEaMtHI3fSrdFbppodFuTwhO6WsiVbU3ECY-bHpEdFBAg8QUpAG-8RKYVKWACeQ87VWx2H7qLWqW-QNtLAt11M6HIEmkxwYucGqk1akI2O1ABcPSONJHGQaQDJnr8mtWyfL4Ho4t6nhZ-XGX-8dUCIn_JQ8CCgCVXyJ1RAnO_AEwww7QY1FQCCwIETfkSRDzzwJ-R-kV6uOdbQ== +``` + +The URL is reduced from 794 bytes to 370 bytes.(46.6 % of original size) There difference in the QR codes can be seen below. + +![](./b9y8VTC.png) +![](./YlU3M52.png) + +### Redirect on failure + +If the client cannot decode the coob message, or does not have the appropriate dictionary, the client can visit the url and will be redirected to the decompressed url. + +## Dictionary Storage + +Dictionaries could be stored along side the RFCs, or an alternative method for transfering dictionaries between clients could be derived. + +## Drawbacks + +Dictionaries may need to be regularly rebuilt to adjust to new protocols. Some dictionaries may not provide any compression benefits depending upon the message. + +## Rationale and alternatives + +### QR Code Quality + +By reducing the size of QR codes for offline or cases where URL redirects are not available, the QR code becomes more manageable. + +### Reducing need for redirect support + +URL Shorterning services may introduce privacy concerns + +### Binary based format + +Instead of using compression, a binary file format would reduce overall message size. + +### Standard Compression without dictionaries + +#### gzip + +Using + +``` +gzip -9 +``` + +We can reduce the size of the Out of Band invitation. + +``` +https://localhost:443?c=gzip&oob=H4sICODx-mUCA3RtcC50eHQAhZFdb5swFIbv9ysqdjtCykdC2E3TbC1qCpqaDy1M02Ts03CSYDvYkEDV_z6cTVsvJu3a5338nPO-WDe6lWBFVxZDFinRRLfdLFfppkiqXYzH7NNyNV3E249KAnVErW3xbOeEM-d6MHSQN6iJRsGtD1fWDTIDIqMhC4EMbRYGz7bvu8ye-MHEhskoIG4ejsdhYMYVVA1SUH3m24v1K_se-QE5mOc3XjYVZVlzpH--qoCiROB6Du0FcNHfQxt1o2QvupjSsevvJnfh0_S-PJfXKT3j-msZJlrNHmcPWTbPjkye7k7Wd4PrF0O-_Sfs6FUyDKpyl_qyUe3mYZ2ui1UzDW5lQmB037pflotgU5xW3ZNRe5vljUyJNz2tw7aLq8ybjzf1rE6yWubxXDNXLr3zQqnQ33XHi8jvm3zmTArk2uxfaC1V5DglMCRaVP5Ag9ID5AwpCg20GKCIfN-zXg2h6LtRBdnDD1kJLag4_F3pf_X2M3CmPWELpt6L0YHkcDAejyS3Xt_9BC2pH8MxAgAA +``` + +Using gzip, we can reduce the size of the Out of Band invitation from 775 bytes to 590 bytes. (76.13 % of original size) + +#### ZSTD without a dictionary + +Using + +``` +zstd -9 +``` + +We can reduce the size of the Out of Band invitation. + +``` +https://localhost:443?c=zstd&oob=KLUv_WQxAW0MAPbYVCjgzMwDaJPAFkV01uPxaHNM71pq1L8QfLwg044FcGs2cBMMwwwjDC8ESQBJAE4AEMhKUkIT1LRQg_q0DQe1XxAXAvHi33T_dz9qMAYie6kGTWBoeziqnjVBxqJELJWDrPOWprs2DKY1SWhQfVhX9m1cVNEzuAsiRQsSBone1-QeLv-p2AD34RQiDjMBopHSo1YrxJvLEVagb0Cf7Oufv3pX_3ochyvk9zn3AyIFxKKK2ut_nWtqPh5TkyjlgDgEoWSa8pkqWbJ7YmnZyy5P4mEekynrrBCcF09kolj-rkNo8WwYilJpkEAFh9MrG1CRz7JdsMsCBtRflpiG66iZu6mTub89HBE9CZ5sO9kkywIAFVGjDBzXKMczl2714_YtB1e8cZclfEM3bS_dKuIkZYWfsVXf-Ovb-4ytfTNkhzd961wUVTrvve37ONuLEBE7oUZOHRQgMMKgpQeLQytzAcvFxYE1CCvGeoAVfTFYf7zoaWmohyZtK6wtoqCuRTa3JQrbbxSl8RATCDPtnYPf +``` + +Using zstd without a dictionary, we can reduce the Out of Band invitation from 775 bytes to 582 bytes. (75.10 % of original size) + +### DIDComm Compression + +It would be possible to use compression in DIDComm communications. Each message would be compressed individually, as DIDComm doesn't guarentee the order of messages being delievered. + +Things to consider + +* Compress may not want to be used until Discover features is shared +* It may be possible to sharing custom dictionaries as a separate protocol + +### Process of creating new dictionaries + +To be defined + +### Distribution of dictionaries + +If dictionaries are used, they should be included in DIDComm libraries +The dictionaries may be a dependency of a DIDComm library + +## Prior art + +[zstd] (http://facebook.github.io/zstd/) +[zstd manual](https://github.com/facebook/zstd/blob/dev/programs/zstd.1.md) +[brotli](https://datatracker.ietf.org/doc/html/rfc7932) +[zlib](https://en.wikipedia.org/wiki/Zlib) +[DEFLATE](https://datatracker.ietf.org/doc/html/rfc1951) + +## Unresolved questions + +- Where are dictionaries stored +- How do we specify compression will be used for DIDComm messages +- What to do when a client doesn't support compression. + +## Implementations + +*Implementation Notes* [may need to include a link to test results](/README.md#accepted). + +Name / Link | Implementation Notes +--- | --- + | + diff --git a/concepts/0812-compression-dictionary/YlU3M52.png b/concepts/0812-compression-dictionary/YlU3M52.png new file mode 100644 index 000000000..9bbc91b0c Binary files /dev/null and b/concepts/0812-compression-dictionary/YlU3M52.png differ diff --git a/concepts/0812-compression-dictionary/b9y8VTC.png b/concepts/0812-compression-dictionary/b9y8VTC.png new file mode 100644 index 000000000..db516c447 Binary files /dev/null and b/concepts/0812-compression-dictionary/b9y8VTC.png differ 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/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 66a271b21..01f90d316 100644 --- a/features/0434-outofband/README.md +++ b/features/0434-outofband/README.md @@ -352,6 +352,8 @@ The standard out-of-band message format is a URL with a **Base64Url** encoded js 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: ```text @@ -395,13 +397,13 @@ Whitespace removed: Base64Url encoded: ```text -eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0= +eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0 ``` Example URL with Base64Url encoded message: ```text -http://example.com/ssi?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0= +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. @@ -419,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=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0=) 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=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4wL2ludml0YXRpb24iLCJAaWQiOiI2OTIxMmEzYS1kMDY4LTRmOWQtYTJkZC00NzQxYmNhODlhZjMiLCJsYWJlbCI6IkZhYmVyIENvbGxlZ2UiLCJnb2FsX2NvZGUiOiJpc3N1ZS12YyIsImdvYWwiOiJUbyBpc3N1ZSBhIEZhYmVyIENvbGxlZ2UgR3JhZHVhdGUgY3JlZGVudGlhbCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9kaWRleGNoYW5nZS8xLjAiLCJodHRwczovL2RpZGNvbW0ub3JnL2Nvbm5lY3Rpb25zLzEuMCJdLCJzZXJ2aWNlcyI6WyJkaWQ6c292OkxqZ3BTVDJyanNveFllZ1FEUm03RUwiXX0= +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. diff --git a/features/0721-revocation-notification-v2/README.md b/features/0721-revocation-notification-v2/README.md index 585e073cf..3b3af4e2d 100644 --- a/features/0721-revocation-notification-v2/README.md +++ b/features/0721-revocation-notification-v2/README.md @@ -17,7 +17,7 @@ This RFC defines the message format which an issuer uses to notify a holder that ## Motivation -We need a standard protocol for an issuer to notify a holder that a previously issued credential has been revoked. +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 @@ -25,28 +25,55 @@ knows that she will be unable to use her passport to travel. ## Tutorial -The Revocation Notification protocol is a very simple protocol consisting of a single message: +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. +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 revoked. It is not a security risk if the issuer does not notify the holder that the credential has been revoked, nor if the message is lost. The holder will still be unable to use a revoked credential without this notification. +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` message to the `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.0/revoke", + "@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": "", 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/mkdocs-requirements.txt b/mkdocs-requirements.txt index d5e48dbc1..05cd7cb50 100644 --- a/mkdocs-requirements.txt +++ b/mkdocs-requirements.txt @@ -1,3 +1,3 @@ -mkdocs-material==9.5.26 -mike==2.1.1 +mkdocs-material==9.5.39 +mike==2.1.3