Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SEP-0010: Add back home domain verification with clarity (v3.0.0) #746

Merged
merged 22 commits into from
Nov 9, 2020
Merged
Changes from 10 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
93c47b3
SEP-0010: Add back home domain verification with clarity (v3.0.0)
leighmcculloch Oct 14, 2020
0c4f269
Make the abstract clearer
leighmcculloch Oct 15, 2020
828b448
Remove ambiguous service term
leighmcculloch Oct 15, 2020
ed16f83
Simplify discussion about servers that do not use stellar.toml for di…
leighmcculloch Oct 17, 2020
55e68ac
Simplify discussion about servers that do not use stellar.toml for di…
leighmcculloch Oct 17, 2020
f666a15
Fix typo
leighmcculloch Oct 17, 2020
ab53bf4
make discovery a clearly separate component
leighmcculloch Oct 17, 2020
aca4d28
Update ecosystem/sep-0010.md
leighmcculloch Oct 17, 2020
4210482
reference domain in discovery flow
leighmcculloch Oct 17, 2020
6c548e8
Fix sentence
leighmcculloch Oct 17, 2020
eb00ba8
Remove ambiguous first step language
leighmcculloch Oct 19, 2020
b22afa9
Remove authenticating for language
leighmcculloch Oct 19, 2020
a235c63
Reference discovery flow in step using signing key
leighmcculloch Oct 21, 2020
bb7700e
Remove longer explanation about how to deal with key rotation that is…
leighmcculloch Oct 23, 2020
5e48d43
Improve description of three components
leighmcculloch Oct 23, 2020
fdcfa0c
Note that the signing key is looked up too
leighmcculloch Oct 23, 2020
b37dac3
Reduce repetition
leighmcculloch Oct 23, 2020
d7fffa3
Update version and details
leighmcculloch Oct 23, 2020
5fb8678
Simplify reptition
leighmcculloch Oct 23, 2020
e732188
Explicitly refer to SEP-1
leighmcculloch Nov 7, 2020
753f5ff
Merge branch 'master' into sep10-v3.0.0-b
leighmcculloch Nov 7, 2020
1d066da
Separate dot point for verification steps
leighmcculloch Nov 7, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions ecosystem/sep-0010.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,21 @@ 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.

The authentication flow is as follows:
It involves three parties:
- A home domain hosting a [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` value.
- A web auth endpoint providing the GET and POST operations discussed in this document.
- A client who will authenticate with a Stellar account.
Copy link
Contributor

@nebolsin nebolsin Oct 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Listing "home domain" and "endpoint" as "parties" sounds a little off to me, maybe we can improve the wording here? Also it might be better to use the word "wallet" instead of "account" because the spec supports authentication with any Stellar keypair, not necessarily created on the network.

Suggested change
- A home domain hosting a [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` value.
- A web auth endpoint providing the GET and POST operations discussed in this document.
- A client who will authenticate with a Stellar account.
- A web service which requires authentication with a Stellar wallet. The service must host [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` and `SIGNING_KEY` values.
- An authentication service providing the GET and POST endpoints discussed in this document.
- A client who wants to authenticate with web service using Stellar wallet.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think to add the terms web service here is more prescriptive than we need to be. An authentication service or simply an endpoint on some other service is an implementation detail and a decision the SEP doesn't need to make. The intention of this three point list is to call out upfront what the three things are that are involved: You need a domain hosting a stellar.toml, an endpoint to provide the challenge and token, and a client who is going to talk to the first two.

I applied some changes to the sentences to make it clearer and removed the term parties.

Let me know if I'm misunderstanding the distinction you're seeing that needs to be here.

Copy link
Contributor

@JakeUrban JakeUrban Oct 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with the intent of the suggestion, just two recommendations:

  • swap wallet for client. Wallets are a subset of SEP-10 clients.
  • We need a clear distinction between the SEP-10 service and the home domain that has the TOML. When saying web service which requires authentication, it is not clear which one we're talking about. I'd change it to web service hosting a [SEP-1 stellar.toml](sep-0001.md) file containing a WEB_AUTH_ENDPOINT at the standardized /.well-known/stellar.toml URL path.


The discovery flow is as follows:

1. The client retrieves the [SEP-1 stellar.toml](sep-0001.md) from the home domain. The home domain hosts the stellar.toml.
Copy link
Contributor

@nebolsin nebolsin Oct 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall we specify how the client gets from the web service URI to a home domain? Starting from "home domain" may be ambiguous, especially in case of non-default ports (for web service "https://host:port/service/", where port is not 443, clients could come up with either host or host:port as a home domain).

Suggested change
1. The client retrieves the [SEP-1 stellar.toml](sep-0001.md) from the home domain. The home domain hosts the stellar.toml.
1. At the beginning of the flow client has an URI of the web service requesting authentication and the public key of the authenticating user. Client extracts the authority component from the service URI (as defined by [RFC-3986](https://tools.ietf.org/html/rfc3986#page-17)) and notes its value, which will be referred to as "home domain" for the rest of this spec.
1. Client retrieves the [SEP-1 stellar.toml](sep-0001.md) metadata file from the home domain.

Copy link
Member Author

@leighmcculloch leighmcculloch Oct 23, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took a look at applying this change here, however I believe this is unnecessary because to do so is to respecify SEP-1 which is linked here. SEP-1 describes how a client should retrieve a stellar.toml from a domain and what portion of the URL is the domain. https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md#specification

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think SEP-1 defines what we need here, specifically there's no reference to RFC3986 => no resolution for host:port vs host ambiguity. SEP-1 starts with Given the domain DOMAIN, which is one step ahead of where we are in this spec, and there's a good reason for that. SEP-1 originated from a need to link Stellar account to some metadata which is stored and accessed off-chain. It is not explicitly mentioned in the specification section, but account de facto provides the entrypoint and root context for SEP-1 flow. As far as SEP-1 is concerned, DOMAIN is whatever we find in account's home_domain field.

On the other hand, with SEP-10 we want to adopt Stellar keypairs as an authentication method for traditional web, which means that we need to carefully define how to plug Stellar concepts into the well-established framework of existing standards, in particular HTTP/1.1: Message Syntax and Routing [RFC7230] and HTTP/1.1: Authentication [RFC7235]. The disposition for SEP-10 is user agent (client) wants to obtain authentication credentials in order to request some representation of the protected resource from the origin server. Resources in HTTP are identified by URI, so one thing we know for sure is that at the start of SEP-10 client is aware of the target URI, but there's no notion of "home domain" or "domain". Without specification every client implementing SEP-10 has to figure out how to convert the URI of the protected resource into the DOMAIN input expected by SEP-1, and that's not a good situation from the compatibility angle.

There's also a security angle, because any loosely specified term like home domain in security boundary definition has a potential for all sorts of vulnerabilities and attacks. For example, RFC3986 goes into great details defining the calculation of URIs equality, which if implemented incorrectly may result in compatibility and/or security issues down the road. Anchoring this SEP to existing well-established internet standards increases the odds that developers will rely on the proper library implementations, instead of going with simple but potentially dangerous approach (like comparing URIs as strings).

Maybe I put too much emphasis on this and this SEP will probably never see the level of adoption where things like that will become important. But if we can eliminate potential ambiguity and make the spec a little more formal, why not take this opportunity?

Copy link
Contributor

@JakeUrban JakeUrban Oct 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1000 this change, we need to clarify the home domains format so there aren't mismatches of the same service represented by slightly different home domain representations.

A couple things I want to note:

  • Add the before client
  • Are we sure we want to use the Authority format? I've never seen a username on a home domain IRL. I think we should instead specify it as Host + Port

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...one thing we know for sure is that at the start of SEP-10 client is aware of the target URI...
...every client implementing SEP-10 has to figure out how to convert the URI of the protected resource into the DOMAIN input expected by SEP-1...

I'm not sure this is consistent with what I know of some wallets and their implementations. From the limited wallets I've seen if there's a fixed list of anchors within a wallet it's a domain, not a URL. Our stellar.toml clients in some SDKs take a domain as input and build the URL themselves. Examples of this are:

I agree there is some room for improvement here, but I don't think it is detrimental to this changes success, and I still think the improvements you're specifying are improvements to SEP-1. SEP-1 is not limited to account-to-toml lookups, it also intended to generally specify how to go from a domain to a stellar.toml. You're correct that the domain is not sufficiently specified in regards to whether it includes a port or not. Practically this is unlikely to matter because production systems consistently use port 443 and HTTPS, or at least not enough for us to address urgently. None of the Stellar TOML clients in SDKs specify ports.

I think we can address this issue independent of SEP-10 v3.0.0.

I have changed the language at this line slightly in e732188 to more explicitly reference SEP-1, rather than casually reference it.

1. The client looks up the `WEB_AUTH_ENDPOINT` value from the [SEP-1 stellar.toml](sep-0001.md).
leighmcculloch marked this conversation as resolved.
Show resolved Hide resolved

1. The client obtains a unique [`challenge`](#challenge), which is represented as specially formed Stellar transaction
The authentication flow is as follows:
1. The client obtains a unique [`challenge`](#challenge) from the `WEB_AUTH_ENDPOINT`, which is represented as specially formed Stellar transaction
1. The client verifies that the transaction has an invalid sequence number 0. This is extremely important to ensure the transaction isn't malicious.
1. The client verifies that the transaction is signed by the `SIGNING_KEY` specified by the requested service's [SEP-1 stellar.toml](sep-0001.md).
leighmcculloch marked this conversation as resolved.
Show resolved Hide resolved
1. The client verifies that the transaction has a single Manage Data operation with its source account set to the user's account and value set to a nonce value. The client ignores the home domain included.
1. The client verifies that the transaction has a single Manage Data operation with its source account set to the user's account and value set to a nonce value. The client verifies the home domain included is the domain from the first step.
JakeUrban marked this conversation as resolved.
Show resolved Hide resolved
leighmcculloch marked this conversation as resolved.
Show resolved Hide resolved
1. The client verifies that if the transaction has other Manage Data operations they 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 @@ -69,7 +78,8 @@ In order for browsers-based wallets to validate the CORS headers, as [specified

### Challenge

This endpoint must respond with a Stellar transaction signed by the server that has an invalid sequence number (0) and thus cannot be executed on the Stellar network. The client can then sign the transaction using standard Stellar libraries and submit it to [`token`](#token) endpoint to prove that they control their account. This approach is compatible with hardware wallets such as Ledger. The client must also verify the server's signature to be sure the challenge is signed by the `SIGNING_KEY` from the server's [`stellar.toml`](sep-0001.md).
This endpoint must respond with a Stellar transaction signed by the server that has an invalid sequence number (0) and thus cannot be executed on the Stellar network. The client can then sign the transaction using standard Stellar libraries and submit it to [`token`](#token) endpoint to prove that they control their account. This approach is compatible with hardware wallets such as Ledger. The client must also verify the server's signature to be sure the challenge is signed by the `SIGNING_KEY` from the server's [`stellar.toml`](sep-0001.md), and the home domain in the challenge is the domain from the discovery flow.


#### Request

Expand All @@ -82,7 +92,7 @@ Request Parameters:
Name | Type | Description
----------|---------------|------------
`account` | `G...` string | The stellar account that the wallet wishes to authenticate with the server
`home_domain` | string | (optional) The [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the service requiring authentication. SEP-10 signing servers used to generate tokens for multiple different web services can use this parameter to create valid tokens for each service. If not provided by the client, a default should be used.
`home_domain` | string | (optional) The home domain the client would like to authenticate for. Servers that generate tokens for multiple home domains can use this parameter to identify which home domain the client hopes to authenticate for. If not provided by the client, the server should assume a default for backwards compatibility with older clients.
JakeUrban marked this conversation as resolved.
Show resolved Hide resolved

Example:

Expand All @@ -100,7 +110,7 @@ On success the endpoint must return `200 OK` HTTP status code and a JSON object
* time bounds: `{min: now(), max: now() + 900 }` (we recommend expiration of 15 minutes to give user time to sign transaction)
* operations:
* `manage_data(source: client_account, key: '<home domain> auth', value: random_nonce())`
* The value of key is the fully qualified domain name of the web service requiring authentication followed by `auth`. It can be at most 64 characters.
* The value of key is the home domain the challenge is providing authentication for, followed by `auth`. It can be at most 64 characters.
JakeUrban marked this conversation as resolved.
Show resolved Hide resolved
* 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
* signature by the service's stellar.toml `SIGNING_KEY`
Expand Down Expand Up @@ -140,6 +150,7 @@ To validate the challenge transaction the following steps are performed by the s
* verify that transaction has time bounds set, and that current time is between the minimum and maximum bounds;
* verify that transaction contains a single [Manage Data](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-data) operation that:
* has a non-null source account
* has the home domain as the key of the operation
* verify that transaction envelope has a correct signature by server's signing key;
* if the operation's source account exists:
* verify that client signatures count is one or more;
Expand Down