Jonathan Silverblood
16 KiB
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. Each user can prove to a service provider that they control a specific Bitcoin Cash address by signing a challenge request, as well as provide optional metadata.
Motivation
Passwords is an inherently flawed concept based on sharing secrets that is increasingly getting hidden away from the users by means of password managers, permanent sessions and single-signon features. Public key cryptography provides a more secure method for authentication where the users secret is never shared.
Secure authentication with optional metadata is useful, for example to...
- Register with a service as a 1-step process.
- Register with 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.
- Support transient user profiles.
Specification
Introduction
When a user needs to access a physical or digital restricted area they are given a Challenge request by the service provider. The identity manager presents the request to the user and allows them to choose a suitable keypair to represent their identity.
If metadata was requested the identity manager provides the 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.
When the user has chosen an identity, the identity manager signs the challenge request, adds the metadata that was approved by the user and sends a Challenge response back to the service provider.
The service provider validates the response and returns a Confirmation status. If the confirmation contains a status message it is shown to the user.
The service provider can now use the address as a user identifier and perform 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 |
Various parameters |
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 |
Nonce
The Nonce parameter acts as a replay-protection mechanism, by making each request challenge and response unique. Each Nonce can only be used a single time during its lifespan and should expire if left unused for a significant amount of time.
The service provider should not process requests that it has not issued nonces for, except for User actions that have a valid and recent Timestamp as their nonce value.
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. When omitted, the Action is assumed to have the default value of "auth" which authenticates with an optional Data message.
Identity managers may implement any predefined and custom actions, but must implement the default auth action.
For a list of Service and User actions, see the Actions resource.
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 field numbers in each category has to be listed in sorted order, starting with the lowest number. If the same information is requested in both required and optional scope, the information is required.
For a list of Identification, Position and Contact metadata fields, see the Metadata resource.
Challenge Response
When the identity manager is ready to submit a Challenge response it forms a Response 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:
| Member | Data type | Description |
|---|---|---|
| request | String | The challenge request URI |
| address | String | Address used to sign the request |
| signature | String | Signature for the request |
| metadata | Object | Requested metadata fields |
Address
The Address field should be a valid Bitcoin Cash address in the CashAddr format.
Signature
The Signature must comply to the "\x18Bitcoin Signed Message:\n#{message.size.chr}#{message}" format.
Metadata
Metadata is stored as a JSON object with property names matching the requested field names. Fields that have multiple values is stored as a JSON object with property names matching their identifier and values matching the field description.
For example, if the request contains r=i12&o=c the metadata part of the request answer could look like this:
metadata:
{
'name': 'John',
'family': '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 status
The service provider should supply a Confirmation status containing a Status code and optionally a Status message.
| Member | Data type | Description |
|---|---|---|
| Status | Integer | Code that identifies the request status. |
| Message | String | Additional information to show the user. |
| 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 | Action not implemented | The requested action is not supported at this service provider |
Resources
Action types
Service actions can only be requested by the service provider.
| Action | Description | Data |
|---|---|---|
| auth | Identifies the user to the service provider | Optional message to display to the user |
| login | Grants the user access to digital services | Session identification ID used to link the login request with an active anonymous session |
| sign | Asks the user to cryptographically sign a message | Message text that the identity is requested to sign |
| register | Registers the user with a service, for example a newsletter or drawing of a lottery. | Description of the service the user signs up to |
| ticket | Grants an identity future access to a resource, for example a ride in a rollercoaster or a seat at a conference | Description of the resource and ticket validity |
| claimtx? | Asks the user to prove ownership of any address used in a transaction | Transaction identifier |
| claimaddr? | Asks the user to prove ownership of a specific address | Address identifier |
User actions can be sent unsolicited to the 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 |
Metadata types
Identification is represented by the letter i followed by a list of numbers corresponding to the following table.
| Number | Name | Description | Examples |
|---|---|---|---|
| 1 | Name | The first or given name of the person | John Jane |
| 2 | Family | The last name or family name of the person | Doe Simpsons |
| 3 | Nickname | A nickname or username for the person | SweetMafia55 |
| 4 | Age | The number of years the person has lived | 31 |
| 5 | Gender | The sex of the person, usually "Male" or "Female" | Male Robot |
| 6 | Birthdate | The date of birth... what format? (YYYY-MM-DD?) | 1969-04-01 |
| 8 | Picture | URL to a profile picture, or Base64 encoded image | https://www.yours.org/gravatar/satoshidoodles/180 data:image/jpeg;base64,/9j/4AAQSkZJRgAB...igAA96KKKAP/Z |
| 9 | National | National identification numbers, such as passport, drivers license and citizenship numbers. | 19840801-1221 |
Position is represented by the letter p followed by a list of numbers corresponding to the following table.
| Number | Name | Description | Examples |
|---|---|---|---|
| 1 | Country | Name of the nation | Norway |
| 2 | State | Name of the state or province | Westshire |
| 3 | City | Name of the city | New York |
| 4 | Street name | Name of the street, without the street number | Elm street |
| 5 | Street number | The street number | 41 |
| 6 | Residence | Building or apartment number that uniquely reference a residence | LGH1102 |
| 9 | Coordinate | Geographical position as specificed in RFC5870 | 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 | Description | Examples |
|---|---|---|---|
| 1 | Email address | john@doe.net | |
| 2 | Instant | Instant Messenger protocol handle | { 'icq': 148264 } { 'jabber': 'testusers@networks.com' } |
| 3 | Social | Social media service handle or URL | { 'twitter': '@bitcoin' } { 'facebook': 'facebook.com/johndoe' } |
| 4 | Mobile phone | Personal cellphone number In ITU-T E.164 format |
+1 555 1234567 |
| 5 | Home phone | Residence phone number In ITU-T E.164 format |
+1 555 7654321 |
| 6 | Work phone | Work phone number In ITU-T E.164 format |
+1 555 3332210 |
| 7 | Postal label | Postal label for a physical address to which a service can send letters and packages |
Jonathan Lionheart Elm street 41 409 33 Gothenburg Sweden |
Examples
Minimal authentication request
The smallest possible request only authenticates a user.
cashid:domain.tld/path?x=2671757324
The JSON encoded response for a user with address ??? will be sent to https://domain.tld/path:
{
'request': 'cashid:domain.tld/path?x=2671757324',
'address': '???',
'signature': '???'
}
The service provider will validate the request and return an Authentication successful status message:
{
'status': 0
}
Logging in to a website
The login action for session 15366-4133-6141-9638 at cashtalk.org can use Nickname and Picture to update the user profile.
cashid:cashtalk.org/cashid?a=login&d=15366-4133-6141-9638&o=i38&x=13534642624
The JSON encoded response for a user with address ??? with an updated Picture will be sent to https://cashtalk.org/cashid:
{
'request': 'cashid:cashtalk.org/cashid?a=login&d=15366-4133-6141-9638&o=i38&x=13534642624',
'address': '???',
'signature': '???',
'metadata':
{
'picture': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFoAAAB[...]'
}
}
Signing up for a newsletter
The register action for the newsletter at bitcoin.com requires Name, Family, Country and Email to work, and will use Picture, Age, Gender and City if provided.
cashid:bitcoin.com/api/cashid?a=register&d=newsletter&r=i12l1c1&o=i458l3&x=95261230581
The JSON encoded response for a user with address ??? and no optional information will be sent to https://bitcoin.com/api/cashid:
{
'request': 'cashid:bitcoin.com/api/cashid?a=register&d=newsletter&r=i12l1c1&o=i458l3&x=95261230581',
'address': '???',
'signature': '???',
'metadata':
{
'name': 'John',
'family': 'Doe',
'country': 'United States',
'email': 'john@does.net'
}
}
Verification...
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
Account removal
The user initiated request to delete their user data from sensitive.cash
cashid:sensitive.cash/api/cashid?a=delete
Transient user profiles
The login action for session a7fbb9341ce3ae21 at democratictools.net (which as a security measure does not store user profile information) will only work if the user provides a nickname and email, and will give a better customized user experience if the user provides Country, Age, Gender and a Postal label.
cashid:democratictools.net/fn/auth?a=login&d=a7fbb9341ce3ae21&r=i3c1&o=i45p1c7&x=4295861935820
The JSON encoded response for a user with address ??? that optionally shares Country and Age will be sent to https://democratictools.net/fn/auth:
{
'request': 'cashid:democratictools.net/fn/auth?a=login&d=a7fbb9341ce3ae21&r=i3c1&o=i45p1c7&x=4295861935820',
'address': '???',
'signature': '???',
'metadata':
{
'nickname': 'Activ1337',
'email': 'activ1337@gmail.com',
'country': 'Norway',
'age': 31
}
}
Implementation support
In order to reduce implementation costs and increase implementation conformity, this specification supplies extra material that can be helpful to developers.
Regular expressions
To parse a Challenge request into its parts
/(?P<scheme>cashid:)[\/]*(?P<domain>[^\/])+(?P<path>\/[^\?]+)(?P<parameters>\?.+)?/
To parse the Parameters into their parts
To parse the Metadata fields into their parts
Libraries
CashID specific libraries:
- ???
Bitcoin Cash generic libraries:
- bitcoincashjs
TODO
These items is an ad-hoc todo list of things to do make CashID useful and widespread, and does not necessarily belong in the specification document.
- QR code guidelines (case)
- code examples
- a website with interface/workflow example, similar to BitID
- 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 IDM (guideline)
- Oath1/2 server that authenticates with CashID, as a compatibiltiy bridge.
- Introduction video in the style of we-use-coins