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.