协同签名API接口文档

申请随机数

申请随机数。

请求方式：POST
url: http://cip.api.ht.demo.smartcert.cn/api/cor/client/get/random
contentType:application/json;charset:utf-8

一、请求参数

名称	类型	是否必须	描述
clientMsg	String	是	客户端请求认证随机数请求消息体
sign	String	否	客户端请求认证随机数请求消息体（appSecret签名结果）

注意：sign参数在协签平台开启appSecret鉴权后必输，否则接口会报错。

二、响应参数

结果信息	类型	描述
data	String	服务端随机数响应体
code	int	状态码 0 成功，其他为失败
message	String	成功为 success，其他为失败原因

三、请求响应示例

请求示例

{
	"clientMsg": "210877384d754743394300",
	"sign":"ed0356e6edfb96722d97fa10b83fc49903249a0c14bcaf3024dc558b3a28fbd3"
}

响应成功示例


	"code": 0,
	"message": "success",
	"data": "210820c5e885d79ced74"
}

协同操作

客户端与服务端协同操作。

请求方式：POST
url: http://cip.api.ht.demo.smartcert.cn/api/cor/client/cosign
contentType:application/json;charset:utf-8

一、请求参数

名称	类型	是否必须	描述
clientMsg	String	是	客户端请求消息体
random	String	是	随机数

二、响应参数

结果信息	类型	描述
data	String	协同服务响应体
code	int	状态码 0 成功，其他为失败
message	String	成功为 success，其他为失败原因

三、请求响应示例

请求示例

{
	"clientMsg": "2220756452683453726970504c4173437546000000000000000000000000000000002055f09a51611ab0ed8d95a0563cdd7d09ce779b8cde0882518b178876c8dc8fbc202b6b4d30131e54e5d4c0489d464c5c7cc883fdc080b7d454b06cfc8e8dd76abe77410446592b295a23ba7eddc90c7aaab34c3ce43c61e7747c21c18da1b98148a57f779e3b68a10bf97f08cd4e6f0b8f8fe1b3013cad8125e043727c9ec83476b6578620f78fb2e635fc7158947ad56ad84cf51bd09cfe47451b5c0ef32e1efba1a9dbe4105a346a4472657173515a643249347469",
	"random": "e1a65132657d59f6"
}

响应成功示例

{
	"code": 0,
	"message": "success",
	"data": "78208abeeeec4c4a02c1281e6bae60d645a30545e16aa3cbacfa83faa0b3281adea7209b31e5f61dae92d1dbfe3defed0624864dbec515a37f9ab406139da244160da220d5bc685f14b43a1e49dddc382ec3af151b503780d582e042be97cfb13ea0c790"
}

参数说明

消息类型	标识值	消息内容格式	说明
C请求认证随机数	0x21	T\|L\|V (appid)	T：消息类型标识占一字节L：数据长度，占一字节V：数据内容，长度由前面的L字段之指定appid:应用标识，为服务端分配给应用的字符串标识auth code:从随机数，appid，应用验证密钥计算出来的32字节数据，appid和appsecret只取字符串部分，不包括结尾的零字符.pinmac:口令校验码，生成规则如下 SM3(pincode \|\| random)pincode口令特征值，服务端验证用户口令时候用到，生成规则如下：SM3（appid \|\| pin \|\| keyid）keyid:服务标识密钥对的字符串数据，如“123456”，random:随机数，p1 p2:密钥生成过程数据每个都为65字节，q1,e,s2,s3,r前面过程数据，q165字节，其他为32字节，C1，T1：协同解密过程数据，每个都为65字节
S返回认证随机数	0x21	T\|L\|V (random)
C认证消息	0x22	T\|L\|V\|L\|V\|L\|V (appid \| auth code \| pinmac)
C请求生成密钥对	0x66	T\|L\|V (p1)
S返回生成密钥值	0x67	T\|L\|V\|L\|V（p2 \| keyid）
C请求协同签名	0x77	T\|L\|V\|L\|V\|L\|V (q1 \| e \| keyid)
S返回协同签名值	0x78	T\|L\|V\|L\|V\|L\|V (s2 \| s3 \| r)
C请求协同解密	0x80	T\|L\|V\|L\|V (C1 \| keyid)
S返回协同解密值	0x81	T\|L\|V (T1)
C请求密钥备份	0x55	T\|L\|V\|L\|V\|L\|V (d1 \| keyid \| pincode)
S返回密钥备份结果	0x57	T\|L\|V (“ok”)
C请求密钥恢复	0x56	T\|L\|V (keyid)
S返回密钥恢复结果	0x58	T\|L\|V\|L\|V (d1 \| p2)
C请求加密密钥备份	0x59	T\|L\|V\|L\|V\|L\|V\|L\|V (dc \| ds \| pub \| keyid)	dc: 加密密钥对客户端部分ds:加密密钥对协同段部分pub:加密密钥对公钥
S返回加密密钥备份结果	0x59	T\|L\|V (“ok”)	成功返回“ok”，失败返回“error”,包含末尾0字符
C请求加密密钥恢复	0x5a	T\|L\|V (keyid)
S返回加密密钥恢复结果	0x5a	T\|L\|V\|L\|V (dc \| pub)
C请求加密密钥协同解密	0x5b	T\|L\|V\|L\|V (C1 \| keyid)	C1:解密过程参数，65字节
S返回加密密钥协同解密结果	0x5b	T\|L\|V （TT1）	TT1:返回的解密过程参数，65字节
C请求加密密钥对协同密钥协商	0x5c	T\|L\|V\|L\|V （param \| keyid）	param:密钥协商过程参数，65字节
S返回加密密钥对协同密钥协商结果	0x5c	T\|L\|V (dp)	dp:密钥协商过程参数，65字节
C请求签名加密密钥对客户端部分更新	0x5d	T\|L\|V\|L\|V\|L\|V (dc \| d1 \| keyid \|\| pincode)	dc: 加密密钥对客户端部分ds:签名密钥对客户端部分
S返回签名加密密钥对客户端部分更新结果	0x5d	T\|L\|V	成功返回“ok”，失败返回“error”,包含末尾0字符
C获取口令重试次数	0x82	T\|L\|V(keyid)	keyid:密钥id
S返回口令重试次数	0X82	T\|V\|V	消息类型0X82后接一字节的重试次数和一字节最大重试次数,二进制示例：820506，表示重试剩余5次机会。初始化时是6次机会
S返回错误信息	0x88	T\|V	消息类型0X88后面接一字节的错误类型（口令错误消息后面再接一字节的重试次数和一字节最大重试次数）

注意：C请求生成密钥对协议优化：标识值：0x66,消息内容格式：T|L|V L|V L|V (p1|pincode2|d1),生成密钥同时完成口令指纹绑定。

客户端向服务端请求操作，共分为三个步骤：

请求认证随机数
发送认证和业务数据
接收服务端返回的结果

下面是生成协同密钥对的例子数据
例子设定各参数值：

appid值为字符串：appid
应用验证秘密appsecret为字符串：appsecret87654321
服务端生成的验证挑战随机数为：35 DF 86 29 34 9D 8A F8
keyid为：1

消息交互流如下：（数据为十六进制表示的字节流数据）

C请求认证随机数：21 06 61 70 70 69 64 00 （T=21 L=06 V=61 70 70 69 64 00）
S返回认证随机数：21 08 35 DF 86 29 34 9D 8A F8 （T=21 L=08 V=35 DF …）
C请求生成密钥对：（认证消息（tag | appid | auth code | pinmac）请求生成密钥对 (tag | p1)）
22 06 61 70 70 69 64 00 20 97 4A 1C 72 7B 37 5B 1E FB DE A4 62 AC 39 71 E5 4A 81 36 59 B9 5C AF A2 4A C3 CD FB 99 94 C8 98 20 88 4A 1C 72 7B 37 5B 1E FB DE A4 62 AC 39 71 E5 4A 81 36 59 B9 5C AF A2 4A C3 CD FB 99 94 C8 98 66 41 04 60 78 30 DD 6D 39 18 FB 6A 95 B1 4F 18 1B 05 56 AA 75 A1 47 CE A3 DD A0 66 A5 27 66 C2 32 29 39 92 EC E6 20 53 E2 87 57 33 4D 37 69 66 E7 38 58 54 70 D6 56 29 EF 62 6E 40 99 87 B0 70 5B 98 62

服务端根据认证消息中的appid字段检索出对应的认证密钥字符串，和第一步生成的随机数拼接做sm3计算出32字节杂凑值和认证消息中的auth code比较，一致则应用授权认证通过。

对于
（1）请求认证随机数 、（2）请求生成密钥对 、（3）请求密钥备份的请求不验证用户口令，其他所有消息，
服务端根据随后消息中的keyid字段检索出该容器对应的pincode和用户口令剩余尝试次数，
如果剩余尝试次数大于零，则计算出验证码和pinmac比较，一致则用户口令认证通过。否则返回对应错误。
#define PININCORRECT   37  // "PIN码错误";
#define PINLOCKED   38     // "PIN码已经锁定";
用户口令特征值pincode的首次设备在（1）请求密钥备份 或 （2）请求签名加密密钥对客户端部分更新时由客户端上传到服务端

S返回生成密钥值：（TLVLV tag|p2|keyid）

67 41 04 46 98 60 16 43 1A 22 54 EC C9 29 6A 01 3E 96 3D 52 CF 4A 5F DC 62 52 81 91 52 6A 63 3D FC F6 69 F3 13 A0 F4 5A 36 80 A1 A1 5F 06 4F BA E7 60 D1 E0 2C 85 6C CF 4B 3F 6E 62 A5 2A D5 22 44 14 05 02 31 00

密钥生成流程

C方生成部分私钥D1，S方生成部分私钥D2

S方计算P2=G/D2

C方计算P=P2/D1-G

P即为共同的公钥

签名流程

C方计算 Q1=k1*G （k1为A生成的1到n之间的随机数）
S方计算 Q2=k2*G （k2、k3为B生成的1到你之间的随机数，e为待签名消息的杂凑值）

(x1, y1)=k2*Q1 + Q2

r=(x1+e) mod n

s2=D2*k3 mod n

s3=D2*(r+k2) mod n

C方计算 sa=(D1k1s2 + D1*s3) mod n

结果整合 S=(sa –r) mod n