Virbox SDK  2.1
函数
Virbox D2C 接口说明

函数

SS_UINT32 SSAPI master_open (OUT MASTER_HANDLE *device_handle)
 打开签发设备（开发锁） 更多...
 
SS_UINT32 SSAPI master_close (IN MASTER_HANDLE device_handle)
 关闭签发设备（开发锁） 更多...
 
SS_UINT32 SSAPI master_get_developer_id (IN MASTER_HANDLE device_handle, OUT SS_BYTE *developer_id)
 获取开发锁开发商ID 更多...
 
SS_UINT32 SSAPI master_get_root_count (IN MASTER_HANDLE device_handle, OUT SS_UINT32 *count)
 获取开发商锁内所有的根证书数量 更多...
 
SS_UINT32 SSAPI master_get_ca_cert (IN MASTER_HANDLE device_handle, IN SS_BYTE ca_type, OUT SS_BYTE *ca_cert, IN SS_UINT32 cert_bufsize, OUT SS_UINT32 *cert_size)
 通过证书类型，获取开发锁 CA 证书 更多...
 
SS_UINT32 SSAPI master_get_ca_cert_ex (IN MASTER_HANDLE device_handle, IN SS_BYTE ca_type, IN SS_UINT32 root_index, OUT SS_BYTE *ca_cert, IN SS_UINT32 cert_bufsize, OUT SS_UINT32 *cert_size)
 通过证书类型，获取开发锁 CA 证书 更多...
 
SS_UINT32 SSAPI master_get_root_ca (IN MASTER_HANDLE device_handle, OUT SS_BYTE *root_ca, IN SS_UINT32 root_bufsize, OUT SS_UINT32 *root_size)
 获取开发锁 Virbox Root CA 证书 更多...
 
SS_UINT32 SSAPI master_get_device_ca (IN MASTER_HANDLE device_handle, OUT SS_BYTE *device_ca, IN SS_UINT32 device_bufsize, OUT SS_UINT32 *device_size)
 获取开发锁设备 CA 证书 更多...
 
SS_UINT32 SSAPI master_get_developer_ca (IN MASTER_HANDLE device_handle, OUT SS_BYTE *developer_ca, IN SS_UINT32 ca_bufsize, OUT SS_UINT32 *ca_size)
 获取开发锁开发者 CA 证书 更多...
 
SS_UINT32 SSAPI master_get_developer_cert (IN MASTER_HANDLE device_handle, OUT SS_BYTE *developer_cert, IN SS_UINT32 cert_bufsize, OUT SS_UINT32 *cert_size)
 获取开发锁开发者证书 更多...
 
SS_UINT32 SSAPI master_get_developer_cert_ex (IN MASTER_HANDLE device_handle, IN SS_UINT32 root_index, OUT SS_BYTE *developer_cert, IN SS_UINT32 cert_bufsize, OUT SS_UINT32 *cert_size)
 根据根证书索引，获取开发锁开发者证书（扩展接口） 更多...
 
SS_UINT32 SSAPI master_verify_ca (IN MASTER_HANDLE device_handle, IN SS_BOOL store, IN SS_BYTE ca_type, IN SS_BYTE *ca_cert, IN SS_UINT32 ca_len)
 验证开发锁 CA 证书 更多...
 
SS_UINT32 SSAPI master_verify_ca_ex (IN MASTER_HANDLE device_handle, IN SS_BOOL store, IN SS_BYTE ca_type, IN SS_UINT32 root_index, IN SS_BYTE *ca_cert, IN SS_UINT32 ca_len)
 验证开发锁CA证书（扩展接口） 更多...
 
SS_UINT32 SSAPI master_get_seedkey (IN MASTER_HANDLE device_handle, OUT SS_BYTE *key, IN SS_UINT32 max_key_len, OUT SS_UINT32 *key_len)
 获取签发设备的种子码密钥（种子码公钥） 更多...
 
SS_UINT32 SSAPI master_get_info (IN MASTER_HANDLE device_handle, IN SS_BYTE type, OUT char **info)
 获取开发锁设备信息 更多...
 
SS_UINT32 SSAPI master_heap_free (IN void *buf)
 释放内存 更多...
 
SS_UINT32 SSAPI master_pin_change (IN MASTER_HANDLE device_handle, IN SS_BYTE pin_index, IN SS_BYTE *old_pin, IN SS_UINT32 old_pin_len, IN SS_BYTE *new_pin, IN SS_UINT32 new_pin_len, IN SS_BYTE *hash)
 修改开发商开发锁 PIN 码 更多...
 
SS_UINT32 SSAPI master_pin_verify (IN MASTER_HANDLE device_handle, IN SS_BYTE pin_index, IN SS_BYTE *pin, IN SS_UINT32 pin_len)
 验证开发锁 PIN 码 更多...
 
SS_UINT32 SSAPI master_pin_is_verified (MASTER_HANDLE device_handle)
 确认 PIN 码是否验证通过 更多...
 
SS_UINT32 SSAPI master_pin_enable (MASTER_HANDLE device_handle)
 启用开发锁 PIN 码 更多...
 
SS_UINT32 SSAPI master_pin_disable (MASTER_HANDLE device_handle)
 禁用开发锁 PIN 码 更多...
 
SS_UINT32 SSAPI master_pin_deauth (MASTER_HANDLE device_handle)
 清除 PIN 权限 更多...
 
SS_UINT32 SSAPI d2c_lic_new (IN MASTER_HANDLE device_handle, OUT D2C_HANDLE *d2c_license, IN ACCOUNT_TYPE account_type, IN SS_BYTE *account_id, IN SS_UINT32 account_size, IN SS_BYTE *cert, IN SS_UINT32 cert_size)
 创建 D2C 句柄，用于签发许可 更多...
 
SS_UINT32 SSAPI d2c_file_new (IN MASTER_HANDLE device_handle, OUT D2C_HANDLE *d2c_file, IN SIGN_TYPE sign_type, IN SS_BYTE *param, IN SS_UINT32 param_size)
 创建D2C句柄，用于签发非许可类型升级包，例如签发文件 更多...
 
SS_UINT32 SSAPI d2c_add_developer_cert (D2C_HANDLE d2c_handle, SS_BYTE *cert, SS_UINT32 cert_len)
 增加开发者证书链（不需要再调用了，保留仅为兼容性） 更多...
 
SS_UINT32 SSAPI gen_dynamic_code (IN MASTER_HANDLE device_handle, IN SIGN_TYPE sign_type, IN SS_BYTE *param, IN SS_UINT32 param_size, IN SS_BYTE *exec_code, IN SS_UINT32 code_size, IN SS_UINT32 *bound_info, IN SS_UINT32 bound_size, OUT SS_BYTE *pkg, IN SS_UINT32 max_pkg_len, OUT SS_UINT32 *pkg_len)
 签发动态代码 更多...
 
SS_UINT32 SSAPI d2c_add_pkg (IN D2C_HANDLE d2c_file, IN SS_CHAR *param, IN SS_CHAR *opr_desc)
 根据描述，生成升级包，并添加升级包到 D2C，针对非许可项内容的升级 更多...
 
SS_UINT32 SSAPI d2c_add_lic (IN D2C_HANDLE d2c_license, IN SS_CHAR *param, IN SS_CHAR *opr_desc, OUT SS_CHAR guid[D2C_GUID_LENGTH])
 根据描述，生成升级包，并添加升级包到D2C，针对许可项内容的升级 更多...
 
SS_UINT32 SSAPI d2c_get (IN D2C_HANDLE d2c_handle, OUT SS_CHAR *d2c_buf, IN SS_UINT32 max_buf_len, OUT SS_UINT32 *out_len)
 从 D2C 句柄中获取 D2C 流，可保存为 .d2c 文件用于升级 更多...
 
const SS_CHAR * d2c_get_pkg_desc (IN D2C_HANDLE d2c_handle, IN SS_UINT32 index)
 获得开发者自定义的 D2C 操作描述 更多...
 
SS_UINT32 SSAPI d2c_delete (IN D2C_HANDLE d2c_handle)
 删除 D2C 句柄 更多...
 
SS_UINT32 SSAPI d2c_sign (IN MASTER_HANDLE master_handle, D2C_HASH_ALGO hash_algo, IN SS_UINT32 root_index, IN SS_BYTE *data_in, IN SS_UINT32 data_len, OUT SS_BYTE *sign, IN SS_UINT32 max_sign_len, OUT SS_UINT32 *sign_len)
 D2C 签名 （开发者不必关心） 更多...
 
SS_UINT32 SSAPI d2c_encrypt (IN SS_BYTE *certs, IN SS_UINT32 certs_len, IN const SS_BYTE *plain, IN SS_UINT32 plain_len, OUT SS_BYTE *cipher, IN SS_UINT32 max_cipher_len, OUT SS_UINT32 *cipher_len)
 D2C加密 （开发者不必关心） 更多...
 
SS_UINT32 SSAPI get_snippet_seed (IN MASTER_HANDLE master, IN SS_UINT32 license_id, OUT SS_BYTE snippet_seed[SNIPPET_SEED_LENGTH])
 获取碎片代码种子（开发者不必关心） 更多...
 
SS_UINT32 SSAPI gen_snippet_code (IN MASTER_HANDLE master, IN SS_UINT32 license_id, IN const SS_BYTE *evx_code, IN SS_UINT32 evx_size, OUT SS_BYTE *snippet_code, IN SS_UINT32 snippet_buf_size, OUT SS_UINT32 *snippet_size)
 生成碎片代码（开发者不必关心） 更多...
 
SS_UINT32 SSAPI gen_snippet_code_with_key (IN const SNIPPET_CODE_CONTEXT *sc_ctx, IN const SS_BYTE *evx, IN SS_UINT32 evx_size, OUT SS_BYTE *snippet_code, IN SS_UINT32 snippet_bufsize, OUT SS_UINT32 *snippet_size)
 获取生成碎片代码请求（开发者不必关心） 更多...
 
SS_UINT32 SSAPI license_encrypt (IN MASTER_HANDLE master, IN SS_UINT32 license_id, IN const SS_BYTE *plain, IN SS_UINT32 len, OUT SS_BYTE *cipher)
 使用开发锁进行许可加密（开发者不必关心） 更多...
 

详细描述

此接口为 Virobx D2C API 说明文档，包含控制锁管理，许可签发，文件签发等功能

函数说明

SS_UINT32 SSAPI d2c_add_developer_cert ( D2C_HANDLE  d2c_handle,
SS_BYTE *  cert,
SS_UINT32  cert_len 
)

增加开发者证书链（不需要再调用了，保留仅为兼容性）

参数
[in]d2c_handleD2C 句柄，由 d2c_lic_new 或 d2c_file_new 得到
[in]cert开发者证书链
[in]cert_len证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
D2C 在生成时将自动添加开发商证书链到 D2C 包中，不必再调用此接口传入证书链。
SS_UINT32 SSAPI d2c_add_lic ( IN D2C_HANDLE  d2c_license,
IN SS_CHAR *  param,
IN SS_CHAR *  opr_desc,
OUT SS_CHAR  guid[D2C_GUID_LENGTH] 
)

根据描述，生成升级包，并添加升级包到D2C，针对许可项内容的升级

参数
[in]d2c_license许可 D2C句柄，由 d2c_lic_new 函数得到
[in]param升级包 json 串
[in]opr_desc包操作描述字符串，开发者自定义
[out]guid许可 GUID
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
  • 升级规则：
    1. 种子码方式，不能签发许可
  • json 参数说明：
    参数名称 参数类型 必选字段 参数值 参数描述
    "op" string 是 "installlic" 安装许可
    "addlic" 添加许可
    "activelic" 激活许可
    "updatelic" 更新许可
    "dellic" 删除许可
    "lockalllic" 锁定所有许可（0号许可专用）
    "unlockalllic" 解锁所有许可（0号许可专用）
    "delalllic" 删除所有许可（0号许可专用）
    "version" string 否 "op number" 许可版本号（数字，范围从 1 ~ 0xFFFFFFFF） op: '+' | '-' | '=' eg. "=123"
    "license_id" number 是(视op) -- 许可ID（数字，范围从 1 ~ 0xFFFFFFFF）（lockalllic, delalllic, unlockalllic不需要）
    "force" bool 否 true/false 是否强制升级，若为 true ，则升级的策略为：
    [addlic]无则添加，有则覆盖
    [dellic]有则删除，无则成功
    "start_time" string 否 "op number" 起始时间(UTC 秒) op : '+' | '-' | '=' | 'disable' eg. "=123456", "disable"(禁用设置，常用于更新时禁用原限制条件)
    "end_time" string 否 "op number" 终止时间，不设置标明是永久许可(UTC秒) op : '+' | '-' | '=' | 'disable' eg. "+456789"
    "counter" string 否 "op number" 使用次数 op : '+' | '-' | '=' | 'disable' eg. "-123"
    "span" string 否 "op number" 时间跨度(UTC 秒) op : '+' | '-' | '=' | 'disable' eg. "=987654"
    "concurrent" string 否 "op number" 最大并发数(0~65535) op : '+' | '-' | '=' | 'disable' eg. "=654"
    "concurrent_type" string 否 "process" 以进程限制并发
    "win_user_session", 以 Windows 会话限制并发数
    "module": json_array 否 [1,2,3,4,5,...,64] 模块区，json 整数数组结构，数组里可以表示模块，范围从 1 到 64
    "timestamp": number 否 -- 许可的签发时间戳，用于防重放，如果JSON中没有此项，则使用当前时间生成一个时间戳
    "serial": number 否 -- 许可的签发流水号，用于防重放，如果JSON中没有此项，则与时间戳配合，生成一个流水号
    "rom": json 否 -- 只读数据区
    {
    "data":"HEX字符串", 数据区内容
    "offset":number, 写入数据区的偏移，默认为 0
    "resize":number 如果存在此字段，表示重置数据区大小，值即为新的大小
    }
    "raw": json 否 {"data":"HEX字符串", "offset":number,"resize":number} 读写数据区，内容参考只读取描述
    "pub": json 否 {"data":"HEX字符串", "offset":number,"resize":number} 公开数据区，内容参考只读取描述
    注： 除"lockalllic", "unlockalllic", "delalllic"外，其它操作均需要设置"license_id"字段
参见
d2c_lic_new d2c_add_developer_cert
SS_UINT32 SSAPI d2c_add_pkg ( IN D2C_HANDLE  d2c_file,
IN SS_CHAR *  param,
IN SS_CHAR *  opr_desc 
)

根据描述，生成升级包，并添加升级包到 D2C，针对非许可项内容的升级

参数
[in]d2c_file文件 D2C 句柄，由 d2c_file_new 得到
[in]param升级包json串
[in]opr_desc包描述字符串
异常
没有异常
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
  • 升级规则：
    1. 更新文件时，执行文件的 offset 必须为 0
    2. 种子码方式，不能签发许可
  • 重置锁注意事项：
    1. 加密锁升级时必须保持与签包服务器时间相同，否则会出现重置锁失败的情况。
    2. 锁时间戳小于重置锁限定开始时间，调整计算机本地时间与服务器相同后升级数据包。
    3. 锁时间戳大于重置锁限定结束时间，重新签发重置锁升级包。
      json 参数说明：
      文件操作：
      {
      "op": "addfile" | "updatefile" | "delfile" 文件操作类型，依次为：添加 | 更新 |删除
      "filename": "file_name.xxx", 文件名，长度需小于 16 字节
      "filetype": "evx" | "evd" | "key" 文件类型，依次为：可执行文件 | 数据文件 | 密钥文件。 （删除文件时不需要填写类型）
      "access": number 文件的访问权限（添加，更新，删除文件时都可以设置，默认为 0x0F （开发者所有权限， Entry 不可访问），参考 #ACCESS_READ 等宏
      "timestamp": number(0 ~ 0xFFFFFFFF) 文件的生成时间（用于抗重放），如果JSON中没有此项，则使用当前时间生成一个时间戳
      "filebuffer": "0123456789ABCDEF" 文件内容 HEX16 字符串（删除文件时不需要填写此项）
      "fileoffset": number (可选) 文件偏移，默认为 0（删除文件时不需要）
      "bind_lic": [1,2,3,4] 可执行文件绑定的许可，仅文件类型为 evx (可执行程序)时有效
      }
      重置锁：
      {
      "op": "reset" 操作类型：重置锁
      "not_before": UTC 时间（有效开始时间）
      "not_after": UTC 时间（有效终止时间），升级包在起止时间范围内（包含起止的那一秒）可重复使用。
      }
      修订时钟：
      {
      "op" : "fixtime", 操作类型：修复时钟
      "lock_time": number, 用户锁的时间
      "rand": "0102030405060708" 8 个字节 HEX16 字符串
      "diff": number, 时间差 (pc_time - lock_time)
      }
参见
d2c_lic_new d2c_add_developer_cert
SS_UINT32 SSAPI d2c_delete ( IN D2C_HANDLE  d2c_handle)

删除 D2C 句柄

参数
[in]d2c_handleD2C句柄，由 d2c_lic_new 或 d2c_file_new 得到
返回
总是返回SS_OK
参见
d2c_lic_new
SS_UINT32 SSAPI d2c_encrypt ( IN SS_BYTE *  certs,
IN SS_UINT32  certs_len,
IN const SS_BYTE *  plain,
IN SS_UINT32  plain_len,
OUT SS_BYTE *  cipher,
IN SS_UINT32  max_cipher_len,
OUT SS_UINT32 *  cipher_len 
)

D2C加密 （开发者不必关心）

参数
[in]certs证书链
[in]certs_len链书链长度
[in]plain明文
[in]plain_len明文长度
[out]cipher密文
[in]max_cipher_len缓冲区大小
[out]cipher_len密文长度
返回
成功返回 SS_OK ，失败返回相应的错误码
SS_UINT32 SSAPI d2c_file_new ( IN MASTER_HANDLE  device_handle,
OUT D2C_HANDLE *  d2c_file,
IN SIGN_TYPE  sign_type,
IN SS_BYTE *  param,
IN SS_UINT32  param_size 
)

创建D2C句柄，用于签发非许可类型升级包，例如签发文件

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]d2c_file返回 D2C 的句柄
[in]sign_type签包类型，参考 SIGN_TYPE
[in]param如果是设备证书，则传入设备证书链，种子码签发填入 Virbox Root CA
[in]param_size证书链的大小或种签子码签发填 Virbox根证书大小
返回
成功返回S S_OK，失败返回相应的错误码
备注
自2018年1月1日起，VirboxLM 对开发锁和用户锁进行安全升级，开发锁将支持多根证书，新用户锁将使用新的根证书， 原来的 d2c_file_seed_new 将废弃，变更为当前的 d2c_file_new 。 主要变更有
  • 在使用种子码签发文件时，param 参数由原来的传空，变成传入 Virbox Root CA。

Virbox Root CA 可以通过 master_get_ca_cert_ex 、 master_get_root_count 获取。 最为正确的证书获取方法是做法是：

  • 开发商从固件版本号 3.1.20 以下版本的用户锁中，获取到 Virbox Root CA 旧版本根证书 传值；
  • 开发商从固件版本号 3.1.20 以上（含 3.1.20 ）版本的用户锁中，获取 Virbox Root CA 新版本根证书 传值；
  • 开发商从深思数盾提供的 设备证书链中获取对应根证书。

由于根证书都是一样的，只是新用户锁使用新版本根证书，因此两种证书只需要取一次保存即可。

SS_UINT32 SSAPI d2c_get ( IN D2C_HANDLE  d2c_handle,
OUT SS_CHAR *  d2c_buf,
IN SS_UINT32  max_buf_len,
OUT SS_UINT32 *  out_len 
)

从 D2C 句柄中获取 D2C 流，可保存为 .d2c 文件用于升级

参数
[in]d2c_handleD2C 句柄，由 d2c_lic_new 或 d2c_file_new 得到
[out]d2c_buf得到的 D2C 数据流，该数据流为字符串格式 如果为 0，则 out_len 返回需要的长度
[in]max_buf_lend2c_buf 的缓冲区大小
[out]out_len得到的 D2C 数据流长度
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
通过此接口获取到最终的 D2C 包内容，可直接将数据写入锁内，也可保存为 .d2c 文件，异步写入锁内。
{
["pkg_type":"type", "pkg_data":"base64", "pkg_desc":"desc"]
["pkg_type":"type", "pkg_data":"base64", "pkg_desc":"desc"]
}
参见
d2c_lic_new d2c_add_developer_cert
const SS_CHAR* d2c_get_pkg_desc ( IN D2C_HANDLE  d2c_handle,
IN SS_UINT32  index 
)

获得开发者自定义的 D2C 操作描述

参数
[in]d2c_handleD2C句柄，由 d2c_lic_new 或 d2c_file_new 得到
[in]indexpkg的索引，从 1 开始
返回
字符串，返回值不需要释放，否则会出错
SS_UINT32 SSAPI d2c_lic_new ( IN MASTER_HANDLE  device_handle,
OUT D2C_HANDLE *  d2c_license,
IN ACCOUNT_TYPE  account_type,
IN SS_BYTE *  account_id,
IN SS_UINT32  account_size,
IN SS_BYTE *  cert,
IN SS_UINT32  cert_size 
)

创建 D2C 句柄，用于签发许可

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]d2c_license返回 D2C 的句柄
[in]account_type账号类型，参考 ACCOUNT_TYPE
[in]account_id账户名（字符串）或锁号（16字节锁号）
[in]account_size账户名长度
[in]cert证书，如果是 account_type = ACCOUNT_TYPE_NONE ，填入硬件锁设备证书链，账户许可填入云开发者证书链
[in]cert_size证书长度
返回
成功返回 SS_OK ，失败返回相应的错误码，SS_ERROR_PARSE_CERT 表示解析设备证书失败。
备注
创建 D2C 句柄，生成 D2C 包的初始化工作。
参见
d2c_delete d2c_add_developer_cert d2c_add_pkg d2c_get
SS_UINT32 SSAPI d2c_sign ( IN MASTER_HANDLE  master_handle,
D2C_HASH_ALGO  hash_algo,
IN SS_UINT32  root_index,
IN SS_BYTE *  data_in,
IN SS_UINT32  data_len,
OUT SS_BYTE *  sign,
IN SS_UINT32  max_sign_len,
OUT SS_UINT32 *  sign_len 
)

D2C 签名 （开发者不必关心）

参数
[in]master_handle开发锁设备句柄，通过调用 master_open 得到
[in]hash_algo哈希算法类型，参考 D2C_HASH_ALGO
[in]root_indexVirbox Root CA 根证书序号
[in]data_in要签名的数据
[in]data_len要签名数据的长度
[out]sign签名后的数据
[in]max_sign_len签名缓冲区长度，至少为 256 + 64 字节
[out]sign_len签名数据长度
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
sign 包含 256字节的开发锁签名结果，和 64 字节的开发商信息结果。前 256 字节为签名，后 64 字节为开发商信息。
SS_UINT32 SSAPI gen_dynamic_code ( IN MASTER_HANDLE  device_handle,
IN SIGN_TYPE  sign_type,
IN SS_BYTE *  param,
IN SS_UINT32  param_size,
IN SS_BYTE *  exec_code,
IN SS_UINT32  code_size,
IN SS_UINT32 *  bound_info,
IN SS_UINT32  bound_size,
OUT SS_BYTE *  pkg,
IN SS_UINT32  max_pkg_len,
OUT SS_UINT32 *  pkg_len 
)

签发动态代码

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]sign_type签包类型，参考 SIGN_TYPE
[in]param设备证书链 (种子码签发方式填对应的 Virbox Root CA)
[in]param_size证书链长度 (种子码签发方式填对应的 Virbox Root CA 长度）
[in]exec_code动态代码
[in]code_size代码大小（最大支持 2048 字节大小的动态代码）
[in]bound_info绑定信息（许可ID 数组，许可ID 为 4 个字节）
[in]bound_size绑定信息的长度（单位：字节）
[out]pkg存放升级包的用户缓冲区
[in]max_pkg_len缓冲区的长度
[out]pkg_len签得的代码长
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
自 2018年1月1日 起，VirboxLM 对开发锁和用户锁进行安全升级，开发锁将支持多根证书，新用户锁将使用新的根证书 主要变更有
  • 在使用种子码签发动态代码时，param 参数由原来的传空，变成传入 Virbox Root CA。

Virbox Root CA 可以通过 master_get_ca_cert_ex 、 master_get_root_count 获取。 最为正确的证书获取方法是做法是：

  • 开发商从固件版本号 3.1.20 以下版本的用户锁中，获取到 Virbox Root CA 旧版本根证书 传值；
  • 开发商从固件版本号 3.1.20 以上（含 3.1.20 ）版本的用户锁中，获取 Virbox Root CA 新版本根证书 传值；
  • 开发商从深思数盾提供的 设备证书链中获取对应根证书。

由于根证书都是一样的，只是新用户锁使用新版本根证书，因此两种证书只需要取一次保存即可。

SS_UINT32 SSAPI gen_snippet_code ( IN MASTER_HANDLE  master,
IN SS_UINT32  license_id,
IN const SS_BYTE *  evx_code,
IN SS_UINT32  evx_size,
OUT SS_BYTE *  snippet_code,
IN SS_UINT32  snippet_buf_size,
OUT SS_UINT32 *  snippet_size 
)

生成碎片代码（开发者不必关心）

参数
[in]master开发锁设备句柄，通过调用 master_open 得到
[in]license_id绑定的许可ID
[in]evx_code执行的原始文件
[in]evx_size执行文件的大小
[out]snippet_code存放生成的碎片代码的缓冲区
[in]snippet_buf_size缓冲区 snippet_code 的大小
[out]snippet_size生成的碎片代码的大小
返回
成功返回 SS_OK ，失败返回相应的错误码
SS_UINT32 SSAPI gen_snippet_code_with_key ( IN const SNIPPET_CODE_CONTEXT *  sc_ctx,
IN const SS_BYTE *  evx,
IN SS_UINT32  evx_size,
OUT SS_BYTE *  snippet_code,
IN SS_UINT32  snippet_bufsize,
OUT SS_UINT32 *  snippet_size 
)

获取生成碎片代码请求（开发者不必关心）

参数
[in]sc_ctx碎片代码上下文
[in]evx执行代码原文
[in]evx_size执行代码原文大小
[out]snippet_code碎片代码缓冲区
[in]snippet_bufsize碎片代码缓冲区大小
[out]snippet_size碎片代码大小
返回
成功返回 SS_OK ，失败返回相应的错误码
SS_UINT32 SSAPI get_snippet_seed ( IN MASTER_HANDLE  master,
IN SS_UINT32  license_id,
OUT SS_BYTE  snippet_seed[SNIPPET_SEED_LENGTH] 
)

获取碎片代码种子（开发者不必关心）

参数
[in]master开发锁设备句柄，通过调用 master_open 得到
[in]license_id许可ID
[out]snippet_seed碎片代码种子（32 字节）
返回
成功返回 SS_OK ，失败返回相应的错误码
SS_UINT32 SSAPI license_encrypt ( IN MASTER_HANDLE  master,
IN SS_UINT32  license_id,
IN const SS_BYTE *  plain,
IN SS_UINT32  len,
OUT SS_BYTE *  cipher 
)

使用开发锁进行许可加密（开发者不必关心）

参数
[in]master开发锁设备句柄，通过调用 master_open 得到
[in]license_id许可ID
[in]plain明文
[in]len加密长度（必须是16的倍数）
[out]cipher密文
返回
成功返回 SS_OK ，失败则返回相应的错误码
SS_UINT32 SSAPI master_close ( IN MASTER_HANDLE  device_handle)

关闭签发设备（开发锁）

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
返回
成功返回SS_OK，失败返回相应的错误码
参见
master_open
SS_UINT32 SSAPI master_get_ca_cert ( IN MASTER_HANDLE  device_handle,
IN SS_BYTE  ca_type,
OUT SS_BYTE *  ca_cert,
IN SS_UINT32  cert_bufsize,
OUT SS_UINT32 *  cert_size 
)

通过证书类型，获取开发锁 CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]ca_type证书类型，详见 PKI_CA_TYPE_DEVELOPER 等
[out]ca_cert存放锁CA证书的缓冲区
[in]cert_bufsize缓冲区大小
[out]cert_sizeCA 证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
签发许可需要带上开发商证书链，因此获取开发锁的证书、CA 将是不可或缺的接口。
{
SS_UINT32 status = SS_OK;
MASTER_HANDLE master_handle;
SS_BYTE ca[2048] = { 0 }; // 证书或者CA的大小一般不会超过1.5k，这里缓冲区使用2k足够大了
SS_UINT32 ca_size = 0;
master_open(&master_handle);
status = master_get_ca_cert(master_handle, PKI_CA_TYPE_DEVELOPER, ca, sizeof(ca), &ca_size);
if(status == SS_OK)
{
// save ca to file
}
master_close(master_handle);
}
SS_UINT32 SSAPI master_get_ca_cert_ex ( IN MASTER_HANDLE  device_handle,
IN SS_BYTE  ca_type,
IN SS_UINT32  root_index,
OUT SS_BYTE *  ca_cert,
IN SS_UINT32  cert_bufsize,
OUT SS_UINT32 *  cert_size 
)

通过证书类型，获取开发锁 CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]ca_type证书类型，详见 PKI_CA_TYPE_DEVELOPER 等
[in]root_index根证书索引序号
[out]ca_cert存放锁CA证书的缓冲区
[in]cert_bufsize缓冲区大小
[out]cert_sizeCA 证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
签发许可需要带上开发商证书链，因此获取开发锁的证书、CA 将是不可或缺的接口。
参见
master_get_ca_cert
SS_UINT32 SSAPI master_get_developer_ca ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  developer_ca,
IN SS_UINT32  ca_bufsize,
OUT SS_UINT32 *  ca_size 
)

获取开发锁开发者 CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]developer_ca存放开发者 CA 证书的缓冲区
[in]ca_bufsize缓冲区大小
[out]ca_size开发者 CA 证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
参见
master_open master_get_ca_cert
SS_UINT32 SSAPI master_get_developer_cert ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  developer_cert,
IN SS_UINT32  cert_bufsize,
OUT SS_UINT32 *  cert_size 
)

获取开发锁开发者证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]developer_cert存放开发者证书的缓冲区
[in]cert_bufsize缓冲区大小
[out]cert_size开发者证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
参见
master_open master_get_ca_cert
SS_UINT32 SSAPI master_get_developer_cert_ex ( IN MASTER_HANDLE  device_handle,
IN SS_UINT32  root_index,
OUT SS_BYTE *  developer_cert,
IN SS_UINT32  cert_bufsize,
OUT SS_UINT32 *  cert_size 
)

根据根证书索引，获取开发锁开发者证书（扩展接口）

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]root_index根证书索引序号
[out]developer_cert存放开发者证书的缓冲区
[in]cert_bufsize缓冲区大小
[out]cert_size开发者证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
参见
master_open master_get_ca_cert
SS_UINT32 SSAPI master_get_developer_id ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  developer_id 
)

获取开发锁开发商ID

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]developer_id开发商ID
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
开发商ID 是每个开发者唯一的一个标识号，每个开发者独立，通过获取开发锁的开发商ID，可判断此开发锁是否为本人所有。 最常使用的区别方式是区别 Demo 开发锁和正式开发锁。
{
MASTER_HANDLE master_handle ;
SS_BYTE developer_id[8] = {0};
SS_UINT32 status = SS_OK;
status = master_open(&master_handle);
if(status != SS_OK)
return status;
status = master_get_developer_id(master_handle, developer_id);
if(status == SS_OK)
{
// todo
// HEXTOSTRING(developer_id); // 将十六进制转换为字符串
}
master_close(master_handle);
}
SS_UINT32 SSAPI master_get_device_ca ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  device_ca,
IN SS_UINT32  device_bufsize,
OUT SS_UINT32 *  device_size 
)

获取开发锁设备 CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]device_ca存放设备 CA 证书的缓冲区
[in]device_bufsize缓冲区大小
[out]device_size设备 CA 证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
参见
master_open master_get_ca_cert
SS_UINT32 SSAPI master_get_info ( IN MASTER_HANDLE  device_handle,
IN SS_BYTE  type,
OUT char **  info 
)

获取开发锁设备信息

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]type获取信息类型，当前只能 = 1
[out]info获取到的信息，json结构
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
info 需要调用 master_heap_free 释放
- info 的 json 结构
{
"support_pin":true,
"enable_pin":true,
"developer_id":"0300000000000009",
"lock_firmware_version":"3.1.16",
"lm_firmware_version":"1.2.1.0", (PIN 码验证通过后获取信息是才有此字段)
"sn":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
SS_UINT32 SSAPI master_get_root_ca ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  root_ca,
IN SS_UINT32  root_bufsize,
OUT SS_UINT32 *  root_size 
)

获取开发锁 Virbox Root CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]root_ca存放开发锁 Virbox Root CA 证书的缓冲区
[in]root_bufsize缓冲区大小
[out]root_size开发锁 Virbox Root CA 证书大小
返回
成功返回 SS_OK ，失败返回相应的错误码
参见
master_open master_get_ca_cert
SS_UINT32 SSAPI master_get_root_count ( IN MASTER_HANDLE  device_handle,
OUT SS_UINT32 *  count 
)

获取开发商锁内所有的根证书数量

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]count根证书数量
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
自 2018年1月1日 起，VirboxLM 对开发锁和用户锁进行安全升级，开发锁将支持多根证书，新用户锁将使用新的根证书。 为兼容之前版本的用户锁，开发锁中将拥有多个根证书
SS_UINT32 SSAPI master_get_seedkey ( IN MASTER_HANDLE  device_handle,
OUT SS_BYTE *  key,
IN SS_UINT32  max_key_len,
OUT SS_UINT32 *  key_len 
)

获取签发设备的种子码密钥（种子码公钥）

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[out]key缓冲区
[in]max_key_len缓冲区长度
[out]key_len证书的长度
返回
成功返回 SS_OK ，失败返回相应的错误码
SS_UINT32 SSAPI master_heap_free ( IN void *  buf)

释放内存

参数
[in]buf内部分配的内存
返回
永远返回 SS_OK
备注
例如 master_get_info 分配的内存
SS_UINT32 SSAPI master_open ( OUT MASTER_HANDLE *  device_handle)

打开签发设备（开发锁）

参数
[out]device_handle开发锁设备句柄
返回
成功返回 SS_OK，失败返回相应的错误码
备注
一切的签发功能都离不开开发锁，若不打开开发锁，所有许可签发的操作将不能进行
参见
master_close d2c_lic_new
SS_UINT32 SSAPI master_pin_change ( IN MASTER_HANDLE  device_handle,
IN SS_BYTE  pin_index,
IN SS_BYTE *  old_pin,
IN SS_UINT32  old_pin_len,
IN SS_BYTE *  new_pin,
IN SS_UINT32  new_pin_len,
IN SS_BYTE *  hash 
)

修改开发商开发锁 PIN 码

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]pin_indexPIN 码所在的索引位置，目前只支持 1 个 PIN 码，当前为 0
[in]old_pin当前使用中的 PIN 码
[in]old_pin_len当前使用的 PIN 码长度
[in]new_pin新 PIN 码
[in]new_pin_len新 PIN 码长度
[in]hash新 PIN 码的 sha256 hash 结果，用于内部校验
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
PIN 码遵循以下格式：
  • 长度不得低于 8 个字符，不得大于 255 个字符
  • 不得使用汉字，全角字符等
  • 不得出现二级制 0 等会影响真实长度的字符
  • 初始 PIN 码必须修改，否则初始 PIN 码无法通过验证，初始 PIN 码从 VirboxLM 开发者中心获取（https://developer.lm.virbox.com）
SS_UINT32 SSAPI master_pin_deauth ( MASTER_HANDLE  device_handle)

清除 PIN 权限

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
清除当前 PIN 权限后，下次签发许可时，需要重新调用 master_pin_verify
SS_UINT32 SSAPI master_pin_disable ( MASTER_HANDLE  device_handle)

禁用开发锁 PIN 码

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
返回
成功返回 SS_OK，失败返回相应的错误码
备注
禁用当前开发锁的 PIN 功能，需先调用 master_pin_verify
SS_UINT32 SSAPI master_pin_enable ( MASTER_HANDLE  device_handle)

启用开发锁 PIN 码

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
启用开发锁 PIN 功能
SS_UINT32 SSAPI master_pin_is_verified ( MASTER_HANDLE  device_handle)

确认 PIN 码是否验证通过

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
如果返回 SS_ERROR_MASTER_OUTDATED_VERSION ，表示控制锁版本太低，必须更换控制锁； 如果返回 0x0100000D ，标明没有进行 PIN 吗验证。
SS_UINT32 SSAPI master_pin_verify ( IN MASTER_HANDLE  device_handle,
IN SS_BYTE  pin_index,
IN SS_BYTE *  pin,
IN SS_UINT32  pin_len 
)

验证开发锁 PIN 码

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]pin_indexPIN 码所在的索引位置，目前只支持 1 个 PIN 码，当前为 0
[in]pin当前使用中的 PIN 码
[in]pin_len当前使用的 PIN 码长度
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
PIN 验证遵循以下规则：
  • 初始 PIN 码不能通过验证
  • 必须通过 PIN 码验证才能签发升级包
SS_UINT32 SSAPI master_verify_ca ( IN MASTER_HANDLE  device_handle,
IN SS_BOOL  store,
IN SS_BYTE  ca_type,
IN SS_BYTE *  ca_cert,
IN SS_UINT32  ca_len 
)

验证开发锁 CA 证书

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]store验证时，是否将证书存储在锁内。TRUE，存储；FALSE，不存储。
[in]ca_type证书类型，详见 PKI_CA_TYPE_DEVELOPER 等
[in]ca_cert证书缓冲区
[in]ca_len证书长度
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
{
SS_UINT32 status = SS_OK;
MASTER_HANDLE master_handle;
SS_BYTE ca[2048] = { 0 }; // 证书或者CA的大小一般不会超过1.5k，这里缓冲区使用2k足够大了
SS_UINT32 ca_size = 0;
master_open(&master_handle);
// 通过master_get_ca_cert、master_get_developer_ca获取到开发者ca，或者加载外部存储的开发者ca
// ... ...
status = master_verify_ca(master_handle, FALSE, PKI_CA_TYPE_DEVELOPER, ca, ca_size);
if(status == SS_OK)
{
// save ca to file
}
master_close(master_handle);
}
SS_UINT32 SSAPI master_verify_ca_ex ( IN MASTER_HANDLE  device_handle,
IN SS_BOOL  store,
IN SS_BYTE  ca_type,
IN SS_UINT32  root_index,
IN SS_BYTE *  ca_cert,
IN SS_UINT32  ca_len 
)

验证开发锁CA证书（扩展接口）

参数
[in]device_handle开发锁设备句柄，通过调用 master_open 得到
[in]store验证时，是否将证书存储在锁内。TRUE，存储；FALSE，不存储。
[in]ca_type证书类型，详见 PKI_CA_TYPE_DEVELOPER 等
[in]root_index根证书序号
[in]ca_cert证书缓冲区
[in]ca_len证书长度
返回
成功返回 SS_OK ，失败返回相应的错误码
备注
此接口仅对 PKI_CA_TYPE_DEVELOPER CA 验证有效
生成于 2020年 一月 7日 星期二 14:58:50 , 为 Virbox SDK使用   doxygen 1.8.4