Imaginary WG B. Werner Internet-Draft UP Updates: 1234, 5678 (if approved) 7 February 2023 Intended status: Standards Track Expires: 11 August 2023 UNITED PAGES - Synergy of Webservice, Email and Public-Key-Encryption draft-up-00 Abstract The objective of UNITED-PAGES is to establish a distributed webservice to exchange structured data posted by users. The webservice is implemented by a dynamically growing number of compliant webservers. Each webserver can be put online by a different provider. Each user can register for his own data with a provider of choice. Email-provider that run a compliant webserver spare its users an additional registration. Email-addresses are used both for addressing data and as an identifier for granting access rights to protected data. The authentication of a requesting user's email-address is based on his public-key, which is also stored in UNITED-PAGES. No external authentication service is required. From a user perspective, UNITED-PAGES is an additional functionality of the email-account. From a technical perspective, UNITED-PAGES is a synergy of email, webservice and public-key encryption. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 11 August 2023. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. Werner Expires 11 August 2023 [Page 1] Internet-Draft UP February 2023 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 1.2. Use Case Example . . . . . . . . . . . . . . . . . . . . 3 1.3. Advantages . . . . . . . . . . . . . . . . . . . . . . . 7 2. UNIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3. UNIT-TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. adr . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2. cal . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.3. dev . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 6.1. Normative References . . . . . . . . . . . . . . . . . . 21 6.2. Informative References . . . . . . . . . . . . . . . . . 21 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 1. Introduction 1.1. Terminology 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 [RFC2119]. The following key words written in capital letters refer to UP: * UPI: the UNITED-PAGES API specifies data types, the URI/URL of data instances and access procedures * WEBSERVER: a webserver that is compliant to UPI * PROVIDER: a provider of a WEBSERVER * APPLICATION: an application that uses the UPI in any way * TYPE: object-oriented data format description Werner Expires 11 August 2023 [Page 2] Internet-Draft UP February 2023 * UNIT: an instance of any TYPE that can be accessed via UPI * USER: user of an APPLICATION * PRODUCER: role of a USER when creating, updating or deleting a UNIT. A PRODUCER MUST be registered with any PROVIDER. * CONSUMER: role of a USER when reading a UNIT. A CONSUMER MAY be registered with a PROVIDER when intending to access protected data * UNIT-READ: rights of a USER to read protected data of a UNIT * UNIT-WRITE: rights of a USER to update data of a UNIT. UNIT-WRITE includes UNIT-READ * UNIT-ADMIN: rights of a USER to grant UNIT-READ and UNIT-WRITE and UNIT-ADMIN to other USER. UNIT-ADMIN includes UNIT-WRITE * UNIT-OWNER: rights of a USER that has created a UNIT. UNIT-OWNER allows deletion of a UNIT and includes UNIT-ADMIN * NATIVE-PROVIDER: role of a PROVIDER that is email-provider, too. No extra registration for any registered email-user is required to act as PRODUCER * PRIME-PROVIDER: default PROVIDER (united-pages.com) for all email- user that do not (yet) have a NATIVE-PROVIDER. Extra registration with existing email-address is required at https://www.united- pages.com. If an email-provider later becomes a NATIVE-PROVIDER existing UNITs can be transferred from the PRIME-PROVIDER 1.2. Use Case Example Alice (alice@amail.com), Arthur (arthur@amail.com) and Bob (bob@bmail.com) have an email-account with an email-provider that is also PROVIDER of a WEBSERVER(NATIVE-PROVIDER). Alice and Arthur are registered with the same PROVIDER (amail), whereas Bob has chosen another (bmail). Alice acts as PRODUCER of her personal contact data (i.a. landline and cell phone number). Every USER should have read access to her (public) landline number, whereas Arthur and Bob additionally should have UNIT-READ to her (protected) cell phone number. The TYPE 'cct' is specified for personal contact data (i.a. landline and cell phone number). The URL of Alice's cct-UNIT can be generated from the URL of the WEBSERVER, the TYPE and her email-address: https://www.amail.com/unit/cct/alice/amail.com Werner Expires 11 August 2023 [Page 3] Internet-Draft UP February 2023 Creation or updating of a UNIT using a PUT-request requires HTTP- authentication with 'Username' (email-address of USER/PRODUCER) and corresponding 'Password' (encoded by https): PUT https://www.amail.com/unit/cct/alice/amail.com AUTHENTICATION-Username: alice@amail.com AUTHENTICATION-Password: ali123? -> JSON-Body: { "land":"++49 89 123456789", "x_land":"true", "cell":"++49 171 987654321", "x_cell":"false", "read":"arthur@amail.com,bob@bmail.com" } Only for access to public data ("x_[variable-name]":"true") there is no need for authentication and for this uncomplicated request a CONSUMER does not necessarily have to be registered with any PROVIDER. Just knowing Alice's email-address enables any APPLICATION to create the URL of her cct-UNIT and send a GET-request: GET https://www.amail.com/unit/cct/alice/amail.com -> JSON-Response: { "land":"++49 89 123456789" } A GET-request that shall return also protected data ("x_[variable- name]":"false") requires HTTP-authentication. GET https://www.amail.com/unit/cct/alice/amail.com AUTHENTICATION-Username: arthur@amail.com AUTHENTICATION-Password: 987art!!! -> JSON-Response: { "land":"++49 89 123456789", "cell":"++49 171 987654321" } Unlike Arthur, Bob's email address is completely unknown to the PROVIDER/WEBSERVER where Alice is registered. The decisive question in a distributed service is how a USER who is not registered on a WEBSERVER can authenticate himself there. The UNITED-PAGES solution uses only the UPI, i.e. no external authentication service is required! It starts with Bob simply making a GET-request for a personal pwd-UNIT (that i.a. contains a password) to 'Alice's' WEBSERVER without any authentication. Werner Expires 11 August 2023 [Page 4] Internet-Draft UP February 2023 GET https://www.amail.com/unit/pwd/bob/bmail.com -> JSON-Response: { "crypt_pass":"46hCdasuicjwe2334sff435fer23w...", "eat":"2023-12-04..." } It is a special case of the pwd-UNIT that a GET-request without HTTP- authentication also returns a result if there is no corresponding UNIT. and that the contained password (crypt_pass) is encrypted with the public-key of the OWNER that is specified within the URL (bob/ bmail.com). Only Bob (the 'real' owner of bob@bmail.com) shall decrypt it. The related question is now how did Alice's WEBSERVER know Bob's public-key? The URL of the pwd-UNIT contained Bob's email-address. This in turn allows Alice's WEBSERVER to generate the URL of Bob's pki-UNIT that i.a. contains his public-key. The GET-request is sent to Bob's WEBSERVER: GET https://www.bmail.com/unit/pki/bob/bmail.com -> JSON-Response: { "public_key":"46hCdasui5fedw..." } After decryption of the temporal password Bob can use it in the same way as e.g. Arthur did. It is a password that Bob can use until expiration date (eat) for authentication of any access on Alice's WEBSERVER, not only for UNITs of Alice. The procedure: APP-BOB WEBSERVER-ALICE WEBSERVER-BOB + + + |---(A) GET pwd-UNIT -->| | | | | | |---(B) GET pki-UNIT -->| | |<--(C) pki-UNIT -------| | | | | (D) generate SESSION-PWD | | (E) encrypt SESSION-PWD | | (F) save SESSION-PWD | | | | |<-(G) pwd-UNIT --------| | | | | (H) decrypt SESSION-PWD | | | | | + + + Figure 1: GET a SESSION-PWD Werner Expires 11 August 2023 [Page 5] Internet-Draft UP February 2023 The flow illustrated in Figure 1 shows how a SESSION-PWD can be requested (the principle is identical for a SESSION-JWT): (A) Bob's APPLICATION requests a pwd-UNIT from Alice's WEBSERVER (without authentication): GET https://www.amail.com/unit/pwd/bob/bmail.com (B) Alice's WEBSERVER requests Bob's pki-UNIT from Bob's WEBSERVER (if not already in cache): GET https://wwww.bmail.com/unit/pki/bob/bmail (C) Bob's WEBSERVER returns public data of Bob's pki-UNIT to Alice's WEBSERVER (public key, but not private key): { "publickey":"-----BEGIN PUBLIC KEY-...-END PUBLIC KEY-----" } (D) Alice's WEBSERVER generates a random SESSION-PWD: e.g. abc123 (E) Alice's WEBSERVER encrypts the SESSION-PWD with Bob's public- key: e.g. encrypted SESSION-PWD: "D9Kl4nNmK..." (F) Alice's WEBSERVER saves SESSION-PWD(encrypted and decrypted) and expiration date to internal DB e.g. db_session_pwd("bob@bmail.com","D9Kl4nNmK...","abc123",2022 -12-24T18:05:00+01:00) (G) Alice's WEBSERVER returns the encrypted SESSION-PWD in parameter _cpwd (crypted pwd) and the expiration in _eat (expiration at) to Bob's pwd-UNIT GET-request: { "_cpwd":"D9Kl4nNmK...", "_eat":"2022-12-24T18:05:00+01:00" } (H) Bob's APPLICATION decrypts the value of _cpwd using Bob's private-key: e.g. SESSION-PWD: abc123 For clearness this flow contains only the basic steps. If a SESSION- PWD that was already saved within a previous GET-request is not expired then (B)-(F) can be skipped. The expiration time can be individually determined by each WEBSERVER e.g. 5 minutes. With any Werner Expires 11 August 2023 [Page 6] Internet-Draft UP February 2023 following GET-request (until expiration) to the same WEBSERVER (e.g. amail.com), HTTP Basic Authentication can be used with email address (username) and the SESSION-PWD (password). Successful authentication is followed by authorization i.e. the WEBSERVER checks whether the username is included in the WHITELIST (if set) of the requested UNIT. GET https://www.amail.com/unit/cct/alice/amail.com HTTP-Basic-Authentication username: bob@bmail.com HTTP-Basic-Authentication password: abc123 -> JSON-Response: { "land":"++49 89 123456789", "cell":"++49 176 987654321" } 1.3. Advantages The synergy of email, RESTful webservice and public-key-encrpytion results in a distributed, non-monopolistic, simple-to-use and secure webservice. * up-to-date If e.g. Alice changes a UNIT (e.g. a new cell number in the cct- UNIT), she no longer has to distribute this (e.g. via vCard) but instead maintain it once-only * integrity of data The email-address of the PRODUCER of a UNIT can be mapped from the URL/URI of a UNIT. If e.g. Bob considers Alice's PROVIDER to be trustworthy, he can assume that Alice has maintained all UNITs whose URL/URI contain her email-address. Integrity is based on the established relationship of trust with email providers. * authentication without external service If e.g. Alice considers Bob's PROVIDER to be trustworthy, she can assume that Bob maintained the corresponding pki-UNIT(public key). UNITED-PAGES can generally (i.e. beside of accessing UNITs) also be used as an authentication service that is not dominated by quasi-monopolists. Authentication is based on the established relationship of trust with email providers. * withdrawable authorization e.g. Alice grants access rights to protected data by adding Bob's email address in a resp. WHITELIST. Dealing with email-addresses is familiar through experience with the email-service. The authorization can be revoked at any time, which is a basic requirement of data protection guidelines [GDPR]. Werner Expires 11 August 2023 [Page 7] Internet-Draft UP February 2023 * non-mandatory registration Each email-user of a NATIVE-PROVIDER does not need any additional registration to offer their own UNITs or to access protected data of other USERs. From the USER's point of view, UNITED-PAGES offers additional functionality for an email-account. * multi-domain UNITED-PAGES is not limited to a specific application domain. There are different TYPEs. Standardized formats simplify maintenance and evaluation. * hypermedia A UNIT can also reference other UNITs, e.g. an adr- UNIT(address) refers to a cct-UNIT(contact) and loc- UNIT(location). A reference to a UNIT of the same type is also possible in the sense of an object-oriented derivation e.g. the loc-UNIT of employees can derive from a loc-UNIT of the company where the common internal postal address is configured and only the room number of an employee has to be configured individually. 2. UNIT Each UNIT is identified by a unique UNIT-URI. From each UNIT-URI the email-address of the PRODUCER can be derived. Each UNIT-URI can be uniquely mapped to a URL. The URL depends on whether the respective email-provider also acts as a NATIVE-PROVIDER or whether the UNIT is stored at the PRIME-PROVIDER. unit-uri = "unit://" unit-type "/" local-part "@" domain-part [ "?" query ]. unit-type = "adr" | "air" | "cal" | "cct" | "dev" | "file" | "loc" | "lst" | "mail" | "pki" | "ref" | "tok". unit-url = "https://" webdom "/" unit-type "/" local-part "/" domain-part [ "?" query ]. webdom = webdom-native | webdom-prime. webdom-prime = "www.united-pages.com/unit". webdom-native = "www." domain-part "/" unit | webdom-get. "local-part" and "domain-part" use the IMF-reference definition from [RFC5322]. "query" uses the URI-reference definition from [RFC3986]. "webdom-get" will be determined by calling a dom-UNIT from the PRIME- PROVIDER. Examples for "webdom": * NATIVE-PROVIDER using default "webdom-native" URI: unit://adr/ doris@dmail.com URL: https:/www.dmail.com/unit/adr/doris/dmail.com Werner Expires 11 August 2023 [Page 8] Internet-Draft UP February 2023 o NATIVE-PROVIDER using "webdom-get" GET https://www.united-pages.com/dom/smail.com -> { "dom":"api.smail.net/up" } URI: unit://cal/steven@smail.com?id=x%40y URL: https://api.smail.net/up/steven/smail.com?id=x%40y * PRIME-PROVIDER using "webdom-prime" URI: unit://pki/pete@pmail.com URL: https://www.united-pages.com/unit/pki/pete/pmail.com The UNIT-URI is shorter and more intuitive for humans. It does not have to be taken into account whether the email-provider is a NATIVE- PROVIDER and if this is later the case, the UNIT-URI does not change even after a transfer of the resp. UNIT. A unique scheme (here: unit) can be coupled with a certain application, i.e. an APPLICATION can be started when clicking on a UNIT-URI within Email or Messenger text e.g. Hello John Doe, your next appointment: unit://cal/praxis@medicus.de?id=123 Regards Your medicus team unit://adr/praxis@medicus.de?id=dispatcher 3. UNIT-TYPE A UNIT is a concrete resource of a certain TYPE and can be addressed via an URI/URL. Each UNIT has general unit-variables and TYPE specific type-variables. The datatype of each variable is specified as STRING(length), BOOLEAN (true or false), INTEGER, ENUM or TIMESTAMP whereas TIMESTAMP is STRING(25) of [RFC3339] format YYYY- MM-DD"T"HH":"mm":"ss"+"hh":"mm" (e.g. 2019-03-28T16:30:10+02:00). Each UNIT belongs to a certain TYPE that is identified by a TYPE-name (e.g. adr, cal, pki), type-variables (eg. forename, street, temperature,...). For each unit- and type-variable there is a corresponding access-variable starting with 'x_' (eg. x_forename, x_street, x_temperature,...). The ENUM (0|1|2) of a access-variable determines whether the corresponding unit- or type-variable is public(2) or protected(1) or private(0) i.e. only accessible for authenticated and authorized users. Typically a UNIT references other UNITs i.e. the value of a variable can be the URI of another UNIT. Werner Expires 11 August 2023 [Page 9] Internet-Draft UP February 2023 It is not specified how the data/resources are stored on a WEBSERVER, the format of UNITs is solely binding for the access methods. Each UNIT (except dom, jwt, pki, pwd, tok) has the following variables: +==========+============+===========================================+ | Name | DataType | Semantic | +==========+============+===========================================+ | _subject | STRING(32) | any (short) textual description | +----------+------------+-------------------------------------------+ | _href | STRING(64) | any http(s)-link | +----------+------------+-------------------------------------------+ | _uref | STRING(64) | any other UNIT-URI | +----------+------------+-------------------------------------------+ | _super | STRING(64) | UNIT-URI of another UNIT of the | | | | same TYPE | +----------+------------+-------------------------------------------+ | | | that may set default values for | | | | any | +----------+------------+-------------------------------------------+ | | | variable of that UNIT (except | | | | _upwd) | +----------+------------+-------------------------------------------+ | _icon | STRING(64) | UNIT-URI of an ico-UNIT | +----------+------------+-------------------------------------------+ | _white | STRING(64) | UNIT-URI of a lst-UNIT that | | | | contains a | +----------+------------+-------------------------------------------+ | | | list of email-adresses that | | | | have read- | +----------+------------+-------------------------------------------+ | | | access on any variable (except | | | | _white, | +----------+------------+-------------------------------------------+ | | | _upwd) of that UNIT | +----------+------------+-------------------------------------------+ | _cat | TIMESTAMP | created at | +----------+------------+-------------------------------------------+ | _uat | TIMESTAMP | updated at | +----------+------------+-------------------------------------------+ | _eat | TIMESTAMP | expire at | +----------+------------+-------------------------------------------+ | _xviews | INTEGER | every authenticated GET request | | | | (except | +----------+------------+-------------------------------------------+ | | | from the PRODUCER) increases | | | | the counter | Werner Expires 11 August 2023 [Page 10] Internet-Draft UP February 2023 +----------+------------+-------------------------------------------+ | _views | INTEGER | every non-authenticated GET | | | | request | +----------+------------+-------------------------------------------+ | | | increases the counter | +----------+------------+-------------------------------------------+ | _lic | STRING(64) | Info that has to be regarded | | | | for usage | +----------+------------+-------------------------------------------+ | _upwd | STRING(64) | UNIT password that authorizes | | | | write | +----------+------------+-------------------------------------------+ | | | access to any user (see | | | | Privacy) | +----------+------------+-------------------------------------------+ Table 1 unit-variables General unit-variables 3.1. adr The adr-UNIT is a container for address data. +======+============+=================+ | Name | DataType | Semantic | +======+============+=================+ | cct | STRING(64) | URI of cct-UNIT | +------+------------+-----------------+ | idy | STRING(64) | URI of idy-UNIT | +------+------------+-----------------+ | loc | STRING(64) | URI of loc-UNIT | +------+------------+-----------------+ Table 2 adr-UNIT type-variables 3.2. cal The cal-UNIT contains calendar data. Werner Expires 11 August 2023 [Page 11] Internet-Draft UP February 2023 +--------------+------------+---------------------------------------+ | Name | DataType | Semantic | +--------------+------------+---------------------------------------+ | sched_sat | TIMESTAMP | scheduled start at | | | | | | sched_eat | TIMESTAMP | scheduled end at | | | | | | est_sat | TIMESTAMP | estimated start at | | | | | | est_eat | TIMESTAMP | estimated end at | | | | | | dat | TIMESTAMP | dispatched at | | | | | | dispatcher | STRING(64) | adr-URI | cct-URI | | | | | | location | STRING(64) | loc-URI | | | | | | executive | STRING(64) | adr-URI | cct-URI | | | | | | participants | STRING(64) | lst-URI of email-addresses | | | | | | description | STRING(64) | detailed description | | | | | | status | ENUM(0-6) | NONE(0) | SCHEDULED(1) | STARTED(2) | | | | | FINISHED(3) | DELAYED(4) | | | | | CANCELED(5) | PRELIMINARY(6) | | | | | | service | STRING(64) | sce-URI | +--------------+------------+---------------------------------------+ cal-UNIT type-variables 3.3. dev The dev-UNIT contains devices data. Werner Expires 11 August 2023 [Page 12] Internet-Draft UP February 2023 +----------+-------------+------------------------------------------+ | Name | DataType | Semantic | +----------+-------------+------------------------------------------+ | sat | TIMESTAMP | start at | | | | | | log | ENUM(0-5) | NONE(0) | TRACE(1) | DEBUG(2) | INFO(3) | | | | | WARN(4) | ERROR(5) | | | | | | poll | INTEGER | Polltimer (minutes) | | | | | | mac | STRING(17) | MAC-Address (FF:FF:FF:FF:FF:FF) | | | | | | ip | STRING(20) | IP-address | | | | | | port | INTEGER | port number | | | | | | status | ENUM(0-4) | NONE(0) | UP(1) | DOWN(2) | TESTING(3) | | | | | IDLE(4) | | | | | | severity | ENUM(0-3) | NONE(0) | CRITICAL(1) | WARNUNG(2) | | | | | OK(3) | | | | | | score | STRING(64) | description of e.g. temperature, | | | | capacity, ... | | | | | | activity | STRING(64) | description of e.g. running mode | | | | | | trouble | STRING(128) | description of problems | | | | | | location | STRING(64) | loc-URI | | | | | | operator | STRING(64) | adr-URI | cct-URI | | | | | | service | STRING(64) | sce-URI | +----------+-------------+------------------------------------------+ dev-UNIT type-variables 4. Methods UP specifies the usage of the HTTP-methods GET, HEAD, PUT, POST and DELETE as described in [RFC2616]. A request may contain a HTTP-body and may use for authentication either Basic-Authentication (Username/ Password) or Bearer-Token. A response contains a HTTP-status and may contain an HTTP-response. UP uses JSON as format for HTTP-body resp. HTTP-response and JWT (JSON Web Token) for Bearer-Token. Werner Expires 11 August 2023 [Page 13] Internet-Draft UP February 2023 * GET - fetch data no HTTP-body, but all request-data is included in the URL and HTTP-header * HEAD - check existence of a resource similar to GET, but no HTTP- response, only HTTP-status * POST - create a new entity as a new subordinate not idempotent, i.e. if you retry the request N times, you will end up having N different subordinate-URIs (eg. a new message within an article) * PUT - update an already existing resource or create a new resource idempotent, i.e. if you retry the same request multiple times, the result is equivalent to single request * DELETE - delete an already existing resource The Internet Assigned Numbers Authority (IANA) maintains the official registry of HTTP status codes. The usage of the following codes in UP is MANDATORY. Werner Expires 11 August 2023 [Page 14] Internet-Draft UP February 2023 +======+==============+=============================================+ | Code | Semantic | UP | +======+==============+=============================================+ | 200 | OK | even when a GET-request | | | | returns only public | +------+--------------+---------------------------------------------+ | | | and/or protected data | +------+--------------+---------------------------------------------+ | 201 | Created | a new UNIT was created. | | | | In case of an | +------+--------------+---------------------------------------------+ | | | update 200 is returned. | +------+--------------+---------------------------------------------+ | 401 | Unauthorized | Authentication failed, | | | | because of invalid | +------+--------------+---------------------------------------------+ | | | username, unknown | | | | username or wrong | +------+--------------+---------------------------------------------+ | | | password. | +------+--------------+---------------------------------------------+ | 403 | Forbidden | Authentication | | | | successful, but no access | +------+--------------+---------------------------------------------+ | | | rights. In case of GET- | | | | request no empty | +------+--------------+---------------------------------------------+ | | | body will be returned but | | | | this error | +------+--------------+---------------------------------------------+ | | | status. | +------+--------------+---------------------------------------------+ | 404 | Not found | UNIT with given URL not | | | | found | +------+--------------+---------------------------------------------+ | 405 | Method not | Some TYPE do not support | | | | any method e.g. | +------+--------------+---------------------------------------------+ | | allowed | PUT for tok-UNIT | +------+--------------+---------------------------------------------+ Table 3 IANA Status-Codes used by UP PUT, POST and DELETE always need authentication whereas it is optional for GET and HEAD. Authentication when Werner Expires 11 August 2023 [Page 15] Internet-Draft UP February 2023 accessing a UNIT is done by HTTP-Basic- Authentication with the specification of "username" and "password" (JWT not yet supported). The "username" can be specified as an email-address registered with any PROVIDER. The corresponding MASTER-PWD can be specified as "password" if the UNIT is stored with the same PROVIDER. Otherwise, a SESSION-PWD that has been exchanged (encrypted) can be specified as "password". Optionally, for each UNIT the unit- variable "_upwd" can be configured. Authentication with "_upwd" as "username" and the value of the variable "_upwd" as "password" receives the same unrestricted access rights as authentication with the email-address of the PROVIDER. An empty string is never a valid password even if no value has been set. Examples: * Arthur (arthur@amail.com) can authenticate himself with his MASTER-PWD for read access (GET) to protected data of Alice (alice@amail.com). * Bob (bob@bmail.com) can authenticate for read access (GET) to protected data of Alice (alice@amail.com) with a SESSION-PWD that he got previously(encrypted) from Alice's WEBSERVER. * Alice (alice@amail.com) can authenticate with her MASTER-PWD to access all her UNITs unrestricted reading (GET) and writing (PUT/ DELETE). * For each UNIT from Alice, for which she has individually configured "_upwd", any CONSUMER (including those who are not registered) with knowledge of the value of "_upwd" authenticate anonymously in order to have unrestricted read and write access to exactly this UNIT like Alice as a PRODUCER. The access right for GET-requests can be controlled individually for each unit-/type-variable by configuring the corresponding access- variable and the WHITELIST. Werner Expires 11 August 2023 [Page 16] Internet-Draft UP February 2023 +======+===========+===============================================+ | ENUM | Semantic | Description | +======+===========+===============================================+ | 0 | PRIVATE | Access only allowed for the authenticated | +------+-----------+-----------------------------------------------+ | | | PRODUCER. An access-variable that is not | +------+-----------+-----------------------------------------------+ | | | explicitly specified when creating a new UNIT | +------+-----------+-----------------------------------------------+ | | | is set to PRIVATE. | +------+-----------+-----------------------------------------------+ | 1 | PROTECTED | Access only allowed for an authenticated | +------+-----------+-----------------------------------------------+ | | | CONSUMER whose email-address is included in | +------+-----------+-----------------------------------------------+ | | | the associated WHITELIST | +------+-----------+-----------------------------------------------+ | 2 | PUBLIC | Access allowed without authentication | +------+-----------+-----------------------------------------------+ Table 4 access-variable The following table shows the HTTP-Status und HTTP-Response of a GET- request depending on the access rights. "-" means that the setting is irrelevant. AUTH=NONE means that no "username"/"password" was set in the HTTP-Basic-Authentication. WHITELIST=TRUE means that the email-address from "username" is member of WHITELIST. PRODUCER=TRUE means that the email-address from "username" is the email-address of the PRODUCER or "_upin" was used for authentication. ANY=FAIL means that there is no access right on any variable. ANY=TRUE means that there is access right on at least one variable. Werner Expires 11 August 2023 [Page 17] Internet-Draft UP February 2023 +-----------+-------+------+------+--------+------------------------+ | AUTH | WHITE | PROD | ANY | HTTP | HTTP Response | | | LIST | UCER | | Status | | +-----------+-------+------+------+--------+------------------------+ | TRUE | - | TRUE | - | 200 | { all variables (incl. | | | | | | | _upwd and all access- | | | | | | | variables) } | | | | | | | | | NONE | - | - | TRUE | 200 | { all PUBLIC variables | | | | | | | } | | | | | | | | | TRUE | FAIL | FAIL | TRUE | 200 | { all PUBLIC variables | | | | | | | } | | | | | | | | | TRUE | TRUE | FAIL | TRUE | 200 | { all PUBLIC and | | | | | | | PROTECTED variables } | | | | | | | | | FAIL | - | - | - | 401 | | | | | | | | | | TRUE|NONE | - | - | FAIL | 403 | | +-----------+-------+------+------+--------+------------------------+ Response of GET-request Examples: * Alice creates a new lst-UNIT and provides her email-address and MASTER-PWD for authentication: PUT https://www.amail.com/unit/lst/alice/amail.com?id=friends Username: alice@amail.com Password: *MASTER-PWD Body: { "elements":"bob@bmail.com, carlos@cmail.com" } -> Status: 200 * Alice creates a new cct-UNIT. Only her friends should be allowed to access her protected cell number. Their email-addresses are included in the previously created lst-UNIT, which is set as WHITELIST. Reading access to the WHITELIST itself can remain private. Also the UNIT-PWD typically remains private (provided that it is set at all as in this example): Werner Expires 11 August 2023 [Page 18] Internet-Draft UP February 2023 PUT https://www.amail.com/unit/cct/alice/amail.com Username: alice@amail.com Password: *MASTER-PWD Body: { "cell":"++49 176 429...", "x_cell":1, "land":"++49 89 123...", "x_land":2, "_white":"lst/alice@amail.com?id=friends", "_upwd":"abc123" } -> Status: 201 * Querying Alice's cct-UNIT without authentication returns the public landline phone number GET https://www.amail.com/unit/cct/alice/amail.com Username: Password: -> Status: 200 Response: { "land":"++49 89 123..." } o Arthur can use his MASTER-PWD for authentication when querying Alice's cct-UNIT, since he is registered with the same PROVIDER as Alice. Since his email-address is not included in the WHITELIST, only the public variables are answered despite successful authentication: GET https://www.amail.com/unit/cct/alice/amail.com Username: arthur@amail.com Password: *MASTER-PWD -> Status: 200 Response: { "land":"++49 89 123..." } o Anyone who knows the UNIT-PWD can change any variable anonymously: PUT https://www.amail.com/unit/cct/alice/amail.com Username: _upwd Password: *UNIT-PWD Body: { "cell":"++49 169 324..." } -> Status: 200 o Bob requests (anonymously) an encrypted SESSION-PWD for his email- address from Alice's/Arthur's WEBSERVER. GET https://www.amail.com/unit/cct/bob/bmail.com Username: Password: -> Status: 200 Response: { "cpwd":"WD3d...", "_eat":"2022-12-24T18:30:00+01:00" } Werner Expires 11 August 2023 [Page 19] Internet-Draft UP February 2023 o The SESSION-PWD is encrypted with the public-key of Bob, that can be requested from his pki-UNIT: GET https://www.bmail.com/unit/pki/bob/bmail.com Username: Password: -> Status: 200 Response: { "privatekey":"---BEGIN..." } o After Bob has decrypted the encrypted SESSION-PWD with his own private-key, he makes a request for Alice's cct-UNIT. Since his email-address is included in the WHITELIST the protected variables are also answered: GET https://www.amail.com/unit/cct/alice/amail.com Username: bob@bmail.com Password: *SESSION-PWD -> Status: 200 Response: { "cell":"++49 169 324...", "land":"++49 89 123..." } o In principle, Bob can use the SESSION-PWD to authenticate all requests to the corresponding WEBSERVER, i. e. also according to Arthur's cct-UNIT. If Arthur didn't share a single variable for Bob e.g. all variables are private or protected and Bob's email- address is not in the corresponding WHITELIST of Arthur's cct-UNIT the error status 403 (Forbidden) is answered: GET https://www.amail.com/unit/cct/arthur/amail.com Username: bob@bmail.com Password: *SESSION-PWD -> Status: 403 o If Bob's request on Alice's cct-UNIT fails because the SESSION-PWD has expired or because it is incorrect, the error status 401 (Unauthorized) will be answered regardless of whether Alice's cct- UNIT contains a public variable: GET https://www.amail.com/unit/cct/alice/amail.com Username: bob@bmail.com Password: *SESSION-PWD -> Status: 401 o Should the APPLICATION used by Bob have access to his private-key but not to his MASTER-PWD, Bob can request his own webserver for a SESSION-PWD: GET https://www.bmail.com/unit/pwd/bob/bmail.com Username: Password: Werner Expires 11 August 2023 [Page 20] Internet-Draft UP February 2023 -> Status: 200 Response: { "cpwd":"WD3d...", "_eat":"2022-12-24T19:45:15+01:00" } o With a valid SESSION-PWD Bob can authenticate himself as the PRODUCER of his cct-UNIT and can even delete it: DELETE https://www.amail.com/unit/cct/bob/bmail.com Username: bob@bmail.com Password: *SESSION-PWD -> Status: 200 o When a UNIT is not existing a Delete (or GET) will cause a 404 (not found): DELETE https://www.amail.com/unit/cct/bob/bmail.com Username: bob@bmail.com Password: *SESSION-PWD -> Status: 404 5. IANA Considerations None. 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . 6.2. Informative References [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, June 1999, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . Werner Expires 11 August 2023 [Page 21] Internet-Draft UP February 2023 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, . Index I Introduction verbiage 2 U UNIT verbiage 7 Author's Address Bernd Werner UNITED PAGES Seestrasse 37 Woerthsee 82237 DE Email: Bernd.Werner@united-pages.com URI: http://info:www.united-pages.com/ Werner Expires 11 August 2023 [Page 22]