From 1c632b202795798d946eebcc957d11f87c534480 Mon Sep 17 00:00:00 2001 From: Irakli Gozalishvili Date: Fri, 19 Jan 2024 10:23:04 -0800 Subject: [PATCH 1/3] chore: import did:mailto spec --- did-mailto.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 did-mailto.md diff --git a/did-mailto.md b/did-mailto.md new file mode 100644 index 0000000..19649e5 --- /dev/null +++ b/did-mailto.md @@ -0,0 +1,148 @@ +# did-mailto + +## Editors + +- [Irakli Gozalishvili](https://github.com/Gozala), [DAG House](https://dag.house/) + +## Authors + +- [Irakli Gozalishvili](https://github.com/Gozala), [DAG House](https://dag.house/) + +## Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## Abstract + +This specification describes "mailto" [DID Method] that +conforms to the core [DID-CORE] specification. The method can be used independent of any central source of truth, and is intended for bootstrapping secure interaction between two parties that can span across arbitrary number of devices. It is suitable for long sessions that need to operating under network partitions. + +## Status of This Document + +This document is draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organization. + +## Introduction + +### Overview + +> This section is non-normative. + +Most documentation about decentralized identifiers (DIDs) describes them as identifiers that are rooted in a public source of truth like a blockchain, a database, or similar. This publicness lets arbitrary parties resolve the DIDs to an endpoint and keys. It is an important feature for many use cases. + +However, the vast majority of interactions between people, organizations, and things have simpler requirements. When Alice(Corp|Device) and Bob want to interact, there are exactly and only 2 parties in the world who should care: Alice and Bob. Instead of arbitrary parties needing to resolve their DIDs, only Alice and Bob do. + +One to one interactions are excellent fit for [did:key] identifiers, however they suffer from key discovery problem and introduce additional challenges when interaction sessions span across more than two devices. + +Mailto DIDs are designed to be used in conjunction with [did:key] and facilitate bootstrapping sessions between two parties that span across multiple devices. + +Mailto DIDs are more accessible alternative to [did:web] and [did:dns] because a lot more people have an email address than there are people with [did:web] or [did:dns] identifier or skills to acquire one. + +Mailto [did document]s are also verifiable offline, when [domain key][] of the email address is known, implying significantly less network requests than with most other DIDs. + +## The `did:mailto` Format + +The format for the `did:key` method conforms to the [DID-CORE] specification and is encoding of the [email address]. It consists of the `did:mailto:` prefix, followed by the `domain` part of an email address, `:` character and percent encoded `local-part` of the email address. + +The ABNF definition can be found below. The formal rules describing valid `domain-name` syntax are described in [RFC1035], [RFC1123], [RFC2181]. The `domain-name` and `user-name` corresponds to `domain` and `local-part` respectively of the email address described in [RFC2822]. All "mailto" DIDs MUST conform to the DID Syntax ABNF Rules. + +```abnf +did = "did:mailto:" domain-name ":" user-name +user-name = 1*idchar +idchar = ALPHA / DIGIT / "." / "-" / "_" / pct_enc +pct_enc = "%" HEXDIG HEXDIG +``` + +##### EXAMPLE 1. A + +``` +did:mailto:example.com:jsmith +``` + +##### EXAMPLE 2 + +``` +did:mailto:web.mail:tag%2Balice +``` + +## Operations + +The following section outlines the DID operations for the `did:mailto` method. + +### Create (Register) + +There is intentionally no specification for publishing `did:mailto` documents as single source of truth are not implied. Same `did:mailto` identifier MAY (intentionally) correspond to different [DID document] in different sessions. + +Creating a `did:mailto` document is done by: + +1. Creating a [did:key] identifier. +2. Sending an email from [DID Subject] email address with a [key authentication] message in the subject. + +#### Key Authentication + +Key authentication message must conform to the following ABNF definition, which refers to `did-key-format` defined in [did:key] specification + +```abnf +auth = "I am also known as " did-key-format +``` + +##### EXAMPLE 3 + +``` +I am also known as did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK +``` + +### Read (Resolve) + +Specification intentionally does not specify how to resolve [DKIM-Signature] for the given `did:mailto` identifier as those could be arranged out of bound between participants. Optional programmatic resolution over [SMTP] could be defined in the future iterations. + +The following steps MUST be executed to resolve the [DID document] from the [DKIM-Signature]: + +1. Extract [key authentication] from the `subject` header. +1. Extract [did:key] from the extracted [key authentication]. +1. Extract sender email address from the `from` header. +1. Resolve [DID document] from extracted [did:key]. +1. Set `id` of the [DID document] to the `did:mailto` identifier of the sender email address. +1. Set `alsoKnownAs` of the document to extracted [did:key]. + +### Deactivate (Revoke) + +Specification intentionally does not specify how to communicate [DKIM-Signature] for deactivating the DID Document. + +[DID Subject] may deactivate specific [DID document] by: + +1. Sending an email from [DID Subject] email address with with a [key revocation] message in the subject. + +#### Key Revocation + +Key revocation message must conform to the following ABNF definition, which refers to `did-key-format` defined in [did:key] specification + +```abnf +auth = "I revoke " did-key-format +``` + +##### EXAMPLE 3 + +``` +I revoke did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK +``` + +### Update + +This DID Method does not support updating the DID Document. + +[did subject]: https://www.w3.org/TR/did-core/#did-subject +[did method]: https://w3c-ccg.github.io/did-spec/#specific-did-method-schemes +[did-core]: https://w3c-ccg.github.io/did-spec/ +[did document]: https://www.w3.org/TR/did-core/#dfn-did-documents +[did:key]: https://w3c-ccg.github.io/did-method-key/ +[did:web]: https://w3c-ccg.github.io/did-method-web/ +[did:dns]: https://danubetech.github.io/did-method-dns/ +[email address]: https://www.rfc-editor.org/rfc/rfc2822.html#section-3.4.1 +[rfc2822]: https://www.rfc-editor.org/rfc/rfc2822.html#section-3.4.1 +[rfc1035]: https://www.rfc-editor.org/rfc/rfc1035 +[rfc1123]: https://www.rfc-editor.org/rfc/rfc1123 +[rfc2181]: https://www.rfc-editor.org/rfc/rfc2181 +[key authentication]: #Key_Authentication +[key revocation]: #Key_Revocation +[dkim-signature]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail +[smtp]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol From 606af9c3c035f4dc291f6b7f2069c48bf2eda91b Mon Sep 17 00:00:00 2001 From: Irakli Gozalishvili Date: Fri, 19 Jan 2024 10:26:59 -0800 Subject: [PATCH 2/3] fix: ignore some words --- .github/workflows/words-to-ignore.txt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/words-to-ignore.txt b/.github/workflows/words-to-ignore.txt index 3c54472..8625fc7 100644 --- a/.github/workflows/words-to-ignore.txt +++ b/.github/workflows/words-to-ignore.txt @@ -134,3 +134,12 @@ Irakli Gozalishvili Vasco invoker +DIDs +dns +DNS +RFC1035 +RFC1123 +RFC2181 +RFC2822 +SMTP +publicness From 025e280b45a032727b71514234d6c362961f1356 Mon Sep 17 00:00:00 2001 From: Irakli Gozalishvili Date: Fri, 19 Jan 2024 17:49:11 -0800 Subject: [PATCH 3/3] fix: markdown --- did-mailto.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/did-mailto.md b/did-mailto.md index 19649e5..4fbdd32 100644 --- a/did-mailto.md +++ b/did-mailto.md @@ -37,7 +37,7 @@ Mailto DIDs are designed to be used in conjunction with [did:key] and facilitate Mailto DIDs are more accessible alternative to [did:web] and [did:dns] because a lot more people have an email address than there are people with [did:web] or [did:dns] identifier or skills to acquire one. -Mailto [did document]s are also verifiable offline, when [domain key][] of the email address is known, implying significantly less network requests than with most other DIDs. +Mailto [did document]s are also verifiable offline, when [domain key] of the email address is known, implying significantly less network requests than with most other DIDs. ## The `did:mailto` Format @@ -52,15 +52,15 @@ idchar = ALPHA / DIGIT / "." / "-" / "_" / pct_enc pct_enc = "%" HEXDIG HEXDIG ``` -##### EXAMPLE 1. A +### EXAMPLE 1. -``` +```txt did:mailto:example.com:jsmith ``` -##### EXAMPLE 2 +### EXAMPLE 2. -``` +```txt did:mailto:web.mail:tag%2Balice ``` @@ -87,7 +87,7 @@ auth = "I am also known as " did-key-format ##### EXAMPLE 3 -``` +```txt I am also known as did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK ``` @@ -110,7 +110,7 @@ Specification intentionally does not specify how to communicate [DKIM-Signature] [DID Subject] may deactivate specific [DID document] by: -1. Sending an email from [DID Subject] email address with with a [key revocation] message in the subject. +1. Sending an email from [DID Subject] email address with a [key revocation] message in the subject. #### Key Revocation @@ -122,7 +122,7 @@ auth = "I revoke " did-key-format ##### EXAMPLE 3 -``` +```txt I revoke did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK ``` @@ -142,7 +142,8 @@ This DID Method does not support updating the DID Document. [rfc1035]: https://www.rfc-editor.org/rfc/rfc1035 [rfc1123]: https://www.rfc-editor.org/rfc/rfc1123 [rfc2181]: https://www.rfc-editor.org/rfc/rfc2181 -[key authentication]: #Key_Authentication -[key revocation]: #Key_Revocation +[Key Authentication]: #key-authentication +[Key Revocation]: #key-revocation [dkim-signature]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail [smtp]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol +[domain key]:https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail