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:
- Command string is coded in UTF-8.
- By separating command string with “&” in CaaS / CVPC API, multiple key value/parameter pairs.
- 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.
- Convert all the command strings into lowercase, as the following shows:
- 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。
- Put signature string behind basic url and command string, and then this is a CaaS / CVPC API with verification function.
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
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
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
表1.
原特殊字元 |
取代字元 |
|---|---|
| "+" | "*" |
| "/" | "-" |
| "=" | ""(Empty Character) |
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:
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.