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.

Sign up for GitHub

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

Jump to bottom

SEP-10: Make SIGNING_KEY required and change manage data op value #708

Merged
merged 7 commits into from
Aug 27, 2020
Merged

SEP-10: Make SIGNING_KEY required and change manage data op value #708

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1c40143
make SIGNING_KEY required and change manage data op value
JakeUrban Aug 14, 2020
fba9de6
fixed the numbering
JakeUrban Aug 14, 2020
3beb591
simplify 2nd added step
JakeUrban Aug 14, 2020
ea9bdfe
changes related to PR comments
JakeUrban Aug 17, 2020
7b753df
update description of managedata op
JakeUrban Aug 17, 2020
59e0c61
update to 2.0
JakeUrban Aug 19, 2020
f32731c
changes regarding manage data op key encoding and optional home_domai…
JakeUrban Aug 24, 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
29 changes: 17 additions & 12 deletions ecosystem/sep-0010.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
```
SEP: 0010
Title: Stellar Web Authentication
Author: Sergey Nebolsin <[email protected]>, Tom Quisel <[email protected]>, Leigh McCulloch <@leighmcculloch>
Author: Sergey Nebolsin <[email protected]>, Tom Quisel <[email protected]>, Leigh McCulloch <@leighmcculloch>, Jake Urban <[email protected]>
Status: Active
Created: 2018-07-31
Updated: 2020-04-03
Version 1.3.1
Updated: 2020-08-14
Version 2.0.0
```

## Simple Summary
Expand All @@ -22,6 +22,8 @@ The authentication flow is as follows:

1. The client obtains a unique [`challenge`](#challenge), 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).
1. The client verifies that the transaction includes a Manage Data operation, and that the value contains the home domain used to request the challenge.
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
1. The server checks that the user's account exists
Expand Down Expand Up @@ -66,7 +68,7 @@ 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 can 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). Additionally, the client must ensure that the challenge transaction was created by the requested service by checking the value of the Manage Data operation.

#### Request

Expand All @@ -79,6 +81,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.

Example:

Expand All @@ -94,21 +97,21 @@ On success the endpoint must return `200 OK` HTTP status code and a JSON object
* source account set to server's signing account
* invalid sequence number (set to 0) so the transaction cannot be run on the Stellar network
* 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: '<anchor name> auth', value: random_nonce())`
* The value of key is not important, but can be the name of the anchor followed by `auth`. It can be at most 64 bytes.
* 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 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).
* signature by the web service signing account
* 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.

Example:
```json
{
"transaction": "AAAAAGjeCRajN67nRkVtYO+lpxax9gvitX9FxhZYGXQvs16hAAAAZAAAAAAAAAAAAAAAAQAAAABbcutKAAAAAFty7HYAAAAAAAAAAQAAAAEAAAAAVIx5odtAgqQ+dp4m4QfWntHbOq0hxRCLGI+2Sm0P6EMAAAAKAAAAC01vYml1cyBhdXRoAAAAAAEAAABAG01TL/Ha0YGVrAF6t0UEKP/0Q/NDUymciQBA/CXzYMVlEx2KcHrq3MkpQ9+9sCbCiOYa7wCtusa1tHKygvZRSwAAAAAAAAABL7NeoQAAAEC9v5jdxReIxoCcCXw90dVsIpXwHXkSHUUthCs98D/zpd6TNPvcMgUsQd6cDHzjNk+/00P8M5bHP4rIpFTm7MwN",
"transaction": "AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAfheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3Ag==",
"network_passphrase": "Public Global Stellar Network ; September 2015"
}
```

You can examine the example challenge transaction in the [XDR Viewer](https://www.stellar.org/laboratory/#xdr-viewer?input=AAAAAGjeCRajN67nRkVtYO%2Blpxax9gvitX9FxhZYGXQvs16hAAAAZAAAAAAAAAAAAAAAAQAAAABbcutKAAAAAFty7HYAAAAAAAAAAQAAAAEAAAAAVIx5odtAgqQ%2Bdp4m4QfWntHbOq0hxRCLGI%2B2Sm0P6EMAAAAKAAAAC01vYml1cyBhdXRoAAAAAAEAAABAG01TL%2FHa0YGVrAF6t0UEKP%2F0Q%2FNDUymciQBA%2FCXzYMVlEx2KcHrq3MkpQ9%2B9sCbCiOYa7wCtusa1tHKygvZRSwAAAAAAAAABL7NeoQAAAEC9v5jdxReIxoCcCXw90dVsIpXwHXkSHUUthCs98D%2Fzpd6TNPvcMgUsQd6cDHzjNk%2B%2F00P8M5bHP4rIpFTm7MwN&type=TransactionEnvelope&network=test).
You can examine the example challenge transaction in the [XDR Viewer](https://laboratory.stellar.org/#xdr-viewer?input=AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX%2BF4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST%2FfImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAfheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA%2BxM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3Ag%3D%3D&type=TransactionEnvelope)

Every other HTTP status code will be considered an error. For example:

Expand All @@ -132,7 +135,9 @@ To validate the challenge transaction the following steps are performed by the s
* decode the received input as a base64-urlencoded XDR representation of Stellar transaction envelope;
* verify that transaction source account is equal to the server's signing key;
* 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 and its source account is not null;
* 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 service's 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 Expand Up @@ -177,10 +182,10 @@ Example:
POST https://auth.example.com/
Content-Type: application/json

{"transaction": "AAAAAGjeCRajN67nRkVtYO+lpxax9gvitX9FxhZYGXQvs16hAAAAZAAAAAAAAAAAAAAAAQAAAABbcutKAAAAAFty7HYAAAAAAAAAAQAAAAEAAAAAVIx5odtAgqQ+dp4m4QfWntHbOq0hxRCLGI+2Sm0P6EMAAAAKAAAAC01vYml1cyBhdXRoAAAAAAEAAABAG01TL/Ha0YGVrAF6t0UEKP/0Q/NDUymciQBA/CXzYMVlEx2KcHrq3MkpQ9+9sCbCiOYa7wCtusa1tHKygvZRSwAAAAAAAAACL7NeoQAAAEC9v5jdxReIxoCcCXw90dVsIpXwHXkSHUUthCs98D/zpd6TNPvcMgUsQd6cDHzjNk+/00P8M5bHP4rIpFTm7MwNbQ/oQwAAAEAz+6EANIKAAR8G62OkGzbnkxgyYuFwbbCwvbDbkk8db31I/EyR0gRpcxv7zzBAkn8g48N6x1huJhTUO0CPl28M"}
{"transaction": "AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAvheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3AsiYk3UAAABArIrkvqmA0V9lIZcVyCUdja6CiwkPwsV8BfI4CZOyR1Oq7ysvNJWwY0G42dpxN9OP1qz4dum8apG2hqvxVWjkDQ=="}
```

You can examine the example signed challenge transaction in the [XDR Viewer](https://www.stellar.org/laboratory/#xdr-viewer?input=AAAAAGjeCRajN67nRkVtYO%2Blpxax9gvitX9FxhZYGXQvs16hAAAAZAAAAAAAAAAAAAAAAQAAAABbcutKAAAAAFty7HYAAAAAAAAAAQAAAAEAAAAAVIx5odtAgqQ%2Bdp4m4QfWntHbOq0hxRCLGI%2B2Sm0P6EMAAAAKAAAAC01vYml1cyBhdXRoAAAAAAEAAABAG01TL%2FHa0YGVrAF6t0UEKP%2F0Q%2FNDUymciQBA%2FCXzYMVlEx2KcHrq3MkpQ9%2B9sCbCiOYa7wCtusa1tHKygvZRSwAAAAAAAAACL7NeoQAAAEC9v5jdxReIxoCcCXw90dVsIpXwHXkSHUUthCs98D%2Fzpd6TNPvcMgUsQd6cDHzjNk%2B%2F00P8M5bHP4rIpFTm7MwNbQ%2FoQwAAAEAz%2B6EANIKAAR8G62OkGzbnkxgyYuFwbbCwvbDbkk8db31I%2FEyR0gRpcxv7zzBAkn8g48N6x1huJhTUO0CPl28M&type=TransactionEnvelope&network=test).
You can examine the example signed challenge transaction in the [XDR Viewer](https://laboratory.stellar.org/#xdr-viewer?input=AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX%2BF4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST%2FfImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAvheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA%2BxM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3AsiYk3UAAABArIrkvqmA0V9lIZcVyCUdja6CiwkPwsV8BfI4CZOyR1Oq7ysvNJWwY0G42dpxN9OP1qz4dum8apG2hqvxVWjkDQ%3D%3D&type=TransactionEnvelope)

#### Response

Expand Down