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

Clarify choice of passphrase in SEP-10 #345

Merged
merged 1 commit into from
Jul 10, 2019
Merged

Clarify choice of passphrase in SEP-10 #345

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 26 additions & 12 deletions ecosystem/sep-0010.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ Title: Stellar Web Authentication
Author: Sergey Nebolsin <sergey@mobius.network>, Tom Quisel <tom.quisel@gmail.com>
Status: Active
Created: 2018-07-31
Updated: 2018-08-14
Version 1.0.1
Updated: 2019-07-09
Version 1.1.0
```

## Simple Summary

This SEP defines the standard way for clients such as wallets or exchanges to create authenticated web sessions on behalf of a user who holds a Stellar account. A wallet may want to authenticate with any web service which requires a Stellar account ownership verification, for example, to upload KYC information to an anchor in an authenticated way as described in [SEP-6](sep-0006.md).
This SEP defines the standard way for clients such as wallets or exchanges to create authenticated web sessions on behalf of a user who holds a Stellar account. A wallet may want to authenticate with any web service which requires a Stellar account ownership verification, for example, to upload KYC information to an anchor in an authenticated way as described in [SEP-12](sep-0012.md).

## Abstract

Expand Down Expand Up @@ -65,20 +65,23 @@ GET https://auth.example.com/?account=GCIBUCGPOHWMMMFPFTDWBSVHQRT4DIBJ7AD6BZJYDI

#### Response

On success the endpoint should return `200 OK` HTTP status code and a JSON object with a `transaction` field containing an XDR-encoded Stellar transaction with the following:
On success the endpoint must return `200 OK` HTTP status code and a JSON object with these fields:

* 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() + 300 }` (we recommend expiration of 5 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.
* The value must be a 64 byte long base64 encoded cryptographic-quality random string
* signature by the web service signing account
* `transaction`: an XDR-encoded Stellar transaction with the following:
* 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() + 300 }` (we recommend expiration of 5 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.
* The value must be a 64 byte long base64 encoded cryptographic-quality random string
* signature by the web service signing account
* `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.
Copy link
Contributor

Choose a reason for hiding this comment

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

Looks good to me. I'm a little bit worried that network_passphrase is optional. It requires code that handles this situation and if developer forgets about it it may result in null pointer exceptions or using empty passphrase.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agreed. I think this is a necessary evil to make the change backwards compatible.


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

Expand Down Expand Up @@ -168,6 +171,17 @@ Every other HTTP status code will be considered an error. For example:
}
```

## A convention for signatures

Signatures in Stellar involve both the secret key of the signer and the passphrase of the network. SEP-10 clients and servers must use the following convention when deciding what network passphrase to use for signing and verifying signatures in SEP-10:

- If the server is for testing purposes or interacts with the Stellar testnet, use the Stellar testnet passphrase.
- Otherwise, use the Stellar pubnet passphrase.

This convention ensures that SEP-10 clients and servers can use the same passphrase as they're using for interacting with the Stellar network.

The client can examine the `network_passphrase` (if defined) that the server includes in its response from the challenge endpoint to be sure it's using the correct passphrase and is connecting to the server that it expected.

## Implementations

* iOS and macOS SDK: https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/README.md#8-stellar-web-authentication