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.
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.
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 **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](https://en.wikipedia.org/wiki/ISO_8601) as their nonce value.
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.
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.
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.
The **Address** field should be a valid Bitcoin Cash address in the [CashAddr](https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/cashaddr.md) format.
The **Signature** must comply with the "\x18Bitcoin Signed Message:\n#{message.size.chr}#{message}" format and should sign the full challenge request string.
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.
**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
<br />
**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
5 | Postal | Postal label for a physical address to which <br /> a service can send letters and packages | Jonathan Lionheart <br /> Elm street 41 <br/> 409 33 Gothenburg <br /> Sweden
231 | Response invalid method | The transmission method does not match specification.
232 | Response invalid address | The address is not valid.
233 | Response invalid signature | The signature is not valid.
234 | Response invalid metadata | The metadata is not valid.
300 | Service broken | The action+data could not be parsed.
311 | Service address denied | The service is not allowed for this address.
312 | Service address revoked | The service has revoked this address.
321 | Service action denied | The service action was denied.
322 | Service action unavailable | The service action is unavailable.
323 | Service action not implemented | The service action is not implemented.
331 | Service internal error | The service encountered an internal error.
#### 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.
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.
The JSON encoded response for a user with address **qz0tyktxwyxdhx0zt4essf5ngfqwv3z6nyrq45n3x7** with an updated **Picture** will be sent to **https://cashtalk.org/cashid**:
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.
The JSON encoded response for a user with address **qqagsast3fq0g43wnrnweefjsk28pmyvwg7t0jqgg4** and no optional information will be sent to **https://bitcoin.com/api/cashid**:
The JSON encoded response for a user with address **qzvelmkfzvq8gw0d4fvmf904ghefq66keq68qwupsv** will be sent to **https://sensitive.cash/api/cashid**:
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**.
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**:
In order to reduce implementation costs and increase implementation conformity, this specification supplies extra material that can be helpful to developers.
* 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.
