开发者指南
平台概述
天津滨海CA是一家优秀的电子认证服务商，依托自身优势和资源整合能力，推出了滨海CA云平台，该平台整合了证书服务、时间戳服务、统一身份认证服务、硬件服务等，为不同行业客户提供了高效的互联互通和快速接入的渠道，实现了电子认证服务及信息安全整体解决方案。
平台特色
• 一站式解决方案
产品介绍
• 时间戳服务: 时间戳是使用数字签名技术产生的数据，签名的对象包括了原始文件信息、签名参数、签名时间等信息。时间戳系统用来产生和管理时间戳，对签名对象进行数字签名产生时间戳，以证明原始文件在签名时间之前已经存在。可信时间戳用于证明电子数据文件自申请可信时间戳后内容保持完整、未被更改，并将起到电子档案和档案数字化副本内容防篡改的作用。
API调用规则及签名算法
云平台调用API遵循以下规则：
签名算法
为了防止 API 调用过程中被恶意篡改，对所有 API 请求参数（包括公共参数和业务参数，但除去sign参数）必须加入签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。拼接好的字符串和密钥分别按照UTF-8编码，用编码后的密钥字符流结合HmacSHA256算法对编码后的参数字符流进行摘要。将摘要后的字符流转换为十六进制大写字符串，即得到签名值。
报文的签名机制
对于报文的签名处理机制如下：
{
"version": "1.0",
"charset": "UTF-8",
"sign": "5060C36C28F6AF6C546C0203598F349A4BC72C40262846A84B0CEEB298A98E76",
"signtype": "SHA-256",
"format": "JSON",
"isEncrypted": "0",
"transactionId": "58e2284bb71947f5b625c64c85951e34",
"appId": "abc",
"jsonRequestData": "{
"dateTime": "20200825143140",
"cert": "MIIDATCCAqWg......le8TrOtVd7XVDgRk91yvSAkn8g="
}
}
待签名字符串为：
cert=MIIDATCCAqWg......le8TrOtVd7XVDgRk91yvSAkn8g=&dateTime=20200825143140&abc&appKey&58e2284bb71947f5b625c64c85951e34
注意：appId 由滨海CA云平台提供，appKey由用户在滨海CA平台上设定。
待签名字符串为：
cert=MIIDATCCAqWg......le8TrOtVd7XVDgRk91yvSAkn8g=&dateTime=20200825143140&abc&appKey&58e2284bb71947f5b625c64c85951e34
注意：appId 由滨海CA云平台提供，appKey由用户在滨海CA云平台上设定。
JAVA 签名示例代码
//排序并获取待签名串
public static StringBuilder mapSortedByKey(Map param) throws ApiException {
try {
StringBuilder stringBuilder = new StringBuilder();
ArrayList keyList = new ArrayList(param.keySet());
Collections.sort(keyList);
for (int i = 0; i < keyList.size(); i++) {
String key = keyList.get(i);
Object value = param.getOrDefault(key, "") ;
value = value == null ? "":value;
if (i == keyList.size() - 1) {
stringBuilder.append(key).append("=").append(URLDecoder.decode(value.toString(), "UTF-8"));
} else {
stringBuilder.append(key).append("=").append(URLDecoder.decode(value.toString(), "UTF-8")).append("&");
}
}
return stringBuilder;
}catch (Exception e){
throw new ApiException("获取待签名数据失败", e);
}
}
//生成签名数据
private static String sign(StringBuilder strToSign,String appId,String appKey,String transactionId) throws ApiException {
String result = "";
try {
//假设已排序字符串为strToSign
//添加商户密钥
strToSign.append("&").append(appId).append("&").append(appKey).append("&").append(transactionId);
//System.out.println("待验签字符串："+strToSign.toString());
//System.out.println(strToSign.toString());
// 创建加密对象
MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
// 传入要加密的字符串,按指定的字符集将字符串转换为字节流
messageDigest.update(strToSign.toString().getBytes("UTF-8"));
byte byteBuffer[] = messageDigest.digest();
// 將 byte数组转换为16进制string
result = StringToHexUtil.bytesToHexString(byteBuffer);
} catch (Exception e) {
throw new ApiException("生成签名数据失败", e);
}
return result;
}
/**
* 获取公钥
*
* @return
*/
private static PublicKey getPublicKey() throws Exception {
String publicKey = BhcaConstant.RSAPUBLICKEY;
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
byte[] decodedKey = Base64Util.decode(publicKey.getBytes());
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(decodedKey);
return keyFactory.generatePublic(keySpec);
}
/**
* 验签
*
* @param srcData 原始字符串
* @param sign 签名
* @return 是否验签通过
*/
public static boolean verify(String srcData, String sign) throws ApiException {
try {
byte[] keyBytes = getPublicKey().getEncoded();
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PublicKey key = keyFactory.generatePublic(keySpec);
Signature signature = Signature.getInstance("MD5withRSA");
signature.initVerify(key);
signature.update(srcData.getBytes());
return signature.verify(Base64Util.decode(sign.getBytes()));
}catch (Exception e){
throw new ApiException("验签失败",e);
}
}
公共参数
公共请求参数是指每个接口都需要使用到的请求参数，如下：
序号
参数名称
类型
是否必填
参数说明
1
version
String
是
版本号目前为（1.0）
2
charset
String
是
编码类型，固定为UTF-8
3
sign
String
否
签名（参考签名）
4
signtype
String
是
签名方式，固定为SHA-256
5
format
String
是
传输格式，固定为JSON
6
isEncrypted
String
是
是否加密，0 未加密 1 已加密。
7
transactionId
String
是
交易编号（业务自定义唯一编码）
8
appId
String
是
应用ID（由TJBHCA提供）
Body中参数如下：
序号
参数名称
类型
是否必填
参数说明
1
jsonRequestData
String
是
请求JSON串，对应业务接口请求参数（详见各个业务请求参数）
jsonRequestData 请求示例如下：（请求数据已经格式化）
{
"dateTime":"20200518154102",
"method":"certQuery",
"name":"测试"
}
API请求示例：
BhcaApiClient bhcaApiClient = new BhcaApiClient("http://xxx/tsa/getTsa", "abc", "10001");
Map< String, String> map = new HashMap< String, String>();
try {
map.put("tsatxt", "hello");
String transactionId = "58e2284bb71947f5b625c64c85951e34";
String result = bhcaApiClient.execute(transactionId, map);
System.out.println("返回结果：" + result);
if (result != null) {
//将结果转化成JSON对象
JSONObject obj = JSONObject.parseObject(result);
//验签
if (BhcaUtil.verifyResponseSign(obj)) {
System.out.println("验签成功。");
if ("200".equals(obj.get("code").toString())) {
System.out.println("调用成功，准备处理业务逻辑。");
}else{
System.out.println("调用时间戳接口失败，失败原因：" + obj.get("code") + ":" + obj.get("message"));
}
}else{
System.out.println("验签失败。");
}
} else {
System.out.println("调用接口失败。");
}
}catch (ApiException e){
e.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
响应参数
调用 API 服务后返回数据采用统一格式，code为200 ，请求成功，其他为失败，这时没有data结果信息
名称
类型
描述
code
Integer
状态码，200请求成功，其他为失败,具体见 API错误码说明
message
String
状态码的描述
data
Object
结果信息，code为200时出现,具体看各个接口说明
sign
String
服务端签名值
成功示例
JSON示例
{
"code": 200,
"data": {
……
},
"sign": "PIBXi7DCv9iynh7……X0OOk1lVM16U=",
"transactionId": "58e2284bb71947f5b625c64c85951e34"
}
失败示例
JSON示例
{
"code": 200,
"code": 1000030000,
"sign": "af1WhBEt7jfxJ……9xFw7xZ6AugHtl3kMObmsUjk=",
"message":"交易流水号重复，58e2284bb71947f5b625c64c85951e34"
}
API错误码说明 错误码解释
返回码
系统错误
备注
200
系统调用成功
504
网关超时
404
未找到
500
服务内部异常
1000010000
请求签名错误
1000020000
请求参数错误
1000030000
交易流水号重复
1000040000
请求头错误
1000050000
请求地址禁止访问
1000060000
请求方式错误
津公网安备 12011602001007号