App-Authentication

Description

For api_secret not be revealed, signature is used when calling App-GetBizToken and App-Verify to ensure the communication security.

Signature Algorithm

String: a=[api_key]&b=[expire_time]&c=[current_time]&d=[random]

Parameters

Parameters	Corresponding	Note
a	api_key	Equivalent to an username, which is obtained from FaceID console.sdkauth.md)
b	expire_time	The validity of signature, which is a number displayed in UNIX Epoch timestamp. Unit: second.Please set to 0 for a single signature.
c	current_time	The timestamp when the signature is generated, in seconds. As a non-single signature, current_time should be not older than expire_time.
d	random	Unsigned decimal integer, which needs to generate it, up to 10 digits.

Note: A single signature means that the generated sign is used only once; a non-single signature means that the sign is allowed to be used multiple times for a period of time, and the time limit needs to be set.

Signature

Using HMAC-SHA1 algorithm to encrypt requests.

The signature generation process is as follows:

Generate a raw by stitching strings through various fields
Use api_secret to sign raw with HMAC-SHA1 algorithm
Splice the generated signature and raw, then performing Base64 encoding to finally generate a sign

Formula:

raw = "a={}&b={}&c={}&d={}".format(api_key, expire_time, current_time, random)
sign_tmp = HMAC-SHA1(api_secret, raw)
sign = Base64(''.join(sign_tmp, raw))

Note:

The standard Base64 encoding is used here, not the Base64 encoding of urlsafe.
Api_secret must be used with api_key and can be obtained from FaceID console.

Sample Code

Python Code Sample

import time
import hashlib
import base64
import random
import hmac
api_key = "Your api_key" 
api_secret = "Your api_secret" 
valid_durtion = 100 # valid time is 100 seconds.
current_time = int(time.time())
expire_time = current_time + valid_durtion
rdm = ''.join(random.choice("0123456789") for i in range(10))
raw = "a={}&b={}&c={}&d={}".format(api_key, expire_time, current_time, rdm)
sign_tmp = hmac.new(api_secret, raw, hashlib.sha1).digest()
sign = base64.b64encode(sign_tmp + raw)

Java Code Sample

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
import java.util.Random;
 
public class HmacSha1Sign {
 
    /** * Generate signature * * @param apiKey * @param secretKey * @param expired * @return * @throws Exception */ 
    public static String genSign(String apiKey, String secretKey, long expired) throws Exception {
        long now = System.currentTimeMillis() / 1000;
        int rdm = Math.abs(new Random().nextInt());
        String plainText = String.format("a=%s&b=%d&c=%d&d=%d", apiKey, now + expired, now, rdm);
        byte[] hmacDigest = HmacSha1(plainText, secretKey);
        byte[] signContent = new byte[hmacDigest.length + plainText.getBytes().length];
        System.arraycopy(hmacDigest, 0, signContent, 0, hmacDigest.length);
        System.arraycopy(plainText.getBytes(), 0, signContent, hmacDigest.length,
                plainText.getBytes().length);
        return encodeToBase64(signContent);
    }
 
    /** * Generate base64 encode * * @param binaryData * @return */
    public static String encodeToBase64(byte[] binaryData) {
        String encodedStr = Base64.getEncoder().encodeToString(binaryData);
        return encodedStr;
    }
 
    /** * Generate hmacsha1 signature * * @param binaryData * @param key * @return * @throws Exception */
    public static byte[] HmacSha1(byte[] binaryData, String key) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA1");
        SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
        mac.init(secretKey);
        byte[] HmacSha1Digest = mac.doFinal(binaryData);
        return HmacSha1Digest;
    }
 
    /** * Generate hmacsha1 signature * * @param plainText * @param key * @return * @throws Exception */
    public static byte[] HmacSha1(String plainText, String key) throws Exception {
        return HmacSha1(plainText.getBytes(), key);
    }
}

Objective-C Code Sample

#import "ViewController.h"
#import <CommonCrypto/CommonHMAC.h>
#import <CommonCrypto/CommonCryptor.h>
#import <math.h>
#define api_key @"Your api_key"
#define api_secret @"Your api_secret"

@interface ViewController ()
@end

@implementation ViewController
- (void)viewDidLoad {
 [super viewDidLoad];
 NSString* sign = [self getSignStr];
 NSLog(@"sign = %@",sign);
}

- (NSString*)getSignStr {
 int validdurtion = 10000;
 NSDate* date = [NSDate dateWithTimeIntervalSinceNow:0];   //get the current time 
 NSTimeInterval currenttime = [date timeIntervalSince1970];
 long int expiretime = currenttime + validdurtion;
 long random = labs(arc4random() % 100000000000);
 NSString* str = [NSString stringWithFormat:@"a=%@&b=%ld&c=%f&d=%ld" ,api_key,expiretime,currenttime,random];
 const char *cKey  = [api_secret cStringUsingEncoding:NSUTF8StringEn coding];
 const char *cData = [str cStringUsingEncoding:NSUTF8StringEncoding];
 
 char cHMAC[CC_SHA1_DIGEST_LENGTH];
 CCHmac(kCCHmacAlgSHA1, cKey, strlen(cKey), cData, strlen(cData), cH MAC);
 NSData *HMAC = [[NSData alloc]initWithBytes:cHMAC length:sizeof(cHM AC)];
 NSData* sign_raw_data = [str dataUsingEncoding:NSUTF8StringEncoding ];
 NSMutableData* data = [[NSMutableData alloc] initWithData:HMAC];
 [data appendData:sign_raw_data];
 NSString* sign = [data base64EncodedStringWithOptions:0];
 return sign;
}

@end

PHP Code Sample

<?php
 
function gen_sign($apiKey, $apiSecret, $expired){
    $rdm = rand();
    $current_time = time();
    $expired_time = $current_time + $expired;
    $srcStr = "a=%s&b=%d&c=%d&d=%d";
    $srcStr = sprintf($srcStr, $apiKey, $expired_time, $current_time, $rdm);
    $sign = base64_encode(hash_hmac('SHA1', $srcStr, $apiSecret, true).$srcStr);
    return $sign;
}