API Authentication

Page Directory

1. API call example

2. Authentication parameter algorithm

3. Parameter Code

4. Authorization generation example - Python

5. Authorization generation example -Java

To improve API access security, the authorization parameterAuthorizationof OneNET API is taken as a Header parameter.

The core key calculated by Authorization is accessKey. The user needs to calculate the signature using the core key adopting signature algorithm, and form the authentication parameter together with other parameters, and then perform authentication using the authentication parameter Authorization as the request header parameter.

The authentication security is improved by avoiding the direct transmission of the core key on the network, increasing the time control of authentication parameters and strengthening key authority granularity control (upcoming), so as to maximum access security.

1. API call example

GET /devices/35****92 //35****92 device ID randomly assigned by the onenet
Authorization: version=2018-10-31&res=products%2F123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw%3D

2. Authentication parameter algorithm

res usage scenario description

2.2 Sign-signature algorithm

sign = base64(hmac_(base64decode(accessKey), utf-8(StringForSignature)))

• accessKey is the unique access key assigned by OneNET for independent resources (e.g. products). It participates in signature calculation as one of the signature algorithm parameters. Please keep it properly to ensure access security.
• Base64decode operation shall be performed before accessKey participates in the calculation.
• The composition order of the string StringForSignature used for calculating signature is in accordance with the parameter name with “/n” as the parameter separator. It is sorted in following sequence in current version: et, Method, res and version

（2） StringForSignature is constituted as follows:

StringForSignature = et + '\n' + method + '\n' + res+ '\n' + version

Note:The format of each parameter is key=value, but only the value in the parameter is used in the composition of the string of StringForSignature for calculating the signature.

2.3 Authorization calculation example

et = 1537255523
method = sha1
res = products/123123
version = 2018-10-31

（2）The string of StringForSignature used for calculating the signature is (following the sequence of et, method, res and version).

StringForSignature = "1537255523" + "\n" + "sha1"+ "\n" + "products/123123"+ "\n" + "2018-10-31"

（3）After sign is calculated, each parameter is expressed in the form of key=value with “&” as the separator. An example is given below:

version=2018-10-31&res=products/123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw=

3. Parameter Coding

After encoding, the Authorization actually transmitted in above example is:

version=2018-10-31&res=products%2F123123&et=1537255523&method=sha1&sign=ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw%3D

4. Authorization generation example-Python

！！！The token in the code here is the Authorization.

import base64
import hmac
import time
from urllib.parse import quote

def token(id,access_key):

    version = '2018-10-31'

    res = 'products/%s' % id  # access to product API by product ID

    # user-defined token expiration time
    et = str(int(time.time()) + 3600)

    # signature method，supports md5、sha1、sha256
    method = 'sha1'

    # decode access_key
    key = base64.b64decode(access_key)

    # calculate sign
    org = et + '\n' + method + '\n' + res + '\n' + version
    sign_b = hmac.new(key=key, msg=org.encode(), digestmod=method)
    sign = base64.b64encode(sign_b.digest()).decode()

    # the value part is URL encoded, and the method/res/version value is relatively simple, with no coding required
    sign = quote(sign, safe='')
    res = quote(res, safe='')

    # token parameters are concatenated
    token = 'version=%s&res=%s&et=%s&method=%s&sign=%s' % (version, res, et, method, sign)

    return token


if __name__ == '__main__':
    id = '123123'
    access_key = 'KuF3NT/jUBJ62LNBB/A8XZA9CqS3Cu79B/ABmfA1UCw='

    print(token(id,access_key))

5. Authorization generation example - Java

！！！The token in the code here is the Authorization.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;


public class Token {

    public static String assembleToken(String version, String resourceName, String expirationTime, String signatureMethod, String accessKey)
            throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {
        StringBuilder sb = new StringBuilder();
        String res = URLEncoder.encode(resourceName, "UTF-8");
        String sig = URLEncoder.encode(generatorSignature(version, resourceName, expirationTime
                , accessKey, signatureMethod), "UTF-8");
        sb.append("version=")
                .append(version)
                .append("&res=")
                .append(res)
                .append("&et=")
                .append(expirationTime)
                .append("&method=")
                .append(signatureMethod)
                .append("&sign=")
                .append(sig);
        return sb.toString();
    }

    public static String generatorSignature(String version, String resourceName, String expirationTime, String accessKey, String signatureMethod) 
            throws NoSuchAlgorithmException, InvalidKeyException {
        String encryptText = expirationTime + "\n" + signatureMethod + "\n" + resourceName + "\n" + version;
        String signature;
        byte[] bytes = HmacEncrypt(encryptText, accessKey, signatureMethod);
        signature = Base64.getEncoder().encodeToString(bytes);
        return signature;
    }

    public static byte[] HmacEncrypt(String data, String key, String signatureMethod)
            throws NoSuchAlgorithmException, InvalidKeyException {
        //construct a secret key from the given byte array,and the second parameter specifies a key algorithm
        SecretKeySpec signinKey = null;
        signinKey = new SecretKeySpec(Base64.getDecoder().decode(key),
                "Hmac" + signatureMethod.toUpperCase());

        //generate a Mac object for th specified Mac algorithm
        Mac mac = null;
        mac = Mac.getInstance("Hmac" + signatureMethod.toUpperCase());

        //initialize the Mac object with the given key
        mac.init(signinKey);

        //Mac operation is finished
        return mac.doFinal(data.getBytes());
    }

    public enum SignatureMethod {
        SHA1, MD5, SHA256;
    }

    public static void main(String[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {
        String version = "2018-10-31";
        String resourceName = "products/123123";
        String expirationTime = System.currentTimeMillis() / 1000 + 100 * 24 * 60 * 60 + "";
        String signatureMethod = SignatureMethod.SHA1.name().toLowerCase();
        String accessKey = "KuF3NT/jUBJ62LNBB/A8XZA9CqS3Cu79B/ABmfA1UCw=";
        String token = assembleToken(version, resourceName, expirationTime, signatureMethod, accessKey);
        System.out.println("Authorization:" + token);
    }
}