Authentication of API Calling


Last Update: 2020/09/25


When CaaS / CVPC API is called through HTTP or HTTPS GET, authentication related parameters should be added to HTTP Query String. When CaaS / CVPC API receives the call, the call would be verified if it contains a legitimate signature. The client should acquire a set of CaaS / CVPC API Key, including Access Key and Secret Key on the entry website of CloudBOSS so as to have captcha through computing.

Below is an example of CaaS / CVPC API calling:

  
https://hws.hicloud.hinet.net/cloud_hws/api/hws/?action=runInstances&version=2013-03-29
&chtAuthType=hwspass&imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false
&instanceName=haha&count=1&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0
&expires=2013-03-29T17:50:04Z&signature=VBUfKTt48Wf6xbdny98N4Gi07f4
    

The example is analyzed as follows.

  • basic url:

https://hws.hicloud.hinet.net/cloud_hws/api/hws/?

  • command string:

action=runInstances&version=2013-03-29&chtAuthType=hwspass&imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false&instanceName=haha&count=1&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&expires=2013-03-29T17:50:04Z

  • signature:

signature=VBUfKTt48Wf6xbdny98N4Gi07f4

A valid CaaS / CVPC API consists of basic url, command strong, and signature.

The signature is produced as follows:

  1. Command string is coded in UTF-8.
  2. By separating command string with “&” in CaaS / CVPC API, multiple key value/parameter pairs.
  3. action=runInstances
    version=2013-03-29
    imageId=hi-olajtpss
    instanceType=HC1.S.LINUX
    monitoringEnabled=false
    instanceName=haha
    count=1
    accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0
    expires=2013-03-29T17:50:04Z

  4. Parameters are arranged according to key values. Command string would be reorganized. (Here a natural ordering is adopted. That is, it is organized according to characters.
  5. accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&action=runInstances

    &chtAuthType=hwspass&count=1&expires=2013-03-29T17:50:04Z&imageId=hi-olajtpss&instanceName=haha&instanceType=HC1.S.LINUX&monitoringEnabled=false&version

    =2013-03-29

  6. Convert all the command strings into lowercase, as the following shows:
  7. accesskey=u0u0mu5uqxhnref3tvrfek5qstvprfkxturneu1uwt0&action=runinstances

    &chtauthtype=hwspass&count=1&expires=2013-03-29T17:50:04Z&imageid=hi-olajtpss&instancename=haha&instancetype=hc1.s.linux&monitoringenabled=false&version=2013-03-29

  8. Encrypt the command string through encryption algorism HMAC SHA-1 with Secret Key and code the encrypted result through Base64. The coded result may contain special characters in URL ("+", "/", "="). After the three special characters are replaced, a signature is produced. The principle of replacement is described in Table 1 while the format of signature is as follows: signature=VBUfKTt48Wf6xbdny98N4Gi07f4。
  9.                     表1.

    原特殊字元
    取代字元
    "+" "*"
    "/" "-"
    "=" ""(Empty Character)

     

  10. Put signature string behind basic url and command string, and then this is a CaaS / CVPC API with verification function.
  11.     https://hws.hicloud.hinet.net/cloud_hws/api/hws/?action=runInstances
        &version=2013-03-29&chtAuthType=hwspass
        &imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false&instanceName=haha
        &count=1&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&expires=2013-03-29T17:50:04Z
        &signature=VBUfKTt48Wf6xbdny98N4Gi07f4
       

 

Acquiring Signature through hws-signature Java

  • The following are examples of signatures produced through JAVA:

package chttl.cloud.hws;

import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class HWSSignature {

	/**
	* Generate signature from your secret key and URL format string.
	* And use the Overload mechanism to call "generateSignature(String userSecretKey, 
	String commandString)" method  for the return value
	* @param String userSecretKey 
	* @param String unsignedUrl
	* @return String URL
	*/
	public static String getSignedUrl(String userSecretKey, String unsignedUrl){
		String commandString  =unsignedUrl.substring(unsignedUrl.indexOf('?') + 1);
		return unsignedUrl + "&signature=" + generateSignature(userSecretKey, commandString);
	}

	/**
	* Generate signature string from your secret key string and the command string.
	* And use the Overload mechanism to call "generateSignature(String userSecretKey, 
	Map<String, List<String>> arguments)" method for the return value.
	* @param String userSecretKey 
	* @param String commandString
	* @return String signature
	*/
	public static  String generateSignature(String userSecretKey, String commandString) {
		Map<String, List<String>> arguments = new HashMap<String, List<String>>();
		String decodedUrl = "";
		try {
			decodedUrl = URLDecoder.decode(commandString, "utf8");
		} catch (UnsupportedEncodingException e) {
			e.printStackTrace();
		}
		
		String [] commands = decodedUrl.split("&");
		for(String command : commands) {
			String [] keyValues = command.split("=");
			if(arguments.containsKey(keyValues[0])){
				List<String> valueList=arguments.get(keyValues[0]);
				valueList.add(keyValues[1]);
			}else{
				List<String> valueList = new ArrayList<String>();
				valueList.add(keyValues[1]);
				arguments.put(keyValues[0], valueList);
			}
		}
		return generateSignature(userSecretKey, arguments);
	}
	
	/**
	* Generate signature string from your secret key string and Map object which is composed of 
      command pairs.
	* But the "arguments" hash map should not contain "signature" key entry.
	* @param String userSecretKey 
	* @param Map<String, List<String>> arguments
	* @return String mySignature
	*/
	public static String generateSignature(String userSecretKey, Map<String, List<String>> arguments){
	 
		List<String> argumentNameList = new ArrayList<String>();
		String mySignature = null;
		
		for(String name : arguments.keySet()) {
			argumentNameList.add(name);
		}
		Collections.sort(argumentNameList);
			
		String requestMsg = null;		
		for(String argumentName : argumentNameList){					
			List<String> valueList = arguments.get(argumentName);
			for(int listCount=0 ; listCount<valueList.size() ; listCount++){
				if(requestMsg == null){
					requestMsg = argumentName + "=" + valueList.get(listCount);
				}else {
					requestMsg += "&" + argumentName + "=" + valueList.get(listCount);
				}					
			}
		}
		requestMsg = requestMsg.toLowerCase();
		System.out.println(requestMsg);
		try {
	        Mac mac;
			mac = Mac.getInstance("HmacSHA1");
			SecretKeySpec keySpec = new SecretKeySpec(userSecretKey.getBytes(), "HmacSHA1");
			mac.init(keySpec);
			mac.update(requestMsg.getBytes());
			byte[] encryptedBytes = mac.doFinal();
      		mySignature = getBase64String(encryptedBytes);
		} catch (NoSuchAlgorithmException e) {
			e.printStackTrace();
		} catch (InvalidKeyException e) {
			e.printStackTrace();
		}
		
		return mySignature;
	}


	/**
	* Generate Base64 encoded string from the byte buffer.
    * Handle and prevent URL from containing the special characters
	* @param byte[] encryptedBytes
	* @return String encodeString
	*/
	private static String getBase64String(byte[] encryptedBytes) {
		String encodeString = null;
		encodeString = new String(Base64.encodeBase64(encryptedBytes));
		encodeString = encodeString.replace("+", "*");
		encodeString = encodeString.replace("/", "-");
		encodeString = encodeString.replace("=", "");
		return encodeString;
	}
}
  • Description:
By using the abovementioned codes, a valid CaaS / CVPC API URL can be acquireed in a static method, such as:

HWSSignature.getSignedUrl(" your secretKey "," https://CaaS / CVPC API basic url/?command string "));

 

Example:

HWSSignature.getSignedUrl("WWpJNU16a3pOV1JsWWpNeU5HVXdOMkkxTURNd1lUbG1OMlEwTXp

SaFptST0","https://hws.hicloud.hinet.net/cloud_hws/api/hws/?action=runInstances&version=2013-03-29&chtAuthType=hwspass&imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false&instanceName=haha&count=1

&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&expires=2013-03-29T17:50:04Z");

 

Output:

https://hws.hicloud.hinet.net/cloud_hws/api/hws/?action=runInstances&version=2013-03-29&chtAuthType=hwspass&imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false&instanceName=haha&count=1

&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&expires=2013-03-29T17:50:04Z&signature=VBUfKTt48Wf6xbdny98N4Gi07f4

 

A signature can be acquired through HWSSignature.generateSignature(" your secretKey ","command string ")

 

Example: HWSSignature.generateSignature("WWpJNU16a3pOV1JsWWpNeU5HVXdOMkkxTURNd1lUbG1OMlEwTX

pSaFptST0", "action=runInstances&version=2013-03-29&chtAuthType=hwspass&imageId=hi-olajtpss&instanceType=HC1.S.LINUX&monitoringEnabled=false&instanceName=haha&count=1

&accessKey=U0U0MU5UQXhNREF3TVRFek5qSTVPRFkxTURneU1UWT0&expires=2013-03-29T17:50:04Z")

Output:

VBUfKTt48Wf6xbdny98N4Gi07f4

 

Note. This example uses Apache common code to process Base64. The library should be imported when using it.