From c304e8fa7454ae3dd037461edadd1572bd85b7fc Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Tue, 5 Jul 2022 21:31:31 +0200 Subject: [PATCH 01/10] add `DCLOGIN` uri scheme --- uri-schemes.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/uri-schemes.md b/uri-schemes.md index 814d2cc..0ddf8ce 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -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,34 @@ 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** + +| | | +| ------------------------ | --------------------- | +| 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:minVersion/CredentialsJSON +# example: +DCLOGIN:1/{"email":"me@example.com","password":""} +``` + +#### `minVersion` + +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). + +It is outside the JSON, because we might want to use a more compact format than JSON in the future, like CBOR, BSON, msgpack or another binary format (see https://www.rfc-editor.org/rfc/rfc8949.html#section-appendix.e for some possible candidates). + ## **DCWEBRTC** | | | From 4c630be4de6f1becfa8a188eeee3b83137aadeef Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Tue, 5 Jul 2022 22:08:12 +0200 Subject: [PATCH 02/10] document json and move the version to the end --- uri-schemes.md | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index 0ddf8ce..5205f7c 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -140,9 +140,9 @@ json object can have other properties too, but currently they are ignored by cor ### Syntax ``` -DCLOGIN:minVersion/CredentialsJSON +DCLOGIN:CredentialsJSON#minVersion # example: -DCLOGIN:1/{"email":"me@example.com","password":""} +DCLOGIN:{"email":"me@example.com","password":""}#1 ``` #### `minVersion` @@ -154,6 +154,45 @@ The version number only increases on incompatible changes (changes to required p It is outside the JSON, because we might want to use a more compact format than JSON in the future, like CBOR, BSON, msgpack or another binary format (see https://www.rfc-editor.org/rfc/rfc8949.html#section-appendix.e for some possible candidates). +Another option for a posible future format could be URI based, like suggested here: +`dclogin://password:name@example.com?smtpserver=loginname:password@smtp.example.com:1234&imapserver=loginname:password@imap.example.com:5678&smtpsecurity=ssltls&imapsecurity=ssltls&authmethod=auto&certchecks=auto` https://support.delta.chat/t/allow-users-to-generate-qr-codes-to-simplify-the-login-process/1406 + +#### `CredentialsJSON` + +Version 1: +```ts +const enum CertificateChecks { + /** + * Same as `AcceptInvalidCertificates` unless overridden by + * `strict_tls` setting in provider database. + */ + Automatic = 0, + Strict = 1, + AcceptInvalidCertificates = 3, +} + +interface DC_LOGIN { + email: string; + password: string; + advanced_imap?: { + host?: string; + port?: number; + username?: string; + password?: string; + security?: "ssl" | "default"; + certificate_checks: CertificateChecks; + }; + advanced_smpt?: { + host?: string; + port?: number; + username?: string; + password?: string; + security?: "ssl" | "starttls" | "plain"; + certificate_checks: CertificateChecks; + }; +} +``` + ## **DCWEBRTC** | | | From 97b34167a1f031d4d8aabf3a8aea67aca75bcc61 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Sun, 10 Jul 2022 14:58:56 +0200 Subject: [PATCH 03/10] uri based scheme instead of json --- uri-schemes.md | 93 +++++++++++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index 5205f7c..8839f29 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -140,11 +140,40 @@ json object can have other properties too, but currently they are ignored by cor ### Syntax ``` -DCLOGIN:CredentialsJSON#minVersion -# example: -DCLOGIN:{"email":"me@example.com","password":""}#1 +dclogin://user:password@host/?options +dclogin://user:password@host?options +dclogin:user:password@host/?options +# example: (email: me@example.com, password: securePassword) +dclogin://me:securePassword@example.com?v=1 +# example: (email: myself@example.com, password: 123456, insecure smtp at different server) +dclogin://myself:123456@example.com?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`, which is the only required option at this point. + +| short name | full name | description | example | +| ---------- | ------------------------- | --------------------------------------------------- | --------------------- | +| `v` | `version` | defines the format version, more explanation below | `v=1` | +| ---------- | ------------------------- | --------------------------------------------------- | ---------------- | +| `ih` | `imap_host` | IMAP host | `ih=imap.example.com` | +| `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`" | `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` Format version: @@ -152,46 +181,32 @@ Used for breaking new versions that add new **required** properties, basically d The version number only increases on incompatible changes (changes to required properties). -It is outside the JSON, because we might want to use a more compact format than JSON in the future, like CBOR, BSON, msgpack or another binary format (see https://www.rfc-editor.org/rfc/rfc8949.html#section-appendix.e for some possible candidates). +#### `CertificateChecks` -Another option for a posible future format could be URI based, like suggested here: -`dclogin://password:name@example.com?smtpserver=loginname:password@smtp.example.com:1234&imapserver=loginname:password@imap.example.com:5678&smtpsecurity=ssltls&imapsecurity=ssltls&authmethod=auto&certchecks=auto` https://support.delta.chat/t/allow-users-to-generate-qr-codes-to-simplify-the-login-process/1406 +| code | name & description | +| ---- | ---------------------------------------------------------------------------------------------------------------- | +| 0 | `Automatic`, same as `AcceptInvalidCertificates` unless overridden by `strict_tls` setting in provider database. | +| 1 | `Strict` | +| 3 | `AcceptInvalidCertificates` | -#### `CredentialsJSON` +#### Important information for using the `DCLOGIN:` scheme -Version 1: -```ts -const enum CertificateChecks { - /** - * Same as `AcceptInvalidCertificates` unless overridden by - * `strict_tls` setting in provider database. - */ - Automatic = 0, - Strict = 1, - AcceptInvalidCertificates = 3, -} +- 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) + - make sure to 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]() +- **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` + +#### Implementation hints + +implementations should be somewhat tolerant: + +- both `dclogin:` and `dclogin://` should work +- both short names and full names should be parsed for properties (though short names are preferred) +- have a test for usename+extention@host cases +- if version is bigger than whats implemented tell the user to update -interface DC_LOGIN { - email: string; - password: string; - advanced_imap?: { - host?: string; - port?: number; - username?: string; - password?: string; - security?: "ssl" | "default"; - certificate_checks: CertificateChecks; - }; - advanced_smpt?: { - host?: string; - port?: number; - username?: string; - password?: string; - security?: "ssl" | "starttls" | "plain"; - certificate_checks: CertificateChecks; - }; -} -``` ## **DCWEBRTC** From b5309b7b1a383ee085e44cbc343f147cc313dc31 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Fri, 15 Jul 2022 01:43:18 +0200 Subject: [PATCH 04/10] dclogin-scheme: discourage usage of full names --- uri-schemes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index 8839f29..dfeba19 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -156,7 +156,7 @@ Format: URL Query parameters also known as GET variables (`varname=value` behind The query parameters contain advanced options and a version parameter. All advanced options are optional except for `v`, which is the only required option at this point. -| short name | full name | description | example | +| short name | stands for | description | example | | ---------- | ------------------------- | --------------------------------------------------- | --------------------- | | `v` | `version` | defines the format version, more explanation below | `v=1` | | ---------- | ------------------------- | --------------------------------------------------- | ---------------- | @@ -203,11 +203,10 @@ The version number only increases on incompatible changes (changes to required p implementations should be somewhat tolerant: - both `dclogin:` and `dclogin://` should work -- both short names and full names should be parsed for properties (though short names are preferred) +- only implement short names (not the full names they stand for) - have a test for usename+extention@host cases - if version is bigger than whats implemented tell the user to update - ## **DCWEBRTC** | | | From a095a0e3af135fac751fb73c1287ce5471d58d8d Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Fri, 15 Jul 2022 01:45:41 +0200 Subject: [PATCH 05/10] only use short names --- uri-schemes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uri-schemes.md b/uri-schemes.md index dfeba19..83e1ea0 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -192,7 +192,7 @@ The version number only increases on incompatible changes (changes to required p #### 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) - - make sure to use the short names for advanced properties + - 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]() - **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) From 7f23e563d8453b2f6bf2f49fde1ea0535a42d282 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Tue, 19 Jul 2022 21:33:58 +0200 Subject: [PATCH 06/10] move password to `p` $GET-field --- uri-schemes.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index 83e1ea0..1f86814 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -140,13 +140,13 @@ json object can have other properties too, but currently they are ignored by cor ### Syntax ``` -dclogin://user:password@host/?options -dclogin://user:password@host?options -dclogin:user:password@host/?options +dclogin://user@host/?p=password&v=1[&options] # example: (email: me@example.com, password: securePassword) -dclogin://me:securePassword@example.com?v=1 +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:123456@example.com?v=1&sh=mail.example.com&sc=3&ss=plain +dclogin://myself@example.com?p=123456&v=1&sh=mail.example.com&sc=3&ss=plain ``` #### Options `?options` @@ -154,17 +154,19 @@ dclogin://myself:123456@example.com?v=1&sh=mail.example.com&sc=3&ss=plain 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`, which is the only required option at this point. +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 | | | ---------- | ------------------------- | --------------------------------------------------- | ---------------- | | `ih` | `imap_host` | IMAP host | `ih=imap.example.com` | | `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`" | `is=ssl` | +| `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` | From 77301aba7cab86314cf9f53fce9f3124a47760e9 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Thu, 4 Aug 2022 23:48:37 +0200 Subject: [PATCH 07/10] 2 more syntax examples for `dclogin:` --- uri-schemes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/uri-schemes.md b/uri-schemes.md index 1f86814..0a384af 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -140,6 +140,8 @@ json object can have other properties too, but currently they are ignored by cor ### 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 From 52a7a5e73a57a7a6b4baa4c25d59fa38c8b449f4 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Tue, 9 Aug 2022 15:30:51 +0200 Subject: [PATCH 08/10] apply link2xt's suggestions --- uri-schemes.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index 0a384af..bdafbbb 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -178,7 +178,7 @@ All advanced options are optional except for `v` and `p`, which are the only req | `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` +#### 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. @@ -197,19 +197,18 @@ The version number only increases on incompatible changes (changes to required p - 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]() + - 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) -- note that email username and password are in different order, than email: `username:password@host` vs. `username@host` #### Implementation hints implementations should be somewhat tolerant: - both `dclogin:` and `dclogin://` should work -- only implement short names (not the full names they stand for) -- have a test for usename+extention@host cases -- if version is bigger than whats implemented tell the user to update +- **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** From 260010997896e2fbbbf152f89c5272efc298b613 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Mon, 12 Sep 2022 22:17:29 +0200 Subject: [PATCH 09/10] address flub's comment --- uri-schemes.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/uri-schemes.md b/uri-schemes.md index bdafbbb..7c0b782 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -139,9 +139,21 @@ json object can have other properties too, but currently they are ignored by cor ### 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] -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 From 42e6f107effcc7ba54dcba1415c162ecfaf1c618 Mon Sep 17 00:00:00 2001 From: Simon Laux Date: Mon, 12 Sep 2022 22:19:01 +0200 Subject: [PATCH 10/10] clarify that `dclogin://` is prefered --- uri-schemes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uri-schemes.md b/uri-schemes.md index 7c0b782..2d5e838 100644 --- a/uri-schemes.md +++ b/uri-schemes.md @@ -217,7 +217,7 @@ The version number only increases on incompatible changes (changes to required p implementations should be somewhat tolerant: -- both `dclogin:` and `dclogin://` should work +- 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