cashId/README.md

Status: Incomplete draft
BitID source: https://github.com/bitid/bitid

Abstract

CashID is an open protocol that allows secure authentication based on the public key cryptography infrastructure that is currently present in the Bitcoin Cash ecosystem. By authentication we mean to prove to a service provider that we control a specific Bitcoin Cash address by signing a challenge request that links the users address and optional metadata to a task or session with the service provider.

Motivation

Secure authentication and safe storage of credentials is useful for many things, and with added metadata we enable the following usecases:

• Register to a service as a 1-step process.
• Register to a service automatically as part of a payment.
• Authenticate to a service to login without a password.
• Authenticate to a service to act as 2FA complementing existing passwords.
• Provide access control to locks based on payment.

Rationale

Passwords is an inherently flawed concept (based on sharing secrets) that 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 users secret is never shared.

The problem with public key infrastructure is that managing private keys securely is complex, but this complexity is now being addressed in the cryptocurrency ecosystem which makes it possible to safely implement a better authentication system.

Specification

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 as QR code, by NFC touch or by any other implementation specific transmission method. The identity manager presents the request information to the end-user and allows the them to choose a suitable keypair to represent their identity.

If metadata was requested the identity manager provides the end-user the option to select which data to use for each metadata field, as well as the option to not supply information for any given field. If the user denies sharing of metadata for a field marked as required, the identity manager aborts the request.

Once approved by the end-user, the identity manager signs the full Challenge request, adds the metadata that was approved by the end-user and sends a Request response back to the service providers Request URL as a POST request.

The service provider validates the request, public key and signature of the response. If the request is valid the service provider then uses the public key as the users identifier and performs the requested action.

Challenge request

The request consists of an Intent, Domain, Path and set of Parameters.

cashid:domain.tld/cashid?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	/cashid	Path to a request manager
Parameters	?a=action &d=data &r=required &o=optional &x=nonce	These are settings that a service provider can use to inform the identity manager about what expectations the service provider has with regards to the response data

Parameters

Every request must have a Nonce parameter and may also have an Action, Data, Required and Optional parameter.

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

Action and Data

The optional Action parameter is used to describe the action that the user authenticates to perform. When a Data parameter is present, the Action also determines how to interpret it.

Service actions

The following is a list of common actions that a service provider can offer to users:

Action	Description	Data
login	Identifies the end-user to the service provider and grants access to digital services	Session identification ID used to link the login request with an active anonymous session
sign	Asks the end-user to cryptographically sign a message	Message text that the identity is requested to sign

User actions

The folowing 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 identity, position or contact metadata

Custom actions

It is plausible that this document cannot predict all possible usecases it enables, and service providers may choose to use custom non-standard action names and data fields to enable new usercases. If an identity manager parses a request with a foreign action it does not know about, it should inform the end-user and must abort the request.

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 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

Nonce

The Nonce parameter acts as a replay-protection mechanism and is a random number between X and Y formatted as a hexadecimal string (0123456789ABCDEF). Each Nonce can only be used a single time during it's lifespan and should expire if left unused.

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?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?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?a=delete

Response

When the identity manager is ready to submit a Request response it forms a Request URL by appending the Domain and Path components to a https:// scheme identifier.

https://domain.tld/cashid
  ^        ^          ^
cashid: domain.tld/cashid?a=action&d=data&r=required&o=optional&x=nonce

It then sends the Response data as a JSON encoded object with the following members:

(NOTE: the original spec just dumps all the data into POST, this is not always convenient, so maybe we should change it to url-encoded POST, like I described below)

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

Metadata is stored as a JSON object with property names matching the requested field names. Fields that has multiple values (for example social media accounts) is stored as a JSON object with property names matching their identifier and the data matching the field description.

For example, if the request contains r=i12&o=c the metadata part of the request answer would look like this:

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

Confirmation

The server responds to the POST with a valid JSON object:

Member	Data type	Description
Code	Integer	Code uniquely identifying the error type
Error	String	Name of the error
Details	String	Description of the error that can be directly presented to the user

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.

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.

Resources (to-do)

Supply a functional regexp!

• 1: that parses the request string

• 2: that parses the metadata scope

• QR code guidelines (case)

• nonce guidelines (probably alphanumeric, need to see what's good for QR, suggestion for length)

• 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