Clarify choice of passphrase in SEP-10

[tomquisel]

• Clarify choice of passphrase for signatures in SEP-10
• Also add an optional response parameter to the challenge endpoint: network_passphrase to make debugging signature issues easier.
• Replace outdated reference to SEP-6 with reference to SEP-12

Addresses problem mentioned in stellar/go#1468
Closes #339

@nebolsin I'd love your feedback.

[bartekn]

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.

[tomquisel]

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

[nebolsin]

I want to point out that server’s network passphrase is implicitly bound to the challenge transaction as part of server’s signature, and the client is required to “verify that transaction envelope has a correct signature by server's signing key“, which I think provides a reliable way to protect from network mismatch issues and halt the flow before it gets to client-side signing.

It might be convenient to extend the response with network_passphrase (or should it actually be specified in stellar.toml? looks like currently SEP-1 doesn’t define this field) to simplify debugging or improve error reporting, but I think that the server’s signature check should still act as the ultimate verification.

[bartekn]

I want to point out that server’s network passphrase is implicitly bound to the challenge transaction as part of server’s signature, and the client is required to “verify that transaction envelope has a correct signature by server's signing key“, which I think provides a reliable way to protect from network mismatch issues and halt the flow before it gets to client-side signing.

I think the problem we're trying to solve is having to guess the passphrase if the first signature is incorrect. I agree that in most cases it will be pubnet or testnet passphrase but it's not defined anywhere so in reality the passphrase can be anything. Also, in #339 (comment) I pointed out that we had very similar problem in the past (two components were talking to each other but using different passphrases) and it was really difficult to debug.