HummerRisk 開發手冊：Restful Api 使用

HummerRisk 是開源的雲原生安全平台，以非侵入的方式解決雲原生環境的安全和治理問題。核心能力包括混合雲的安全治理和容器雲安全檢測。

本文将介紹如何使用HummerRisk 中的Restful Api進行調用和開發，來友善各位小夥伴進行對接和擴充。

簽名方法

首先我們介紹 API 請求中簽名 ( signature ) token 的生成方法。

擷取 HummerRisk Access Key 和 Secret Key

在已運作的 HummerRisk 平台，點選左側菜單"系統設定"，二級菜單"個人資訊"，三級菜單"API Keys"頁面擷取，如圖所示：

點選右側操作按鈕，可以根據 Access Key 和 Secret Key 和目前時間戳，生成 token，以便于調用 RestFul API 使用：

點選 Access Key 和 Secret Key 可以複制，粘貼出來，用于代碼生成 token，以便于調用 RestFul API 使用：

根據 AK/SK 生成 ( signature ) token

代碼示例:

以 Java 代碼為例 (其他語言類似，需要使用 AES 加密)， 如下面示例所示：

accessKey=r2MHQGeUdmT6LXzR
secretKey=1TV98lz1ttXpqyiO
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.lang3.StringUtils;


import javax.crypto.*;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;


/**
 * 加密解密工具
 *
 * @author harris
 */
public class CodingUtil {


    private static final String UTF_8 = "UTF-8";


    /**
     * JAVA 簽名方法, API 調用 DEMO
     * @throws Exception
     */
    @org.junit.Test
    public void test () throws Exception {
        try {
            URL url = new URL("http://localhost:1024/prod-api/system/user/list/all");
            HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
            urlConnection.setRequestProperty("Accept", "application/json;charset=UTF-8");
            urlConnection.setRequestProperty("accessKey", accessKey);
            String str = accessKey + "|" + System.currentTimeMillis();//時間戳
            String signature = aesEncrypt(str, secretKey, accessKey);
            urlConnection.setRequestProperty("signature", signature);
            InputStream is = urlConnection.getInputStream();
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            byte[] buffer = new byte[1024];
            int len = 0;
            while (-1 != (len = is.read(buffer))) {
                baos.write(buffer, 0, len);
                baos.flush();
            }
            System.out.println(urlConnection.getResponseCode());
            System.out.println(baos.toString("utf-8"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }


    /**
     * AES加密
     *
     * @param src       待加密字元串
     * @param secretKey 密鑰
     * @param iv        向量
     * @return 加密後字元串
     */
    public static String aesEncrypt(String src, String secretKey, String iv) throws Exception {
        if (StringUtils.isBlank(secretKey)) {
            throw new Exception("secretKey is empty");
        }


        try {
            byte[] raw = secretKey.getBytes(UTF_8);
            SecretKeySpec secretKeySpec = new SecretKeySpec(raw, "AES");
            // "算法/模式/補碼方式" ECB
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            IvParameterSpec iv1 = new IvParameterSpec(iv.getBytes());
            cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, iv1);
            byte[] encrypted = cipher.doFinal(src.getBytes(UTF_8));
            return Base64.encodeBase64String(encrypted);
        } catch (Exception e) {
            throw new Exception("AES encrypt error:", e);
        }


    }


    /**
     * AES 解密
     *
     * @param src       待解密字元串
     * @param secretKey 密鑰
     * @param iv        向量
     * @return 解密後字元串
     */
    public static String aesDecrypt(String src, String secretKey, String iv) {
        if (StringUtils.isBlank(secretKey)) {
            throw new RuntimeException("secretKey is empty");
        }
        try {
            byte[] raw = secretKey.getBytes(UTF_8);
            SecretKeySpec secretKeySpec = new SecretKeySpec(raw, "AES");
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            IvParameterSpec iv1 = new IvParameterSpec(iv.getBytes());
            cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, iv1);
            byte[] encrypted1 = Base64.decodeBase64(src);
            byte[] original = cipher.doFinal(encrypted1);
            return new String(original, UTF_8);
        } catch (BadPaddingException | IllegalBlockSizeException e) {
            // 解密的原字元串為非加密字元串，則直接傳回原字元串
            return src;
        } catch (Exception e) {
            throw new RuntimeException("decrypt error，please check parameters", e);
        }
    }


    public static String secretKey() {
        try {
            KeyGenerator keyGen = KeyGenerator.getInstance("AES");
            keyGen.init(128);
            SecretKey secretKey = keyGen.generateKey();
            return Base64.encodeBase64String(secretKey.getEncoded());
        } catch (Exception e) {
            throw new RuntimeException("generate secretKey error", e);
        }


    }
}           

API 調用

HummerRisk API 文檔調用

HummerRisk 右上角，點選 API 文檔按鈕，跳轉 API 文檔頁面。左上角 API 按微服務子產品展示，需要調用哪個子產品的方法在此切換，如圖所示：

在此頁面，點選文檔管理-全局參數設定，添加參數，參數名稱 Authorization，将已生成的簽名 ( signature ) token 粘貼到此項參數值中；

以查詢所有使用者為例，找到左側菜單，點選調試，如果有其他參數請填寫其他參數，點選發送進行 API 請求，即可得到傳回值：

Postman 調用

填寫請求 url 等資訊，找到 Authorization 菜單，TYPE 選擇 Bearer Token，右側 Token 粘貼已生成的簽名 ( signature ) token，點選發送進行 API 請求，即可得到傳回值：

其他注意事項

• 請求中簽名 ( signature ) 即是 HummerRisk 中請求的 token，概念相同；
• token 根據目前時間戳生成，時效為 30 分鐘；
• 生成環境(即主控端根據安裝包部署的 HummerRisk 平台，URL 路徑為 prod-api)，而本地代碼啟動 (URL 路徑為 dev-api，以查詢所有使用者為例：http://localhost:1024/dev-api/system/user/list/all)。

關于 HummerRisk

HummerRisk 是開源的雲原生安全平台，以非侵入的方式解決雲原生的安全和治理問題。核心能力包括混合雲的安全治理和K8S容器雲安全檢測。

GitHub 位址：https://github.com/HummerRisk/HummerRisk

Gitee 位址：https://gitee.com/hummercloud/HummerRisk