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

Jump to bottom

add DCLOGIN uri scheme #48

Merged
merged 10 commits into from
Sep 28, 2022
Merged

add DCLOGIN uri scheme #48

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c304e8f
add `DCLOGIN` uri scheme
Simon-Laux Jul 5, 2022
4c630be
document json and move the version to the end
Simon-Laux Jul 5, 2022
97b3416
uri based scheme instead of json
Simon-Laux Jul 10, 2022
b5309b7
dclogin-scheme: discourage usage of full names
Simon-Laux Jul 14, 2022
a095a0e
only use short names
Simon-Laux Jul 14, 2022
7f23e56
move password to `p` $GET-field
Simon-Laux Jul 19, 2022
77301ab
2 more syntax examples for `dclogin:`
Simon-Laux Aug 4, 2022
52a7a5e
apply link2xt's suggestions
Simon-Laux Aug 9, 2022
2600109
address flub's comment
Simon-Laux Sep 12, 2022
42e6f10
clarify that `dclogin://` is prefered
Simon-Laux Sep 12, 2022
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
98 changes: 98 additions & 0 deletions uri-schemes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,8 @@ see the [mailadm](https://github.com/deltachat/mailadm) project for more details
DCACCOUNT:https://example.org/new_email?t=1w_7wDjgjelxeX884x96v3
```

You may want to use [`DCLOGIN`](#DCLOGIN) instead, if you want a qr code containing login information for a single account.

#### The http endpoint needs the following api:

##### On Success
Expand Down Expand Up @@ -124,6 +126,102 @@ HTTP Status code: NOT 2XX, idealy the 4XX if it's user error and 5XX if it's the

json object can have other properties too, but currently they are ignored by core.

## **DCLOGIN** <a name="DCLOGIN"></a>

| | |
| ------------------------ | --------------------- |
| Scheme | `DCLOGIN:` |
| Used for | Account setup |
| Related Terms\* | Account Login QR code |
| Available on | draft |
| Decoded by the core \*\* | draft |
| Other apps using it | none, only DeltaChat |

### Syntax

The generic URI schema is:

URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment]
authority = [userinfo "@"] host [":" port]

For DCLOGIN this means:
- *scheme* is always dclogin
- There must be an *authority* section
- The *userinfo* part is required.
- The *path* may be omitted or be a single `/`.
- The fragment must be omitted.
- The query parameters are described down below.

Examples:
```
dclogin://user@host/?p=password&v=1[&options]
# example: (email: me@example.com, password: securePassword)
dclogin://me@example.com?p=securePassword&v=1
# example: (email: myself@example.com, password: url/Encoded\@passw@rd)
dclogin://myself@example.com?p=url%2FEncoded%5C%40passw%40rd&v=1
# example: (email: myself@example.com, password: 123456, insecure smtp at different server)
dclogin://myself@example.com?p=123456&v=1&sh=mail.example.com&sc=3&ss=plain
```

#### Options `?options`

Format: URL Query parameters also known as GET variables (`varname=value` behind the question mark, chained/delimited by `&`)

The query parameters contain advanced options and a version parameter.
All advanced options are optional except for `v` and `p`, which are the only required options at this point.
(BTW: Later/Other versions in the future might specify a different authentication and thus `p` might become unnecessary in those formats.)

| short name | stands for | description | example |
| ---------- | ------------------------- | --------------------------------------------------- | --------------------- |
| `v` | `version` | defines the format version, more explanation below | `v=1` |
| `p` | `password` | required in version 1, password of the account | |
Copy link
Contributor

Choose a reason for hiding this comment

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

I would not require p= in the options if it is supplied in the userinfo part.

| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `ih` | `imap_host` | IMAP host | `ih=imap.example.com` |
Copy link
Member

Choose a reason for hiding this comment

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

mmh ok so actually the host can be specified in options, then splitting the email address in local part and host kinda feels unnecessary 🤔

Copy link
Member Author

@Simon-Laux Simon-Laux Jul 11, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

it's because url spec has username:password@host as format, so to be consistent with other schemes/standards

Copy link
Member

@r10s r10s Jul 11, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

following this "auth spec" seems not to be needed and does not really match anyway as we have to deal with potentially two different usernames and passwords. and if we follow: the part before the colon is the username, so that would be the full email address in many, but of course not all cases.

so, trying to reconstruct the email address and username from different parts is doable, but would results in quite some "if" and unneeded complexity.

it seems much easier to have a dedicated field for the email address: DCLOGIN:?a=foo%40bar.de&ipw= password just map everything 1:1 to the existing config fields. having that as a parameter also eliminates doubts how and if to urlencode, it is just all the same.

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not sure we need to "simplify" everything that much,

maybe DCLOGIN:email@example.com?pw=1234&v=1, but I don't see the big benefit in specifying everything in the query part, though we could do it, minimum version (no advanced options) would then look like:

DCLOGIN:?a=email@example.com&p=1234&v=1

and when reusing the existing imap password field (though that might be more annoying to explain than an extra property):

DCLOGIN:?a=email@example.com&ipw=1234&v=1

BTW: the v=1 is there for future proofing, that we can increase this number to force specific advanced options like oauth2 or similar in the future, if it's a number not supported by dc it will tell the user to update the app.

Copy link
Contributor

@missytake missytake Sep 27, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

We also can have separate passwords for IMAP & SMTP, right? So what about recommending DCLOGIN://user:password@example.com/?v=1 as default, not having a p= option at all, but instead smtp_password= and imap_password= options, which override the password in the "authority" field?

That would feel most intuitive for me, and kind of maps the login field with the advanced login settings.

edit: I just saw that there are smtp_password and imap_password parameters already 🙃 I like to have the password in the front, as it makes it clearer what overrides which imho.

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not really willing to change everything at this stage again, r10s is right that it might be more complicated to do it in the userinfo part (because URI encoding and stuff like that, passwords tend to contain special characters)

| `ip` | `imap_port` | IMAP port | `ip=993` |
| `iu` | `imap_username` | IMAP username | |
| `ipw` | `imap_password` | IMAP password | |
| `is` | `imap_security` | IMAP security: "`ssl`" or "`default`" or "`plain`" | `is=ssl` |
| `ic` | `imap_certificate_checks` | IMAP certificate checks, see below for options | `ic=1` |
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `sh` | `smtp_host` | SMTP host | `sh=mail.example.com` |
| `sp` | `smtp_port` | SMTP port | `sp=465` |
| `su` | `smtp_username` | SMTP username | |
| `spw` | `smtp_password` | SMTP password | |
| `ss` | `smtp_security` | SMTP security: "`ssl`", "`starttls`" or "`plain`" | `ss=plain` |
| `sc` | `smtp_certificate_checks` | SMTP certificate checks, see below for options | `sc=3` |

#### format version

Format version:
Used for breaking new versions that add new **required** properties, basically deltachat checks for this and if it's newer than the version deltachat supports it prompts the user to update the app.

The version number only increases on incompatible changes (changes to required properties).

#### `CertificateChecks`

| code | name & description |
| ---- | ---------------------------------------------------------------------------------------------------------------- |
| 0 | `Automatic`, same as `AcceptInvalidCertificates` unless overridden by `strict_tls` setting in provider database. |
| 1 | `Strict` |
| 3 | `AcceptInvalidCertificates` |

#### Important information for using the `DCLOGIN:` scheme

- There is a maximum length of how much data fits in side of a qr code (depending on the error correction level 1273 chars to 2953 chars)
- only use the short names for advanced properties
- If working with long domains/password/usernames in advanced options, **consider creating a configuration file at the server instead** using either [Autoconfigure](https://web.archive.org/web/20210402044801/https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration)
- **Every value** (username & password too) **needs to be URI encoded**:
- [`encodeURIComponent()` in JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)

#### Implementation hints

implementations should be somewhat tolerant:

- both `dclogin:` and `dclogin://` should work (though only `dclogin://` is technically correct)
- **only** implement short names (not the full names they stand for)
- have a test for usename+extension@host cases
- if version number is higher than what is implemented, tell the user to update

## **DCWEBRTC**

| | |
Expand Down