BitcoinCash/cashId
1
Fork 0
Code Issues Pull Requests Releases Activity

Remove progressive example. (Downloaded it first, will use it for a guide/tutorial on a website later)

Browse Source
This commit is contained in:
Jonathan Silverblood
2018-09-29 05:52:17 +00:00
parent d4f6c8f579
commit e54d3669bc
1 changed files with 0 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README2.md
-310
View File
@@ -1,310 +0,0 @@
*Status: Incomplete draft*<br/>
*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>
```
**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=<nonce>&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=<nonce>
```
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=<action>&d=<data>&r=<required>&o=<optional>&x=<nonce>
```
**Part** | **Example** | **Description**
--- | --- | ---
Intent | cashid: | Protocol identifier.
Domain | domain.tld | Fully qualified domain name.
Path | /path | Path to a request manager.
Parameters | a=action<br/>d=data<br/>r=required<br/>o=optional<br />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.
<br />
**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)<br/>*For example: "geo:13.4125,103.8667"*
<br />
**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=<action>&d=<data>&r=<required>&o=<optional>&x=<nonce>
```
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).
<br />
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
```
<br />
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
```
<br />
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
```
<br />
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