Skip to content

Commit

Permalink
SEP-0010: Add web auth domain manage data operation (v3.1.0) (#767)
Browse files Browse the repository at this point in the history
### What
Add a new manage data operation containing the server domain of the SEP-10 server that the server includes in the challenge transaction.

### Why
The challenge transaction includes the home domain in the challenge transaction which provides some certainty to the client that the challenge transaction they are signing is for the home domain they intend to sign for. In some situations where a home domain is not involved in the SEP-10 process it would be useful to have an explicit field containing the domain of the issuer so there is something the client can verify to ensure it is signing a change that was generated by the issuer and not just for the home domain.

In some cases the server domain and home domain are the same and this is somewhat redundant. However, the server domain are not always the same domain as the home domain because it is common to deploy SEP-10 as a separate service, and deploying separate services is usually easier implemented on different subdomains or entirely separate domains. This is reasonably common. One example of this is [this](https://stablecoin.anchorusd.com/.well-known/stellar.toml):
   - Home domain is `stablecoin.anchorusd.com`
   - SEP-10 domain is `api.anchorusd.com`

This change is not breaking for any server and client pair who are using [SEP-10 v2.1] or greater. SEP-10 v2.1 changes clients to allow there to be additional manage data operations as long as they followed some basic rules. It is not breaking because if servers include the new operation and clients have not upgraded, clients will ignore it. If clients upgrade and servers do not, clients will continue to verify challenge transactions because the new operation is only verified if the server includes it. Servers and clients opt-in to the benefit of an improved challenge-response handshake. SDKs that implement this should probably make the new field mandatory in their APIs, but the optionality supports this change being backwards compatible and allows us to roll it out with zero coordination between clients and servers. 

[SEP-10 v2.1]: 5acf11b
  • Loading branch information
leighmcculloch authored Jan 11, 2021
1 parent b99d112 commit 6c8c9cf
Showing 1 changed file with 12 additions and 5 deletions.
17 changes: 12 additions & 5 deletions ecosystem/sep-0010.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ Title: Stellar Web Authentication
Author: Sergey Nebolsin <@nebolsin>, Tom Quisel <tom.quisel@gmail.com>, Leigh McCulloch <@leighmcculloch>, Jake Urban <jake@stellar.org>
Status: Active
Created: 2018-07-31
Updated: 2020-12-14
Version 3.0.1
Updated: 2021-01-11
Version 3.1.0
```

## Simple Summary
Expand All @@ -19,8 +19,8 @@ This SEP defines the standard way for clients such as wallets or exchanges to cr
This protocol is a variation of mutual challenge-response, which uses Stellar transactions to encode challenges and responses.

It involves three components:
- A domain hosting a [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` and `SIGNING_KEY`, referred to as the home domain.
- An endpoint providing the GET and POST operations discussed in this document.
- A domain hosting a [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` (URL) and `SIGNING_KEY` (`G...`), referred to as the home domain.
- An endpoint providing the GET and POST operations discussed in this document. The endpoint may be hosted on the home domain, a sub-domain of the home domain, or any other domain. The domain where the endpoint is hosted is referred to as the web auth domain.
- A client who will authenticate using a Stellar account.

The discovery flow is as follows:
Expand All @@ -36,6 +36,10 @@ The authentication flow is as follows:
1. Source account set to the user's account.
1. Key set to `<home domain> auth` where the home domain is the home domain from the discovery flow.
1. Value set to a nonce value.
1. The client verifies that if the transaction has a Manage Data operation with key `web_auth_domain` that it has:
1. Source account set to the server's account.
1. Key set to `web_auth_domain`.
1. Value set to the domain name of the SEP-10 server from which the client requested the challenge.
1. The client verifies that if the transaction has other operations they are Manage Data operations that all have their source accounts set to the the server's account.
1. The client signs the transaction using the secret key(s) of signers for the user's Stellar account
1. The client submits the signed challenge back to the server using [`token`](#token) endpoint
Expand Down Expand Up @@ -115,7 +119,10 @@ On success the endpoint must return `200 OK` HTTP status code and a JSON object
* `manage_data(source: client_account, key: '<home domain> auth', value: random_nonce())`
* The value of key is the home domain the client is authenticating with, followed by `auth`. It can be at most 64 characters.
* The value must be 64 bytes long. It contains a 48 byte cryptographic-quality random string encoded using base64 (for a total of 64 bytes after encoding).
* zero or more `manage_data(source: server_account, ...)` reserved for future use
* subsequent operations, order unimportant:
* `manage_data(source: server_account, key: 'web_auth_domain', value: web_auth_domain)`
* The value is the web auth domain, the domain hosting the web auth endpoint and that the client connected to when requesting the challenge transaction. It can be at most 64 characters.
* zero or more `manage_data(source: server_account, ...)` reserved for future use
* signature by the service's stellar.toml `SIGNING_KEY`
* `network_passphrase`: (optional but recommended) Stellar network passphrase used by the server. This allows the client to verify that it's using the correct passphrase when signing and is useful for identifying when a client or server have been configured incorrectly.

Expand Down

0 comments on commit 6c8c9cf

Please sign in to comment.