From e54d3669bc8839a10cad8f9888c811def09b748a Mon Sep 17 00:00:00 2001 From: Jonathan Silverblood Date: Sat, 29 Sep 2018 05:52:17 +0000 Subject: [PATCH] Remove progressive example. (Downloaded it first, will use it for a guide/tutorial on a website later) --- README2.md | 310 ----------------------------------------------------- 1 file changed, 310 deletions(-) delete mode 100644 README2.md diff --git a/README2.md b/README2.md deleted file mode 100644 index fb9f23a..0000000 --- a/README2.md +++ /dev/null @@ -1,310 +0,0 @@ -*Status: Incomplete draft*
-*BitID source: https://github.com/bitid/bitid* - - -# Abstract - -CashID is an open protocol that allows secure authentication based on Bitcoin Cash public key cryptography. Each user can prove to a service provider that he controls a specific Bitcoin Cash address by signing a challenge request, as well as provide optional metadata. - - -# Rationale - -Passwords is an inherently flawed concept based on sharing secrets, which is increasingly getting hidden away from the users by means of password managers, 'remember me' and single-signon features. Public key cryptography provides a more secure method for authentication where the user's secret is never revealed. - -Secure authentication combined with added metadata enables, for example: - -* Registering with a service as a 1-step process. -* Registering with a service automatically as part of a payment. -* Signing in without a password. -* Authenticating as a 2-FA that complements existing passwords. -* Providing access control to various locks based on payment. - - -# Basic Authentication - -When a user needs to access a restricted area (physically or digitally), they are given a **Challenge request** by the service provider. This request can be transmitted via QR code, NFC touch or any other implementation-specific method. The identity manager (IDM) presents the requested information to the user and allows him to choose a suitable identity. - - -### Challenge request - - -``` -cashid:domain.tld/path?a=auth&x= -``` - -**nonce** is a unique value used only once. You can use a session ID as the nonce or generate a special value for it. The usual practice is to generate a string of alpha-numeric characters long enough to make the probability of reuse extremely small. For example **r2YkB1XrbV**. - -The nonce should expire after some time if it wasn't used. - -### Challenge response - -Once approved by the user, IDM signs the full **Challenge request** and sends a **Challenge response** back to the service provider's end point: - -``` -POST https://domain.tld/path -``` - -This response contains a single URL-encoded variable **data**, which holds a valid **JSON** object with the following members: - -**Member** | **Data type** | **Description** ---- | --- | --- -**uri** | String | The original URI requested (cashid:domain.tld/path?a=auth&x=nonce). -**address** | String | Native or CashAddr address used to sign the above URI. -**signature** | String | Hex-encoded signature. - - -### Confirmation - -The server replies to **Challenge response** with a valid JSON object: - -**Member** | **Data type** | **Description** ---- | --- | --- -**code** | Integer | Numerical code uniquely identifying the error. -**error** | String | Description of the error that can be presented to the user. - -On success **code** = 0 and **error** = ''. - -After successful authentication the service or device should allow the user to use it. - - -## Metadata - -Service providers can request additional data about user's identity. After review, the user can decide whether to grant or reject the access to his data. - - -To request the metadata, the service provider can add **&r=** for required and **&o=** for optional metadata fields to the original URI, like this: - -``` -cashid:domain.tld/path?a=auth&x=&r=i&o=p9 -``` - -For brevity a single-letter plus optional digit is used to identify pieces of metadata. - -IDM will show the user which identity pieces the service provider requested and give him the option to approve or reject each one. In case the user rejects a required identity piece, the whole process is aborted. - -Otherwise IDM will add **metadata** member to the **Challenge response** with the requested information. - -You can find the details about metadata codes and responses in the Appendix N. - - -## User-Initiated Actions - -It is often useful for the user to send an unsolicited command to the service provider. For example, to log off or if he thinks his identity has been compromised. - -To do this the user can send a POST request to the original end-point and add **&a=** parameter to specify the action and **&d=** parameter to specify optional data, like this: - -``` -cashid:domain.tld/path?a=logout&x= -``` - -See the list of available actions in Appendix N. - -## Apendix 1. Challenge request format - -The request consists of an **Intent**, **Domain**, **Path** and set of **Parameters**. - -``` -cashid:domain.tld/path?a=&d=&r=&o=&x= -``` - -**Part** | **Example** | **Description** ---- | --- | --- -Intent | cashid: | Protocol identifier. -Domain | domain.tld | Fully qualified domain name. -Path | /path | Path to a request manager. -Parameters | a=action
d=data
r=required
o=optional
x=nonce | Various parameters. - - -### Parameters - -Every request must have a **nonce** parameter and may also have an **action**, **data**, **required** and **optional** parameters. - -**Letter** | **Name** | **Description** ---- | --- | --- -**a** | action | Name of the action the user authenticates to perform. -**d** | data | Data relevant to the requested action. -**r** | required | List of metadata that the action needs to function. -**o** | optional | List of metadata that the action can use but still works without. -**x** | nonce | Random data unique for this request. - - -#### List of actions the service provider can request - -The following is a list of common actions that a service provider can offer to users: - -**Action** | **Description** | **Data** ---- | --- | --- -**auth** | Identifies the end-user to the service provider and grants access to digital | - -**sign** | Asks the end-user to cryptographically sign a message | Message text that the identity is requested to sign - - -#### User actions - -The following is a list of common actions that end-users can initiate without an active session with service provider: - -**Value** | **Description** ---- | --- -**delete** | Requests the service provider to delete this identity and related metadata. -**logout** | Requests the service provider to close all active sessions for this identity. -**revoke** | Informs the service provider that this identity has been compromised. -**update** | Informs the service provider about changes to metadata. - - -#### Custom actions - -The protocol can be extended with custom actions. If IDM doesn't understand the action used, it must inform the user and abort the request. - - -## Appendix N: Required and Optional Metadata - -The **required** and **optional** parameters allow the service to request personal information from the user. In order to do this in the least amount of space, the information is shorthanded by a letter and a string of numbers representing various pieces of personal information. For **Optional** metadata, the numbers after a letter can be omitted to request all fields in that category. The same metadata fields can only be requested in either **Required** or **Optional** scope, not both. The field numbers in each category has to be listed in sorted order, starting with the lowest number. - - -**Identification** is represented by the letter **i** followed by a list of numbers corresponding to the following table. - -**Number** | **Name** | **Data type** | **Description** ---- | --- | --- | --- -1 | Name | String | The first or given name of the person -2 | Family | String | The last name, surname of family name of the person -3 | Nickname | String | A nickname or username -4 | Age | Integer | The number of years the person has lived -5 | Gender | String | The sex of the person, usually "Male" or "Female" -6 | Birthdate | Date | The date of birth... what format? (YYYY-MM-DD?) -8 | Picture | String | URL to a profile picture, or Base64 encoded image -9 | National | string | National identification numbers, such as passport, drivers license and citizenship numbers. - -
- -**Position** is represented by the letter **p** followed by a list of numbers corresponding to the following table. - -**Number** | **Name** | **Data type** | **Description** ---- | --- | --- | --- -1 | Country | String | Name of the nation -2 | State | String | Name of the state or province -3 | City | String | Name of the city -4 | Street name | String | Name of the street, without the street number -5 | Street number | String | The street number -6 | Residence | String | Building or apartment number that uniquely reference a residence -9 | Coordinate | String | Geographical position as specificed in [RFC5870](https://tools.ietf.org/html/rfc5870)
*For example: "geo:13.4125,103.8667"* - -
- -**Contact information** is represented by the letter **c** followed by a list of numbers corresponding to the following table. - -**Number** | **Name** | **Data type** | **Description** ---- | --- | --- | --- -1 | Email | String | Email address -2 | Instant | String | Instant Messenger protocol handle -3 | Social | string | Social media service handle or URL -4 | Mobile phone number | string | Personal cellphone number -5 | Home phone number | string | Residence phone number -6 | Work phone number | string | Work phone number -7 | Postal label | string | Postal label for a physical address to which a service can send letters and packages - - -## Appendix N: Response format - -When IDM is ready to submit a **Challenge response** it forms a **Request URL** by appending the **Domain** and **Path** components to a **https://** scheme identifier (HTTP is not allowed). - -``` -https://domain.tld/path - ^ ^ ^ -cashid: domain.tld/path?a=&d=&r=&o=&x= -``` - -It then sends the **JSON** encoded object as **data** variable with the following members: - - -**Member** | **Data type** | **Description** ---- | --- | --- -**uri** | String | The original URI requested. -**address** | String | Native or CashAddr address used to sign the above URI. -**signature** | String | Hex-encoded signature. -**metadata** | String | Requested metadata fields encoded as a JSON object (if any). - -
- -Metadata is provided as a JSON object with property names matching the requested field names. - -For example, if the request contains **r=i12&o=c** the metadata part of the request answer would look like this: - -```javascript -metadata: -{ - 'name': 'John', - 'last name': 'Doe', - 'email': 'johndoe@gmail.com', - 'social': - { - 'facebook': 'https://facebook.com/johndoe', - 'twitter': 'https://twitter.com/johndoe' - } -} -``` - -*Note that there is two fields for social media presence and no fields for optional contact data the user did not want to supply* - - -## Apendix N: Error codes - -**Code** | **Error message** | **Description** ---- | --- | --- - 0 | | Authentication successful - 1 | Malformed request | ... - 2 | Malformed URI | ... - 3 | Timeout (nonce has expired) | ... - 4 | Nonce has been already used | ... - 5 | Required metadata is missing | ... (would be nice to also specify which one...) - 6 | Metadata format is not supported | ... (again, would be nice to specify the exact problem...) - 7 | Service temporary unavailable | ... (or Busy, try again later) - 8 | Signature verification failed | ... - 9 | Access denied for this identity | ... (can be more detailed ban reason...) -10 | Access revoked | This identity was marked as compromised and cannot be used anymore. -11 | Not implemented | This feature is not implemented by the service provider. - - -Error codes above 100 are available for custom responses, not specified here. If such a response is received, which IM doesn't recognize, it must simply show the textual error to the user. - -## Appendix N: Request examples - -The **register** action at **example.com** requires **Name**, **Last Name**, **Country** and **Email** to work, and will use **Picture**, **Age**, **Gender** and **City** if provided. -``` -cashid:example.com/cashid.php?a=register&r=i12l1c1&o=i567l3&x=95261230581 -``` - -
- -The **verify** action (2FA) at **bankers.net** requires that the address **qqzafeafd...** authenticates -``` -cashid:bankers.net/api/v1/cashid.php?a=verify&data=qqzafeafd...&x=23563567325 -``` - -
- -The **login** action at **cashtalk.org** can make use of **Name** and **Last Name**, for example to update user profiles. -``` -cashid:cashtalk.org/auth?a=login&d=15366-4133-6141-9638&o=i12&x=13534642624 -``` - -
- -The user initiated request to **delete** their user data from **sensitive.cash** -``` -cashid:sensitive.cash/api/cashid.php?a=delete -``` - -# Appendix N: Resources (to-do) - -Supply a functional regexp! - -* 1: that parses the request string -* 2: that parses the metadata scope - -* code examples -* a website with interface/workflow example, similar to BitID -* social integration protocol -* interface guidelines (color-coding privacy impact, etc.) -* What about localization? Are local languages allowed for metadata or not? -* favicon or something more advanced to help identify the site in IM (guideline) -* Oath1/2 server that authenticates with CashID, as a compatibiltiy bridge. -* Introduction video in the style of we-use-coins \ No newline at end of file