Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

first draft #2

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

first draft #2

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1e49b14
first draft
Gozala Jan 7, 2023
66b1a16
Apply suggestions from code review
Gozala Jan 7, 2023
6b94060
Update words-to-ignore.txt
Gozala Jan 7, 2023
aa48c29
Update README.md
Gozala Jan 7, 2023
7ac044a
Update words-to-ignore.txt
Gozala Jan 7, 2023
47c09c2
Update README.md
Gozala Jan 7, 2023
6bd7e0e
Update words-to-ignore.txt
Gozala Jan 7, 2023
736027a
Update README.md
Gozala Jan 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/words-to-ignore.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
CIDs
DIDs
Hardt
Holmgren
JSON
Expand All @@ -20,6 +21,7 @@ requestor's
responder
signalling
trustless
publicness
v0
validator
gozala
Expand All @@ -39,6 +41,12 @@ URIs
interop
permissionless
stateful
dns
ABNF
RFC1035
RFC1123
RFC2181
RFC2822

# actually correct
reimagine
Expand Down
150 changes: 149 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,150 @@
# did-mailto
did:mailto Method Specification

## 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The DID method specification MUST define sensitivity and normalization of the value of the method-specific-id.

https://www.w3.org/TR/did-core/#method-syntax

It's probably good to appease that MUST by having a small section on normalization. e.g. is it safe to canonicalize did:mailto:dag.house:bEnGo to did:mailto:dag.house:bengo?

I think the answer is no?

The
local-part of a mailbox MUST BE treated as case sensitive.

https://www.rfc-editor.org/rfc/rfc5321#section-2.4

Copy link

@blaine blaine Jan 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a fan of the canonicalization complexity here. I have a bunch of use-cases for this sort of approach that extend beyond did:mailto: and can see the complexity spiralling out of control. This is not helped by the fact that these identifiers need to be checked with a simple string comparison; using modified "canonical" identifiers runs the risk of changing the security semantics.

tbh, if the intent of the did scheme is to be opaque, I'd prefer:

aud: did:mailto:${multihash(email)} along with some other field (maybe in fct?) that clearly states the hashed email address according to 5321 rules (but not canonicalized). (repeat for other schemes as necessary)

Looking through the DID/VC specs, it seems like this is the same conclusion that the VC folks came to: https://www.w3.org/TR/vc-data-model/#identifiers – specifically, there's a separate id field that is the raw URI identifier, separate from the credentialSubject did (unless I'm misreading this; there's a lot in these specs, and I may very well have missed something).

That all said, I would love to be convinced that the canonicalization is possible to do reliably; I just feel like there are too many unknowns there to be confident about it.


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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any advantages to domain-name ":" user-name over user-name%40domain-name over the precieved uglyness of "%40"?

If no then I'd favor user-name%40domain-name because extracting it from the DID is way simplier.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My rationale was:

  1. Unfortunately new URL(“did:mailto:[email protected]”) does not get escaped, so it’s seems more likely to encounter malformed versions unless encoding is distinct enough
  2. DIDs seem to love : delimiter, did:web even goes as far as replacing / with them, so this seemed reasonable
  3. And yeah I find it harder to read

Above said I’m not feeling strongly about this

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fwiw I also kinda prefer the simplicity of just did:mailto:pct-encoded-email-address

We could also establish some norms around, regardless of did mailto, what to do if someone sends you a did that is not actually a valid did, e.g. did:mailto:[email protected] or just did:whatever:[email protected]. We could just say "percent-encode any colon-delimited segment in method-specific-id that isn't already in the valid alphabet, and implement that in @ipld/dag-ucan or something in DID.from

DID.from('did:whatever:[email protected]')
// did:whatever:bengo%40dag.house

This is a little inspired by how web browsers in practice don't always show you the perfectly encoded URL in the URL bar. It does its best to decode the url-like strings you put in there. If we do something like that, maybe we can avoid the annoyance of %40 instead of @ because a lot of our tooling will accept the @ and only throw when it really needs to be strict about being a compliant did.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just wanted to add as an additional perspective: we use DIDs as domain-style origins within a human-author-able link syntax. For example, a user may write:

@did:key:.../foo

...or...

@did:web:example.com/foo

In the case of did:key, it is not convenient for a human to write by hand w/o copy-pasting the DID. In practice, we implement a petname system and alias DIDs by petnames that are easy for humans to write.

But, with did:web (and perhaps did:mailto), it is more plausible that a human will author a DID by hand, or read a link with a bare (not-petname-aliased) DID in it. And, for that case it would be preferable for did:mailto to be written and rendered without a %-encoded @ in the email address.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it would be preferable for did:mailto to be written and rendered without a %-encoded @ in the email address.

I think we can accomodate this by in practice users just typing did:mailto:[email protected] but anywhere that gets that string as input and is casting it to a valid did needs to pct-encode the :-delimited segments to match syntax requirements of DIDs.

i.e. if the method-specific-identifier contains a @, you can tell it's not a valid DID, but that it wants to be a did:mailto, so software can deterministically get to a valid did by pct-encoding the email address.

user-name = 1*idchar
idchar = ALPHA / DIGIT / "." / "-" / "_" / pct_enc
pct_enc = "%" HEXDIG HEXDIG
```

##### EXAMPLE 1. A [email protected]

```
did:mailto:example.com:jsmith
```

##### EXAMPLE 2 [email protected]

```
did:mailto:web.mail:tag%2Balice
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@blaine and I talked about the %-encoding a bit yesterday. I don't think the ugly %s are the end of the world, buthave you considered making this either a multibase or a hash?

A hash seems strange at first, but since you will have that info in the DKIM or similar later, you can validate it at that time. The downside is that it's harder for a human to track visually, but a fringe benefit is that you don't have to worry about encoding and they're constant size.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@blaine and I talked about the %-encoding a bit yesterday. I don't think the ugly %s are the end of the world, buthave you considered making this either a multibase or a hash?

I was mostly bothered about this in because it would turn @ into %40 which is why I end up moving username into the tail of the did. Otherwise I think most email addresses won't actually encounter this so probably not a big deal ?

I have thought about hashes, but mostly for the user privacy, but then realized it probably won't provide much. At the moment I think %-encoding a reasonable compromise and seems to be expected approach for DIDs, but I'm fine taking it other way.

A hash seems strange at first, but since you will have that info in the DKIM or similar later, you can validate it at that time. The downside is that it's harder for a human to track visually, but a fringe benefit is that you don't have to worry about encoding and they're constant size.

I would prefer to not to with DKIM assumption, because we already have a system in place that adds did:mailto support without it, which I think will continue to be useful even when we implement DKIM support.

```

## 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
Copy link

@gobengo gobengo Jan 9, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be good to make a distinction between 'key authentication' and 'subject aliasing'. DID documents support both, but they're not identical. It looks like this section here, because it mentions 'I am also known as' seems like the human-readable instruction is more about subject aliasing and did-core alsoKnownAs.

"Key Authentication" could be confused with did-core's Authentication verification relationship. This is how a did can use its did document to enumerate the ways (e.g. a signing key) someone can authenticate as the did.

If you alias from your did:mailto:ab:c via alsoKnownAs to did:key:abc, you're authorizing did:key for all verification relationships, not just authentication but also assertionMethod, capabilityInvocation, and capabilityDelegation

So whereas the spec currently calls this "Key Authentication", what it's doing by using did alsoKnownAs is quite a bit more than that, and we might want to either:

  • call what the spec currently does "DID Aliasing" and leave the perhaps-ambiguous 'key-authentication' unused
    • if you want to, say 'and you can only alias to did:key' (for now)
    • I think this is the best thing to do
  • keep supporting a 'key-authentication', but have it only affect the derrived did document by adding an authentication verification method (not using alsoKnownAs
    • and maybe as the human readable string use I use {did:key} for {verificationMethod} where verificationMethod can be authentication


```abnf
auth = "I am also known as " did-key-format
```

##### EXAMLPLE 3
Gozala marked this conversation as resolved.
Show resolved Hide resolved

```
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)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the biggest reasons to revoke would be because the user lost access to the email address. Is there a way to revoke in this case?

How do I prevent any other user from claiming my did:key:x? Is it correct that we don't have to...because anything I send with issuer as did:mailto:x has to be signed with the private key for did:key:x.

Assuming that is true, anyone could claim they are known as did:key:x, but they wouldn't be able to act as did:key:x because they don't have the private key.

So then, presumably if I have multiple email addresses I can register them all as being aka did:key:x, so my question is what does "I revoke ..." mean?

Without signed proof, you can't revoke the use of did:key:x (since we don't know you have the private key) but it could revoke the use of the senders email address as an alias of did:key:x. Perhaps it is better for this to read "I am no longer also known as..."?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the biggest reasons to revoke would be because the user lost access to the email address. Is there a way to revoke in this case?

Note that revocation here implies revoking a key as opposed to revoking a whatever permissions email has, which is I think what you’re thinking of. If I don’t have access to the email, I may want to revoke it’s privileges but that is to be done at another layer - delegation to the email address. That is out of scope here.

Reason you’d want to revoke here is because you’ve lost a private key, or perhaps key got compromised.

How do I prevent any other user from claiming my did:key:x? Is it correct that we don't have to...because anything I send with issuer as did:mailto:x has to be signed with the private key for did:key:x.

If someone say [email protected] associates my key with their email they are essentially granting me all the privileges that email address has, which is opposite of what they would want so there is no initiative to do this.

Assuming that is true, anyone could claim they are known as did:key:x, but they wouldn't be able to act as did:key:x because they don't have the private key.

I think you could put it that way.

Without signed proof, you can't revoke the use of did:key:x (since we don't know you have the private key) but it could revoke the use of the senders email address as an alias of did:key:x.

I think you’re thinking of association in opposite direction.

If I send you an email saying X is my key it’s reasonable to expect that messages signed by that key is from the owner of that email. If I then send you a message (from the same email address) saying I no longer use that X key it is reasonable to expect that if you see message signed with that key X it’s probably an attacker trying to impersonate me.

Here you trust that messages are from trusted source (email address) and what you verify is the DKIM signature to ensure that email is indeed from the owner of the address.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I understand thanks for the clarification.


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
```

##### EXAMLPLE 3
Gozala marked this conversation as resolved.
Show resolved Hide resolved

```
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/
[session keys]: https://en.wikipedia.org/wiki/Session_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
[dkim]: https://www.rfc-editor.org/rfc/rfc6376
[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