Web Auth API

If you want to authorize a user in your service by means of his Waves.Exchange account, here's the solution. You can redirect the user to the official Waves.Exchange Client (https://waves.exchange) with certain query parameters including some arbitrary data for the user to sign.

That might be needed in cases when you work with user personal data and to be sure that a given blockchain account belongs to that user.

Process

1. You add the Waves.Exchange Auth widget to your site.
2. A user stumbles upon your site and wants to log in using his Waves.Exchange account.
3. The user clicks the widget button and gets redirected to the official Waves.Exchange Client, along with some data from the widget.
4. There, the user chooses whether to log in or cancel that chain of actions.
5. If the user proceeds, the data will be signed with the user's private key.
6. The user then gets redirected back to your site, along with the signature and user's public key.
7. You check the validity of the signature against the data provided for the user.
8. If everything is correct, the user is now authenticated in your service.

If the user interrupts the process, he stays on the Waves.Exchange Client page.

Details

Due to the length limitations of the query string all parameters are expressed with one character.

Request

Example

https://waves.exchange#gateway/auth?r=https://example.com&n=ServiceName&d=0123456789abc&i=/img/logo.png&success=/wavesAuth

Basic path is https://waves.exchange#gateway/auth. Then the query parameters go.

Referrer

r=https://example.com — the URL of your service. It should be HTTPS-only. (Required)

Name

n=Service%20Name — the name of your service. (Required)

Data

d=randomChars — the data which is signed by the user's private key. (Required)

Icon path

i=/path/to/the/icon.png — a path relative to the Referrer parameter. It hosts the logo of your app. (Optional)

Success path

s=/path/to/an/API/method — a path to the method which redirects the user while the signing is successful. By default, the user is redirected to the referrer root. (Optional)

Debug mode

debug=true — a flag to display error messages. (Optional)

Response

Example

https://example.com/?s=2w7QKSkxKEUwCVhx2VGrt5YiYVtAdoBZ8KQcxuNjGfN6n4fi1bn7PfPTnmdygZ6d87WhSXF1B9hW2pSmP7HucVbh&p=2M25DqL2W4rGFLCFadgATboS8EPqyWAN3DjH12AH5Kdr&a=3PCAB4sHXgvtu5NPoen6EXR5yaNbvsEA8Fj

Signature

s=base58EncodedSignature — a signature of the data which is signed by the user's private key.

Public key

p=base58EncodedPublicKey — user's public key.

Address

a=base58EncodedAddress — user's Waves.Exchange address.

How to check signature validity

You can use the @waves/signature-generator npm package.

Signed data consists of three objects Prefix string + URL host + Provided Data. Signature is taken from the data in the following order: a WavesWalletAuthentication string, then a string with your host parameter value, then a string with your data parameter value. All strings are converted to length bytes + value bytes as in Data Transactions Prefix string and the host is required for security purposes if malicious service tries to use transaction data and signature from Auth API it would be useless to broadcast into blockchain.

We also suggest address validation in case the signature and public key is valid but the address was swapped.

typescript example code

import { verifyAuthData, libs } from '@waves/waves-transactions';


const authValidate = (data: { host: string; data: string }, signature: string, publicKey: string, chainId: string | number): boolean => {
    const chain = typeof chainId === 'string' ? chainId : String.fromCharCode(chainId);
    const address = libs.crypto.address({ publicKey }, chain);
    return verifyAuthData({ publicKey, address, signature }, data);
};

// Example
const data = await WavesKeeper.auth({data: '123'});

authValidate(data, { host: data.host, data: '123' }); // true

js example code

import { verifyAuthData, libs } from '@waves/waves-transactions';


const authValidate = (data, signature, publicKey, chainId) => {    
   const chain = typeof chainId === 'string' ? chainId : String.fromCharCode(chainId);
   const address = libs.crypto.address({ publicKey }, chain);
   return verifyAuthData({ publicKey, address, signature }, data);
};

// Example
const data = await WavesKeeper.auth({data: '123'});

authValidate(data, { host: data.host, data: '123' }); // true

Python example code

import axolotl_curve25519 as curve
import pywaves.crypto as crypto
import base58
from urllib.parse import urlparse, parse_qs
 
 
def str_with_length(string_data):
    string_length_bytes = len(string_data).to_bytes(2, byteorder='big')
    string_bytes = string_data.encode('utf-8')
    return string_length_bytes + string_bytes
 
 
def signed_data(host, data):
    prefix = 'WavesWalletAuthentication'
    return str_with_length(prefix) + str_with_length(host) + str_with_length(data)
 
 
def verify(public_key, signature, message):
    public_key_bytes = base58.b58decode(public_key)
    signature_bytes = base58.b58decode(signature)
 
    return curve.verifySignature(public_key_bytes, message, signature_bytes) == 0
 
 
def verifyAddress(public_key, address):
    public_key_bytes = base58.b58decode(public_key)
    unhashed_address = chr(1) + str('W') + crypto.hashChain(public_key_bytes)[0:20]
    address_hash = crypto.hashChain(crypto.str2bytes(unhashed_address))[0:4]
    address_from_public_key = base58.b58encode(crypto.str2bytes(unhashed_address + address_hash))
 
    return address_from_public_key == address
 
 
 
redirected_url = 'https://example.com/?s=2w7QKSkxKEUwCVhx2VGrt5YiYVtAdoBZ8KQcxuNjGfN6n4fi1bn7PfPTnmdygZ6d87WhSXF1B9hW2pSmP7HucVbh&p=2M25DqL2W4rGFLCFadgATboS8EPqyWAN3DjH12AH5Kdr&a=3PCAB4sHXgvtu5NPoen6EXR5yaNbvsEA8Fj'
parsed_url = urlparse(redirected_url)
parsed_query = parse_qs(parsed_url.query)
 
address = parsed_query['a'][0]
pub_key = parsed_query['p'][0]
signature = parsed_query['s'][0]
data_string = '0123456789abc'
host_string = parsed_url.netloc
message_bytes = signed_data(host_string, data_string)
 
print('Address:', address)
print('Public key:', pub_key)
print('Signed Data:', message_bytes)
print('Real signature:', signature)
print('Verified:', verify(pub_key, signature, message_bytes))
print('Address verified:', verifyAddress(pub_key, address))
 
fake_signature = '29qWReHU9RXrQdQyXVXVciZarWXu7DXwekyV1zPivkrAzf4VSHb2Aq2FCKgRkKSozHFknKeq99dQaSmkhUDtZWsw'
 
print('Fake signature:', fake_signature)
print('Fake signature verification:', verify(pub_key, fake_signature, message_bytes))

Php example code

<?php

/*
 * Requires WavesKit by deemru
 * https://github.com/deemru/WavesKit
 */

require_once __DIR__ . '/vendor/autoload.php';
use deemru\WavesKit;

function signed_data( $host, $data )
{
    $prefix = 'WavesWalletAuthentication';
    return str_with_length($prefix) . str_with_length($host) . str_with_length($data);    
}

function str_with_length( $data )
{
    return pack('n', strlen($data)).$data;
}

$wk = new WavesKit("W");
$redirected_url = "https://example.com/?s=2w7QKSkxKEUwCVhx2VGrt5YiYVtAdoBZ8KQcxuNjGfN6n4fi1bn7PfPTnmdygZ6d87WhSXF1B9hW2pSmP7HucVbh&p=2M25DqL2W4rGFLCFadgATboS8EPqyWAN3DjH12AH5Kdr&a=3PCAB4sHXgvtu5NPoen6EXR5yaNbvsEA8Fj";
$parsed_url = parse_url($redirected_url);
parse_str($parsed_url['query'], $parsed_query);
$address = $parsed_query['a'];
$pub_key = $parsed_query['p'];
$signature = $parsed_query['s'];
$data_string = '0123456789abc';
$host_string = $parsed_url['host'];
$message_bytes = signed_data($host_string, $data_string);

$wk->log('i', 'Address: '. $address);
$wk->log('i', 'Public key:' . $pub_key);
$wk->log('i', 'Signed Data: ' . $message_bytes);
$wk->log('i', 'Real signature: '. $signature);

$wk->setPublicKey( $pub_key );
$is_address_verified = $address === $wk->getAddress();

if ( $is_address_verified === true) 
    $wk->log('s', "Address: Verified: TRUE"); 
else 
    $wk->log('e', "Address: Verified: FALSE");

$signature_verified = $wk->verify($wk->base58Decode($signature), $message_bytes);

if ( $signature_verified === true) 
    $wk->log('s', "Signature Verified: TRUE"); 
else 
    $wk->log('e', "Signature Verified: FALSE");

$fake_signature = '29qWReHU9RXrQdQyXVXVciZarWXu7DXwekyV1zPivkrAzf4VSHb2Aq2FCKgRkKSozHFknKeq99dQaSmkhUDtZWsw';
$wk->log('i', 'Fake Signature: '. $fake_signature);

$signature_verified = $wk->verify($wk->base58Decode($fake_signature), $message_bytes);

if ( $signature_verified === true) 
    $wk->log('e', "Fake Signature Verified: TRUE"); 
else 
    $wk->log('s', "Fake Signature Verified: FALSE");
?>