-
-
Notifications
You must be signed in to change notification settings - Fork 3
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.
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
add DCLOGIN
uri scheme
#48
Changes from 7 commits
c304e8f
4c630be
97b3416
b5309b7
a095a0e
7f23e56
77301ab
52a7a5e
2600109
42e6f10
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -124,6 +126,91 @@ 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 | ||
|
||
``` | ||
dclogin:user@host?p=password&v=1[&options] | ||
dclogin:user@host/?p=password&v=1[&options] | ||
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 | | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would not require |
||
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- | | ||
| `ih` | `imap_host` | IMAP host | `ih=imap.example.com` | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 🤔 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. it's because url spec has There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not sure we need to "simplify" everything that much, maybe
and when reusing the existing imap password field (though that might be more annoying to explain than an extra property):
BTW: the There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe 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` | | ||
|
||
#### `minVersion` | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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) or [Autodiscover](<https://technet.microsoft.com/library/bb124251(v=exchg.150).aspx>) | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- **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) | ||
- note that email username and password are in different order, than email: `username:password@host` vs. `username@host` | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
#### Implementation hints | ||
|
||
implementations should be somewhat tolerant: | ||
|
||
- both `dclogin:` and `dclogin://` should work | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- only implement short names (not the full names they stand for) | ||
- have a test for usename+extention@host cases | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- if version is bigger than whats implemented tell the user to update | ||
Simon-Laux marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## **DCWEBRTC** | ||
|
||
| | | | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you're diverging a bit far from the URI syntax.
I'd refer to the URI spec and say:
userinfo
host
/
for pathThis means example 1 and 2 should be considered invalid.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
so
path
is allowed to be emtpy, may as well omit/
in that case.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So force using
://
at beginning and no / for the path?It is parsed by an URL parser lib we already use in core so path is just ignored anyway but we could still remove that example from the spec.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That the existing parser lib parses it is already great. As usual being strict in the spec but liberal in parsing is a good thing probably.
Yes to requiring
://
as separator (though if parsing without works then that's great), so I'd remove the examples without it. All the other examples are already following the URI spec I think.And maybe it's also worth specifically describing the syntax wrt to URI schema. Something like:
The benefit of this is that it explicitly acknowledges the URI format and signals that we're aiming to be compatible. Though I won't mind too much if you don't agree with this.