AUTH.md

Coinfloor Authentication Process

WebSocket clients authenticate by sending an authentication message containing a numeric user identifier, a cookie (described as an API key on the Coinfloor website), a nonce chosen by the client, and an ECDSA signature. The signature covers the user identifier, a nonce chosen by the server (which is transmitted to the client upon its connecting to the server), and the nonce chosen by the client. The connection is secured using TLS.

Protocol

Authentication to the WebSocket server is by a Welcome notification sent to the client and an Authenticate command sent by the client.

• The Welcome notification contains a nonce field, whose value is a base64-encoded nonce that has been randomly generated by the server. The nonce is 16 bytes, and the base64 encoding transforms it into a 24-character string. This 16-byte nonce is hereafter referenced as the server nonce.
• The Authenticate command contains the following fields:
  • user_id: (integer) The unique numeric identifier of the authenticating user.
  • cookie: (string) A base64-encoded value that varies by user but is fixed for each specific user. In the Coinfloor web interface, this authentication cookie is called an "API Key."
  • nonce: (string) A base64-encoded nonce that has been randomly generated by the client. The nonce is 16 bytes, and the base64 encoding transforms it into a 24-character string. This 16-byte nonce is hereafter referenced as the client nonce.
  • signature: (pair of strings) The base64-encoded r and s values of an ECDSA signature over the SHA-224 digest of a message consisting of the concatenation of the 8-byte (big-endian) user identifier, the 16-byte server nonce, and the 16-byte client nonce. The signature uses the secp224k1 curve parameters published by the Standards for Efficient Cryptography Group in SEC 2: Recommended Elliptic Curve Domain Parameters version 2.0 (mirror). The private key used in signing is the 224-bit (big-endian) integer interpretation of the SHA-224 hash of the concatenation of the 8-byte (big-endian) user identifier and the UTF-8-encoded passphrase of the user.

Example

Suppose a client whose user identifier is 1 and whose passphrase is "opensesame" wishes to authenticate to the WebSocket server.

1. The client connects to the server and performs the WebSocket handshake.

2. The server sends a Welcome notification:

   {
   	"notice": "Welcome",
   	"nonce": "azRzAi5rm1ry/l0drnz1vw=="
   }

3. The client decodes the server nonce into these 16 bytes:

    0x6b347302 2e6b9b5a f2fe5d1d ae7cf5bf
   

   (N.B: Spaces are shown for the sake of clarity and do not denote elements of the actual value.)

4. The client randomly generates a 16-byte client nonce:

    0xf08c98ca f1fd82e8 cea9825d bff04fd0
   

5. The client encodes the client nonce using base64:

    8IyYyvH9gujOqYJdv/BP0A==
   

6. The client's cookie is:

    HGREqcILTz8blHa/jsUTVTNBJlg=
   

7. The client constructs a 40-byte message to sign, consisting of its user identifier, the server nonce, and the client nonce:

    0x00000000 00000001
    0x6b347302 2e6b9b5a f2fe5d1d ae7cf5bf
    0xf08c98ca f1fd82e8 cea9825d bff04fd0
   

8. The client constructs a seed for its private key, consisting of its user identifier and UTF-8-encoded passphrase:

    0x00000000 00000001
    0x6f70656e 73657361 6d65
   

9. The client hashes its seed using SHA-224 to obtain its private key:

    0xb89ea7fc d22cc059 c2673dc2 4ff40b97 83074646 86560d0a d7561b83
   

10. The client signs the 28-byte SHA-224 digest of the 40-byte message using its private key under secp224k1 and obtains, for example:

     r = 0x3fb77a9d 7b5b2a68 209e76f6 872078c5 791340d5 989854ad a3ab735e
     s = 0x34b84341 2f18a910 f18a7d4c e1d35978 60e6345b 22bf7894 cf67780a
    

    The sign_secp224k1 utility may be used to produce the signature.

11. The client encodes the signature using base64:

     P7d6nXtbKmggnnb2hyB4xXkTQNWYmFSto6tzXg==
     NLhDQS8YqRDxin1M4dNZeGDmNFsiv3iUz2d4Cg==
    

12. The client sends an Authenticate command to the server:

    {
    	"method": "Authenticate",
    	"user_id": 1,
    	"cookie": "HGREqcILTz8blHa/jsUTVTNBJlg=",
    	"nonce": "8IyYyvH9gujOqYJdv/BP0A==",
    	"signature": [
    		"P7d6nXtbKmggnnb2hyB4xXkTQNWYmFSto6tzXg==",
    		"NLhDQS8YqRDxin1M4dNZeGDmNFsiv3iUz2d4Cg=="
    	]
    }

13. The server verifies the cookie and signature and returns a success response:

    {
    	"error_code": 0
    }