Signature

Table of Contents

• Introduction

• Mechanism

• Code Examples

Introduction

In this section, we will show you the mechanism of generating parameter sign. Additionally, we will provide some code examples to expedite the integration process.

Mechanism

The signature is hashed with SecurityKey using SHA256 algorithm.

For example:

curl 'https://domain/path/getSth?xx=1001&yy=&aa=hello&sign=signstring'

curl -X POST 'https://domain/path/updateSth' \
    -d '{"xx":1001,"yy":"","aa":"hello","sign":"signstring"}' \
    -H "Content-Type:application/json"

1. Rearrange all parameters alphabetically, excluding the parameter sign.

2. Concatenate the rearranged parameters with &, e.g. aa=hello&xx=1001. (yy is excluded here due to its empty value)

3. Append SecurityKey to the end of string aa=hello&xx=1001, and will get the pre-sign string likes: aa=hello&xx=1001&key=abc123

4. Encrypt the pre-sign string by using SHA256 algorithm.

5. Convert the ciphertext into lower case, and now the string is the sign.

Note: Please keep in mind that the provided example assumes a simplified scenario. In a real implementation, you would need to handle encoding, proper encryption, and other security considerations.

Code Examples

PHP7

Note: Please don't use function http_build_query to build the parameters.

function genSignature($params, $securityKey) {
  if (!is_array($params) || count($params) == 0) {
    return '';
  }

  ksort($params);
  $qs = '';
  foreach ($params as $k => $v) {
    if (!empty($v)) {
      $qs = $qs . "{$k}={$v}&";
    }
  }
  // e.g. $qs='aa=hello&xx=1001&key=abc123'
  $qs = $qs.'key='.$securityKey;
  return strtolower(hash_hmac("sha256", $qs, $securityKey));
}

// using
$params = [
  'aa' => 'hello',
  'xx' => 1001,
  'yy' => ""
];
$sign = genSignature($params, 'abc123');

// output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
echo $sign;

Golang

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"sort"
	"strings"

	"github.com/shopspring/decimal"
)

func GenSignature(p map[string]interface{}, securityKey string) string {
	delete(p, "sign")

	counter := len(p)
	ks := make([]string, 0, counter)
	for k := range p {
		ks = append(ks, k)
	}
	sort.Strings(ks)

	var val interface{}
	qs, tmp := "", ""
	for i := 0; i < counter; i++ {
        val = p[ks[i]]
        tmp = fmt.Sprintf("%v", val)

		switch val.(type) {
		case int64, int, float64:
			ss, _ := decimal.NewFromString(tmp)
			tmp = ss.String()
		}
		if len(tmp) > 0 {
			qs += ks[i] + "=" + tmp + "&"
		}
	}

    // e.g. $qs='aa=hello&xx=1001&key=abc123'
	qs = qs + fmt.Sprintf("key=%s", securityKey)
	h := hmac.New(sha256.New, []byte(securityKey))
	h.Write([]byte(qs))
	return strings.ToLower(hex.EncodeToString(h.Sum(nil)))
}

// using
params := make(map[string]interface{})
params["aa"] = "hello"
params["xx"] = 1001
params["yy"] = ""

// output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
sign := GenSignature(params, "abc123")
fmt.Println(sign)

Java

package com.xxx.demo;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public class Demo {
    public static void main(String[] args) {
        Map<String, Object> params = new HashMap<>();
        params.put("aa", "hello");
        params.put("xx", 1001);
        params.put("yy", "");
        try {
            String sign = genSignature(params, "abc123");

            // output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
            System.out.println(sign);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    public static String genSignature(Map<String, Object> params, String securityKey) throws Exception {
        if (params.isEmpty()) {
            throw new Exception("invalid params");
        }
        Collection<String> keySet = params.keySet();
        List<String> list = Lists.newArrayList(keySet);
        Collections.sort(list);
        StringBuilder sb = new StringBuilder();
        for (String s : list) {
            sb.append(s).append("=").append(params.get(s)).append("&");
        }
        sb.append("key=").append(securityKey);
        // sb.toString() = $qs='aa=hello&xx=1001&key=abc123'

        Mac sha256HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(securityKey.getBytes("UTF-8"), "HmacSHA256");
        sha256HMAC.init(secretKey);
        byte[] array = sha256HMAC.doFinal(sb.toString().getBytes("UTF-8"));

        StringBuilder res = new StringBuilder();
        for (byte item : array) {
            res.append(Integer.toHexString((item & 0xFF) | 0x100).substring(1, 3));
        }
        return res.toString().toLowerCase();
    }
}

Python3

import hashlib
import hmac

def genSignature(params, securityKey):
    if not isinstance(params, dict) or len(params) == 0:
        return ''

    sortedParams = sorted(params.items())
    qs = ''
    for k, v in sortedParams:
        if v:
            qs += f'{k}={v}&'

    qs += f'key={securityKey}'
    h = hmac.new(bytes(securityKey, "utf-8"), bytes(qs, "utf-8"), hashlib.sha256)
    return h.hexdigest().lower()

# using
params = {
    'aa': 'hello',
    'xx': 1001,
    'yy': ""
}
sign = genSignature(params, 'abc123')

# output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
print(sign)

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

class Demo
{
    static string genSignature(Dictionary<string, object> parameters, string securityKey)
    {
        if (parameters == null || parameters.Count == 0)
        {
            return string.Empty;
        }

        var sortedParams = parameters.OrderBy(p => p.Key);
        var queryString = string.Join("&", sortedParams
            .Where(p => !string.IsNullOrEmpty(p.Value?.ToString()))
            .Select(p => $"{p.Key}={p.Value}"));

        queryString += $"&key={securityKey}";

        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(securityKey)))
        {
            var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(queryString));
            return BitConverter.ToString(hash).Replace("-", "").ToLower();
        }
    }

    static void Main(string[] args)
    {
        var parameters = new Dictionary<string, object>
        {
            { "aa", "hello" },
            { "xx", 1001 },
            { "yy", "" }
        };

        var sign = genSignature(parameters, "abc123");

        // output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
        Console.WriteLine(sign);
    }
}

NodeJS

function genSignature(params, securityKey) {
  if (!Array.isArray(params) || params.length === 0) {
    return '';
  }

  params.sort(function(a, b) {
    return a[0].localeCompare(b[0]);
  });

  let qs = '';
  for (let i = 0; i < params.length; i++) {
    const [key, value] = params[i];
    if (value !== '') {
      qs += `${key}=${value}&`;
    }
  }

  qs += `key=${securityKey}`;
  qs = String(qs).toLowerCase();

  const crypto = require('crypto');
  return crypto
    .createHmac('sha256', securityKey)
    .update(qs)
    .digest('hex');
}

// using
const params = {
  aa: 'hello',
  xx: 1001,
  yy: ''
};
const sign = genSignature(Object.entries(params), 'abc123');

// output: 1c4492e23f7812c5781a30046c5d760ba3ae344de99a5700542715866f448825
console.log(sign);