From 95492267a8396a16c83a6196c5d4856a891eec30 Mon Sep 17 00:00:00 2001 From: Tom Quisel Date: Tue, 9 Jul 2019 14:34:04 -0700 Subject: [PATCH] Clarify choice of passphrase in SEP-10 --- ecosystem/sep-0010.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/ecosystem/sep-0010.md b/ecosystem/sep-0010.md index ca9b4678b..29686f12d 100644 --- a/ecosystem/sep-0010.md +++ b/ecosystem/sep-0010.md @@ -6,13 +6,13 @@ Title: Stellar Web Authentication Author: Sergey Nebolsin , Tom Quisel 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 @@ -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: ' 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: ' 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. 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" } ``` @@ -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