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

As a means of authentication, passwords have inherent security and UX issues. These issues are often mitigated by means of password managers, permanent sessions and single-signon features. CashID is designed to replace password authentication, thus solving the security and UX issues it has, instead of simply mitigating them.

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

Parameters

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

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 according to ISO-8601 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 Identity, 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:

Address

The Address field should be a valid Bitcoin Cash address in the CashAddr format.

Signature

The Signature must comply with the "\x18Bitcoin Signed Message:\n#{message.size.chr}#{message}" format and should sign the full challenge request string.

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.

Confirmation status

The service provider should supply a Confirmation status containing a Status code and optionally a Status message.

For a list of Status codes, see the Status codes resource.

Resources

Action types

Service actions can only be requested by the service provider.

User actions can be sent unsolicited to the service provider.

Metadata types

Identity is represented by the letter i followed by a list of numbers corresponding to the following table.

Position is represented by the letter p followed by a list of numbers corresponding to the following table.

Contact information is represented by the letter c followed by a list of numbers corresponding to the following table.

Status Codes

Status codes are used in the Request Confirmation.

Previous Status Codes

In a previous version of this document the status codes were different, but due to a vast number of issues encountered during initial implementations they are being scheduled to be removed from the specification.

Known security risks

Decoy provider (Man in the middle attack)

Since the challenge request is allowed to be transferred over a medium that is disconnected from the service provider it is possible for an attacker to fetch an authentication request that gives them access, and then present this to the user in a way that tricks the user into believing that they are legitimately interacting with the original service provider rather than the attacker.

When the user authenticates, they will then fullfill the attackers challenge request and the attacker will have gained access.

To mitigate this attack, identity managers that have the capability of knowing what domain delivered them the challenge request should verify that it is the same domain in the request as delivered it to them. There is no known mitigations when this relation cannot be verified.

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 qrprejjynve6e0qaecylv5m0k8a48acyvs5759l8kl will be sent to https://domain.tld/path :

{
 'request': 'cashid:domain.tld/path?x=2671757324',
 'address': 'qrprejjynve6e0qaecylv5m0k8a48acyvs5759l8kl',
 'signature': 'HyGJKQYaMk9aZ38Q9IJBCFi6a0q+QueIICEGCNsDJZaBft6SUMRNy5FGD0Rb2XIQ51Arff408AnrVxtg3tiWs4g='
}

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 qz0tyktxwyxdhx0zt4essf5ngfqwv3z6nyrq45n3x7 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': 'qz0tyktxwyxdhx0zt4essf5ngfqwv3z6nyrq45n3x7',
 'signature': 'HwSDACaveIdcdKxRJHQNWEV+wWK57XU4WfiRBusiR6PeaiWl8m/1VgCH5SYF3PO5YozJtrw5SGdCJo28SD2scbw=',
 '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 qqagsast3fq0g43wnrnweefjsk28pmyvwg7t0jqgg4 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': 'qqagsast3fq0g43wnrnweefjsk28pmyvwg7t0jqgg4',
 'signature': 'IKjtNWdIp+tofJQrhxBrq91jLwdmOVNlMhfnKRiaC2t2C7vqsHRoUA+BkdgjnOqX6hv4ZdeG9ZpB6dMh/sXJg/0=',
 'metadata':
 {
 'name': 'John',
 'family': 'Doe',
 'country': 'United States',
 'email': 'john@does.net'
 }
}

Account removal

The user initiated request to delete their user data from sensitive.cash

cashid:sensitive.cash/api/cashid?a=delete&x=20180929T063418Z

The JSON encoded response for a user with address qzvelmkfzvq8gw0d4fvmf904ghefq66keq68qwupsv will be sent to https://sensitive.cash/api/cashid :

{
 'request': 'cashid:sensitive.cash/api/cashid?a=delete&x=20180929T063418Z',
 'address': 'qzvelmkfzvq8gw0d4fvmf904ghefq66keq68qwupsv',
 'signature': 'IDwIyQCsmFKwWWibwtxVqppt+KCDBgTKy4IN8+rL+8a9XtGN/AAl/koKPKnIQOr2/nlzOW9XaxtWP96298XkiJE='
}

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 qqndur5yga4uej625xvatt03d0ryzd4u9sdj99f2mw 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': 'qqndur5yga4uej625xvatt03d0ryzd4u9sdj99f2mw',
 'signature': 'IN+npgZWwi+wDAgG4Za4goSws9jNcZG5EK5EPKuG/b/TMtzY67kU8olR26tAjDomQvf5KJif2Fc1nTdN8v10dpc=',
 '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

The expressions listed here is shown with whitespace and linebreaks for clarity and ease of updating and should be removed before use.

To parse a Challenge request into its parts

/
 (?P<intent>cashid:)
 (?:[\/]{2})?
 (?P<domain>[^\/]+)
 (?P<path>\/[^\?]+)
 (?P<parameters>\?.+)
/

To parse the Parameters into their parts

/
 (?(?:[\?\&]a=)(?P<action>[^\&]+))?
 (?(?:[\?\&]d=)(?P<data>[^\&]+))?
 (?(?:[\?\&]r=)(?P<required>[^\&]+))?
 (?(?:[\?\&]o=)(?P<optional>[^\&]+))?
 (?(?:[\?\&]x=)(?P<nonce>[^\&]+))?
/

To parse the Metadata fields into their parts

/
 (i
 (?P<identity>(?![1-9]+))?
 (?P<name>1)?
 (?P<family>2)?
 (?P<nickname>3)?
 (?P<age>4)?
 (?P<gender>5)?
 (?P<birthdate>6)?
 (?P<picture>8)?
 (?P<national>9)?
 )?
 (p
 (?P<position>(?![1-9]+))?
 (?P<country>1)?
 (?P<state>2)?
 (?P<city>3)?
 (?P<streetname>4)?
 (?P<streetnumber>5)?
 (?P<residence>6)?
 (?P<coordinate>9)?
 )?
 (c
 (?P<contact>(?![1-9]+))?
 (?P<email>1)?
 (?P<instant>2)?
 (?P<social>3)?
 (?P<phone>4)?
 (?P<postal>5)?
 )?
/

Libraries

CashID specific libraries:

• reference libraries (https://gitlab.com/cashid/libraries)
• react-cashid (https://github.com/paOol/react-cashid)
• cashid (https://github.com/paOol/CashID)

Bitcoin Cash generic libraries:

• bitcoincashjs

Links and Refences

BitID

The CashID specification was built on and inspired by the BitID draft and metadata documents:

• Specification: https://github.com/bitid/bitid/blob/master/BIP_draft.md
• Metadata: https://github.com/bitid/bitid/blob/master/bitid_metadata.md

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.

• code examples
• a website with interface/workflow example, similar to BitID
• interface guidelines (color-coding privacy impact, etc.)
• Oath1/2 server that authenticates with CashID, as a compatibiltiy bridge.
• Introduction video in the style of we-use-coins
• Look at alternatives to using 'application/json' headers with the encoded response in the body of the request, and then clarify in more detail what should be used.
• Consider using CashID for a legal canary notification, and/or usecase example showcasing how CashID simplified the process.