飞天诚信加密锁ROCKEY3用户手册

ROCKEY3 用户手册 V1.0 北京飞天诚信科技有限公司 网址：www.FTsafe.com ROCKEY3 用户手册 修订记录： 修订日期 版本 修订内容 2009 年 10 月 V1.0 第一版发布 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com i ROCKEY3 用户手册 软件开发协议 北京飞天诚信科技有限公司（以下简称飞天）的所有产品，包括但不限于：开发工具包，磁盘，光盘， 硬件设备和文档，以及未来的所有定单都受本协议的制约。如果您不愿接受这些条款，请在收到后的 7 天 内将开发工具包寄回飞天，预付邮资和保险。我们会把货款退还给您，但要扣除运费和适当的手续费。 1. 许可使用 您可以将本软件合并、连接到您的计算机程序中，但其目的只是如开发指南中描述的那样保护该程序。 您可以以存档为目的复制合理数量的拷贝。 2. 禁止使用 除在条款 1 中特别允许的之外，不得复制、反向工程、反汇编、反编译、修改、增加、改进软件、硬 件和产品的其它部分。禁止对软件和产品的任何部分进行反向工程，或企图推导软件的源代码。禁止使用 产品中的磁性或光学介质来传递、存储非本产品的原始程序或由飞天提供的产品升级的任何数据。禁止将 软件放在服务器上传播。 3. 有限担保 飞天保证在自产品交给您之日起的 12 个月内，在正常的使用情况下，硬件和软件存储介质没有重大的 工艺和材料上的缺陷。 4. 修理限度 当根据本协议提出索赔时，飞天唯一的责任就是根据飞天的选择，免费进行替换或维修。飞天对更换 后的任何产品部件都享有所有权。 保修索赔单必须在担保期内写好，在发生故障 14 天内连同令人信服的证据交给飞天。当将产品返还给 飞天或飞天的授权代理商时，须预付运费和保险。 除了在本协议中保证的担保之外，飞天不再提供特别的或隐含的担保，也不再对本协议中所描述的产 品负责，包括它们的质量，性能和对某一特定目的的适应性。 5. 责任限度 不管因为什么原因，不管是因合同中的规定还是由于刑事的原因，包括疏忽的原因，而使您及任何一 方受到了损失，由我方产品所造成的损失或该产品是起诉的原因或与起诉有间接关系，飞天对您及任何一 方所承担的全部责任不超出您购买该产品所支付的货款。在任何情况下，飞天对于由于您不履行责任所导 致的损失，或对于数据、利润、储蓄或其它的后续的和偶然的损失，即使飞天被建议有这种损失的可能性， 或您根据第 3 方的索赔而提出的任何索赔均不负责任。 6. 协议终止 当您不能遵守本协议所规定的条款时，将终止您的许可和本协议。但条款 2, 3，4，5 将继续有效。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com ii ROCKEY3 用户手册 章节目录 快速入门及注意事项 ........................................................................................................................................ 1 第 1 章 ROCKEY3 简介 ...................................................................................................................................... 3 1.1 关于ROCKEY3 加密锁 ................................................................................................................................ 3 1.2 ROCKEY3 加密锁的优点 ............................................................................................................................. 3 1.3 软件保护 .................................................................................................................................................... 4 第 2 章 ROCKEY3 加密锁的基本概念 ............................................................................................................... 5 2.1 开发商口令 ................................................................................................................................................ 5 2.2 开发商ID ..................................................................................................................................................... 5 2.3 硬件ID ......................................................................................................................................................... 6 2.4 数据存储区 ................................................................................................................................................ 6 2.5 共享内存区 ................................................................................................................................................ 6 2.6 用户可用空间 ............................................................................................................................................ 6 2.7 ROCKEY3 文件系统 ..................................................................................................................................... 6 2.7.1 ROCKEY3 文件特性 ......................................................................................................................................................7 2.8 ROCKEY3 其他功能 ..................................................................................................................................... 7 第 3 章 软件加密方法举例 .............................................................................................................................. 9 3.1 一些简单的加密技巧 ................................................................................................................................ 9 3.1.1 有迷惑性的代码.........................................................................................................................................................9 3.1.2 虚假的检查.................................................................................................................................................................9 3.1.3 验证时机的选择.......................................................................................................................................................10 3.2 使用ROCKEY3 进行加密 .......................................................................................................................... 10 3.2.1 ROCKEY3 新的软件加密方法 ....................................................................................................................................10 3.2.2 在ROCKEY3 内进行逻辑判断 ...................................................................................................................................11 3.2.3 设置输入和输出迷宫 ...............................................................................................................................................12 3.2.4 计时功能 ..................................................................................................................................................................12 3.2.5 计次功能 ..................................................................................................................................................................12 3.2.6 3DES，RSA与应用程序的综合运用.......................................................................................................................... 12 3.2.7 远程升级 ..................................................................................................................................................................13 第 4 章 ROCKEY3 工具使用说明 ..................................................................................................................... 15 4.1 KEIL集成环境............................................................................................................................................. 15 4.1.1 4.1.2 4.1.3 4.1.4 4.1.5 创建工程 ..................................................................................................................................................................15 设置工程选项...........................................................................................................................................................15 调试 ..........................................................................................................................................................................17 退出 ..........................................................................................................................................................................17 写入C51 程序 ...........................................................................................................................................................17 4.2 ROCKEY3 加密锁设置工具 ....................................................................................................................... 18 4.2.1 4.2.2 4.2.3 4.2.4 4.2.5 4.2.6 4.2.7 启动、登录设置工具 ...............................................................................................................................................18 基本功能 ..................................................................................................................................................................19 文件操作 ..................................................................................................................................................................20 加密解密 ..................................................................................................................................................................21 密码管理 ..................................................................................................................................................................22 远程升级 ..................................................................................................................................................................23 初始化 ......................................................................................................................................................................25 4.3 ROCKEY3 虚拟文件系统管理器................................................................................................................ 29 4.3.1 4.3.2 4.3.3 4.3.4 工具界面 ..................................................................................................................................................................29 新建、保存和打开虚拟文件系统 ........................................................................................................................... 30 创建文件 ..................................................................................................................................................................32 导入文件 ..................................................................................................................................................................34 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com iii ROCKEY3 用户手册 4.3.5 打开文件 ..................................................................................................................................................................36 4.3.6 编辑文件 ..................................................................................................................................................................37 4.3.7 导出文件 ..................................................................................................................................................................39 4.3.8 删除文件 ..................................................................................................................................................................40 4.3.9 附属功能 ..................................................................................................................................................................41 4.3.10 菜单栏和工具栏.....................................................................................................................................................42 4.4 ROCKEY3 加密锁标准外壳加密工具........................................................................................................ 43 4.5 ROCKEY3 加密锁DotNet外壳加密工具.................................................................................................... 46 第 5 章 ROCKEY3 高级应用 ............................................................................................................................ 51 第 6 章 ROCKEY3 内部系统函数（C51 语言） ............................................................................................... 54 6.1 退出程序 .................................................................................................................................................. 54 6.1.1 exit .............................................................................................................................................................................54 6.2 输入输出 .................................................................................................................................................. 55 6.2.1 pbInBuff和wInLen ......................................................................................................................................................55 6.2.2 set_response ..............................................................................................................................................................58 6.2.3 swap ...........................................................................................................................................................................60 6.3 文件操作 .................................................................................................................................................. 60 6.3.1 create .........................................................................................................................................................................60 6.3.2 open ...........................................................................................................................................................................61 6.3.3 close ...........................................................................................................................................................................62 6.3.4 read ............................................................................................................................................................................62 6.3.5 write ...........................................................................................................................................................................63 6.3.6 get_file_infor ..............................................................................................................................................................64 6.4 密码学算法 .............................................................................................................................................. 65 6.4.1 des_enc ......................................................................................................................................................................66 6.4.2 des_dec ......................................................................................................................................................................67 6.4.3 tdes_enc .....................................................................................................................................................................68 6.4.4 tdes_dec .....................................................................................................................................................................68 6.4.5 6.4.5 sha1_init ............................................................................................................................................................69 6.4.6 sha1_update...............................................................................................................................................................70 6.4.7 sha1_final ...................................................................................................................................................................70 6.4.8 md5_init .....................................................................................................................................................................71 6.4.9 md5_update ...............................................................................................................................................................72 6.4.10 md5_final .................................................................................................................................................................73 6.4.11 rsa_enc .....................................................................................................................................................................74 6.4.12 rsa_dec .....................................................................................................................................................................75 6.4.13 rsa_gen_key .............................................................................................................................................................76 6.4.14 rsa_sign ....................................................................................................................................................................77 6.4.15 rsa_verify..................................................................................................................................................................79 6.5 系统功能 .................................................................................................................................................. 80 6.5.1 rand ............................................................................................................................................................................80 6.5.2 get_version .................................................................................................................................................................81 6.6 双精度浮点运算 ...................................................................................................................................... 81 6.6.1 add .............................................................................................................................................................................82 6.6.2 sub..............................................................................................................................................................................83 6.6.3 mul .............................................................................................................................................................................83 6.6.4 div...............................................................................................................................................................................83 6.6.5 atan2 ..........................................................................................................................................................................84 6.6.6 mod ............................................................................................................................................................................84 6.6.7 pow ............................................................................................................................................................................84 6.6.8 modf ...........................................................................................................................................................................85 6.6.9 frexp ...........................................................................................................................................................................85 6.6.10 ldexp .........................................................................................................................................................................86 6.6.11 sin .............................................................................................................................................................................86 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com iv ROCKEY3 用户手册 6.6.12 cos ............................................................................................................................................................................86 6.6.13 tan ............................................................................................................................................................................87 6.6.14 asin ...........................................................................................................................................................................87 6.6.15 acos ..........................................................................................................................................................................87 6.6.16 atan ..........................................................................................................................................................................88 6.6.17 sinh ...........................................................................................................................................................................88 6.6.18 cosh ..........................................................................................................................................................................88 6.6.19 tanh ..........................................................................................................................................................................89 6.6.20 ceil ............................................................................................................................................................................89 6.6.21 floor ..........................................................................................................................................................................89 6.6.22 abs ............................................................................................................................................................................90 6.6.23 exp............................................................................................................................................................................90 6.6.24 log ............................................................................................................................................................................90 6.6.25 log10 ........................................................................................................................................................................91 6.6.26 sqrt ...........................................................................................................................................................................91 6.6.27 cmp ..........................................................................................................................................................................91 6.7 单精度浮点运算 ...................................................................................................................................... 92 6.7.1 addf ............................................................................................................................................................................92 6.7.2 subf ............................................................................................................................................................................93 6.7.3 6.7.3 mulf ...................................................................................................................................................................93 6.7.4 divf .............................................................................................................................................................................93 6.7.5 atan2f .........................................................................................................................................................................94 6.7.6 fmodf..........................................................................................................................................................................94 6.7.7 6.7.7 powf ..................................................................................................................................................................94 6.7.8 cmpf ...........................................................................................................................................................................95 6.7.9 sinf..............................................................................................................................................................................95 6.7.10 cosf ...........................................................................................................................................................................96 6.7.11 tanf ...........................................................................................................................................................................96 6.7.12 asinf ..........................................................................................................................................................................96 6.7.13 acosf .........................................................................................................................................................................96 6.7.14 atanf .........................................................................................................................................................................97 6.7.15 sinhf..........................................................................................................................................................................97 6.7.16 coshf .........................................................................................................................................................................97 6.7.17 tanhf .........................................................................................................................................................................98 6.7.18 ceilf ...........................................................................................................................................................................98 6.7.19 floorf ........................................................................................................................................................................98 6.7.20 absf ...........................................................................................................................................................................99 6.7.21 expf ..........................................................................................................................................................................99 6.7.22 logf ...........................................................................................................................................................................99 6.7.23 log10f .......................................................................................................................................................................99 6.7.24 sqrtf ........................................................................................................................................................................100 6.8 类型转换 ................................................................................................................................................ 100 6.8.1 dbltof ........................................................................................................................................................................100 6.8.2 ftodbl ........................................................................................................................................................................101 6.8.3 dbltol ........................................................................................................................................................................101 6.8.4 ltodbl ........................................................................................................................................................................102 6.8.5 dtof ...........................................................................................................................................................................102 6.8.6 ftod ...........................................................................................................................................................................103 6.8.7 dtol ...........................................................................................................................................................................103 6.8.8 ltod ...........................................................................................................................................................................104 6.9 结构和常量 ............................................................................................................................................ 104 6.9.1 数据类型 ................................................................................................................................................................104 6.9.2 宏定义 ....................................................................................................................................................................104 6.9.3 结构和枚举.............................................................................................................................................................106 6.10 错误编码 .............................................................................................................................................. 108 第 7 章 ROCKEY3 外部API函数（PC语言） ...................................................................................................110 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com v ROCKEY3 用户手册 7.1 API接口函数 ............................................................................................................................................ 110 7.1.1 RY3_Find ..................................................................................................................................................................110 7.1.2 RY3_Open.................................................................................................................................................................110 7.1.3 RY3_Close .................................................................................................................................................................111 7.1.4 RY3_GetHardID ........................................................................................................................................................113 7.1.5 RY3_GenRandom .....................................................................................................................................................115 7.1.6 RY3_GetFreeSize ......................................................................................................................................................117 7.1.7 RY3_LEDControl........................................................................................................................................................119 7.1.8 RY3_VerifyDevPin .....................................................................................................................................................122 7.1.9 RY3_SetVendorID .....................................................................................................................................................124 7.1.10 RY3_ChangeDevPin ................................................................................................................................................127 7.1.11 RY3_Read ...............................................................................................................................................................129 7.1.12 RY3_Write ..............................................................................................................................................................131 7.1.13 RY3_VendorWrite ...................................................................................................................................................134 7.1.14 RY3_ReadShare ......................................................................................................................................................136 7.1.15 RY3_WriteShare .....................................................................................................................................................139 7.1.16 RY3_CreateFile .......................................................................................................................................................141 7.1.17 RY3_WriteFile .........................................................................................................................................................144 7.1.18 RY3_ExecuteFile .....................................................................................................................................................147 7.1.19 RY3_EraseAllFile .....................................................................................................................................................150 7.1.20 RY3_GenRsaKey......................................................................................................................................................152 7.1.21 RY3_SetRsaKey .......................................................................................................................................................155 7.1.22 RY3_PublicEncrypt .................................................................................................................................................159 7.1.23 RY3_PrivateDecrypt................................................................................................................................................159 7.1.24 RY3_MD5................................................................................................................................................................162 7.1.25 RY3_SHA1 ...............................................................................................................................................................164 7.1.26 RY3_Set3DESKey ....................................................................................................................................................166 7.1.27 RY3_3DES ...............................................................................................................................................................168 7.1.28 RY3_Update............................................................................................................................................................172 7.1.29 RY3_GenUpdatePacket...........................................................................................................................................173 7.2 7.2 错误编码 .......................................................................................................................................... 177 7.2.1 错误编码 ................................................................................................................................................................177 附录A 函数接口速查 ....................................................................................................................................179 附录B ROCKEY3 保留ID ..................................................................................................................................183 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com vi ROCKEY3 用户手册 快速入门及注意事项 „ ROCKEY3 加密锁出厂设置为： 产品VendorID：“00000000”。 开发商口令：“123456781234567812345678”。 没有重试次数限制。 如果您设置了根目录开发商口令的重试次数，那么当使用者连续输入错误的次数达到了最大限制 的次数，开发商口令被锁死，这时只能退回给我公司重新生产。 „ ROCKEY3 加密锁是 USB 接口的高速 HID 设备，支持 Win98SE 以上的 Windows 操作系统，包 括最新的 Windows 7 操作系统，不需要安装额外的驱动程序。 „ ROCKEY3 加密锁具有 64 位（8 个字节）全球唯一硬件序列号。 „ ROCKEY3 用户空间为 32K。硬件擦写次数 10 万次，读没有限制。工作温度：0℃－70℃。 „ 光盘的 TOOLS 目录下，您能找到 ROCKEY3 加密锁设置工具（RY3Tools.exe), 该工具能帮您完 成诸如加密锁的初始化、编辑修改等操作，是您使用加密锁的实用工具（详细参见 4.2 ROCKEY3 加密锁设置工具）。 „ 光盘的 TOOLS 目录下，您能找到 ROCKEY3 虚拟文件系统管理器（VfsSet.exe），该工具相当 于一个真实加密锁的模拟环境，一个虚拟文件就相当于一把 ROCKEY3。（详细参见 4.3 ROCKEY3 虚拟文件系统管理器）。 „ 光 盘 的 EncryptTool\ PE32 目 录 下 ， 您 能 找 到 ROCKEY3 加 密 锁 标 准 外 壳 加 密 工 具 （Rockey3Env.exe），该工具可以方便、快捷的加密 Win32 位应用程序。不需要写一行代码，是 最简单最快速的加密方案。（详细参见 4.4 ROCKEY3 加密锁标准外壳加密工具）。 „ 光盘的 EncryptTool\ DotNet 目录下，您能找到 ROCKEY3 加密锁 DotNet 外壳加密工具 （Rockey3_NetShell.exe），该工具可以方便、快捷的加密 DotNet 应用程序（详细参见 4.5 ROCKEY3 加密锁 DotNet 外壳加密工具）。 „ ROCKEY3 加密锁提供外部函数调用（API）保护方法，您可以在自己要保护的应用程序中连接 入 ROCKEY3 API,完全的发挥加密锁的所有功能,这种方法提供了极高的安全性。结合示例，相信您 会很快学会如何使用 ROCKEY3 API 来加密保护软件的技巧(详细参见 第七章 ROCKEY3 外部 API 函数调用及光盘 Samples 目录下的程序示例)。 „ ROCKEY3 加密锁的软件接口丰富，对于大多数开发工具都有相应的软件接口。光盘的 API 目 录下是各种库文件。 API\BCB\ RY3_BCB.lib C++ Builder静态链接库 API\Com\Rockey3Com.dll Com组件，使用时需要先注册： 1．将Rockey3Com.dll拷贝到系统目录（%Windows%\system32\）下 2．在控制台中注册：regsvr32 FTRockey2Control.dll 3．卸载系统目录下控件：regsvr32 /u FTRockey2Control.dll API\Delphi\ Rockey3_Delphi.obj Delphi库文件 API\Dynamic\ Rockey3.dll 动态链接库 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 1 ROCKEY3 用户手册 API\Dynamic\ Rockey3.lib 动态链接库LIB文件 API\Include\ RY3_API.h 头文件 API\Java\ RY3Java.dll JAVA的jni接口库 API\Java\ RY3jni.jar API\Static\ Rockey3.lib JAVA库文件 C语言静态链接库 „ 光盘的 C51 目录下是编写加密锁内部 C51 程序所需的库文件和头文件。 „ 如果您需要使用ROCKEY3 加密锁进行开发或者测试请与我公司联系。并请关注我们的网 站：http://www.FTsafe.com.cn（中文） ，http://www.FTsafe.com（英文），http://www.FTsafe.co.jp（日 文） 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 2 ROCKEY3 用户手册 第1章 ROCKEY3 简介 1.1 关于ROCKEY3 加密锁 ROCKEY3 加密锁是一款以智能卡硬件为核心的软件加密锁。硬件擦写次数 10 万次，保存 10 年。工作 温度：0℃－70℃。ROCKEY3 融合了加密锁和智能卡技术，采用无驱设计，功能强大，价格实在，是集各 种先进技术于一身的多用途产品，在软件保护、身份认证、电子交易、数据安全等多个领域都能发挥其强 大的功能。 1.2 ROCKEY3 加密锁的优点 „ 小巧美观 ROCKEY3 加密锁美观、时尚、精巧，便于携带。 „ 速度快 ROCKEY3采用高速无驱设计，将高速和应用简便集成到一体。 使用 ROCKEY3 加密锁加密后的软件，其运行速度同加密前区别不大，即使用户在加密锁内定义 了极其复杂的加密算法，ROCKEY3 加密锁也能够在很短的时间内处理完毕，保证用户程序的顺畅运行。 „ 使用简单 ROCKEY3 加密锁从用户角度出发，设计了合理的内部构造，并提供方便的设置工具，最大限度地 简化API接口。用户能够在很短的时间内掌握 ROCKEY3加密锁的使用方法，节约在软件加密上所投入 的时间。 „ 加密强度高 ROCKEY3 加密锁是全新设计的高强度加密锁。软件生产厂商与最终用户具有不同的权限，从而提 高加密锁的安全度。 ROCKEY3 加密锁采用通讯加扰, 可以防止多机共享，防止USB通讯数据模拟，同时实现多线程访 问加密锁。 ROCKEY3 加密锁采用了种子的方式产生开发商ID，种子长度最大为250字节，大大增加了安全性。 ROCKEY3 加密锁采用智能卡芯片，内置C51虚拟机，软件开发商可以将核心算法和数据移植到加 密锁内部，并在锁内运行。在卡片操作系统的管理下，ROCKEY3加密锁成为一个与计算机平行的小型 计算机系统，并通过USB接口同计算机交换数据。保证在可靠解决方案和一定的算法复杂度的前提下， 程序被破解的可能性等于零。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 3 ROCKEY3 用户手册 „ 系统支持全面 ROCKEY3 加密锁支持的平台：Windows 98SE、Windows Me、Windows 2000、Windows XP、Windows Server 2003、Windows 2008、Windows Vista、Windows 7。 „ 软件接口丰富 对于大多数开发工具都有相应的软件接口， VB、VC、C++ BUILDER、PB、DELPHI、VFP、VS.NET、 JAVA、C51 1.3 软件保护 在软件加密方面，ROCKEY3 采用了多种先进的关键加密技术，是目前软件保护领域中最安全的保护产 品。 „ 硬件上的安全性 很多软件被盗版都是由于硬件被复制，不能抵御破解攻击造成的。一个高强度的加密锁首先应有 牢固的硬件基础。ROCKEY3 采用了安全强度最高的智能卡芯片，硬件不能被复制，多重安全级别，并 且集成了 16 位 CPU，32 字节内存，32k 存储空间等模块。ROCKEY3 在具有如此强大和安全功能的同 时，改进了生产工艺，极大降低了生产成本，从而使广大的软件厂商不必再花费高额的加密锁成本就 能够使用上智能卡型加密锁，从根本上提高了软件的加密强度。 „ 硬件上的兼容性 ROCKEY3 采用无驱设计，使用高速 HID 协议，在 WIN98 二版以上的操作系统中不需要安装驱动程 序，彻底解决了由于驱动安装而给软件开发商带来的各种各样的问题。无驱的同时，ROCKEY3 使用高 速协议，对应用软件没有任何速度上的影响。正因为 ROCKEY3 在硬件上卓越的兼容性，使用 ROCKEY3 几乎不需要任何维护，大大节省了维护成本。 „ 先进的软件保护 ROCKEY3 就像一个小型计算机，能够完成众多以前只能在 PC 上完成的功能，如复杂的浮点运算。 软件开发商可以将自己的程序代码转移到 ROCKEY3 中运行，计算机中没有任何程序的痕迹，同时 ROCKEY3 内部的代码任何人也获取不到。软件开发商发行的是一个不完整的软件，只有与 ROCKEY3 结合，软件才能够正确执行。由于硬件上的安全性，可以认为 ROCKEY3 是不可破解的。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 4 ROCKEY3 用户手册 第2章 ROCKEY3 加密锁的基本概念 2.1 开发商口令 在使用 ROCKEY3 进行软件保护时，ROCKEY3 提供了开发商口令，使用更加方便。当硬件重新插拔或者 断电时，安全权限会被重置成没有认证过的状态。注意：当硬件被关闭，例如调用 RY3_Close（RY_HANDLE handle , BOOL IsReset）函数时，若参数 IsReset 值为 TRUE 则清除设备内存中的数据和安全状态，若 IsReset 值为 FALSE 则不清除。 开发商口令（24 字节）是开发商在进行软件保护开发时使用到的，其作用主要是对 ROCKEY3 硬件进行 设置，如：创建文件，删除文件等。该口令为 24 个字节，初始值为：“123456781234567812345678”， 十六进制表示为“0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38”。虽然开发商口令只能向锁内写入和删除文件，而不能获 取锁内的任何数据，但还是建议开发商在初始化时，将默认的开发商口令更改成自己的设定的独特值，以 防止被非法者获取。 开发商口令的相关事项： „ 开发商口令的长度必须为 24 字节。 „ 开发商口令默认没有重试次数的限制，但为了防止暴力破解，我们建议开发商自己设定这个 口令的重试次数，可以设置为 1‐254 次（见 7.1.10 节中 RY3_ChangePin 函数的说明），当设置为 255（0xFF）次时，表明没有限制。这时应注意：在验证开发商口令时，当口令不正确，并且连续 验证的次数超过了重试次数，口令将被锁死。这时即使再输入正确的口令，也无法恢复。为了最 大限度的保护您的安全性，我们也无法进行解锁和重新设置，只能退回我公司重新生产。所以请 开发商妥善保存好开发商口令。 „ 当开发商口令被泄漏或者被盗取时，由于 ROCKEY3 设计上和硬件上的安全性，也不会对软件 带来任何安全上的影响，开发商完全可以不必担心。开发商口令验证后只能写入和删除锁内的数 据，而不能获取锁内的任何数据。那么非法拥有该口令的人只能破坏加密锁中的数据，而不能读 到锁内的任何内容，不能进行软件或者硬件上的仿真，应用软件还是无法使用。必须拥有数据完 好的加密锁，软件才能正确执行。即便如此，我们还是建议开发商要妥善的保存好自己的口令， 增加一道安全措施。 2.2 开发商ID 开发商 ID 为 8 个字节，初始值为“00000000”。开发商可以通过 ROCKEY3 加密锁设置工具或者 API 接 口函数来重新设置开发商 ID，并通过开发商 ID 来判断是否是自己的 ROCKEY3。在设置开发商 ID 时，为了 防止其他人设置相同的开发商 ID，ROCKEY3 采用了种子的方式来生成开发商 ID，即开发商输入产生开发 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 5 ROCKEY3 用户手册 商 ID 的种子（种子长度最大为 250 字节），ROCKEY3 会在硬件内部根据该种子产生相应的开发商 ID，而且 是不可逆的。只有生成者，才知道什么样的种子能生成自己的开发商 ID，这样其他人即使获得了开发商 ID， 但由于不知道产生开发商 ID 的种子，因此无法设置相同的硬件，大大增加了安全性。 开发商可以通过 RY3_SetVendorID 接口来设置开发商 ID，详见 7.1.9 节。 2.3 硬件ID 每个 ROCKEY3 加密锁内部都有一个唯一的硬件 ID，这个硬件 ID 是在加密锁出厂时烧入的，即使是 厂家也不能修改这个硬件 ID，而且这个硬件 ID 具有唯一性， 即世界上不可能有两个相同硬件 ID 的 ROCKEY3 加密锁，当开发者需要给特定用户加密时，可以通过检查这个 ID 来确认加密的唯一有效性。 开发商可以通过 RY3_GetHardID 接口来获得硬件序列号，详见 7.1.4 节。 2.4 数据存储区 ROCKEY3 加密锁提供 8k 的数据存储区。其中 0‐7168 字节为低级数据存储区，7169‐8192 字节（共 1024 字节）为高级数据存储区。低级存储区不论是开发商模式还是用户模式都可以进行读、写操作。高级 数据存储区只有在验证了开发商密码后（即开发商模式），才能进行写操作，读操作不需要验证开发商密 码。用户模式只能对高级数据存储区进行读操作。 软件开发商在调用 API 函数对数据存储区进行写操作时，请调用 RY3_VendorWrite 接口（详见 7.1.13） 。 2.5 共享内存区 ROCKEY3 加密锁内有 32 字节的共享内存区。能够充分保证在锁内运行的程序享有充足的卡片内存。 开发商可以通过 RY3_ReadShare、RY3_WriteShare 接口来读写共享内存区，详见 7.1.4 节。 2.6 用户可用空间 ROCKEY3 加密锁提供 32k 的用户可用空间。在此空间中，用户可以存放自己的文件。文件系统请参考 2.7 章节。 2.7 ROCKEY3 文件系统 ROCKEY3 中的文件系统与 Windows 的文件系统一样，是文件结构，文件包括：可执行文件，数据文件 和密钥文件。每个文件都有自己的 ID，这个 ID 为 2 个字节，例如：0x1002，0x100A 等，文件的 ID 不能重 复。对文件系统的操作，可以通过调用内部函数（C51 语言）和外部 API 函数来实现。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 6 ROCKEY3 用户手册 2.7.1 ROCKEY3 文件特性 „ 可执行文件 可执行文件是由 C51 语言编写的，在加密锁内部运行的文件。您的应用程序运行时，调用我们提 供的各种语言的 API 接口，向该文件传入输入数据，可执行文件在加密锁内部运行后，将结果返回给 外部的应用程序。可执行文件可以被其他可执行文件改写，验证开发商口令后可以创建和写入。文件 中的内容不能被任何人读取。当需要远程升级时，可以创建可执行文件，通过程序改写锁内的可执行 文件（见 3.2.7 节中的说明）。 „ 内部数据文件 存放数据信息的文件。该文件在开发商口令验证后，可以通过 API 接口写入，但不能读。或者通 过锁内可执行文件来读取和写入。即应用程序调用外部的 API 接口，API 接口调用 ROCKEY3 内部的可 执行文件，可执行文件（通过 C51 语言）读写内部数据文件。 „ 密钥文件 存储 RSA 密钥对（公钥和私钥）的文件。对于公钥文件开发商口令可以写，可执行文件可以读写。 对于私钥文件，开发商口令可以写，但文件中的内容不能被任何人读取。在使用 ROCKEY3 加密锁设置 工具（见 4.2 节中的说明）产生 RSA 密钥对时会返回公钥和私钥的数据，因为私钥文件不能读取，只 有在这时才能备份相关数据，因此开发商需要妥善保存，以备以后使用。 各种文件与口令的权限关系总结如下： 开发商口令验证 可执行文件 可执行文件 写入 写入 内部数据文件 写入 写入/读取 公钥 写入 写入/读取 私钥 写入 写入 密钥文件 表 2­1 文件与口令权限关系表 2.8 ROCKEY3 其他功能 ROCKEY3 为硬件级通讯加密，在 USB 接口上传输的数据都是密文。即软件中的数据，经过加密传送给 ROCKEY3，ROCKEY3 再在硬件内部进行解密，然后进行操作，反之亦然。 ROCKEY3 硬件实现 512、1024、2048 位的 RSA 运算功能，开发商可以使用 RSA 非对称算法对数据进行 加解密。同时 ROCKEY3 具有 DES 和 3DES 对称加解密功能。在 PKI（公共密钥基础体系）领域中有数字信封 的概念，即将对称密钥通过 RSA 非对称密钥在双方进行交换，然后双方所有的交换数据都是经过对称密钥 进行加解密的。这种标准的过程也可以使用在软件保护中。注意，用 C51 程序进行 RSA 运算时，RSA 密钥 长度可以为 512/1024/2048 中的一个（详见 6.4.11、6.4.12、6.4.13）。调用 API 接口进行 RSA 运算时， 只支持 1024 位（详见 7.1.20、7.1.21） 。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 7 ROCKEY3 用户手册 ROCKEY3 提供了 MD5，SHA1 散列算法。散列算法是根据不同的输入，产生固定长度的对应输出，相 当于以前软件保护中经常提到的种子码算法。 ROCKEY3 能够像 PC 一样完成各种复杂的单精度和双精度浮点运算。开发商可以将应用软件中的公式 放入到加密锁中来完成。浮点数运算是在 ROCKEY3 硬件中完成的，比在 C51 语言中效率高。 ROCKEY3 的指示灯可以通过程序来设置为：开，关，闪烁三种状态。开发商可以在程序中来进行设置， 这样可以起到迷惑作用。如指示灯闪烁时并不一定在调用锁内的可执行文件。 ROCKEY3 具有远程升级功能。软件升级时，开发商不需要将加密锁回收，只需要发给用户一个升级程 序，就可以将锁内的文件进行升级（详见 3.2.7 节中的说明） 。升级数据包可以使用 ROCKEY3 加密锁设置工 具产生（详见 4.2.6），也可以调用 API 接口产生（详见 7.1.28、7.1.29）。 ROCKEY3 中不同的可执行文件可以共享加密锁中的内存区。这样不同的可执行文件在共享数据时，不 必先写到文件中再读取出来，而是直接使用内存指针就可以实现，减少了硬件的读写操作，增加了运行效 率。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 8 ROCKEY3 用户手册 第3章 软件加密方法举例 上一章介绍了 ROCKEY3 超级多功能锁的特点，那么怎样才能将 ROCKEY3 与我们开发的软件结合起来呢？ 本章将介绍一下软件保护中常见的方法和使用 ROCKEY3 来保护软件。这些方法都是您在软件保护的书籍中 或者相关的网站上可以找到的，在这里只是给大家做个参考。真正好的软件加密方法还是智者见智，希望 每个软件开发商都能够在本章的基础上，使用 ROCKEY3 设计出自己独特的加密方案，真正达到您的软件不 可破解。 3.1 一些简单的加密技巧 对于软件保护来说，有些技巧并不需要你掌握很多汇编或系统低层的知识也能够做到。我们都知道， 不论您的软件采用何种方式来加密，很多情况下总是会归结为某些条件的判定，如果满足了这些条件，程 序就会认为软件是允许执行下去的，否则就会报告一些错误并退出执行。不论你采用任何方法，这些代码 是必然存在在你的程序中的，不要费心思去考虑如何消除这些代码，这些代码必然以这样或那样的形式存 在，我们考虑的重点是如何有效的隐藏和保护这些代码。 3.1.1 有迷惑性的代码 通常来说，编程人员和解密者都具有很好的逻辑思维能力，他们都会认为如果某段程序存在，那么就 应该有这段程序存在的意义。编程人员为了代码的效率和空间会不断的剔除无用的代码，解密者也是这么 理解开发人员的，他通过分析程序中保护代码的每一段指令来追索编程人员的保护思路。如果反其道而行 之，故意添加大量的无用的代码，把程序复杂化，毕竟开发者是在拿高级语言编写程序，而解密者是在看 汇编代码，想搞清楚哪些代码是有用的，哪些代码是无用的，并不是一件简单的事。 3.1.2 虚假的检查 故意去把返回结果和一些错误的答案进行比较，比较结果一定应该是错误的，如果比较结果发现是正 确的，说明有人正在试图破解您的软件。反击的手段可以有多种选择。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 9 ROCKEY3 用户手册 3.1.3 验证时机的选择 图 3.1.3­1 验证时机的选择 软件在运行时，验证时机可以是没有规律的，是散乱的，那么要查找到所有的加密点则不是一件容易 的事情。 3.2 使用ROCKEY3 进行加密 软件加密方法是每个软件开发商结合自己软件特点所设计出来的具有独特性的方案，每个开发商应该 有自己特别的方案，不要雷同，更要做好保密工作，防止破解者根据经验进行破解。下面对几个方案进行 分析，这些方案充分利用了 ROCKEY3 加密锁的硬件不可复制性、智能卡的复杂运算能力和密钥保密性等特 点。 3.2.1 ROCKEY3 新的软件加密方法 传统的软件加密方法很多只是把加密锁当作存储设备，将简单的信息存储在里面，然后在软件运行时 进行判断，也有许多开发商只是检测硬件是否存在，这些加密手段 在现在的破解中十分容易，根本就没有任何加密价值，软件非常容易被盗版。后来有的加密锁中加入 了自定义算法，但由于硬件的限制，算法也只有简单的加，减，左移，右移等，算法再怎么变化也就是这 几种之间的组合，最主要的是这样的算法根本不能完成软件需要的功能。 智能卡技术的介入，使加密锁可以完成以前只有在PC中才可以实现的功能，软件开发商可以通过这样 的步骤来实现软件加密。 （1）使用高级语言开发软件 （2）将核心算法转换成 C51 语言，进行编译。转换成 ROCKEY3 的可执行文件的方式存储在加密锁中。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 10 ROCKEY3 用户手册 （3）应用程序运行过程中，遇到关键算法时，将需要运行的数据传给 ROCKEY3，ROCKEY3 在加密锁内 调用可执行文件内完功能，将结果传给应用程序，程序继续执行。 图 3.2.1­1ROCKEY3 保护软件示意图 很多商业软件，如 CAD 设计软件，工程预算软件，财务软件等里面包括很多数学计算的公式，对这样 的软件进行高强度的加密是非常容易的。由于 ROCKEY3 具有复杂的双精度浮点运算的能力，可以运算复杂 的三角函数，因此能够满足这些软件的计算要求。那么原来在计算机内存中完成的运算完全可以植入到加 密锁中运行，这样破解者只能跟踪到程序中的输入和输出，而不清楚加密锁中的算法是什么，在没有加密 锁的情况下，程序中就没有计算的结果或结果不正确，从而软件不能运行。例如：我们可以将身份证 15 位 升级到 18 位的算法放入 ROCKEY3 中运行，没有加密锁就没有正确的结果，软件必须靠加密锁来完成，从而 不可破解。这种加密方法需要注意： （1）算法要够复杂。算法如太简单，如只是一个加法，那么破解者完全可以通过输入和输出猜测到锁 内的算法，使用软算法模拟，则程序被破解。 （2）ROCKEY3 采用的是 16 位的智能卡芯片，浮点运算能力非常快。能满足多数运算要求。如某些应 用软件要求运算速度，可以将复杂公式中的部分放到加密锁内运行。 （3）加密锁内的公式不能是已经公开的或者是泄漏的公式，这些不安全的公式可以被破解者软件模拟。 （4）计算的结果一定要是软件使用到的，而不是在软件中比较。如加密过程是比较的话，破解者很容 易找到比较的逻辑判断点，进行屏蔽等修改，这样即使锁内的运算是多么复杂都是无效的。 上述的方法是软件保护中最有效的，ROCKEY3 就是一个黑盒子，那么只要注意上面的四点说明，使用 这样的方法进行保护的软件是不可能被破解的。 3.2.2 在ROCKEY3 内进行逻辑判断 在对软件进行加密时，可以使用外部的 API 函数接口或者在锁内使用 C51 的接口来获得硬件信息，如硬 件 ID 号，开发商 ID 等。由于这些硬件信息是唯一的，因此可以在 ROCKEY3 加密锁内部针对这些信息进行 处理和判断，逻辑处理在加密锁内部，破解者是无法修改的，从而达到软件不能被破解。在这种加密方法 中加入随机数的成份会大大增加加密强度。如：（1）软件运行时得到一个随机数和硬件 ID，将随机数与这 个 ID 进行处理，传入到锁内的可执行文件中。 （2）在锁内进行反向处理，得到硬件 ID，这个 ID 与使用 C51 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 11 ROCKEY3 用户手册 语言得到的硬件 ID 进行比较，进行逻辑判断。这样破解者每次跟踪到的是随机内容，而逻辑的过程又是在 加密锁内进行，软件不能被破解。 3.2.3 设置输入和输出迷宫 有的破解者使用 USB 协议分析仪，对 PC 与加密锁之间传输的数据进行分析。ROCKEY3 在 USB 接口传输 的数据是密文。但为了更加安全，建议软件开发商在传输数据时做一些处理，即加解密的算法由每个软件 开发商自己掌握，各不相同。除了 ROCKEY3 的通讯算法外，再加上每个开发商自己的算法，一家的算法泄 漏也不会影响其他的软件。加解密算法可以开发商自己设计，也可以使用 3DES 等流行的对称算法。其过程 如下： （1）在外部 API 函数进行调用时，对要传输的数据进行处理。 （2）在锁内的程序进行反向处理，得到 真正的输入，再进行下面的程序。 3.2.4 计时功能 开发商可以在第一次运行时，将系统时间记录下来，在锁内创建一个起始时间的内部数据文件，然后 把这个起始时间在加上一个时间（如 30 天，或使用分钟数等），再创建一个结束时间的内部数据文件，那 么就可以解决如何设定开始时间的问题。 程序第一次运行时，锁内没有这 2 个数据文件，返回打开失败，开始创建，后面在运行时，这 2 个文 件打开成功，可以向开始时间文件写新读到的系统时间，这时要比较新的时间是否比开始时间文件中的时 间要早，防止用户修改系统时间，然后再与结束时间比较，看是否在范围内。这样就可以完全实现外部时 钟的功能，即节省了成本，又可以防止外部时钟失效的问题。 3.2.5 计次功能 开发商可以在 ROCKEY3 内创建一个内部数据文件用来记录软件的使用次数，软件每使用一次，就将这 个文件的次数改写一次，当文件不存在或者记录的次数为 0 时，软件使用到期。可以在 ROCKEY3 的可执行 文件中进行逻辑处理，使用到期后核心的可执行文件无法运行。 3.2.6 3DES，RSA与应用程序的综合运用 ROCKEY3 加密锁采用的是 16 位的智能卡芯片，具备高性能的 3DES 和 RSA 运算能力。3DES，RSA 这些 对称和非对称的加解密算法可以使用在单机版软件，C/S 结构和 B/S 结构中的软件中。下面就对 C/S 结构的 软件举例说明： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 12 ROCKEY3 用户手册 图 3.2.6­13DES,RSA 综合运用 <1>为插在服务器上运行的加密锁，锁内存储有 RSA 运算的私钥，以及开发商自己编写的关联算法。 <2>服务器端程序，该程序主要是将客户端传来的数据进行处理，传输给加密锁，或者将加密锁处理的 数据传给客户端。 <3>客户端程序，客户端需要有与服务器端加密锁中私钥对应的公钥。 应用程序运行时，客户端的程序产生随机数作为 3DES 加解密的密钥，使用程序中存在的公钥对随机数 进行加密传给服务器端，服务器端在 ROCKEY3 在锁内使用私钥进行解密，并将对称密钥存储成内部数据文 件。这样程序运行时在网络上传输的数据都是使用 3DES 算法加密过的数据，保证了传输数据的保密性，被 跟踪到没有关系。 为了防止解密者篡改客户端程序，即购买一把 ROCKEY3 加密锁，然后使用破解者自己的 RSA 密钥对， 将客户端的公钥替换进行解密，开发商还应该在 ROCKEY3 中加入自己设计的关联算法，这些算法以 C51 程 序的形式在加密锁中，任何人无法得知其中的过程，那么即使公私钥被替换，但开发商这些独特的算法破 解者是不知道的，软件也无法被破解。例如：如果要限制客户端的数目，当一个用户发出登录请求时，客 户端将客户端的信息经过软件的 3DES 加密传给服务器端，服务器端软件将这些信息传入给 ROCKEY3，加密 锁在锁内进行：（1）将信息解密，与关联算法得到的信息进行比对，如一致则认为该客户端有效。（2）同 时在锁内判断登陆数量是否已满。如这两点都满足，则表明客户端是一个合法用户，将登陆加密的信息发 给客户端，客户端使用软件的 3DES 解密出客户端需要的正确结果，完成连接。如条件不满足，返回错误的 加密信息，虽然表面看起来，与正确的数据差不多，但这时使用客户端的对称密钥解密后的数据是一堆无 用乱码，连接失败。在这个示例中需要注意的就是：（1）一定要有关联算法，否则很容易被重新生成 RSA 密钥对，而被破解。（2）各种检查和判断一定要在锁内进行，服务器端的程序只是起到一个传输的作用。 3.2.7 远程升级 软件开发商将加密后的软件卖给最终用户后，在软件进行升级时可以利用远程升级功能而不必回收加 密锁。远程升级时，在用户模式下就可更改加密锁中的资源:8192 字节的数据存储区,1‐8 号的 RSA 公私钥 对,1‐8 号的 3DES 密钥。但是不能升级 32k 用户空间中的内容，用户空间中的内容如果要升级，需要用户自 行处理。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 13 ROCKEY3 用户手册 升级过程如下： （1）在软件发行时，ROCKEY3 内部存有可执行文件和内部数据文件，另外还要有一个用于升级的可执 行文件，这里称为 UP 文件。升级时要保证传输的是密文，您可以使用 RSA 非对称加解密或者使用 3DES 对 称加解密。这里我们使用 RSA 非对称加解密，就需要 ROCKEY3 中已经存在一个私钥。例如 ROCKEY3 内存 在：A（可执行文件）、B（内部数据文件）、PRI（私钥文件）和 UP(可执行文件)。 （2）当软件进行升级时，开发商需要将新的 A’和 B’使用与已经存在的 ROCKEY3 中私钥文件（PRI）对 应的公钥文件（PUB）进行加密，将加密后的结果传输给最终用户。注意，公钥文件最好不要存放在锁内。 虽然即使写入也没有办法读出来，但是我们建议公钥文件最好不要存放在锁内。因为公钥泄漏可能会导致 其他人产生非法的升级包，不过即使这样也只能破坏锁内数据，不会造成加密的安全问题。 （3）在最终用户处的 ROCKEY3 内部的 UP 可执行文件接收到 A’和 B’的密文，使用锁内的私钥文件（PRI） 将 A’和 B’解密，然后使用 C51 语言的文件操作接口（见 6.3.1‐6.3.6 节中的说明），将锁内的 A 和 B 替换为 A’ 和 B’，升级完成。 产生升级包时可以指定允许被升级的硬件 ID，这样就能对指定 ROCKEY3 进行升级。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 14 ROCKEY3 用户手册 第4章 ROCKEY3 工具使用说明 上一章通过一个简单的示例演示了整个加密的过程。本章将介绍在使用 ROCKEY3 时要用到的工具，包 括 KEIL 集成环境、ROCKEY3 加密锁设置工具、ROCKEY3 虚拟文件系统管理器、ROCKEY3 外壳加密工具等。 4.1 KEIL集成环境 运行在 ROCKEY3 硬件中的可执行文件是使用 C51 语言编写的。C51 语言与 C 语言的语法基本一致，该 语言经常用于硬件程序的开发上。在 KEIL 环境下编译后，出来的是一个后缀为 bin 的二进制文件，这种文 件导入到 ROCKEY3 中就可以通过外部的 API 函数（见 7.1.15）调用运行了。 KEIL 公司出品的 C51 语言的编译器为 uVision，您可以在 KEIL 公司的网站（http://www.keil.com）上 下载到测试版，测试版与正式版相比有一些限制。本节中以 uVision2 的版本来进行说明。 4.1.1 创建工程 打开 KEIL uVision2，在“Project”菜单中选择“New Project”菜单项建立新的工程，在弹出的保存对话 框中输入工程的名字进行保存。在保存工程文件名时显示“Options for Target ‘Target1’”， 选择 51 系列的 CPU， 如 Intel 80C51BH，对于已有工程如没有选择 51 系列 CPU 的要重新选择，见下图所示： 图 4.1.1­1 选择 51 系列 CPU 4.1.2 设置工程选项 打开菜单项“工程ÆOptions for Target‘Target1’”,对于 Target 页中 Memory Modul 可以选择默认的 Small 模式，建议用户使用这种模式，见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 15 ROCKEY3 用户手册 图 4.1.2­1 选择 Small 模式 对于在 4.1.1 中打开的界面“工程ÆOptions for Target’Target1” ,在 output 页中选中复选项“C reat HEX File”, 同时复选“Run User Program #1”输入“hexbin.exe test.hex test.bin”，其中 test.hex 和 test.bin 根据工程的名 称不同而不同，使用前请将 hexbin.exe 文件（Tools 目录下）拷贝到您的工程目录下。hexbin.exe 工具的功 能就是将 KEIL 产生的十六进制 HEX 文件转变成二进制 BIN 文件，该 BIN 文件就是导入到 ROCKEY3 中的可执 行文件。见下图所示： 图 4.1.2­2 设置 Output 项 完成上面的工程配置后就可以向工程中添加文件了。选中菜单项“ViewÆProject Window”,在右边显示 树列表，一般默认都已经打开。选中“Source Group1”点击右键选中 Add files to Group ‘Source Group1’将 ROCKEY3.h 和 small_mode.LIB 添加到工程中，然后加入用户的 C51 文件。测试时可以加入我们提供的 C51 示例。加入方法见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 16 ROCKEY3 用户手册 图 4.1.2­3 加入 C51 文件 4.1.3 调试 完成上述过程，程序进入调试状态。菜单项“ViewÆProject Window”窗口中显示的是 C51 的寄存器。 关于 Keil uVision2 的使用和调试，请参考其自身帮助说明。 4.1.4 退出 为了让 C51 程序停止执行并结束调试，程序末尾必须调用_exit()函数（见 6.1.1 中的说明）。当然，用 户可在程序调试的任何阶段，选中“DebugÆStart/StopDebug Session”菜单项，结束调试。 C51 程序遇到_exit()时就会退出，因此可以在 C51 程序中间加上_exit()，来看中间的返回值，以便查找 问题。 4.1.5 写入C51 程序 调试好的 C51 程序可以写入到虚拟卡中或者真实卡片中。使用 ROCKEY3 虚拟文件系统管理器，可以将 已经调试好的.BIN 文件写入到虚拟卡中（参考 4.3.4 章节）。使用 ROCKEY3 加密锁设置工具，可以将已经调 试好的.BIN 文件写入到真实加密锁中（参考 4.2.5）。也可以编写程序通过调用 API 接口，将文件写入到加密 锁中（参考 7.1.16 和 7.1.17 章节）。 将 C51 程序写入到加密锁中后，可以使用 ROCKEY3 加密锁设置工具或者编写程序调用 API 接口，运行 这个可执行文件（参看 4.2.3、7.1.18） ，查看运行结果是否正确。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 17 ROCKEY3 用户手册 4.2 ROCKEY3 加密锁设置工具 ROCKEY3 加密锁设置工具的主要功能为： „ 基本功能：访问数据存储区、共享内存区；产生随机数；LED 灯控制。 „ 文件操作：创建、写入、运行文件；清空文件（删除所有文件）。 „ 加密解密：执行各种加、解密运算。 „ 密码管理：更改开发商密码，重设开发商 ID。 „ 远程升级：产生、测试远程升级文件。 „ 初始化加密锁。 在光盘 Tools 目录下，RY3Tools.exe 是 ROCKEY3 加密锁设置工具。 4.2.1 启动、登录设置工具 运行 RY3Tools.exe。进入界面如下： 图 4.2.1­1ROCKEY3 加密锁设置工具界面 此设置工具只支持一把 ROCKEY3。运行该工具前在计算机的 USB 接口上插入一把硬件。如果插上两把 以上的 ROCKEY3，则打开找到的第一把锁。 在使用工具的过程中，如果将 ROCKEY3 从机器上拔出，则返回登录界面。 输入 VendorID 和开发商密码，选择登录模式。登录模式有用户模式和开发商模式两种。用户模式登录 时，不需要输入开发商密码，但权限会受到限制，需要开发商权限的功能将不能使用。输入完成后，点击 “登录”按扭，即进入操作界面。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 18 ROCKEY3 用户手册 4.2.2 基本功能 登录加密锁后即可进入基本功能页面，或者点击界面左侧的“基本功能” 图标也可进入基本功能页面。 如下图所示： 图 4.2.2­1 基本功能界面 „ 数据存储区 直接在数据存储区的数据显示区内写入数据，点击“写入”按扭，就可以将数据写入加密锁的数 据存储区内。写入成功，提示“操作成功”。写入失败，提示“操作失败，错误编码....”。可以根据提 示中的错误编码，查看具体的错误原因，错误编码请参照 7.2.1 章节。 点击“读出”按扭，可以读出加密锁中数据存储区内的数据。读出成功，提示“操作成功”，并在 数据显示区中显示数据。 点击“导入”按扭，弹出文件选择对话框，选择数据文件后，文件中的信息即可显示在数据显示 区中，然后可以点击“写入”按扭，将文件中的数据写入加密锁的数据存储区。 点击“导出”按扭，弹出文件选择对话框，选择要保存数据的文件，则可以将数据显示区中的数 据保存到文件中。 „ 共享内存区 直接在共享内存区的数据显示区内写入数据，点击“写入”按扭，就可以将数据写入加密锁的共 享内存区内。写入成功，提示“操作成功”。写入失败，提示“操作失败，错误编码....”。可以根据提 示中的错误编码，查看具体的错误原因，错误编码请参照 7.2.1 章节。 点击“读出”按扭，可以读出加密锁中共享内存内的数据。读出成功，提示“操作成功” ，并在数 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 19 ROCKEY3 用户手册 据显示区中显示数据。 „ LED 控制 选择亮、灭、闪可以控制 ROCKEY3 加密锁的灯。 „ 产生随机数 输入需要随机数的长度，点击“产生”按扭，产生的随机数显示在随机显示区。点击“导出”按 扭，可以选择文件保存随机数。 4.2.3 文件操作 点击 ROCKEY3 加密锁工具界面左侧的“文件操作” 图标可以进入文件操作页面。如下图所示： 图 4.2.3­1 文件操作界面 „ 写入文件 选择好操作动作、文件路径、文件类型，输入文件长度、文件 ID,点击“写入”按扭，可以在加密 锁中写入文件。写入成功，提示“操作成功”。写入失败，提示“操作失败，错误编码....”。可以根据 提示中的错误编码，查看具体的错误原因，错误编码请参照 7.2.1 章节。 操作动作：创建并写入文件数据、创建一个空文件、 从虚拟文件系统导入（虚拟文件可以用 VfsSet.exe 工具生成）。 文件类型：可执行文件、数据文件、公钥文件、私钥文件。文件类型请参照 2.7.1 章节。 „ 运行文件 只有可执行文件可以运行。先输入数据的长度，然后光标移至数据显示区，输入数据，见图 4.2.3‐2 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 20 ROCKEY3 用户手册 所示。也可以点击“导入”按扭，从文件中导入数据。输入可执行文件的文件 ID，然后点击“运行” 按扭，就可以运行可执行文件了。运行成功，提示“操作成功”，并在输出数据区显示输出的结果。运 行失败提示“操作失败，错误编码....”。可以根据提示中的错误编码，查看具体的错误原因，错误编码 请参照 7.2.1 章节。 图 4.2.3­2 运行文件 „ 清空文件 删除加密锁内的所有文件。点击“清空”按扭，即可删除加密锁内的所有文件。成功，提示“操 作成功”。失败，提示“操作失败，错误编码....”。可以根据提示中的错误编码，查看具体的错误原因， 错误编码请参照 7.2.1 章节。空闲空间大小，显示当前加密锁的剩余空间。 4.2.4 加密解密 设置工具可以导入 RSA、3DES 密钥对，生成 RSA 密钥对，并将密钥导出备份。加密锁内可以保存 8 组 密钥对和远程升级专用密钥。如果您在加密过程中使用到 RSA 功能，就需要先产生 RSA 密钥对。可以使用 C51 程序产生 RSA 密钥对，但这样产生的密钥对中的私钥无法导出，那么每把 ROCKEY3 中的私钥都不一样。 如果您需要密钥对相同的 ROCKEY3 硬件，这时就需要使用设置工具或者 API 接口（见 7.1.20 中的说明）来 产生 RSA 密钥对，并将密钥对导出备份，然后通过本工具下文件操作的功能，虚拟文件管理器或者 API 接口 将密钥对导入到其他的 ROCKEY3 中。用鼠标左键单击左边的“加密解密”图标，显示的界面如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 21 ROCKEY3 用户手册 图 4.2.4­1 加密解密界面 „ 密钥的产生与导入 选择动作，密钥编号，点击 按扭，选择要导入或者备份的文件，然后点击“执行”按扭。执 行成功，提示“操作成功”。失败，提示“操作失败，错误编码....”。可以根据提示中的错误编码，查 看具体的错误原因，错误编码请参照 7.2.1 章节。 „ 加解密运算 输入数据长度，直接在显示区中输入要加密的数据，或者点击“标准填充”，设置工具自动填写数 据，也可以点击“导入”按扭选择文件，将文件中的数据导入到显示区内。然后选择算法，密钥编号， 点击“执行”按扭，即可完成加解密运算。运算成功，提示“操作成功”。失败，提示“操作失败，错 误编码....”。可以根据提示中的错误编码，查看具体的错误原因，错误编码请参照 7.2.1 章节。 4.2.5 密码管理 使用鼠标左键单击左边的“密码管理”图标，显示的界面如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 22 ROCKEY3 用户手册 图 4.2.5­1 密码管理界面 „ 更改开发商密码 输入开发商旧密码、新密码、重试次数，点击“更改”按扭，即可更改开发商密码。更改成功， 提示“操作成功”。失败，提示“操作失败，错误编码....”。可以根据提示中的错误编码，查看具体的 错误原因，错误编码请参照 7.2.1 章节。 „ 重设开发商 ID 输入产生 VendorID 的种子，点击“重设”按扭，就可以重新设置 VendorID, 重设成功，提示“操 作成功”。失败，提示“操作失败，错误编码....”。可以根据提示中的错误编码，查看具体的错误原因， 错误编码请参照 7.2.1 章节。 4.2.6 远程升级 远程升级的详细过程请参见 3.2.7 章节，这里介绍一下利用 ROCKEY3 加密锁设置工具实现远程升级。 使用鼠标左键单击左边的“远程升级”图标，显示的界面如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 23 ROCKEY3 用户手册 图 4.2.6­1 远程升级界面 „ 产生升级文件 点击“添加”按扭，增加升级数据。如下图所示： 图 4.2.6­2 添加数据界面 选择数据类型，输入数据，也可以点击“导入”按扭，从文件中导入数据。输入完成后，点击“确 定”按扭，返回远程升级界面。 选中图 4.2.6‐1 数据列表中的数据条目，可以点击“编辑”、“删除”按扭对选中的数据条目进行编 辑、删除操作。 点击 按扭，选择升级公钥文件。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 24 ROCKEY3 用户手册 如果选中绑定加密锁硬件 ID，输入硬件序列号，则可以将升级包与某一特定的硬件绑定。 点击“产生升级包”按扭，输入文件名称，即可产生升级包了。成功，弹出对话框提示“升级包 已成功产生” 。失败弹出对话框提示错误信息。 „ 升级测试 点击 按扭，选择远程升级包，然后点击“升级测试”，可以测试升级包。成功，提示“操作成 功”。失败，提示“操作失败，错误编码....”。可以根据提示中的错误编码，查看具体的错误原因，错 误编码请参照 7.2.1 章节。 升级时会调用锁内的私钥解密升级包，所以升级前必须将远程升级用的私钥导入锁中，详细请参 考 4.2.4 章节中密钥的产生与导入部分。但是注意，远程升级用的公钥最好不要写入锁中。 4.2.7 初始化 开发商可以将要所需的设置批量写入为最终用户做的锁中。 启动设置工具后，使用鼠标左键单击左边的“初始化加密锁”图标，显示的界面如下图所示： 图 4.2.7­1 格式化界面 “加密锁设置”框中列出了初始化加密锁时可以设置的内容。 （1） “开发商密码与 VendorID 的种子码” 双击“加密锁设置”框中的第一条“1 开发商密码与 VendorID 的种子码”，则进入开发商密码与 VendorID 的设置界面。如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 25 ROCKEY3 用户手册 图 4.2.7­2 设置开发商密码与 VendorID 输入图中各项内容，其中 VendorID 默认为 00000000,开发商密码默认为 123456781234567812345678。 输入完成后，点击“确定”按扭，返回初始化界面。设置工具会根据当前 VendorID 查找加密锁，如果没有 找到，会提示“等待插入加密锁..”。并且根据当前开发商口令 （“123456781234567812345678”）进行验证， 如果失败，会提示“校验开发商密码失败”。需要注意：开发商口令默认没有重试次数限制，如果您设置了 重试次数，请输入正确的开发商口令，否则连续输入错误口令的次数超过重试次数，开发商口令将被锁死， 这时只能将锁退回给我公司，重新生产，参见 2.2 节的说明。 （2）“数据存储区” 双击“加密锁设置”框中的第二条“2 数据存储区”，则进入数据存储区设置界面。如下图所示： 图 4.2.7­3 设置数据存储区 我们可以直接在对话框中的十六进制显示区中更改，也可以在右边的 ASCII 字符显示区中更改文件中的 内容，如上图的红圈处。然后点击“确定”按扭。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 26 ROCKEY3 用户手册 （3）“远程升级用 RSA 公私钥对” 双击图 5.1.2‐1 中“3 远程升级用 RSA 公私钥对”，则进入远程升级用 RSA 公私钥对设置界面，如下图所 示： 图 4.2.7­4 设置远程升级用 RSA 公私钥对 选择“数据类型”，在数据显示区直接修改数据，或者点击“导入”按扭，从磁盘中选择文件，将文件 中的数据导入数据区。如下图所示： 图 4.2.7­5 选择公钥文件 （4）“1 号 RSA 公私钥对” 双击图 5.1.2‐1 中“4 1 号 RSA 公私钥对”，则进入 1 号 RSA 公私钥对设置界面，如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 27 ROCKEY3 用户手册 图 4.2.7­6 设置 1 号 RSA 公私钥对 选择“数据类型”，在数据显示区直接修改数据，或者点击“导入”按扭，从磁盘中选择文件，将 文件中的数据导入数据区。 图 4.2.7‐1 中“加密锁设置”框中，序号 5 至序号 19 的设置过程如同以上 1 号 RSA 公私钥对的设 置方法。 （5）用户文件系统 双击图 5.2.2‐1 中“20 用户文件系统” ，则进入用户文件系统设置界面，如下图所示： 图 4.2.7­7 设置用户文件系统 点击“导入”按扭，选择虚拟文件，虚拟文件可以使用 VfsSet.exe（虚拟文件管理器）产生。然后点击 “确认”按扭。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 28 ROCKEY3 用户手册 各项设置都完成后，点击图 4.2.1‐1 中“初始化”按扭。初始化成功后提示“操作成功”。选中“自动批 量初始化”，可以按设置批量初始化 ROCKEY3 加密锁，锁上的灯闪烁时表示正在初始化，灯灭时可以换锁。 4.3 ROCKEY3 虚拟文件系统管理器 软件开发商在进行 ROCKEY3 内部程序（C51 语言）开发时，可以结合 KEIL 编译器和本章所介绍的工具 一起使用。ROCKEY3 虚拟文件系统管理器相当于一个真实加密锁的模拟环境，用户在开发时可以不需要 ROCKEY3 硬件，只需在这个工具中完成所有内部程序（C51 语言）的开发工作。本工具可以完成全部 ROCKEY3 内部系统函数（第六章）的功能。一个虚拟文件就相当于一把 ROCKEY3。 用 ROCKEY3 虚拟文件系统管理器生成虚拟文件（.vfs 文件），可以通过此虚拟文件来创建加密锁中的文 件系统。 在光盘 Tool 目录下，VfsSet.exe 是 ROCKEY3 虚拟文件系统管理器。下面我们通过一些具体的操作过程来 熟悉这个工具。 4.3.1 工具界面 ROCKEY3 虚拟文件系统管理器界面简单，包括：菜单栏，工具栏，列表栏和信息栏。如下图所示： 图 4.3.1­1ROCKEY3 虚拟文件系统管理器界面 菜单栏：包括了各种功能的菜单选项。 工具栏：与菜单栏上的提供的功能一样，用户可以方便的点击图标来完成各种操作。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 29 ROCKEY3 用户手册 列表栏：列出虚拟文件系统中的目录结构。 信息栏：列出虚拟文件系统中的文件的详细信息。 4.3.2 新建、保存和打开虚拟文件系统 （1）首先我们要新建一个新的虚拟文件，有两种方法来实现： 点击菜单栏上的“文件（F）”菜单，选择弹出的下拉菜单上的“新建（N）”选项，如下图所示： 图 4.3.2­1 新建虚拟文件 点击工具栏上的新建按钮 （位于工具栏左起第一个按钮），来新建虚拟文件。 （2）保存已经存在的虚拟文件，有两种方法实现： 点击菜单栏上的“文件（F）”菜单，选择弹出的下拉菜单上的“保存（S）”选项，如下图所示： 图 4.3.2­2 保存虚拟文件 选择“保存（S）”选项后会弹出保存文件的对话框，选择路径后，将虚拟文件保存在硬盘上。见下图 所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 30 ROCKEY3 用户手册 图 4.3.2­3 保存文件对话框 点击工具栏上的保存按钮 （位于工具栏左起第三个按钮），来保存虚拟文件。点击完后会弹出如图 4.3.2‐3 所示的保存文件对话框，选择路径后，将虚拟文件保存在硬盘上。 （3）打开已经存在的虚拟文件，有两种方法实现： 点击菜单栏上的“文件（F）”菜单，选择弹出的下拉菜单上的“打开（O）”选项，如下图所示： 图 4.3.2­4 打开虚拟文件 选择“打开（O）”选项后会弹出打开文件的对话框，选择路径后，打开已经存储在磁盘上的虚拟文件， 如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 31 ROCKEY3 用户手册 图 4.3.2­5 打开文件对话框 点击工具栏上的打开按钮 （位于工具栏左起第二个按钮），打开已经存在的虚拟文件。点击完后会 弹出如图 4.3.2‐5 所示的打开文件对话框，选择路径后，打开已经存储在磁盘上的虚拟文件。 4.3.3 创建文件 创建文件有两种方法实现： （1）点击菜单栏上的“编辑（E）”菜单，选择弹出的下拉菜单上的“新建文件（N）”选项，如下图所 示： 图 4.3.3­1 创建文件 选择“新建文件（N）”选项后，弹出创建文件对话框，见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 32 ROCKEY3 用户手册 图 4.3.3­2 创建文件对话框 创建文件时需要填写文件 ID，文件大小和文件类型。需要注意：文件 ID 为 2 个字节，以十六进制数表 示的范围：0x0001‐0xFFFF，文件大小不能超过 ROCKEY3 加密锁的剩余空间。创建文件后，可以在信息栏 中看到多了一个 ID 为“1002”的内部数据文件。见下图所示： 图 4.3.3­3 创建文件完成 （2）在信息栏单击鼠标右键，在弹出的上下文菜单上选择“新建文件”选项，来创建新的文件。如下 图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 33 ROCKEY3 用户手册 图 4.3.3­4 上下文菜单创建文件 4.3.4 导入文件 除了在虚拟文件系统中创建文件外，我们还可以将存在磁盘上的文件导入到虚拟环境中来。有两种方 法实现： （1） 点击工具栏上的导入文件的按钮 （位于工具栏右起第四个按钮），来导入文件。说明中 是将经过 KEIL 编译器编译好的 C51 程序，即将编译好的二进制文件（.bin 文件）导入到虚拟 系统中。点击按钮后会弹出如图 4.3.4‐1 所示的导入文件对话框，填写完相关的信息后，按“创 建”按钮，导入文件。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 34 ROCKEY3 用户手册 图 4.3.4­1 导入文件 “源文件（磁盘）”框中的 按钮用于浏览磁盘上已经存在的文件。 “目的文件（虚拟文件系统）”框 中的文件大小会自动填入要导入文件的大小。 当导入文件大小手工输入时。如果输入值大于磁盘上文件的实际大小，则导入后，多余的填充“0”； 如果反之，则截取输入的长度进行导入。 （2）在信息栏单击鼠标右键，在弹出的上下文菜单上选择“导入文件”选项，来导入新的文件。如下 图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 35 ROCKEY3 用户手册 图 4.3.4­2 上下文菜单导入文件 4.3.5 打开文件 打开文件，有两种方法实现： （1）双击信息栏中列出的文件，就可以打开相应的文件。如下图所示： 图 4.3.5­1 双击打开文件 打开文件，会弹出编辑文件的对话框，见下面的编辑文件的说明。 （2）在信息栏中将鼠标移到文件上，单击鼠标右键，在弹出的上下文菜单上选择“打开”选项，来打 开文件。见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 36 ROCKEY3 用户手册 图 4.3.5­2 上下文菜单打开文件 4.3.6 编辑文件 在虚拟文件系统中可以对所有文件进行编辑操作，考虑到开发时的方便，在操作时不需要验证开发商 口令和用户口令。编辑文件，有三种方法实现： （1）在信息栏中选择文件后（鼠标左键单击），点击菜单栏上的“编辑（E）”菜单，选择弹出的下拉 菜单上的“编辑文件（E）”选项，如下图所示： 图 4.3.6­1 编辑文件 选择“编辑文件（E）”选项后，弹出编辑文件对话框，见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 37 ROCKEY3 用户手册 图 4.3.6­2 编辑文件对话框 我们可以直接在对话框中的十六进制显示区中更改，也可以在右边的 ASCII 字符显示区中更改文件中的 内容，如上图的红圈处。 “导入“按钮可以将存在磁盘上文件导入到正在编辑的文件中。需要注意：如果导入的文件大小不足 所要编辑的文件，那么导入进来后，后面的部分保持原来的内容。如果导入的文件大小超过所要编辑的文 件，则将会把导入的文件进行截取。总之，正在编辑的文件的大小是不会变的。 “导出”按钮可以将正在编辑的文件导出到磁盘上。 （2）选择文件后，点击工具栏上的编辑文件的按钮 （位于工具栏右起第五个按钮），来编辑文件。 （3）在信息栏中将鼠标移到文件上，单击鼠标右键，在弹出的上下文菜单上选择“编辑文件”选项， 来编辑文件。见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 38 ROCKEY3 用户手册 图 4.3.6­3 上下文菜单编辑文件 4.3.7 导出文件 可以将虚拟文件系统中的文件导出到磁盘中，有三种方法实现： （1）在信息栏中将鼠标移到文件上，单击鼠标右键，在弹出的上下文菜单上选择“导出到磁盘”选项， 来导出文件。见下图所示： 图 4.3.7­1 上下文菜单导出文件 （2）点击工具栏上的导出文件的按钮 （位于工具栏右起第三个按钮），来导出文件。 （3）使用编辑文件对话框来导出文件。见 5.3.6 中的说明，弹出编辑文件对话框中后，点击“导出” 按钮，来导出文件。见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 39 ROCKEY3 用户手册 图 4.3.7­2 导出文件 4.3.8 删除文件 我们可以删除在虚拟文件系统中的文件。与我们在 Windows 操作系统上的操作一致。可以通过三种办 法来完成这项操作。 （1）使用菜单栏进行操作。先在信息栏中选择要删除的文件后（鼠标左键单击），点击菜单栏上的“编 辑（E）”菜单，选择弹出的下拉菜单上的 “删除（D）”选项，如下图所示： 图 4.3.8­1 菜单栏操作 （2）使用工具栏进行删除。先在信息栏中选择要删除的文件后（鼠标左键单击），点击工具栏上的删 除按钮 （位于工具栏左起第五个按钮）。 （3）使用信息栏中的上下文菜单进行删除。先在信息栏中选择要删除的文件后，单击鼠标右键，在弹 出的上下文菜单上选择“删除”选项。见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 40 ROCKEY3 用户手册 图 4.3.8­2 上下文菜单操作 4.3.9 附属功能 （1）打开最近打开过的虚拟文件系统。点击菜单栏上的“文件（F）”菜单，在弹出的下拉菜单上有最 近曾经打开的虚拟文件系统，鼠标单击要打开的虚拟文件，就可以方便的打开，不需要再通过文件选择框 浏览磁盘上的文件。如下图所示： 图 4.3.9­1 打开最近的文件 （2）隐藏列表栏。通过工具栏上的隐藏列表栏按钮 （位于工具栏左起第四个按钮） ，来隐藏列表 栏。 （3）视图菜单。可以隐藏工具栏，状态栏和设备目录树（列表栏）。见下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 41 ROCKEY3 用户手册 图 4.3.9­2 视图菜单 （4）刷新功能。当虚拟文件系统中的目录或者文件发生改变时，有时需要刷新一下，以便能够显示最 新的状态。使用工具栏上的刷新按钮 （位于工具栏右起第二个按钮），刷新当前状态。或者使用信息栏 中上下文菜单上的刷新功能，见下图所示： 图 4.3.9­3 上下文菜单刷新 4.3.10 菜单栏和工具栏 新建 打开 新建虚拟文件 打开已经存在的虚拟文件 保存 将虚拟文件保存到磁盘 另存为 将虚拟文件保存到磁盘 退出 退出虚拟文件系统管理工具 表 4­1 文件菜单 删除 文件删除操作 新建文件 创建文件 编辑文件 编辑文件 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 42 ROCKEY3 用户手册 导入文件 将磁盘上的文件导入到虚拟环境中 导出到磁盘 将文件导到到磁盘中 表 4­2 编辑菜单 工具栏 状态栏 隐藏/显示工具栏 隐藏/显示状态栏 设备目录树 隐藏/显示列表栏 表 4­3 视图菜单 新建虚拟文件系统 打开虚拟文件系统 保存虚拟文件系统 隐藏/显示列表栏（设备目录树） 文件删除操作 编辑文件 导入文件 导出文件 刷新 关于信息 表 4­4 工具栏 4.4 ROCKEY3 加密锁标准外壳加密工具 ROCKEY3 加密锁的外壳加密是保护您的软件最快捷的方法， 执行外壳加密这种加密方案使用非常简单， 对于没有源代码或没有很多时间编写加密代码的开发者是极为方便的。考虑到软件的发展趋势，我们的外 壳加密工具目前仅对 Win32 位应用程序有效。目前支持的文件格式有 Win32 PE 格式文件，如：EXE、DLL， ARX 等。此工具不支持 win98 系统。 在光盘 EncryptTool\PE32 目录下，Rockey3Env.exe 是 ROCKEY3 标准外壳加密工具。该工具运行时需要 RyXShell_Rockey3.dll 文件。开发商使用该工具对应用软件进行外壳加密，建议和 API 接口调用结合使用，增 加软件的加密强度。运行 Rockey3Env.exe，即可进入标准外壳加密工具的主界面，如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 43 ROCKEY3 用户手册 图 4.3.10­1 标准外壳加密工具 点击 按钮，弹出选择文件对话框，选择要加密的程序。如下图所示： 图 4.3.10­2 选择要加密的文件 待加密的文件路径和加密后的文件路径都会显示在界面上，如下图： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 44 ROCKEY3 用户手册 图 4.3.10­3 选择要加密的文件完成 输入无锁时的提示信息，按需求选择加密选项： „ 后台定时检测 选择此项后，应用程序在运行时，将按设置检测 ROCKEY3 是否存在，防止加密锁被拔出后程序还 能运行。在“时间间隔”的输入框中填写检查 ROCKEY3 的间隔时间（建议大于等于 120 秒）。 „ 检测方式 定时器方式没有启用线程，是在应用程序的进程中检查硬件。多线程方式是启用线程来检查硬件。 有窗口的应用程序可以使用上述二种方式，没有窗口的应用程序只能使用多线程方式。考虑到应用程 序运行的效率和稳定性，建议使用“多线程方式”检测 ROCKEY3。 „ 绑定硬件序列号 如果选择了“绑定硬件序列号”选项，由于每把 ROCKEY3 的硬件序列号是唯一的，这时加密后的 程序只能被进行外壳加密时的那把 ROCKEY3 打开。 „ 加密锁开发商 ID 必须输入加密锁开发商 ID，出厂时开发商 ID 设置为“00000000”，为了保证安全性，加密前请先 重新设置开发商 ID，详见 4.2.5 章节。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 45 ROCKEY3 用户手册 点击 按扭，开始执行加密操作。成功，提示加密成功。不成功，提示错误信息。 在使用外壳工具加密后如出现错误，请按照下面的步骤检查： （1）请检查客户号输入的是否正确。 （2）有可能所加密的文件格式不支持，这时请使用系统中自带的 NOTEPAD.EXE 进行测试，该文件一般 位于 C:\WINDOWS\NOTEPAD.EXE。 4.5 ROCKEY3 加密锁DotNet外壳加密工具 ROCKEY3 加密锁 DotNet 外壳加密工具是专门为 VB.Net,VC#.Net 软件开发商准备的外壳加密工具。这使 VB.Net 和 VC#.Net 应用程序的加密变的简单、快捷。此工具不支持 win98 系统。 在光盘 EncryptTool\DotNet 目录下，Rockey3_NetShell.exe 是 DotNet 外壳加密工具。开发商使用该工具 对 DotNet 应用软件进行外壳加密，建议和 API 接口调用结合使用，增加软件的加密强度。 要使用 DotNet 外壳加密工具，系统中必须安装 Framework,否则在运行 DotNet 外壳加密工具时，会提 示请安装 Framework,如下图所示： 图 4.3.10­1 提示信息 运行 Rockey3_NetShell.exe，即可进入 DotNet 外壳加密工具的主界面，如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 46 ROCKEY3 用户手册 图 4.3.10­2DotNet 外壳加密工具 „ 输入加密锁开发商 ID 出厂时开发商 ID 设置为“00000000” ，为了保证安全性，加密前请先重新设置开发商 ID，详见 4.2.5 章节。 „ 点击 选择要加密的程序 按扭，弹出选择文件对话框，选择要加密的文件。如下图所示： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 47 ROCKEY3 用户手册 图 4.3.10­3 选择要加密的程序 选中文件后，在界面左侧的列表框中会列出程序中的所有类及函数。如下图所示： 图 4.3.10­4 选择函数和类 根据需要选择要加密的函数。 „ 设置加密选项 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 48 ROCKEY3 用户手册 点击 按扭，进入设置加密选项界面，如下图所示： 图 4.3.10­5 加密选项 根据需求设置加密选项，点击 按扭，可以设置加密前、后程序的路径，生成的运行时所需的库文 件的路径。 选择后台定时检测项，应用程序在运行时，将按设置检测 ROCKEY3 是否存在，防止加密锁被拔出后程 序还能运行。在“时间间隔”的输入框中填写检查 ROCKEY3 的间隔时间（建议大于等于 120 秒） 。 选择同名时备份原文件，可以在设置加密前后的文件名相同的情况下，备份原文件。 点击 按扭，进入提示信息的设置界面，可以设置找不到锁和程序终止时的提示。按图 中提示输入自己需要的信息，即可。如下图所示： 图 4.3.10­6 设置错误提示 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 49 ROCKEY3 用户手册 点击图 4.3.10‐2 中的 按扭，可以继续添加要加密的程序，程序列表中会列出所有需要 加密的程序，函数列表中会列出所有函数。选中列表中的某一程序，就可以按以上所述步骤进行加密设置。 点击图 4.3.10‐2 中的 按扭，可以加密列表中选中的函数。点击 按扭，则 加密列表中所有程序。 加密成功，弹出对话框提示“加密成功”。否则弹出对话框提示错误信息。 如果程序中的类、函数比较多，建议不要选择全部类和函数，有可能会影响运行的速度。在使用 DotNet 外壳工具加密后如出现错误，请按照下面的步骤检查： （1）请检查客户号输入的是否正确。 （2）确认加密的程序是否是 VB.Net 或 VC#.Net 程序。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 50 ROCKEY3 用户手册 第5章 ROCKEY3 高级应用 上几章讲述了一些加密手段和使用 ROCKEY3 的特点来对软件进行加密的方案，以及如何使用 ROCKEY3 的设置工具。本章通过一个简单的示例程序，进一步的阐明 ROCKEY3 的高级应用，对软件进行保护。示例 是一个身份证号由 15 位升级到 18 位的 C 语言程序。 #include #include #include #include "stdafx.h" "RY3_API.h" unsigned char Wi[18] = {7,9,10,5,8,4,2,1,6,3,7,9,10,5,8,4,2,1}; char Ai[11]={'1','0','x','9','8','7','6','5','4','3','2'}; void ConvertID(char ID[15],char newID[18]) //转换算法 { int i,j,s; s=0; memcpy(newID,ID,6); newID[6]='1'; newID[7]='9'; memcpy(newID+8,ID+6,9); for(i=0;i<17;i++) { j=(newID[i]‐48)*Wi[i]; s+=j; } s%=11; newID[17]=Ai[s]; } void main(int argc, char* argv[]) { char cOldID[16] = "110105720924001"; //15 位身份证号 char cNewID[19] = {0}; //18 位身份证号 ConvertID(cOldID, cNewID); printf("%s\n", cNewID); //进行转换 } 下面我们就把上面的 ConvertID 算法转换成 C51 语言，转换后如下面所示： #include "RY3_C51.h" #include unsigned char Wi[18] = {7,9,10,5,8,4,2,1,6,3,7,9,10,5,8,4,2,1}; char Ai[11]={'1','0','x','9','8','7','6','5','4','3','2'}; void main(void) { int i,j,s; byte ID[15], newID[18]; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 51 ROCKEY3 用户手册 s=0; if(wInLen != 15) _exit(); //判断输入的数据是否是 15 个字符 memcpy(ID, pbInBuff, 15); //将外部程序输入的数据赋给 ID 数组 memcpy(newID,ID,6); newID[6]='1'; newID[7]='9'; memcpy(newID+8,ID+6,9); for(i=0;i<17;i++) { j=(newID[i]‐48)*Wi[i]; s+=j; } s%=11; newID[17]=Ai[s]; _set_response(18, newID); // 输出新身份证号码 _exit(); //结束程序 } 在 C51 程序中有两个参数 wInLen 和 pbInBuff。wInLen 里面的存放的值是外部 PC 程序向 C51 程序输入 数据的长度，pbInBuff 里面存放输入的数据（见 6.2.1 节中的说明）。我们在 KEIL 编译器中对 C51 程序进行 编译，得到一个二进制文件（.bin），这时可以把编译好的可执行文件下载到 ROCKEY3 中，有两种方法： （1）使用 ROCKEY3 加密锁设置工具（见 4.2 节中的说明）。 （2）使用 ROCKEY3 提供的 API 接口（见 7.1.16 和 7.1.17 中的说明）。 我们将可执行文件导入到 ROCKEY3 中，文件 ID 设为 0x0001。原来的程序我们可以更改为： #include #include #include #include "stdafx.h" "RY3_API.h" void main(int argc, char* argv[]) { BYTE cOldID[16] = "110105720924001"; BYTE cNewID[20] = {0}; int newLen=19; char vendorID[10] = "A8C3E6FD"; RY_HANDLE handle; DWORD dwRet = 0; int dwCount=0; //第一次查找 ROCKEY3，得到机器上的 ROCKEY3 的个数 dwRet=RY3_Find(vendorID,&dwCount); if(dwRet != RY3_SUCCESS && dwRet) { printf("RY3_Find Error:0x%08x\n", dwRet); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 52 ROCKEY3 用户手册 return; } //打开第一把 ROCKEY3 dwRet = RY3_Open(&handle,1); if(dwRet != RY3_SUCCESS) { printf("RY3_Open Error:0x%08x\n", dwRet); return; } //运行 ROCKEY3 硬件内文件 ID 为 0x0001 的可执行文件 dwRet = RY3_ExecuteFile(handle, 0x0001, cOldID, 15, cNewID, &newLen); if(dwRet != RY3_SUCCESS) { printf("RY3_ExecuteFile Error:0x%08x\n", dwRet); return; } //关闭 ROCKEY3 RY3_Close(handle,true); //打印出结果 printf("%s\n", cNewID); } 我们看到 PC 程序中没有任何算法的痕迹，所有算法的运行都是在 ROCKEY3 内部，破解者破解 PC 程序 没有任何意义，只能跟踪到旧身份证号和新身份证号输入和输出，根本得不到运算过程，同时程序必须与 ROCKEY3 一起使用才能计算出正确的新身份证号码。由于 ROCKEY3 采用的是安全强度最高的智能卡芯片， 可执行文件的内容是任何人，包括我们都无法得到的。可以认为，只要算法够复杂并且没有外泄，使用 ROCKEY3 进行加密是无法被破解的。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 53 ROCKEY3 用户手册 第6章 ROCKEY3 内部系统函数（C51 语言） 前面已经讲述了 ROCKEY3 的产品特点，工具说明和加密过程。本章将要详细介绍 ROCKEY3 内部系统函 数的接口。运行在 ROCKEY3 内部的程序是使用 C51 语言进行开发的，C51 语言基本与 C 语言一致，可以认 为是 C 语言的一个子集，它是专门用于硬件开发的语言。很多做硬件程序的朋友对 C51 语言应该是很熟悉 的。C51 语言自带有丰富的函数库，包括字符串处理，内存处理等，在编写 ROCKEY3 的 C51 程序时都可以 方便的调用。同时我们也提供了相当多的额外接口，这些接口将在本章中进行说明，包括：输入输出、文 件操作、数学运算、密码学算法等。 在使用 C51 语言加入 ROCKEY3 的 C51 库时，有三种模式：微型模式（compact_mode.LIB），小模式 （small_mode.LIB）和大模式（large_mode.LIB）。建议使用小模式或者大模式。不建议使用微型模式，因为 其寻址范围有限，不能完成某些功能。当选用不同的库时，注意 C51 工程的设置中（见 4.1.2 节）选择对应 的选项，只更改 Memory Model 项就可以了。 内存分为：128 字节的 data 区，128 字节 idata 区和 2k＋256 字节的 xdata 区。其中 data 和 xdata 中存 放 C51 程序的变量和函数的参数等，idata 区是用来给内部寄存器传递参数使用的，所以不要将 C51 程序的 变量声明在 idata 区中。 „ 小模式（small_mode.LIB）： 默认的变量声明在 data 区中，所以在编程中声明变量时要加上 xdata， 将变量声明在 xdata 区中。一般情况下建议使用这种模式。 „ 大模式（large_mode.LIB）：默认的变量声明在 xdata 区中，当程序中的函数较多，并存在多次 调用时，建议使用这种模式。 在声明变量时要加上 xdata 标志（例如：int xdata i = 0;）。如果没有 xdata 标志，当在小模式下，声明的 变量都在 128 字节的 data 区中，存在不能分配超过 128 字节数组的情况。加上 xdata 标志后，变量是分配 在 2K 的 xdata 空间中。 当您赋值常量时，建议您放到 code 区，即加上 code 标志（例如：const int code I = 8; ）这样是占用可 执行文件的区域，而不占用内存。 通过下面的一些方法，可以增加锁内文件的运行速度： „ 将一些附加操作在 PC 中运行，如：_swap 倒序等 „ 跳转语句在 PC 中。如：swith‐case 语句（可以将不同的情况分别写成单独的 C51）等。 6.1 退出程序 6.1.1 exit void _exit() 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 54 ROCKEY3 用户手册 说明： 退出在 ROCKEY3 中运行的使用 C51 编写的程序。在 C51 程序中一旦遇到 exit()，则程序终止运行。 参数： 无 返回值： 无 6.2 输入输出 ROCKEY3 内的可执行文件（C51 语言）接收外部程序的输入数据或者向外部程序输出结果的最大长度 为 256 个字节。 6.2.1 pbInBuff和wInLen #define pbInBuff ((BYTE xdata *)INPUT_DATA_OFFSET + 2 ) #define wInLen (*(WORD xdata *)INPUT_DATA_OFFSET ) 说明： 输入数据。外部接口（即 PC 上的程序）向在 ROCKEY3 内运行的 C51 程序传入数据，C51 程序接收到数 据后在 ROCKEY3 内进行处理。 pbInBuff 是一个地址，指向输入的数据。 wInLen 是输入数据的长度。 参数： 无 返回值： 无 举例： （1）C51 程序中，在给 int，long，word，dword，float，double 等类型赋值时是反序，即高字节在前， 低字节在后。而 PC 上的程序为低字节在前，高字节在后，因此在输入时需要先做一下倒序。倒序可以在外 部的高级语言中使用函数完成，或者在 C51 语言中使用 6.2.3 节中的 swap 接口完成。示例如下：例如要向 C51 程序输入一个数字 8，外部为 C 语言。 C 语言中： ////////倒序函数//////// 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 55 ROCKEY3 用户手册 void FlipBuffer(unsigned char* pBuf, unsigned long ulLen) { unsigned char ucTemp; for(unsigned long i = 0; i < ulLen >> 1; ++i) { ucTemp = pBuf[i]; pBuf[i] = pBuf[ulLen ‐ i ‐ 1]; pBuf[ulLen ‐ i ‐ 1] = ucTemp; } } int main(int argc, char* argv[]) { short sCData = 8; //内存中为：0x08 0x00 long lCData = 8; //内存中为：0x08 0x00 0x00 0x00 float fCData = 8.0; //内存中为：0x00 0x00 0x00 0x41 double dCData = 8.0; //内存中为：0x00 0x00 0x00 0x00 0x00 0x00 0x20 0x40 BYTE pbInData[18]={0}; //输入 short，long，float 和 double，一共 18 个字节 FlipBuffer((unsigned char*)&sCData, 2); //内存中为：0x00 0x08 FlipBuffer((unsigned char*)&lCData, 4); //内存中为：0x00 0x00 0x00 0x08 FlipBuffer((unsigned char*)&fCData, 4); //内存中为：0x41 0x00 0x00 0x00 FlipBuffer((unsigned char*)&dCData, 8); //内存中为：0x40 0x20 0x00 0x00 0x00 0x00 0x00 0x00 memcpy(pbInData, &sCData, 2); memcpy(pbInData+2, &lCData, 4); memcpy(pbInData+6, &fCData, 4); memcpy(pbInData+10, &dCData, 8); //将 pbInData 输入到 ROCKEY3 中，输入 18 个字节 } C51 语言中： if(wInLen != 18) _exit(); //判断输入的数据长度是否是 10 个字节 //////C51 的 int 类型为 2 个字节，因此在 C 语言中声明为 short//////// int xdata iData; //数值 8 赋值给 iData，pbInBuff 中前 2 个字节，序号为 0，1 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 56 ROCKEY3 用户手册 memcpy(&iData, pbInBuff, 2); //////C51 的 long 类型与 C 语言一样，为 4 个字节//////// long xdata lData; //数值 8 赋值给 lData，pbInBuff 中序号为 2 到 5 的 4 个字节 memcpy(&lData, pbInBuff + 2, 4); //////C51 的 foat 类型与 C 语言一样，为 4 个字节//////// float xdata fData; //数值 8.0 赋值给 fData //pbInBuff 中序号为 6 到 9 的 4 个字节 memcpy (&fData, pbInBuff + 6, 4); //////C51 中 Double 类型为 8 字节数组//////// DOUBLE xdata dData; //数值 8.0 赋值给 dData //pbInBuff 中序号为 10 到 17 的 8 个字节 memcpy (&dData, pbInBuff + 10, 8); （2）赋值给字符串类型时不需要倒序。 C 语言中： int main(int argc, char* argv[]) { //包括字符串结尾 0x48 0x45 0x4C 0x4C 0x4F 0x00 char cBuffer[6] = “HELLO”; } C51 语言中： char xdata buffer[250]; memcpy(buffer, pbInBuff, 6); //将 6 个字节（“HELLO”，0x48 0x45 0x4C 0x4C 0x4F 0x00）赋值给 buffer （3）给多个变量赋值时，例如：将 long，char 数组和 double 传给 C51 程序。 C 语言中： int main(int argc, char* argv[]) { BYTE pbInData[18] = {0}; long lCData = 8; FlipBuffer((unsigned char*)&lCData, 4); char cBuffer[6] = “HELLO”; double dCData = 8.0; FlipBuffer((unsigned char*)&dCData, 8); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 57 ROCKEY3 用户手册 memcpy(pbInData, &lCData, 4); memcpy(pbInData+4, cBuffer, 6); memcpy(pbInData+10, &dCData, 8); //将 pbInData 输入到 ROCKEY3 中，输入 18 个字节 } C51 语言中： long xdata lData; char xdata buffer[250]; double xdata dData; if(wInLen != 18) _exit(); //判断输入的数据长度是否是 18 个字节 memcpy(&lData, pbInBuff, 4); //数值 8（0x00 0x00 0x00 0x08）赋值给 lData，long 为 4 个字节， //pbInBuff 中序号为 0 到 3 的 4 个字节 memcpy(buffer, pbInBuff + 4, 6); //“HELLO”（0x48 0x45 0x4C 0x4C 0x4F 0x00）赋给 buffer， //pbInBuff 中序号为 4 到 9 的 6 个字节 memcpy(&dData, pbInBuff + 10, 8); //8.0（0x40 0x20 0x00 0x00 0x00 0x00 0x00 0x00）赋值给 dData， //pbInBuff 中序号为 10 到 17 的 8 个字节 6.2.2 set_response BYTE _set_response(WORD wLen, void *pvData) 说明： 输出数据。C51 程序在 ROCKEY3 内运行完成后，调用这个函数将结果返回给外部程序（即高级语言的 程序）。注意：输出数据的最大长度为 256 字节。 参数： wLen *pvdata [in]输出数据的长度。 [in]输出数据的所在的地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： （1）当输出数据为 int，long，word，dword，float，double 等时，由于 C51 程序与外部的程序有一个 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 58 ROCKEY3 用户手册 顺序颠倒的问题，因此需要将输出倒序后，再继续进行后面的处理。倒序可以在外部的高级语言中使用函 数完成，或者在 C51 语言中使用 6.2.3 节中的 swap 接口完成。 C51 语言中： int xdata a; a = 1+2; _set_response(2,&a); //内存中为：0x00 0x03 C 语言中： ////////倒序函数//////// void FlipBuffer(unsigned char* pBuf, unsigned long ulLen) { unsigned char ucTemp; for(unsigned long i = 0; i < ulLen >> 1; ++i) { ucTemp = pBuf[i]; pBuf[i] = pBuf[ulLen ‐ i ‐ 1]; pBuf[ulLen ‐ i ‐ 1] = ucTemp; } } int main(int argc, char* argv[]) { int i = 0; …… //ROCKEY3 中运行结果传出给 i，这时 i 的内存为：0x00 0x03 FlipBuffer((unsigned char*)&i, 2); //倒序后为：0x03 0x00 printf(“%d\n”,i); //这时打印的结果是正确的，为 3。 } （2）输出字符串时不需要倒序。 C51 语言中： char xdata buffer[] = “HELLO”; _set_response(6, buffer); //将“HELLO”传出 C 语言中： int main(int argc, char* argv[]) { char cBuffer[1024]; …… //ROCKEY3 中运行结果传出给 cBuffer， //这时 cBuffer 内存为：0x48 0x45 0x4C 0x4C 0x4F 0x00 printf(“%s\n”, cBuffer); //这时打印的结果是“HELLO”。 } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 59 ROCKEY3 用户手册 6.2.3 swap void _swap(void* pvData,unsigned short wLen) 说明： 颠倒数据的顺序。在导入 int，long，word，dword，float，double 等数据时需要颠倒。建议：颠倒数据 顺序的工作最好不要在 C51 中实现，而是在外部高级语言中实现。这样可以提高锁内文件的运行速度。 参数： *pvData wLen [in]要颠倒顺序的数据的存放地址。 [in]数据的长度。 返回值： 无 举例： char xdata buffer[] = “HELLO”; _swap(buffer, 5); //颠倒后的 buffer 为：“OLLEH” 6.3 文件操作 6.3.1 create BYTE _create( WORD wFileID, WORD wSize, BYTE bFileType, BYTE bFlag, HANDLE *pHandle) 说明： 创建文件。用户可以在 ROCKEY3 中创建数据文件，可执行文件和密钥文件。 参数： wFileID [in]文件的标识符，即文件的 ID，2 个字节。 wSize [in]文件的大小，2 个字节。 bFileType [in]文件类型字节，1 个字节，参看表 6‐1。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 60 ROCKEY3 用户手册 [in]文件标志字节，1 个字节，参看表 6‐2。 bFlag *pHandle [out]返回的文件句柄。如果文件已打开，则返回文件的句柄。 名称 值 含义 FILE_TYPE_EXE 0x00 可执行文件（可写） FILE_TYPE_DATA 0x01 内部数据文件（可读写） FILE_TYPE_RSA_PUB 0x02 RSA 公钥文件（可读写） FILE_TYPE_RSA_SEC 0x03 表 6­1 文件类型 RSA 私钥文件（可写） 关于文件类型见 2.3.2 中的说明。在 C51 程序（即 ROCKEY3 内部的可执行文件）中，对这些文件的读写 属性说明如下： 可执行文件：可以被其他可执行文件改写，任何情况下都不能读取。 内部数据文件：可以被可执行文件读写。 RSA 公钥文件：可以被可执行文件读写。 RSA 私钥文件：可以被可执行文件改写，任何情况下都不能读取。 CREATE_OPEN_ALWAYS CREATE_FILE_NEW CREATE_OPEN_EXISTING 0x00 如果文件已存在，打开该文件；反之则创建新 文件并打开 创建并打开新文件，如果文件已经存在则返回 0x01 错误 打开已存在文件，功能同_open()函数 0x02 表 6­2 文件标志 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： HANDLE xdata hFile = 0; BYTE xdata bRes = 0; //创建一个大小为 16（0x10）个字节，文件 ID 为 0x1008 的数据文件 bRes=_create(0x1008,0x10,FILE_TYPE_DATA,CREATE_OPEN_ALWAYS,&hFile); if(bRes != 0) { _set_response(1,&bRes); _exit(); } 6.3.2 open BYTE _open(WORD wFileID, HANDLE *pHandle) 说明： 打开文件。打开 ROCKEY3 中的文件， „ 当打开，数据文件，公钥文件时，可对这些文件进行读写， 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 61 ROCKEY3 用户手册 „ 当打开，私钥文件，可执行文件时，只能改写，不能读取。 参数： wFileID *pHandle [in]文件 ID，2 个字节。 [out]返回的文件句柄。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： word xdata wFid = 0x1008; HANDLE xdata hFile = 0; BYTE xdata bRes = 0; bRes = _open(wFid, &hFile); //打开一个文件 ID 为 0x1008 的文件 if(bRes != 0) { _set_response(1,&bRes); _exit(); } 6.3.3 close BYTE _close(HANDLE handle) 说明： 关闭文件。对文件操作完成后，请调用该函数关闭文件。调用该函数前必须先要打开文件（open）。 参数： handle [in]文件句柄。使用 open 函数时得到的句柄。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： word xdata wFid = 0x1008; HANDLE xdata hFile = 0; _open(wFid, &hFile); //打开一个文件 ID 为 0x1008 的文件 …… _close(hFile); //关闭文件 ID 为 0x1008 的文件 6.3.4 read BYTE _read(HANDLE handle, WORD wOffset, BYTE bLen, void *pvData) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 62 ROCKEY3 用户手册 说明： 读取文件。该函数只能使用在：数据文件和公钥文件。该函数不能使用在可执行文件上，可执行文件 的内容是不能被读出的。调用该函数前必须先要打开文件（open）。 参数： handle [in]文件句柄。使用 open 函数时得到的句柄。 wOffset [in]偏移值。即从文件的第几个字节开始读取数据。 bLen [in]读取数据的长度。 *pvData [out]从文件中读出数据所要放入的地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： word xdata wFid = 0x1008; HANDLE xdata hFile = 0; char xdata buffer[250]; BYTE xdata bRes = 0; bRes = _open(wFid, &hFile); //打开一个文件 ID 为 0x1008 的文件 if(bRes != 0) { _set_response(1,&bRes); _exit(); } bRes = _read(hFile, 0, 10, buffer); //从文件 ID 为 0x1008 的文件中，第 0 个字节开始读取 10 个字节到 buffer 中 if(bRes != 0) { _set_response(1,&bRes); _exit(); } _close(hFile); //关闭文件 ID 为 0x1008 的文件 6.3.5 write BYTE _write(HANDLE handle, WORD wOffset, BYTE bLen,const void *pvData) 说明： 写入文件。将数据写入到文件中。该函数使用在：数据文件，公钥文件和可执行文件。调用该函数前 必须先要打开文件（open）。 参数： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 63 ROCKEY3 用户手册 handle [in]文件句柄。使用 open 函数时得到的句柄。 wOffset [in]偏移值。即从文件的第几个字节开始写入数据。 bLen [in]写入数据的长度。 *pvData [in]存放要写入数据的地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： word xdata wFid = 0x1008; HANDLE xdata hFile = 0; char xdata buffer[] = “HELLO”; BYTE xdata bRes = 0; bRes = _open(wFid, &hFile); //打开一个文件 ID 为 0x1008 的文件 if(bRes != 0) { _set_response(1,&bRes); _exit(); } bRes = _write(hFile, 0, sizeof(buffer), buffer); //将“HELLO”写入到 ID 为 0x1008 的文件中，从该文件的第 0 字节开始写入 if(bRes != 0) { _set_response(1,&bRes); _exit(); } _close(hFile); //关闭文件 ID 为 0x1008 的文件 6.3.6 get_file_infor BYTE _get_file_infor(PEFINFO pFileInfo) 说明： 获取文件的属性信息。 参数： pFileInfo [out]文件信息结构的指针，包括：文件 ID，文件类型和文件大小。 EFINFO 文件信息结构定义如下： typedef struct _FILE_INFO { WORD wFileID; //文件 ID 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 64 ROCKEY3 用户手册 BYTE bFileType; WORD //文件类型，见前面的表 6‐1 wFileSize; //文件大小 } EFINFO,*PEFINFO; 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： EFINFO xdata fInfo; BYTE xdata bRes = 0; fInfo.wFileID = 0x1008; bRes = _get_file_infor(&fInfo); //取得 ID 为 0x1008 文件的信息 if(bRes != 0) { _set_response(1,&bRes); _exit(); } 6.4 密码学算法 本节涉及到很多密码学中的概念，在这里做一个简单的介绍 „ 对称加解密算法 对称加解密算法的密钥是相同的，即加密和解密使用的密钥是同一个。密钥的长度也是固定的， 如 DES：8 个字节，3DES：16 个字节。加密的数据的长度也要是固定的，一般为 8 的倍数。目前流行的 对称加解密算法有 DES，3DES 等。 „ ECB 和 CBC ECB 和 CBC 是加解密中常用的两种模式。在对称加解密中，数据是按块来进行的，DES 和 3DES 都 是 8 个字节为一块。ECB 模式下，块与块之间没有关系，是各自独立的。CBC 模式下，块与块之间是有 关系的，前块的加密结果与后块做异或，然后再进行加密，以此类推。 „ 补齐方式 在对称加解密时，数据是分块进行的，DES 和 3DES 都是 8 个字节为一块。这时如果加密的数据不 是 8 的倍数，就需要进行补齐。补齐的规则可以由开发商自己来设定。常见的方式为，少几个字节就 补上该数字。如：原数据为 0x11 0x22 0x33 三个字节，这时缺少 5 个字节，那么后面都补数字 5，即： 0x11 0x22 0x33 0x05 0x05 0x05 0x05 0x05，这时解密后读取最后一个字节，然后去掉相应的 5 个字节， 即得到原文。如果原文正好是 8 的倍数，那么就多补 8 个字节，都赋值为 0x08，这样解密后，最后一 个字节是 0x08，去掉 8 个字节后就是原文。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 65 ROCKEY3 用户手册 „ 散列算法 散列算法是根据不同的输入，产生与之对应的固定长度的输出。目前流行的散列算法有 SHA1，MD5 等。SHA1 的散列结果长度为 20 字节，MD5 的散列结果长度为 16 字节。 „ 非对称加解密算法 非对称加解密的加密密钥和解密密钥是不同的，分为公钥和私钥。公钥是公开的密钥，可以散发 给其他人；私钥是秘密的，需要拥有者本人自己掌握，不能透露给任何人。公钥和私钥是匹配的，通 常称为公私钥对。一般使用公钥进行加密，即私钥的主人将与之匹配的公钥散发给其他人，其他人使 用这个公钥进行加密，将加密后的数据发送给私钥主人，这时只有与这个公钥匹配的私钥才能正确解 密数据。目前流行的非对称加解密算法有 RSA 算法等。RSA 密钥对通常分为 512 位，1024 位和 2048 位， 位数越高，加密强度越强，但运算速度也越慢。 ROCKEY3 采用高性能智能卡芯片，在硬件中支持 512 位，1024 位和 2048 位 RSA 运算。 „ 数字签名 数字签名的功能是防止数据在传输中被篡改。整个功能是使用 RSA 密钥对运算来实现的。数字签 名的过程为： （1）先将数据使用散列算法进行散列，当然也可以直接使用明文数据，但如果明文数据比较大， RSA 运算将会比较慢。一般都采用先将明文数据散列的方法，得到一个固定长度的数据。 （2）将（1）中的散列后的数据使用私钥进行签名操作，将原文数据和签名的结果发送给接收者。 （3）接收者使用与（1）中相同的散列算法，将原文数据进行散列，然后使用与私钥匹配的公钥， 把散列的结果与签名后的结果进行验签，如果验证签名成功表示数据在传输过程中没有被篡改。 6.4.1 des_enc BYTE _des_enc(const void *pvKey, BYTE bLen, void *pvData) 说明： 使用 DES 对称算法加密数据。请注意：DES 密钥为 8 个字节，要加密的数据长度一定要是 8 的倍数。 数据长度不为 8 的倍数时，请自行补齐，常见的补齐原则参看本节开始的说明。这里的加密为 ECB 模式。 如要完成 CBC 模式或者其他模式，请在此基础上自行处理。 参数： *pvKey [in]DES 加密密钥的地址。密钥长度为 8 个字节。 bLen [in]加密数据长度。一定要是 8 的倍数。 *pvData [in/out]输入为要加密的明文数据，输出为加密后的密文数据。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 66 ROCKEY3 用户手册 举例： BYTE xdata bRes = 0; //要加密的明文，长度为 8 的倍数 char xdata text[8] = {0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07}; //DES 密钥，长度 8 字节 BYTE xdata deskey[8] = {0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88}; bRes = _des_enc(deskey, 8, text); //text 为双向缓冲区 if(bRes != 0) { _set_response(1,&bRes); _exit(); } //加密后的 text 为：0x9A 0xB9 0xB1 0x88 0xB1 0x6A 0x62 0x40 _set_response(8,text); _exit(); 6.4.2 des_dec BYTE _des_dec(const void *pvKey, BYTE bLen, void *pvData) 说明： 使用 DES 对称算法解密数据。请注意：DES 密钥为 8 个字节，要解密的数据长度一定要是 8 的倍数。 解密后的数据可以按照本节开始的补齐原则来得到原文。这里的解密为 ECB 模式。如要完成 CBC 模式或者 其他模式，请在此基础上自行处理。 参数： *pvKey [in]DES 解密密钥的地址。密钥长度为 8 个字节。 bLen [in]解密数据长度。一定要是 8 的倍数。 *pvData [in/out]输入为要解密的密文数据，输出为解密后的明文数据。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; //要解密的密文，长度为 8 的倍数 char xdata text[8] = {0x9A, 0xB9, 0xB1, 0x88, 0xB1, 0x6A, 0x62, 0x40,}; //DES 密钥，长度 8 字节 BYTE xdata deskey[8] = {0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88}; bRes = _des_dec(deskey, 8, text); if(bRes != 0) { _set_response(1,&bRes); //text 为双向缓冲区 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 67 ROCKEY3 用户手册 _exit(); } //解密后的 text 为：0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 _set_response(8,text); _exit(); 6.4.3 tdes_enc BYTE _tdes_enc(const void *pvKey, BYTE bLen, void *pvData) 说明： 使用 3DES 对称算法加密数据。请注意：3DES 密钥为 16 个字节，要加密的数据长度一定要是 8 的倍数。 数据长度不为 8 的倍数时，请自行补齐，常见的补齐原则参看本节开始的说明。这里的加密为 ECB 模式。 如要完成 CBC 模式或者其他模式，请在此基础上自行处理。 参数： *pvKey [in]3DES 加密密钥的地址。密钥长度 16 字节。 bLen [in]加密数据长度。一定要是 8 的倍数。 *pvData [in/out]输入为要加密的明文数据，输出为加密后的密文数据。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; //要加密的明文，长度为 8 的倍数 char xdata text[8] = {0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07}; //3DES 密钥，长度 16 字节 BYTE xdata tdeskey[16] = {0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77, 0x88,0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF}; bRes = _tdes_enc(tdeskey, 8, text); //text 为双向缓冲区 if(bRes != 0) { _set_response(1,&bRes); _exit(); } //加密后的 text 为：0x5D 0x99 0x07 0x87 0xB0 0x67 0x37 0x87 _set_response(8,text); _exit(); 6.4.4 tdes_dec BYTE _tdes_dec(const void *pvKey, BYTE bLen, void *pvData) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 68 ROCKEY3 用户手册 说明： 使用 3DES 对称算法解密数据。请注意：3DES 密钥为 16 个字节，要解密的数据长度一定要是 8 的倍数。 解密后的数据可以按照本节开始的补齐原则来得到原文。这里的解密为 ECB 模式。如要完成 CBC 模式或者 其他模式，请在此基础上自行处理。 参数： *pvKey [in]3DES 解密密钥的地址。密钥长度 16 字节。 bLen [in]解密数据长度。一定要是 8 的倍数。 *pvData [in/out]输入为要解密的密文数据，输出为解密后的明文数据。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; //要解密的密文，长度为 8 的倍数 char text[8] = {0x5D, 0x99, 0x07, 0x87, 0xB0, 0x67, 0x37, 0x87}; //3DES 密钥，长度 16 字节 BYTE xdata tdeskey[16] = {0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77, 0x88,0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF}; bRes = _tdes_dec(tdeskey, 8, text); //text 为双向缓冲区 if(bRes != 0) { _set_response(1,&bRes); _exit(); } //解密后的 text 为：0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 _set_response(8,text); _exit(); 6.4.5 6.4.5 sha1_init BYTE _sha1_init(PSHA_CONTEXT pCtx) 说明： 使用 SHA1 散列算法前，先要进行初始化。 参数： pCtx [in]上下文环境结构的地址。 SHA_CONTEXT 上下文环境结构定义如下： typedef struct _tagSHA_CONTEXT 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 69 ROCKEY3 用户手册 { DWORD h[5]; DWORD dwTotalLength; BYTEbRemainLength; BYTEpbRemainBuf[ROCKEY3_SHA_CBLOCK]; }SHA_CONTEXT,*PSHA_CONTEXT; 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 sha1_final 的示例。 6.4.6 sha1_update BYTE _sha1_update(PSHA_CONTEXT pCtx,const void *pvData, BYTE bLen) 说明： 使用 SHA1 散列算法进行运算。 参数： pCtx [in]上下文环境结构的地址。 *pvData [in]进行散列的数据。 bLen [in]进行散列数据的长度。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 sha1_final 的示例。 6.4.7 sha1_final BYTE _sha1_final(PSHA_CONTEXT pCtx, void *pvResult) 说明： 得到 SHA1 散列算法运算的结果。SHA1 的散列结果长度为 20 字节。 参数： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 70 ROCKEY3 用户手册 pCtx [in]上下文环境结构的地址。 *pvResult [out]散列结果存放的地址。 注意事项： „ 散列结果也会在 COS 内部保留（见 3.2.9），COS 内部存在一个 Buffer 会保存上一次散列计算的 结果。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; char xdata result[20]; BYTE xdata text[] = "HELLO"; SHA_CONTEXT xdata sha1ctx; //进行散列前要先初始化上下文环境 bRes = _sha1_init(&sha1ctx); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //进行散列计算 bRes = _sha1_update(&sha1ctx, text, 5); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //得到散列的结果，SHA1 的散列结果长度为 20 个字节 bRes = _sha1_final(&sha1ctx, result); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(20,result); _exit(); 6.4.8 md5_init BYTE _md5_init(PMD5_CONTEXT pCtx) 说明： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 71 ROCKEY3 用户手册 使用 MD5 散列算法前，先要进行初始化。 参数： pCtx [in]上下文环境结构的地址。 MD5_CONTEXT 上下文环境结构定义如下： typedef struct _tagMD5_CONTEXT { DWORD h[4]; DWORD dwTotalLength; BYTE bRemainLength; BYTE pbRemainBuf[ROCKEY3_MD5_CBLOCK]; }MD5_CONTEXT,*PMD5_CONTEXT; 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 md5_final 的示例。 6.4.9 md5_update BYTE _md5_update(PMD5_CONTEXT pCtx,const void *pvData, BYTE bLen) 说明： 使用 MD5 散列算法进行运算。 参数： pCtx [in]上下文环境结构的地址。 *pvData [in]进行散列的数据。 bLen [in]进行散列数据的长度。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 md5_final 的示例。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 72 ROCKEY3 用户手册 6.4.10 md5_final BYTE _md5_final(PMD5_CONTEXT pCtx, void *pvResult) 说明： 得到 MD5 散列算法运算的结果。MD5 的散列结果长度为 16 字节。 参数： pCtx [in]上下文环境结构的地址。 *pvResult [in] 散列结果存放的地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; char xdata result[16]; BYTE xdata text[] = "HELLO"; MD5_CONTEXT xdata md5ctx; //进行散列前要先初始化上下文环境 bRes = _md5_init(&md5ctx); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //进行散列计算 bRes = _md5_update(&md5ctx, text, 5); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //得到散列的结果，MD5 的散列结果长度为 16 个字节 bRes = _md5_final(&md5ctx, result); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(16,result); _exit(); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 73 ROCKEY3 用户手册 6.4.11 rsa_enc BYTE _rsa_enc(BYTE bMode, WORD wFileID, WORD wLen, void *pvData) 说明： 使用 RSA 公钥进行加密。 参数： [in]RSA 加密模式，见表 6‐3。默认为 1024 位加密。 bMode wFileID [in]公钥文件 ID。 wLen [in]要加密数据的长度。见下面的注意事项。 *pvData [in/out]输入为要加密的明文数据，输出为加密后的密文数据。 注意事项： „ bMode：RSA 加密模式。RSA 运算模式分为 RSA_CALC_NORMAL 和 RSA_CALC_PKCS。每种模式 都要与 RSA 密钥的位数结合使用（如：RSA_CALC_NORMAL | RSA_CALC_BIT_1024） ，位数默认为 1024。 RSA 加密模式 名称 值 含义 RSA_CALC_NORMAL 0x00 直接运算，无编码 RSA_CALC_PKCS 0x02 RSA 密钥位数 RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） RSA_CALC_BIT_2048 PKCS#1 标准加密 0x10 使用 512 位 RSA 密钥加密 0x00 使用 1024 位 RSA 密钥加密 0x20 使用 2048 位 RSA 密钥加密 表 6­3RSA 运算模式 „ 当为 RSA_CALC_NORMAL 模式时，这时输入的是固定长度，根据 RSA 密钥的长度不同而不同， 这时第 3 个参数应根据下表的规则给相应的值。如果原文数据超出或者不足这个固定的字节长度 时，需要先进行分块和补齐操作，可以参看 6.4 节开始的补齐原则。如果不进行补齐操作，接口会 自动在前面填充 0。 RSA_CALC_NORMAL 模式明文长度 模式 值 明文长度（字节） RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） 0x10 64 0x00 128 RSA_CALC_BIT_2048 0x20 256 表 6­4RSA_CALC_NORMAL 模式明文长度 „ 当为 RSA_CALC_PKCS 模式时，输入的数据长度根据 RSA 密钥的长度不同而不同。这时第 3 个 参数应根据下表的规则给相应的值。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 74 ROCKEY3 用户手册 RSA_CALC_PKCS 模式明文长度 模式 值 明文长度（字节） RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） 0x10 1-53 0x00 1-117 RSA_CALC_BIT_2048 0x20 1-245 表 6­5RSA_CALC_PKCS 模式明文长度 „ RSA 加密后的数据根据 RSA 密钥的长度不同而不同，这时要注意分配给第 4 个参数*pvData 缓 冲区的空间大小。 加密后密文数据长度 名称 值 加密后密文数据长度（字节） RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） 0x10 64 0x00 128 RSA_CALC_BIT_2048 0x20 256 表 6­6 加密后密文数据长度 „ 在使用 RSA 进行加密时，为了防止被加密的数据大于 n 的情况，请将原文数据的第一个字节 设为 0。*pvData 参数所指的第一个字节为 0。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 rsa_gen_key 的示例。 6.4.12 rsa_dec BYTE _rsa_dec(BYTE bMode, WORD wFileID, WORD wLen, void *pvData) 说明： 使用 RSA 私钥进行解密。 参数： [in]RSA 运算模式见表 6‐3。默认为 1024 位加密。 bMode wFileID [in]私钥文件 ID。 wLen [in]要解密数据的长度。见下面的注意事项。 *pvData [in/out]输入为要解密的密文数据，输出为解密后的明文数据。 注意事项： „ bMode：RSA 加密模式。见 6.4.11 rsa_enc 中的说明 „ wLen：输入数据的长度根据 RSA 密钥的长度不同而不同。由于是加密后的数据，该长度为一 固定值。如在加密时对原文数据进行过分块和补齐操作，解密后需要进行相应的反向操作得到明 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 75 ROCKEY3 用户手册 文数据。 密文数据长度 名称 值 RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） 0x10 64 0x00 128 0x20 256 RSA_CALC_BIT_2048 加密后密文数据长度（字节） 表 6­7 密文数据长度 „ 当以 RSA_CALC_PKCS 解密后的数据的第一个字节表示的是原文的长度，后跟原文。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 rsa_gen_key 的示例。 6.4.13 rsa_gen_key BYTE _rsa_gen_key(WORD wPubID, WORD wPriID,WORD wKeyBitLen) 说明： 产生 RSA 密钥对。 参数： wPubID [in]公钥文件 ID。 wPriID [in]私钥文件 ID。 wKeyBitLen [in]RSA 密钥长度。为：512/1024/2048 中的一个。 注意事项： „ 考虑到加密强度和运算速度，一般采用的 RSA 密钥长度为 1024 位。不同长度的 RSA 密钥在加 解密时对应不同长度的数据，参见 6.4.11 和 6.4.12 中的注意事项。 „ wPubID 和 wPriID 必须为当前目录下没有被使用的 ID，该函数会创建 2 个新文件。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： char xdata plaintext[] = "HELLO"; BYTE xdata ciphertext[128]; BYTE xdata bRes = 0; WORD xdata wPubKeyFileID = 0x1002; //公钥文件 ID WORD xdata wPriKeyFileID = 0x1004; //私钥文件 ID 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 76 ROCKEY3 用户手册 WORD xdata wKeyLen = 1024; //RSA 密钥长度 //产生 1024 位 RSA 密钥对 bRes = _rsa_gen_key(wPubKeyFileID, wPriKeyFileID, wKeyLen); if(bRes != 0) { _set_response(1,&bRes); _exit(); } memset(ciphertext,0,128); //将 ciphertext 赋值为 0 //将“HELLO”拷贝到 ciphertext 中 //为了防止被加密数据大于 n 值，第一个字节为 0，所以从 ciphertext+1 开始 memcpy(ciphertext+1, plaintext, 6); //RSA 加密，加密结果 128 字节在 ciphertext 中 bRes = _rsa_enc(RSA_CALC_PKCS | RSA_CALC_BIT_1024, wPubKeyFileID, 6, ciphertext); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //RSA 解密，输入长度为 128 字节，解密结果在 ciphertext 中 bRes = _rsa_dec(RSA_CALC_PKCS | RSA_CALC_BIT_1024, wPriKeyFileID, 128, ciphertext); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(128, ciphertext); _exit(); 6.4.14 rsa_sign BYTE _rsa_sign(BYTE bMode, WORD wFileID, WORD wLen, void *pvData) 说明： 使用 RSA 私钥进行签名。 参数： bMode [in]签名模式，见表 6‐8。 wFileID [in]私钥文件 ID。 wLen [in]要签名的数据长度，见表 6‐8。 *pvData [in/out]输入为要签名的数据。输出为签名后的数据。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 77 ROCKEY3 用户手册 注意事项; „ 在进行签名时，一般先要进行 HASH 散列运算，参见 6.4 开始的数字签名中的说明。本接口使 用的散列算法为 SHA1 算法，散列后的数据长度为 20 字节。标准的签名一般要遵循 PKCS#1 的标准， 该标准规定，将经过 SHA1 散列算法散列后的 HASH 值（20 个字节），在前面补充 108 个字节（0x00， 0x01，105 个 0xFF，0x00），拼成 128 字节再进行签名运算（签名运算实际上就是私钥加密运算）。 如果要将签名结果符合微软的 CAPI 标准，则在散列值前面填充 15 个字节（0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x1a, 0x05, 0x00, 0x04, 0x14），即一共 35 个字节，然后填充 93 个 字节（0x00，0x01，90 个 0xFF，0x00），进行签名。因此您的签名要与其他的标准应用交互，那么 要使用 RSA_CALC_PKCS 的模式。在进行签名时有四种模式，每种模式都要与 RSA 密钥的位数结合 使用（如：RSA_CALC_HASH | RSA_CALC_BIT_1024），位数默认为 1024。请参看下表中的说明： RSA 签名模式 名称 值 RSA_CALC_NORMAL RSA_CALC_PKCS RSA_CALC_HASH|RSA_CALC_PKCS RSA_CALC_BIT_2048 „ 直接对 SHA1 散列后的 HASH 值进行私钥签 名。您需要先在外部做 一下 SHA1 散列运算 接口内部对输入数据进 0x01 行 SHA1 散列运算，再 将 HASH 结果进行私钥 签名 直接对 SHA1 散列后的 0x02 HASH 值按照 PKCS#1 的标准进行私钥签名， 接口内部做了填充操 作。您需要先在外部做 一下 SHA1 散列运算 接口内部对输入数据进 0x03 行 SHA1 散列运算，再 将 HASH 结果按照 PKCS#1 的标准进行私 钥签名 RSA 密钥位数 签名数据长度（字节） 20 0x00 RSA_CALC_HASH RSA_CALC_BIT_512 RSA_CALC_BIT_1024（默认） 含义 因为是先做 HASH 运 算，因此长度没有限 制，但要小于卡片的内 存 2K 20 因为是先做 HASH 运 算，因此长度没有限 制，但要小于卡片的内 存 2K 0x10 使用 512 位 RSA 密钥签名 0x00 使用 1024 位 RSA 密钥签名 使用 2048 位 RSA 密钥签名 0x20 表 6­8RSA 签名模式 输出的签名后的数据根据 RSA 密钥的长度不同而不同，这时要注意分配给第 4 个参数*pvData 缓冲区的空间大小。具体长度见下表： RSA 签名后结果长度 RSA 密钥 签名后结果长度（字节） 512 64 1024 128 2048 256 表 6­9RSA 签名后结果长度 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 78 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： 见 rsa_verify 的示例。 6.4.15 rsa_verify BYTE _rsa_verify(BYTE bMode, WORD wFileID, WORD wLen, void *pvData) 说明： 使用 RSA 公钥进行验证签名。 参数： bMode [in]签名模式，见表 6‐8 和下面的注意事项。 wFileID [in]公钥文件 ID。 [in]签名的数据长度。为：64/128/256 的其中一个 wLen *pvData [in]签名后的数据。 注意事项： „ 在使用 rsa_sign 签名函数签名时如果选择的签名模式为 RSA_CALC_NORMAL 和 RSA_CALC_HASH 时，这两种模式都是对 SHA1 散列后的 HASH 值直接签名，那么验证签名的模式（第 1 个参数）应 为 RSA_CALC_NORMAL。 „ 在 使 用 rsa_sign 签 名 函 数 签 名 时 如 果 选 择 的 签 名 模 式 为 RSA_CALC_PKCS 和 RSA_CALC_HASH|RSA_CALC_PKCS 时，这两种模式都是对 SHA1 散列后的 HASH 值按照 PKCS#1 的标 准进行填充后再进行签名，那么验证签名的模式（第 1 个参数）应为 RSA_CALC_PKCS。 „ 在验证签名时，本函数会使用到 COS 内部的一个保存散列结果的 Buffer，该 Buffer 会保存上 一次散列计算的结果（见 3.2.9）。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： char xdata text[] = "HELLO"; BYTE xdata signtext[128]; BYTE xdata bRes = 0; WORD xdata wPubKeyFileID = 0x1002; //公钥文件 ID WORD xdata wPriKeyFileID = 0x1004; //私钥文件 ID memset(signtext,0,128); memcpy(signtext,text,6); //使用 RSA 私钥进行签名，先进行 SHA1 散列， 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 79 ROCKEY3 用户手册 //再按 PKCS#1 标准进行签名运算。返回 128 字节的签名结果 bRes=_rsa_sign(RSA_CALC_HASH|RSA_CALC_PKCS, wPriKeyFileID,6,signtext); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //使用 RSA 公钥验证签名 bRes = _rsa_verify(RSA_CALC_PKCS, wPubKeyFileID, 128, signtext); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //返回签名后的结果 _set_response(128, signtext); _exit(); 6.5 系统功能 6.5.1 rand BYTE _rand(void *pvData, BYTE bLen) 说明： 取随机数。 参数： *pvData bLen [out]取得的随机数存放的地址。 [in]随机数的长度。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; BYTE xdata bRand[8]; memset(bRand, 0, 8); bRes = _rand(bRand,8); if(bRes != 0) { _set_response(1,&bRes); _exit(); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 80 ROCKEY3 用户手册 } _set_response(8, bRand); _exit(); 6.5.2 get_version BYTE _get_version(BYTE bFlag,void *pvData,BYTE bLen) 说明： 获取硬件信息。 参数： bFlag [in]标识，取得标识对应的相关信息。见下表的说明 *pvData [out]存放信息的缓冲区的地址。 bLen [in]缓冲区的大小。 硬件信息 Flag 标识 GLOBAL_SERIAL_NUMBER 取 8 字节序列号 GLOBAL_CLIENT_NUMBER 取 4 字节开发商 ID 取 2 字节 COS 版本 GLOBAL_COS_VERSION 表 6­10 硬件信息 Flag 标识说明 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; BYTE xdata bSN[8]; memset(bSN, 0, 8); bRes = _get_version(GLOBAL_SERIAL_NUMBER,bSN,8); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(8, bSN); _exit(); 6.6 双精度浮点运算 C51 语言本身并不支持双精度浮点运算，是我们在 ROCKEY3 中实现的。在使用双精度浮点数运算 时，不能像整数和单精度浮点数运算一样，直接使用+，‐，×，÷等符号，而要使用 ROCKEY3 提供的接口。 C51 中双精度浮点数在表示时与 PC 中的高级语言不同，有一个倒序的问题。例如：双精度浮点数 1.0 在 PC 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 81 ROCKEY3 用户手册 高级语言中（Debug 调试时可以查看双精度浮点数的地址）表示为：0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F。在 C51 语言中双精度浮点数 1.0 为：0x3F, 0xF0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00，因此由外部输入到 C51 程序时，需要倒序，参见 6.2.1 中的说明。 我们提供了一个工具（Double2Byte.exe），可以方便的在双精度将浮点数与 8 字节数组之间进行 自动转换。本节所讲述的双精度数学运算的接口中声明为 DOUBLE 类型的，都是一个 8 个字节的数组。调用 方法参见 add 后的示例，其他接口的调用方法类似。注意：如果要保证双精度浮点运算的精度，请不要使 用 DOUBLE_INIT 函数，而应该直接使用数组的方式给双精度变量赋值。如：DOUBLE A，给 A 赋值 1.0，直 接使用 memcpy(&A, "\x3F\xF0\x00\x00\x00\x00\x00\x00", 8); 6.6.1 add BYTE _add(DOUBLE result, DOUBLE x, DOUBLE y) 说明： 双精度浮点数加法运算。 参数： result [out]相加的结果。 x [in]被加数。 y [in]加数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; DOUBLE xdata dx, dy, dResult; //dx 为 1.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F） DOUBLE_INIT(dx, 1.0); //dy 为 2.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40） DOUBLE_INIT(dy, 2.0); bRes = _add(dResult, dx, dy); if(bRes != 0) { _set_response(1,&bRes); _exit(); } //返回为双精度浮点数 3.0，（0x00 0x00 0x00 0x00 0x00 0x00 0x08 0x40） _set_response(8, &dResult); _exit(); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 82 ROCKEY3 用户手册 6.6.2 sub BYTE _sub(DOUBLE result, DOUBLE x, DOUBLE y) 说明： 双精度浮点数减法运算。 参数： result [out]相减的结果。 x [in]被减数。 y [in]减数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.3 mul BYTE _mul(DOUBLE result, DOUBLE x, DOUBLE y) 说明： 双精度浮点数乘法运算。 参数： result [out]相乘的结果。 x [in]被乘数。 y [in]乘数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.4 div BYTE _div(DOUBLE result, DOUBLE x, DOUBLE y) 说明： 双精度浮点数除法运算。 参数： result [out]相除的结果。 x [in]被除数。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 83 ROCKEY3 用户手册 y [in]除数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.5 atan2 BYTE _atan2(DOUBLE result, DOUBLE x, DOUBLE y) 说明： 双精度浮点数商的反正切运算。 参数： result [out]商的反正切运算的结果。 x [in]被除数。 y [in]除数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.6 mod BYTE _mod(DOUBLE result, DOUBLE x, DOUBLE pMod) 说明： 双精度浮点数求模运算。 参数： result [out]求模运算的结果。 x [in]被除数。 pMod [in]除数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.7 pow BYTE _pow(DOUBLE result, DOUBLE x, DOUBLE pExp) 说明： 双精度浮点数求幂运算。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 84 ROCKEY3 用户手册 参数： result [out]求幂运算的结果。 x [in]底数。 pExp [in]指数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.8 modf BYTE _modf(DOUBLE remain, DOUBLE x, DOUBLE intpart) 说明： 将一个双精度浮点数分割为整数部分和小数部分。 参数： remain [out]分割后小数部分。 x [in]被分割的数。 intpart [out]分割后整数部分。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.9 frexp BYTE _frexp(DOUBLE result, DOUBLE x, WORD *pExp) 说明： 把一个双精度浮点数拆成一个小数乘 2 的幂。 参数： result [out]分拆后小数部分。 x [in]被分拆的数。 *pExp [out]指数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 85 ROCKEY3 用户手册 6.6.10 ldexp BYTE _ldexp(DOUBLE result, DOUBLE x, WORD exp) 说明： 求双精度浮点数乘 2 的幂。 参数： result [out]运算结果。 x [in]参与计算的双精度浮点数。 exp [in]2 的指数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.11 sin BYTE _sin(DOUBLE result, DOUBLE x) 说明： 正弦运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.12 cos BYTE _cos(DOUBLE result, DOUBLE x) 说明： 余弦运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 86 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.13 tan BYTE _tan(DOUBLE result, DOUBLE x) 说明： 正切运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.14 asin BYTE _asin(DOUBLE result, DOUBLE x) 说明： 反正弦运算。 参数： result [out]运算结果。 x [in]正弦值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.15 acos BYTE _acos(DOUBLE result, DOUBLE x) 说明： 反余弦运算。 参数： result [out]运算结果。 x [in]余弦值。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 87 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.16 atan BYTE _atan(DOUBLE result, DOUBLE x) 说明： 反正切运算。 参数： result [out]运算结果。 x [in]正切值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.17 sinh BYTE _sinh(DOUBLE result, DOUBLE x) 说明： 双曲正弦运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.18 cosh BYTE _cosh(DOUBLE result, DOUBLE x) 说明： 双曲余弦运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 88 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.19 tanh BYTE _tanh(DOUBLE result, DOUBLE x) 说明： 双曲正切运算。 参数： result [out]运算结果。 x [in]弧度值。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.20 ceil BYTE _ceil(DOUBLE result, DOUBLE x) 说明： 不小于该双精度浮点数的最小整数。 参数： result [out]运算结果。 x [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.21 floor BYTE _floor(DOUBLE result, DOUBLE x) 说明： 不大于该双精度浮点数的最大整数。 参数： result [out]运算结果。 x [in]双精度浮点数。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 89 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.22 abs BYTE _abs(DOUBLE result, DOUBLE x) 说明： 双精度浮点数的绝对值。 参数： result [out]运算结果。 x [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.23 exp BYTE _exp(DOUBLE result, DOUBLE x) 说明： 求以 e 为底，双精度浮点数为指数的幂。 参数： result [out]运算结果。 x [in]指数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.24 log BYTE _log(DOUBLE result, DOUBLE x) 说明： 求双精度浮点数的自然对数。 参数： result [out]运算结果。 x [in]双精度浮点数。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 90 ROCKEY3 用户手册 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.25 log10 BYTE _log10(DOUBLE result, DOUBLE x) 说明： 求双精度浮点数的常用对数。 参数： result [out]运算结果。 x [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.26 sqrt BYTE _sqrt(DOUBLE result, DOUBLE x) 说明： 求双精度浮点数的平方根。 参数： result [out]运算结果。 x [in] 双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.6.27 cmp char _cmp(DOUBLE x, DOUBLE y) 说明： 比较两个双精度浮点数的大小。 参数： x [in]双精度浮点数。 y [in]双精度浮点数。 返回值： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 91 ROCKEY3 用户手册 返回 0 表示相等；返回‐1 表示 xy。 举例： char xdata cRes = 0; DOUBLE xdata dx,dy; //dx 为 1.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F） DOUBLE_INIT(dx, 1.0); //dy 为 2.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40） DOUBLE_INIT(dy, 2.0); cRes = _cmp(dx, dy); _set_response(1, &cRes);//返回为 0xFF = ‐1 _exit(); 6.7 单精度浮点运算 C51 语言中单精度浮点数的表示和 PC 机上的高级语言一样，都是 4 个字节，但顺序相反，需要进行倒 序处理，请参看 6.2.1 中的说明。例如：单精度浮点数 3.0，高级语言中（Debug 调试时可以查看单精度浮 点数的地址）表示为：0x00, 0x00, 0x40, 0x40）。而在 C51 中，表示为：0x40 0x40 0x00 0x00 四个字节，需要 进行倒序，考虑到 PC 的性能远远高于智能卡，建议在高级语言中做倒序处理。调用方法参见 addf 后的示例， 其他接口的调用方法类似。 6.7.1 addf float _addf(float x, float y) 说明： 单精度浮点数加法运算。 参数： x y [in]被加数。 [in]加数。 返回值： 返回运算结果。 举例： float xdata fx; float xdata fy; float xdata fResult; fx = 1.0; fy = 2.0; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 92 ROCKEY3 用户手册 fResult = _addf(fx, fy); //结果返回 0x40 0x40 0x00 0x00 四个字节，与高级语言中的顺序相反。 _set_response(4, &fResult); _exit(); 6.7.2 subf float _subf(float x, float y) 说明： 单精度浮点数减法运算。 参数： x [in]被减数。 y [in]减数。 返回值： 返回运算结果。 6.7.3 6.7.3 mulf float _mulf(float x, float y) 说明： 单精度浮点数乘法运算。 参数： x [in]被乘数。 y [in]乘数。 返回值： 返回运算结果。 6.7.4 divf float _divf(float x, float y) 说明： 单精度浮点数除法运算。 参数： x [in]被除数。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 93 ROCKEY3 用户手册 y [in]除数。 返回值： 返回运算结果。 6.7.5 atan2f float _atan2f(float x, float y) 说明： 单精度浮点数商的反正切运算。 参数： x [in]被除数。 y [in]除数。 返回值： 返回运算结果。 6.7.6 fmodf float _fmodf(float x, float y) 说明： 单精度浮点数求模运算。 参数： x [in]被除数。 y [in]除数。 返回值： 返回运算结果。 6.7.7 6.7.7 powf float _powf(float x, float y) 说明： 单精度浮点数求模运算。 参数： x [in]底数。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 94 ROCKEY3 用户手册 y [in]指数。 返回值： 返回运算结果。 6.7.8 cmpf char _cmpf(float x, float y) 说明： 比较两个单精度浮点数的大小。 参数： x [in]单精度浮点数。 y [in]单精度浮点数。 返回值： 返回 0 表示相等；返回-1 表示 xy。 举例： float xdata fx; float xdata fy; char xdata cRes; fx = 1.0; fy = 2.0; cRes = _cmpf(fx, fy); _set_response(1, &cRes); //返回为 0xFF = ‐1 _exit(); 6.7.9 sinf float _sinf(float x) 说明： 正弦运算。 参数： x [in]弧度值。 返回值： 返回运算结果。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 95 ROCKEY3 用户手册 6.7.10 cosf float _cosf(float x) 说明： 余弦运算。 参数： x [in]弧度值。 返回值： 返回运算结果。 6.7.11 tanf float _tanf(float x) 说明： 正切运算。 参数： x [in]弧度值。 返回值： 返回运算结果。 6.7.12 asinf float _asinf(float x) 说明： 反正弦运算。 参数： x [in]正弦值。 返回值： 返回运算结果。 6.7.13 acosf float _acosf(float x) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 96 ROCKEY3 用户手册 说明： 反余弦运算。 参数： x [in]余弦值。 返回值： 返回运算结果。 6.7.14 atanf float _atanf(float x) 说明： 反正切运算。 参数： x [in]正弦值。 返回值： 返回运算结果。 6.7.15 sinhf float _sinhf(float x) 说明： 双曲正弦运算。 参数： x [in]弧度值。 返回值： 返回运算结果。 6.7.16 coshf float _coshf(float x) 说明： 双曲余弦运算。 参数： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 97 ROCKEY3 用户手册 x [in]弧度值。 返回值： 返回运算结果。 6.7.17 tanhf float _tanhf(float x) 说明： 双曲正切运算。 参数： x [in]弧度值。 返回值： 返回运算结果。 6.7.18 ceilf float _ceilf(float x) 说明： 不小于该单精度浮点数的最小整数。 参数： x [in]单精度浮点数。 返回值： 返回不小于该单精度浮点数的最小整数。 6.7.19 floorf float _floorf(float x) 说明： 不大于该单精度浮点数的最大整数。 参数： x [in]单精度浮点数。 返回值： 返回不大于该单精度浮点数的最大整数。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 98 ROCKEY3 用户手册 6.7.20 absf float _absf(float x) 说明： 单精度浮点数的绝对值。 参数： x [in]单精度浮点数。 返回值： 返回该单精度浮点数的绝对值。 6.7.21 expf float _expf(float x) 说明： 求以 e 为底，单精度浮点数为指数的幂。 参数： x [in]指数。 返回值： 返回运算结果。 6.7.22 logf float _logf(float x) 说明： 求单精度浮点数的自然对数。 参数： x [in]单精度浮点数。 返回值： 返回运算结果。 6.7.23 log10f float _log10f(float x) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 99 ROCKEY3 用户手册 说明： 求单精度浮点数的常用对数。 参数： x [in]单精度浮点数。 返回值： 返回运算结果。 6.7.24 sqrtf float _sqrtf(float x) 说明： 求单精度浮点数的平方根。 参数： x [in]单精度浮点数。 返回值： 返回运算结果。 6.8 类型转换 C51 语言中使用不同数据类型进行计算时，有时需要相互之间进行转换，这就需要调用本节所提供的接 口。 在 C51 语言中，int，long，float，double 等类型的表示与在高级语言中是相反的，参见 6.2.1 中的说明。 例如：单精度浮点数 1.0 在高级语言中（Debug 调试时可以查看单精度浮点数的地址）表示为：0x00, 0x00, 0x80, 0x3F。这与 C51 语言中 0x3F，0x80，0x00，0x00 是相反的。要注意倒序的问题。 在 C51 语言中 DOUBLE 为一个 8 字节的数组，其表示也是与 PC 中高级语言相反的。例如：双精度浮点 数 1.0 在 PC 的高级语言中（Debug 调试时可以查看双精度浮点数的地址） 表示为：0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F。但在 C51 中为：0x3F, 0xF0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00。 本节中的 6.8.1‐6.8.4 的调用方法参见 dbltof 后的示例。 本节中的 6.8.5‐6.8.8 中使用的是宏定义，调用时给宏的名称。参见 dtof 后的示例。 6.8.1 dbltof BYTE _dbltof(float *result, DOUBLE x) 说明： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 100 ROCKEY3 用户手册 双精度浮点数转换为单精度浮点数。 参数： *result [out]单精度浮点数的地址。 x [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; float xdata fRes; DOUBLE xdata dx; //dx 为 1.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F） DOUBLE_INIT(dx, 1.0); bRes = _dbltof(&fRes, dx); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(4, &fRes); //输出：0x3F 0x80 0x00 0x00，与高级语言相反 _exit(); 6.8.2 ftodbl BYTE _ftodbl(DOUBLE result, float x) 说明： 单精度浮点数转换为双精度浮点数。 参数： result [out]双精度浮点数。 x [in]单精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.8.3 dbltol BYTE _dbltol(long *result, DOUBLE x) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 101 ROCKEY3 用户手册 说明： 双精度浮点数转换为 32 位有符号整数。 参数： *result [out]32 位有符号整数的地址。 x [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.8.4 ltodbl BYTE _ltodbl(DOUBLE result, long x) 说明： 32 位有符号整数转换为双精度浮点数。 参数： result [out]双精度浮点数。 x [in] 32 位有符号整数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.8.5 dtof BYTE _dtof(float* presult, DOUBLE px) 说明： 双精度浮点数转换为单精度浮点数。 参数： *presult px [out]单精度浮点数地址。 [in] 双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 举例： BYTE xdata bRes = 0; float xdata fRes; DOUBLE xdata dx; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 102 ROCKEY3 用户手册 //dx 为 1.0，（0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F） DOUBLE_INIT(dx, 1.0); bRes = _dtof(&fRes, dx); if(bRes != 0) { _set_response(1,&bRes); _exit(); } _set_response(4, &fRes); //输出：0x3F 0x80 0x00 0x00，与高级语言相反 _exit(); 6.8.6 ftod BYTE _ftod(DOUBLE presult, float* px) 说明： 单精度浮点数转换为双精度浮点数。 参数： presult [out]双精度浮点数。 *px [in]单精度浮点数地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.8.7 dtol BYTE _dtol(long* presult, DOUBLE px) 说明： 双精度浮点数转换为 32 位有符号整数。 参数： *presult px [out] 32 位有符号整数地址。 [in]双精度浮点数。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 103 ROCKEY3 用户手册 6.8.8 ltod BYTE _ltod (DOUBLE presult, long* px) 说明： 32 位有符号整数转换为双精度浮点数。 参数： presult [out]双精度浮点数。 *px [in] 32 位有符号整数地址。 返回值： 返回 0 表示成功。返回非 0 值表示执行该函数失败，参看 6.10 错误编码。 6.9 结构和常量 在使用 C51 语言进行编程时为了方便，定义了一些结构，常量和宏。这些都可以在 RY3_C51.h 头文件中 查找到。见下面的说明。 6.9.1 数据类型 为了与程序员熟悉的多数高级语言一样，我们在 C51 中声明了如下类型： typedef unsigned char BOOL; //布尔类型 typedef unsigned short word; //无符号短整形，16 位（2 字节） typedef unsigned short WORD; //无符号短整形，16 位（2 字节） typedef unsigned long dword; //无符号长整形，32 位（4 字节） typedef unsigned long DWORD; //无符号长整形，32 位（4 字节） typedef unsigned char byte; //无符号字符，1 字节 typedef unsigned char BYTE; //无符号字符，1 字节 //双精度浮点数，8 字节数组 typedef BYTE DOUBLE[8]; typedef BYTE HANDLE; //句柄，1 字节 6.9.2 宏定义 #define SHA_DIGEST_LENGTH 20 //SHA1 散列值长度 #define MD5_DIGEST_LENGTH 16 //MD5 散列值长度 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 104 ROCKEY3 用户手册 //DES 密钥长度 #define DES_KEY_LENGTH 8 #define TDES_KEY_LENGTH 16 //3DES 密钥长度 #define ROCKEY3_SHA_CBLOCK 64 //SHA1 散列块长度 #define ROCKEY3_MD5_CBLOCK 64 //MD5 散列块长度 #define RSA_CRYPT_NOPKCS RSA_CALC_NORMAL //直接加密 #define RSA_CRYPT_PKCS RSA_CALC_PKCS //按标准#PKCS1 模式加密 #define RSA_SIGN_NOPH RSA_CALC_NORMAL //对散列后的数据签名 #define RSA_SIGN_HASH RSA_CALC_HASH #define RSA_SIGN_PKCS RSA_CALC_PKCS //先进行 SHA1 散列，再签名 //按#PKCS1 标准，对散列后的数据签名 //按#PKCS1 标准，先进行 SHA1 散列，再签名 #define RSA_SIGN_PH #define RSA_VERI_NOPKCS (RSA_CALC_HASH|RSA_CALC_PKCS) RSA_CALC_NORMAL #define RSA_VERI_PKCS RSA_CALC_PKCS //直接对数据验证签名 //按#PKCS1 标准验证签名 #define RSA_CALC_BIT_512 0x10 //512 位加密 #define RSA_CALC_BIT_1024 0x00 //1024 位加密 #define RSA_CALC_BIT_2048 0x20 //2048 位加密 //双精度浮点数转换成单精度浮点数 #define _dtof(result,x) _dbltof(result,x) //双精度浮点数转换为 32 位有符号整数 #define _dtol(result,x) _dbltol(result,x) //单精度浮点数转换成双精度浮点数 #define _ftod(result,x) _ftodbl(result,*(x)) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 105 ROCKEY3 用户手册 //32 位有符号整数转换为双精度浮点数 #define _ltod(result,x) _ltodbl(result,*(x)) //短整形（short，int）倒序 #define _swap_u16(pvData) _swap(pvData,2) //长整形（long），单精度浮点数（float）倒序 #define _swap_u32(pvData) _swap(pvData,4) //将单精度浮点数 y 赋值给双精度浮点数 x #define DOUBLE_INIT(x,y) _ftodbl(x,y) 6.9.3 结构和枚举 „ SHA1 散列算法上下文结构 typedef struct _tagSHA_CONTEXT { DWORD h[5]; DWORD dwTotalLength; BYTEbRemainLength; BYTEpbRemainBuf[ROCKEY3_SHA_CBLOCK]; }SHA_CONTEXT,*PSHA_CONTEXT; typedef SHA_CONTEXT ShaContext; typedef ShaContext* PShaContext; „ //SHA_CONTEXT 结构类型 //指向 SHA_CONTEXT 结构的指针类型 MD5 散列算法上下文结构 typedef struct _tagMD5_CONTEXT { DWORD h[4]; DWORD dwTotalLength; BYTE bRemainLength; BYTE pbRemainBuf[ROCKEY3_MD5_CBLOCK]; }MD5_CONTEXT,*PMD5_CONTEXT; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 106 ROCKEY3 用户手册 //MD5_CONTEXT 结构类型 typedef MD5_CONTEXT Md5Context; typedef Md5Context* PMd5Context; „ //指向 MD5_CONTEXT 结构的指针类型 文件结构 typedef struct _FILE_INFO { wFileID; //文件 ID WORD BYTE bFileType; WORD //文件类型 wFileSize; //文件大小 }EFINFO,*PEFINFO; „ 文件类型 enum { FILE_TYPE_EXE = 0x00, //可执行文件 FILE_TYPE_DATA, //数据文件 FILE_TYPE_RSA_PUBLIC, //RSA 公钥文件 FILE_TYPE_RSA_PRIVATE, //RSA 私钥文件 }; „ 创建文件 enum { //如果文件已存在，打开该文件；反之则创建新文件并打开 CREATE_OPEN_ALWAYS = 0x00, //创建并打开新文件，如果文件已经存在则返回错误 CREATE_FILE_NEW, //打开已存在文件，功能同_open()函数 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 107 ROCKEY3 用户手册 CREATE_OPEN_EXISTING }; „ 硬件信息 enum { GLOBAL_SERIAL_NUMBER = 0x00, //取 8 字节序列号 GLOBAL_CLIENT_NUMBER, //取 4 字节开发商 ID GLOBAL_COS_VERSION //取 2 字节 COS 版本 }; „ 加解密和签名 enum { RSA_CALC_NORMAL = 0x00, //直接运算，无编码 RSA_CALC_HASH, //对输入数据进行 HASH 运算，再将结果进行私钥加密 RSA_CALC_PKCS, //PKCS#1 标准加密 }; 6.10 错误编码 错误编码定义如下： #define RY3_C51_SUCCESS 0x00000000 //成功 #define RY3_C51_UNKNOWN 0x00000001 //未知错误 #define RY3_C51_INVALID_PARAMETER 0x00000002 //无效的参数 #define RY3_C51_INVALID_ADDRESS 0x00000003 //无效的地址,虚拟机地址越界 #define RY3_C51_INVALID_SIZE 0x00000004 //无效的长度 #define RY3_C51_FILE_NOT_FOUND 0x00000005 //文件没找到 #define RY3_C51_ACCESS_DENIED 0x00000006 //访问文件失败 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 108 ROCKEY3 用户手册 #define RY3_C51_FILE_SELECT 0x00000007 //文件打开个数已达上限 #define RY3_C51_INVALID_HANDLE 0x00000008 //无效的文件句柄 #define RY3_C51_FILE_OUT_OF_RANGE 0x00000009 //文件读写越界 #define RY3_C51_FILE_TYPE_MISMATCH 0x0000000A //文件存在但类型不匹配 #define RY3_C51_FILE_SIZE_MISMATCH 0x0000000B //文件存在但长度不匹配 #define RY3_C51_NO_SPACE 0x0000000C //文件夹空间不足 #define RY3_C51_FILE_EXIST 0x0000000D //文件或子目录已存在 #define RY3_C51_INVALID_KEY_FORMAT 0x0000000E //无效的 RSA 密钥文件格式 #define RY3_C51_KEY_LEN_MISMATCH 0x0000000F //用户传入的密钥长度与实际长度不匹 #define RY3_C51_RSA_INVALID_KEY_FILE 0x00000010 //文件类型不符合要求 #define RY3_C51_RSA_ENC_DEC_FAILED 0x00000011 //RSA 加密解密失败 #define RY3_C51_RSA_SIGN_VERI_FAILED 0x00000012 //RSA 签名验证失败 #define RY3_C51_SHA1 0x00000013 //SHA1 计算错误 #define RY3_C51_MD5 0x00000014 //MD5 计算错误 #define RY3_C51_INVALID_ADDERSS 0x00000015 //无效的内存指针 #define RY3_C51_EEPROM 0x00000016 //写 EEPROM 错误 配 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 109 ROCKEY3 用户手册 第7章 ROCKEY3 外部API函数（PC语言） 7.1 API接口函数 7.1.1 RY3_Find DWORD WINAPI RY3_Find(char* pVendorID, int* pCount); 说明： 查找计算机上连接的 ROCKEY3 加密锁设备。 参数： [in/out]指向存放开发商 ID 的字符串指针，开发商 ID 长度为 4 字节。 * pVendorID [out]指向存放 ROCKEY3 设备个数的整形指针。 * pCount 注意事项： „ 此函数得到的是指定开发商 ID 的 ROCKEY3 设备的个数，如果* pVendorID 参数赋值为 0，则* pCount 的返回值为 0。 „ 一台计算机上允许最多同时插入 32 把 ROCKEY3。 „ 通常情况下，这个函数只需要在程序一开始时调用 1 次，这个函数会进行一些初始化工作， 并建立内部的设备列表，所以至少要调用 1 次。 „ 如果是多线程程序，最好在主线程开始的时候调用 1 次。 „ 当用户有插/拔动作时，不会导致设备个数的变化。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： 见 RY3_Close 的示例。 7.1.2 RY3_Open DWORD WINAPI RY3_Open(RY_HANDLE* pHandle, int Item); 说明： 打开 ROCKEY3 设备。调用该函数前需要先调用 RY3_Find 函数。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 110 ROCKEY3 用户手册 参数： * pHandle [out]句柄指针，返回被打开的 ROCKEY3 加密锁的句柄。 Item [in]输入条目，从 1 开始，指打开第几个 ROCKEY3 加密锁。 注意事项： „ 打开成功，* pHandle 指向被打开的 ROCKEY3 加密锁的设备句柄。 „ 该函数打开时是共享模式，即允许其他进程也可以打开 ROCKEY3。在这种模式下是支持多进 程的。因此，只在程序开始和退出时打开和关闭一次就可以，频繁的打开和关闭动作会降低程序 的效率。 „ 如果需要在一个程序中打开多个 ROCKEY3 加密锁，可以定义 handle 数组来保存打开过的加密 锁的句柄，为下一步具体操作加密锁做好准备。也可以循环操作每一个加密锁（见 RY3_Close 的示 例）。 „ 用户完成自己的操作后，应该调用 RY3_Close 动作，释放设备句柄。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： 见 RY3_Close 的示例。 7.1.3 RY3_Close DWORD WINAPI RY3_Close(RY_HANDLE handle , BOOL IsReset); 说明： 关闭 ROCKEY3 设备。调用该函数前需要先打开设备（RY3_Open）。 参数： [in]要关闭的 ROCKEY3 设备的句柄，与 RY3_Open 返回的句柄保持一致。 handle IsReset [in]是否清除安全状态标志。 注意事项： 调用该函数关闭 ROCKEY3 设备。若 IsReset 值为 TRUE 则清除设备内存中的数据和安全状态，若 IsReset 值为 FALSE 则不清除。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 111 ROCKEY3 用户手册 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int //查找到的加密锁个数 count = 0; char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); // //可在此加入对加密锁的操作 // 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 112 ROCKEY3 用户手册 retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.4 RY3_GetHardID DWORD WINAPI RY3_GetHardID(RY_HANDLE handle, char* pbuf); 说明： 获得 ROCKEY3 设备的硬件序列号。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pbuf [out]硬件序列号指针。 注意事项： 返回的硬件序列号为 16 字节的字符串。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com //指定开发商 ID 113 ROCKEY3 用户手册 char buf[20]; //存放返回的硬件序列号 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Get HardID memset(buf, 0, sizeof(buf)); retcode = RY3_GetHardID(handle, buf); //获取硬件序列号 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_GetHardID()错误，错误码：%08X \r\n", retcode); return; } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 114 ROCKEY3 用户手册 printf("\r\n RY3_GetHardID()成功，硬件序列号：%s\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.5 RY3_GenRandom DWORD WINAPI RY3_GenRandom(RY_HANDLE handle, int len_need, BYTE* pOutbuf); 说明： 获取指定长度的随机数。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 len_need [in]指定要取得的随机数的长度。 *pOutbuf [out] 随机数指针。 注意事项： 要返回的随机数的长度最大为 16 字节。如果指定的长度大于 16 字节，系统只返回 16 字节的随机数， 不会报错。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; DWORD retcode; //设备的句柄 //错误码 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 115 ROCKEY3 用户手册 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID BYTE buf[18]; //存放返回的随机数 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Get Random memset(buf, 0, sizeof(buf)); retcode = RY3_GenRandom(handle,10, buf); //获取长度是 10 字节的随机数 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 116 ROCKEY3 用户手册 printf("\r\n RY3_GenRandom()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_GenRandom()成功，产生随机数：%08x\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.6 RY3_GetFreeSize DWORD WINAPI RY3_GetFreeSize(RY_HANDLE handle, int* pSize); 说明： 获取剩余用户空间的大小。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pSize [out]指向剩余用户空间大小的指针。 注意事项： 可以查看加密锁剩余用户空间的大小，以便更好的管理加密锁。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 117 ROCKEY3 用户手册 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int pSize; //存放返回的剩余空间的大小 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Get FreeSize retcode = RY3_GetFreeSize(handle,&pSize); //获取剩余空间的大小 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 118 ROCKEY3 用户手册 printf("\r\n RY3_GetFreeSize()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_GetFreeSize()成功，剩余空间：%d 字节\r\n",pSize); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.7 RY3_LEDControl DWORD WINAPI RY3_LEDControl(RY_HANDLE handle, int flag); 说明： 控制指示灯。调用该函数前需要先打开设备（RY3_Open）。 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle flag [in]指令。 注意事项： flag 值的宏定义： #define ET_LED_ON 1 //指示灯亮 #define ET_LED_OFF 2 //指示灯灭 #define ET_LED_WINK 3 //指示灯闪烁 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 119 ROCKEY3 用户手册 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 120 ROCKEY3 用户手册 //Control LED retcode = RY3_LEDControl(handle,ET_LED_WINK); //指示灯闪烁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_LEDControl()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_LEDControl()成功，指示灯闪烁\r\n"); printf("请按任意键："); getchar(); retcode = RY3_LEDControl(handle,ET_LED_OFF); //指示灯灭 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_LEDControl()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_LEDControl()成功，指示灯灭\r\n"); printf("请按任意键："); getchar(); retcode = RY3_LEDControl(handle,ET_LED_ON); //指示灯亮 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_LEDControl()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_LEDControl()成功，指示灯亮\r\n"); //close 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 121 ROCKEY3 用户手册 retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.8 RY3_VerifyDevPin DWORD WINAPI RY3_VerifyDevPin(RY_HANDLE handle, char* pInPin, int* pRemainCount); 说明： 验证开发商口令，以取得相应权限。调用该函数前需要先打开设备（RY3_Open）。 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle *pInPin [in]口令指针，指向要校验的口令字符串。 *pRemainCount [out]口令重试次数指针。 注意事项： „ 开发商口令默认没有重试次数的限制，可以无限次重试。如果开发商设置了重试次数，那么 当连续输错的次数超过了设定的次数，则口令被锁死。开发商口令默认值： “123456781234567812345678”。 „ 调用此函数成功时，参数*pRemainCount 返回值：0。 „ 函数返回错误编码：0xF0000CXX 时，表示密码错误，最后两位 XX，是口令重试次数。参数 *pRemainCount 返回值为口令的重试次数：0:已锁死 1‐254:剩余次数 „ 函数返回其他错误编码时，参数*pRemainCount 返回值：0。 „ 开发商口令的长度必须是 24 字节。 255:无限制。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 122 ROCKEY3 用户手册 RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 123 ROCKEY3 用户手册 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功\r\n"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.9 RY3_SetVendorID DWORD WINAPI RY3_SetVendorID(RY_HANDLE handle, char* pSeed, int len, char* pOutVendorID); 说明： 为设备设置开发商 ID。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pSeed [in]指向种子码的指针。 len *pOutVendorID [in]种子码的长度。 [out]指向开发商 ID 的指针。 注意事项： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 124 ROCKEY3 用户手册 „ 用户给出的用于生成开发商 ID 的种子是最大长度是 250 字节的字符串，返回的开发商 ID 为 8 字节的字符串。 „ 调用此函数前必须验证开发商口令。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 125 ROCKEY3 用户手册 printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功\r\n"); //set vendorID char seed[10]="12345"; //种子码 char buf[10]; //存放输出的 8 字节开发商 ID， memset(buf, 0, sizeof(buf)); retcode = RY3_SetVendorID(handle, seed, lstrlen(seed), buf); //设置开发商 ID if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_SetVendorID()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_SetVendorID()成功，开发商 ID：%s\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 126 ROCKEY3 用户手册 { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.10 RY3_ChangeDevPin DWORD WINAPI RY3_ChangeDevPin(RY_HANDLE handle, char* pOldPin, char* pNewPin, int TryCount); 说明： 修改开发商口令，修改成功后取得相应的权限。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pOldPin [in]旧口令指针。 *pNewPin [in]新口令指针。 TryCount [in]口令重试次数。 注意事项： „ 参数 TryCount，设置口令的重试次数。取值范围为 1‐255, 其中 255 表示无限制。 „ 修改口令的接口中包括了验证口令的功能，因此涉及到口令锁死的问题，请参见 RY3_VerifyDevPin 接口中的注意事项。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com //指定开发商 ID 127 ROCKEY3 用户手册 int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Change DevPin char OldPin[30]="123456781234567812345678"; //开发商口令 char NewPin[30]="111111111111111111111111"; //新密码 retcode = RY3_ChangeDevPin(handle, OldPin, NewPin, 255); //修改开发商口令，口令 重试次数不限制。 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_ChangeDevPin()错误，错误码：%08X \r\n", retcode); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 128 ROCKEY3 用户手册 return; } printf("\r\n RY3_ChangeDevPin()成功\r\n"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.11 RY3_Read DWORD WINAPI RY3_Read(RY_HANDLE handle, int offset, BYTE* pOutbuf, int len); 说明： 读取加密锁数据存储区的内容。调用该函数前需要先打开设备（RY3_Open）。 参数： handle offset *pOutbuf len [in]设备的句柄，与 RY3_Open 返回的句柄一致。 [in] 偏移地址，即读取位置。 [out]缓冲区指针，成功时返回读取的内容。 [in]读取长度。 注意事项： 数据存储区的大小为 8192 字节。其中 0‐7168 字节为低级存储区，7169‐8192 字节为高级存储区，调 用此函数可以读取所有存储区的内容。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 129 ROCKEY3 用户手册 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Read Memery int offset = 0; //偏移地址 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 130 ROCKEY3 用户手册 int len = 10; //读取长度 BYTE buf[30]; //存放读出的数据 memset(buf, 0, sizeof(buf)); retcode = RY3_Read(handle, offset, buf, len); //读取加密锁数据存储区的内容 //偏移地址 0 读取长度 10 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Read()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Read()成功，读取内容：%08X\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.12 RY3_Write DWORD WINAPI RY3_Write(RY_HANDLE handle, int offset, BYTE* pInbuf, int len); 说明： 在加密锁低级数据存储区写入内容。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 131 ROCKEY3 用户手册 offset [in]偏移地址，即写入位置。 *pInbuf [in]缓冲区指针，存放要写入的内容。 len [in]写入长度。 注意事项： 数据存储区的大小为 8192 字节。其中 0‐7168 字节为低级存储区，7169‐8192 字节为高级存储区，调 用此函数只能在低级存储区（0‐7168）写入内容。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 132 ROCKEY3 用户手册 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Write Memery int offset = 0; //偏移地址 int len = 5; //写入数据的长度 BYTE buf[10]="hello"; //存放读出的数据 retcode = RY3_Write(handle, offset, buf, len); //在加密锁数据存储区写入内容 //偏移地址 0 长度 5 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Write()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Write()成功，写入内容：%s\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 133 ROCKEY3 用户手册 7.1.13 RY3_VendorWrite DWORD WINAPI RY3_VendorWrite(RY_HANDLE handle, int offset, BYTE* pInbuf, int len); 说明： 开发商在加密锁数据存储区写入内容。此函数只能开发商使用。调用该函数前需要先打开设备 （RY3_Open），并验证开发商口令。 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle [in] 偏移地址，即写入位置。 offset *pInbuf [in]缓冲区指针，存放要写入的内容。 len [in]写入长度。 注意事项： „ 数据存储区的大小为 8192 字节，其中 0‐7168 字节为低级存储区，7169‐8192 字节为高级存 储区。 „ 此函数可以在所有数据存储区写入内容，包括高级存储区，所以此函数只能开发商使用，调 用前必须验证开发商密码（RY3_VerifyDevPin）。 返回值： 返回RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看7.2.1错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 134 ROCKEY3 用户手册 { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin char pInPin[30]="111111111111111111111111"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //Write Memery 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 135 ROCKEY3 用户手册 int offset = 0; //偏移地址 int len = 5; //写入数据的长度 BYTE buf[10]="hello"; //存放读出的数据 retcode = RY3_VendorWrite(handle, offset, buf, len); //在加密锁数据存储区写入内 容 //偏移地址 0 长度 5 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VendorWrite()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_VendorWrite()成功，写入内容：%s\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.14 RY3_ReadShare DWORD WINAPI RY3_ReadShare(RY_HANDLE handle, int offset, BYTE* pbuf, int len); 说明： 读取加密锁共享内存区的内容。调用该函数前需要先打开设备（RY3_Open）。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 136 ROCKEY3 用户手册 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle offset *pbuf [in] 偏移地址，即读取位置。 [out]缓冲区指针，成功时返回读取的内容。 len [in]读取长度。 注意事项： 共享内存区的大小为 32 字节。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 137 ROCKEY3 用户手册 retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Read Share int offset = 0; //偏移地址 int len = 10; //读取长度 BYTE buf[30]; //存放读出的数据 memset(buf, 0, sizeof(buf)); retcode = RY3_ReadShare(handle, offset, buf, len); //读取加密锁共享内存区的内容 //偏移地址 0 读取长度 10 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_ReadShare()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_ReadShare()成功，读取内容：%08X\r\n",buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 138 ROCKEY3 用户手册 printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.15 RY3_WriteShare DWORD WINAPI RY3_WriteShare(RY_HANDLE handle, int offset, BYTE* pbuf, int len); 说明： 在加密锁共享内存区写入的内容。调用该函数前需要先打开设备（RY3_Open）。 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle offset [in] 偏移地址，即写入位置。 *pbuf [in]缓冲区指针，存放要写入的内容。 len [in]写入长度。 注意事项： 共享内存区的大小为 32 字节。写入的内容不能大于 32 字节。用户可以通过对共享内存区的操作，来 防止多机共享和防止 USB 通讯数据模拟。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 139 ROCKEY3 用户手册 { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Write Share int offset = 0; //偏移地址 int len = 5; //写入数据的长度 BYTE buf[10]="hello"; //写入的数据 retcode = RY3_WriteShare(handle, offset, buf, len); //在加密锁共享内存区写入内容 //偏移地址 0 长度 5 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_WriteShare()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_WriteShare()成功，写入内容：%s\r\n",buf); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 140 ROCKEY3 用户手册 //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.16 RY3_CreateFile DWORD WINAPI RY3_CreateFile(RY_HANDLE handle, WORD FileID, int Size, int Type); 说明： 创建文件。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle FileID Size [in]设备的句柄，与 RY3_Open 返回的句柄一致。 [in] 文件 ID。 [out]文件大小。 Type [in]文件类型。 注意事项： „ ROCKEY3 提供的用户可用空间为 32k。 „ 文件 ID 为 2 字节。如：0x1002、0x009B。ROCKEY3 中有些 ID 是内部使用的，用户不能使用。 详见附录。 „ 创建文件要指定文件的大小，此时指定的大小不包括文件属性信息（16 字节） 。如：创建 100 字节的文件时（Size=100），实际占用的空间为 100+16=116 字节。 „ 通过参数 Type 设置文件类型，文件类型参见下表： FILE_TYPE_EXE 可执行文件。可执行文件在开发商口令验证后可以写 入，或者通过 ROCKEY3 内部的其他可执行文件写 入，但任何情况下都不能读取可执行文件中的内容。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 141 ROCKEY3 用户手册 FILE_TYPE_DATA 内部数据文件。通过 ROCKEY3 内部的可执行文件 进行读写。外部操作只能在开发商口令验证后可以删 除或着写入，但是不能读。 FILE_TYPE_RSA_PUBLIC RSA 公钥文件。公钥文件在开发商口令验证后可以 写入，或者可以通过 ROCKEY3 内部的可执行文件 进行读写。 FILE_TYPE_RSA_PRIVATE RSA 私钥文件。私钥文件在开发商口令验证后可以 写入，或者可以通过 ROCKEY3 内部的可执行文件 进行写入，但任何情况下都不能读取私钥文件中的数 据。 表 7­1 文件类型 文件类型的宏定义： #define FILE_TYPE_EXE 0 #define FILE_TYPE_DATA //可执行文件 1 //数据文件 2 //RSA 公钥文件 #define FILE_TYPE_RSA_PRIVATE 3 //RSA 私钥文件 #define FILE_TYPE_RSA_PUBLIC 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 142 ROCKEY3 用户手册 } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //Create File WORD fileID = 0x1002; //偏移地址 int fileSize = 100; //写入数据的长度 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 143 ROCKEY3 用户手册 retcode = RY3_CreateFile(handle, fileID, fileSize, FILE_TYPE_DATA); //在加密锁 内存创建内部数据文件 // 文 件 ID=1002 长度 100 字节 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_CreateFile()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_CreateFile()成功，创建文件成功"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.17 RY3_WriteFile DWORD WINAPI RY3_WriteFile(RY_HANDLE handle, WORD FileID,int offset,BYTE* pbuf,int Size); 说明： 写入文件内容。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle FileID [in]设备的句柄，与 RY3_Open 返回的句柄一致。 [in]文件 ID。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 144 ROCKEY3 用户手册 offset [in]偏移地址，即写入位置。 pbuf [in]缓冲区指针，存放要写入的内容。 Size [in]写入大小。 注意事项： „ ROCKEY3 提供的用户空间为 32k。 „ 在向文件写入数据时，要保证该文件存在，如果文件不存在，需要先创建文件（RY3_CreateFile）。 „ 文件 ID 为 2 字节。如：0x1002、0x009B。ROCKEY3 中有些 ID 是内部使用的，用户不能使用。 详见附录。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 145 ROCKEY3 用户手册 retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //Create File WORD fileID = 0x1006; //偏移地址 int fileSize = 100; //写入数据的长度 retcode = RY3_CreateFile(handle, fileID, fileSize, FILE_TYPE_DATA); //在加密锁 内存创建数据文件 //文件 ID=1006 长 度 100 字节 if ( retcode != RY3_SUCCESS) 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 146 ROCKEY3 用户手册 { printf("\r\n RY3_CreateFile()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_CreateFile()成功，创建文件成功"); //Write File int offset = 0; //偏移 BYTE buf[30]="hello"; retcode = RY3_WriteFile(handle, fileID, offset, buf, fileSize); //写入文件内容 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_WriteFile()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_WriteFile()成功，写入文件成功"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.18 RY3_ExecuteFile DWORD WINAPI RY3_ExecuteFile(RY_HANDLE handle, WORD FileID, 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 147 ROCKEY3 用户手册 BYTE* pInBuf, int InSize, BYTE* pOutBuf, int* pOutSize); 说明： 执行指定的可执行文件。调用该函数前需要先打开设备（RY3_Open）。 参数： [in]设备的句柄，与 RY3_Open 返回的句柄一致。 handle FileID [in]文件 ID。 *pInBuf [in]输入缓冲区指针，存放传给可执行文件（C51 程序）的数据。 InSize [in]传入数据的长度。 *pOutBuf [out]输出缓冲区指针，存放由可执行文件（C51 程序）传出的数据。 *pOutSize [in/out]可执行文件（C51 程序）返回的数据长度。 注意事项： „ 文件 ID 为 2 字节。如：0x1002、0x009B。ROCKEY3 中有些 ID 是内部使用的，用户不能使用。 详见附录。 „ pOutSize 参数：为*pOutBuf 指针所指向的输出缓冲区的长度，当该长度小于 ROCKEY3 内部的 可执行文件（C51 程序）返回的长度时，该接口将返回错误。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定客户号 int i; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 148 ROCKEY3 用户手册 //find retcode = RY3_Find(vendorID, &count); //查找指定客户号的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Execute File WORD fileID = 0x2001; //文件 ID int inSize = 10; //输入数据的长度 int outSize = 10; //输出数据的长度 BYTE inBuf[30] = "1"; BYTE outBuf[30] = "0"; retcode = RY3_ExecuteFile(handle, fileID, inBuf, inSize,outBuf,&outSize); // 运行可执行文件 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 149 ROCKEY3 用户手册 printf("\r\n RY3_ExecuteFile()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_ExecuteFile()成功，返回结果：%s\r\n",outBuf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.19 RY3_EraseAllFile DWORD WINAPI RY3_EraseAllFile(RY_HANDLE handle); 说明： 清空文件，即删除所有文件。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 注意事项： 调用此函数删除所有文件。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 150 ROCKEY3 用户手册 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com //验证开发商口令 151 ROCKEY3 用户手册 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //Erase All File retcode = RY3_EraseAllFile(handle); //清空文件 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_EraseAllFile()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_EraseAllFile()成功，清空文件成功"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.20 RY3_GenRsaKey DWORD WINAPI RY3_GenRsaKey(RY_HANDLE handle, int kid, BYTE* pPubBakup, BYTE* pPriBakup); 说明： 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 152 ROCKEY3 用户手册 产生 RSA 公私钥对。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 kid [in]公私钥对组号, 取值范围为 0‐8。 *pPubBakup [out]公钥缓冲区指针，输出 140 字节的公钥供备份。 *pPriBakup [out]私钥缓冲区指针，输出 340 字节的私钥供备份。 注意事项： „ 参数 kid，生成第几组公私钥对。取值范围为 0‐8；0 表示升级公私钥对，1‐8 表示第 1‐8 号公 私钥对。 „ *pPubBakup 或*pPriBakup 为 NULL 时，表示不备份。 „ 调用此函数时生成的 RSA 公私钥位数只支持 1024 位。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 153 ROCKEY3 用户手册 printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Verify DevPin char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //Rsa Key int kid = 1; //公私钥对组号 retcode = RY3_GenRsaKey(handle,kid,NULL,NULL); //生成 1 号公私钥对 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 154 ROCKEY3 用户手册 printf("\r\n RY3_GenRsaKey()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_GenRsaKey()成功\r\n"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.21 RY3_SetRsaKey DWORD WINAPI RY3_SetRsaKey(RY_HANDLE handle, int kid, BYTE* pPubKey, BYTE* pPriKey); 说明： 设置 RSA 公私钥对。调用该函数前需要先打开设备（RY3_Open），并验证开发商口令。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 kid [in]公私钥对组号, 取值范围为 0‐8。 *pPubKey [in]公钥缓冲区指针，输入 140 字节的公钥供写入。 [in]私钥缓冲区指针，输入 340 字节的私钥供写入。 *pPriKey 注意事项： „ 参数 kid，设置第几组公私钥对。取值范围为 0‐8；0 表示升级公私钥对，1‐8 表示第 1‐8 号公 私钥对。 „ *pPubKey 或*pPriKey 为 NULL 时，表示不写入。 „ 调用此函数时，RSA 只支持 1024 位。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 155 ROCKEY3 用户手册 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 156 ROCKEY3 用户手册 //Verify DevPin char pInPin[30]="123456781234567812345678"; //开发商口令 int pRemainCount=0; //口令重试次数 retcode = RY3_VerifyDevPin(handle, pInPin, &pRemainCount); //验证开发商口令 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_VerifyDevPin() 错 误 ， 错 误 码 ： %08X pRemainCount=%d\r\n ", retcode,pRemainCount); return; } printf("\r\n RY3_VerifyDevPin()成功，验证开发商口令成功。\r\n"); //set Rsa Key int kid = 1; //公私钥对组号 BYTE pubBuf[140]={0x00,0x00,0x00,0x80,0xa7,0x0e,0xb4,0x0a,0x41,0x2f,0x09,0x1f,0x79,0xc5,0 xe1,0x5e, 0xd4,0xe6,0xaa,0xca,0x71,0xae,0xa0,0x8c,0x8d,0x99,0x7d,0x44,0x17,0x88,0xd6,0x1c, 0xf8,0x76,0x0c,0x38,0x70,0xcc,0x59,0xa1,0xed,0xd1,0x47,0x49,0x1a,0xcd,0x0c,0xf8, 0x92,0xbb,0x59,0x65,0x5e,0x5c,0x1a,0x68,0x25,0xe8,0x47,0xe2,0x1f,0x4c,0xe8,0x2e, 0x66,0x39,0x90,0xf7,0xb0,0x8d,0x63,0xcd,0xcc,0xa0,0x93,0xe9,0xab,0xae,0xf5,0x99, 0x7b,0xa8,0x2f,0x86,0x71,0xe0,0x7c,0x81,0x7f,0x47,0xc9,0xe0,0x0e,0xe2,0x7a,0x99, 0x10,0x9f,0x7a,0x7f,0xac,0x96,0x0d,0x5d,0xcf,0xf7,0xb4,0x6b,0xbf,0xa4,0xa4,0x87, 0x84,0x81,0xb9,0x2c,0x66,0x32,0x7a,0xdc,0xcc,0x3f,0x4b,0x37,0x25,0x10,0xe5,0x75, 0xe5,0xcb,0x32,0x93,0x00,0x00,0x00,0x04,0x00,0x01,0x00,0x01, }; //公钥 BYTE priBuf[340]={0x01,0x00,0x00,0x40,0xd3,0x6b,0xd4,0x80,0xac,0xe7,0x95,0x15,0xdc,0xc2,0 x2d,0xa0, 0xae,0xe3,0xd9,0x79,0xd0,0x63,0x9d,0xad,0xab,0x44,0xe5,0x56,0xca,0xb2,0x07,0x18, 0xbd,0x59,0x2b,0xeb,0x34,0x4f,0xc6,0xe6,0x1f,0x99,0xd0,0x0b,0x71,0xab,0x03,0xe3, 0x87,0x62,0xe7,0xb0,0xbd,0x66,0xbb,0xe8,0x06,0xbf,0x9d,0x40,0xe3,0x62,0x32,0xdd, 0xd6,0x53,0x3b,0x29,0x00,0x00,0x00,0x40,0xca,0x48,0x30,0x79,0xfa,0x58,0x27,0x62, 0x18,0x8f,0x50,0x02,0x55,0x74,0x61,0x30,0xa1,0x96,0x31,0x67,0xa7,0x16,0x38,0x40, 0x75,0x67,0xcf,0xdd,0xc3,0xe6,0x4f,0x1e,0x05,0xd7,0xe3,0xaa,0x90,0xc7,0x14,0x4e, 0x23,0x02,0x72,0xbe,0x88,0x3c,0xbf,0xd1,0xe5,0x5d,0xcd,0x0f,0xb7,0xc6,0xf8,0x08, 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 157 ROCKEY3 用户手册 0x18,0xd5,0x21,0x75,0x6f,0x8c,0x33,0x5b,0x00,0x00,0x00,0x40,0x10,0x57,0xc3,0x83, 0x76,0xda,0x27,0xf2,0x1a,0xb0,0x7f,0xea,0x6d,0xda,0x7b,0x13,0x29,0x82,0xa9,0xcb, 0xa4,0xf3,0x9c,0x6e,0xcb,0x18,0x5b,0xe8,0x13,0xaa,0xf2,0xf4,0x29,0x85,0x09,0x30, 0xfc,0xbc,0x5d,0x12,0xa5,0x64,0xbc,0xd6,0x37,0xbe,0xf3,0x7d,0xfc,0x06,0x16,0xfc, 0x66,0x99,0x25,0x44,0xc0,0xce,0xf4,0x73,0xa5,0x7f,0xa5,0x91,0x00,0x00,0x00,0x40, 0x30,0x7e,0x13,0xd8,0xfa,0x11,0xee,0x07,0x0f,0x3a,0x34,0x05,0x0b,0x35,0x66,0x23, 0x41,0x69,0x7f,0x18,0x89,0x2e,0xc3,0x77,0x78,0x6d,0xd5,0xa0,0x25,0x59,0x6d,0xf8, 0x15,0x90,0x86,0xcc,0x99,0xfe,0x8f,0xb8,0x97,0x9d,0xfb,0xa1,0xff,0x89,0x08,0xb7, 0x29,0xd4,0x4d,0xd7,0x89,0xc8,0x12,0x27,0xe6,0xc4,0x19,0x4c,0x4c,0xdc,0x80,0x67, 0x00,0x00,0x00,0x40,0x9e,0x20,0x54,0x80,0x49,0x6e,0xc7,0x8d,0x39,0x87,0x61,0x5a, 0xc5,0x7f,0xb4,0x47,0xb2,0xaa,0x21,0x7b,0xce,0x73,0x4f,0x3d,0xa5,0x35,0x39,0xb9, 0x69,0xdc,0x1d,0x3b,0xe4,0x90,0xa9,0xad,0xb0,0x48,0xf5,0x46,0x8e,0x80,0x83,0xa2, 0x3d,0x3f,0xc3,0x18,0xaf,0xdb,0x72,0xf6,0x3b,0x3a,0xe7,0x60,0xe0,0x2a,0x54,0x2e, 0xff,0xb0,0x1a,0x91, }; //私钥 retcode = RY3_SetRsaKey(handle,kid,pubBuf,priBuf); //生成 1 号 RSA 公私钥对 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_SetRsaKey()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_SetRsaKey()成功\r\n"); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 158 ROCKEY3 用户手册 7.1.22 RY3_PublicEncrypt DWORD WINAPI RY3_PublicEncrypt(RY_HANDLE handle, int kid, BYTE* pBuf, int len); 说明： RSA 公钥加密。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 kid [in]密钥对组号, 取值范围为 1‐8。 *pBuf [in]缓冲区指针，存放要加密的数据。 len [in]数据长度，必须为 128 的整数倍。 注意事项： „ 参数 kid，设置生成第几组密钥对。取值范围为 1‐8。 „ 加密的数据长度必须是 128 的整数倍。 „ RSA 加解密时，算法 RY3_PublicEncrypt 通常用来做公钥加密，实际此函数也可以用来对公钥解 密。但是 RY3_PublicEncrypt 必须对应公钥。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： 见 RY3_PrivateDecrypt 的示例。 7.1.23 RY3_PrivateDecrypt DWORD WINAPI RY3_PrivateDecrypt(RY_HANDLE handle, int kid, BYTE* pBuf, int len); 说明： RSA 私钥解密。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 kid [in]密钥对组号, 取值范围为 1‐8。 *pBuf [out]缓冲区指针，存放解密的数据。 len [in]数据长度，必须为 128 的整数倍。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 159 ROCKEY3 用户手册 注意事项： „ 参数 kid，设置生成第几组密钥对。取值范围为 1‐8。 „ 加密的数据长度必须是 128 的整数倍。 „ RSA 加解密时，算法 RY3_PrivateDecrypt 通常用来做私钥解密，实际此函数也可以用来对私钥 加密。但是 RY3_PrivateDecrypt 必须对应私钥。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 160 ROCKEY3 用户手册 printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //Public Encrypt int kid = 1; //公私钥对组号 int len =128; //数据长度 BYTE buf[128]="hello"; retcode = RY3_PublicEncrypt(handle,kid,buf,len); //RSA 公钥加密 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_PublicEncrypt()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_PublicEncrypt()成功\r\n"); //Public Encrypt BYTE rbuf[128]; //存放解密数据 memset(rbuf, 0, sizeof(rbuf)); retcode = RY3_PrivateDecrypt(handle,kid,rbuf,len); //RSA 私钥解密 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_PrivateDecrypt()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_PrivateDecrypt()成功，解密后数据为：%08X\r\n",rbuf); //close 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 161 ROCKEY3 用户手册 retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.24 RY3_MD5 DWORD WINAPI RY3_MD5(RY_HANDLE handle, BYTE* pBuf, int len, BYTE* pMD5); 说明： 使用 MD5 散列算法进行加密运算。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pBuf [in]缓冲区指针，存放要进行运算的数据。 len [in]数据长度。 *pMD5 [out]缓冲区指针，存放运算后的数据,长度为 16 字节。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 162 ROCKEY3 用户手册 //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //MD5 int len =5; //数据长度 BYTE buf[10]="hello"; //要加密数据 BYTE md5Buf[20]; memset(md5Buf, 0, sizeof(md5Buf)); retcode = RY3_MD5(handle,buf,len,md5Buf); //MD5 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_MD5()错误，错误码：%08X \r\n", retcode); return; } 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 163 ROCKEY3 用户手册 printf("\r\n RY3_MD5()成功，加密后数据为：%08X\r\n",md5Buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.25 RY3_SHA1 DWORD WINAPI RY3_SHA1(RY_HANDLE handle, BYTE* pBuf, int len, BYTE* pSHA1); 说明： 使用 SHA1 散列算法进行加密运算。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 *pBuf [in]缓冲区指针，存放要进行运算的数据。 len [in]数据长度。 [out]缓冲区指针，存放运算后的数据,长度为 20 字节。 *pSHA1 注意事项： „ 散列结果也会在 COS 内部保留，COS 内部存在一个 Buffer 会保存上一次散列计算的结果。 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 164 ROCKEY3 用户手册 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); //SHA1 int len =5; //数据长度 BYTE buf[10]="hello"; //要加密数据 BYTE sha1Buf[30]; memset(sha1Buf, 0, sizeof(sha1Buf)); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 165 ROCKEY3 用户手册 retcode = RY3_SHA1(handle,buf,len,sha1Buf); //SHA1 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_SHA1()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_SHA1()成功，加密后数据为：%08X\r\n",sha1Buf); //close retcode = RY3_Close(handle, TRUE); //关闭加密锁，并清除安全状态 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Close()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Close()成功，关闭第%d 把加密锁\r\n", i); } 7.1.26 RY3_Set3DESKey DWORD WINAPI RY3_Set3DESKey(RY_HANDLE handle, int kid, BYTE* pKey); 说明： 设置 3DES 加/解密的密钥。调用该函数前需要先打开设备（RY3_Open）。 参数： handle [in]设备的句柄，与 RY3_Open 返回的句柄一致。 kid [in]密钥对组号, 取值范围为 1‐8。 *pKey [in]缓冲区指针，存放密钥。 注意事项： „ 参数 kid，设置生成第几组密钥对。取值范围为 1‐8。 „ 密钥长度固定为 16 字节。 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 166 ROCKEY3 用户手册 返回值： 返回 RY3_SUCCESS（0x00000000）表示成功。返回其它值表示执行该函数失败，参看 7.2.1 错误编码。 举例： RY_HANDLE handle = 0; //设备的句柄 DWORD retcode; //错误码 int count = 0; //查找到的加密锁个数 char vendorID[10]="A8C3E6FD"; //指定开发商 ID int i; //find retcode = RY3_Find(vendorID, &count); //查找指定开发商 ID 的加密锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Find()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Find()成功，查找到的加密锁个数：%d\r\n", count); for(i=1; i<=count; i++) { //open retcode = RY3_Open(&handle, i); //打开第 i 把锁 if ( retcode != RY3_SUCCESS) { printf("\r\n RY3_Open()错误，错误码：%08X \r\n", retcode); return; } printf("\r\n RY3_Open()成功，打开第%d 把加密锁\r\n", i); 版权所有 © 北京飞天诚信科技有限公司 公司网址： www.FTsafe.com 167 ROCKEY3 用户手册 //set ES Key int kid = 1; //密钥对组号 BYTE buf[16];//密钥 for(int j=0; j