格尔加密Token接口与信息格式标准_2009

上海格尔软件股份有限公司1格尔加密Token 接口与信息格式标准v1.40上海格尔软件股份有限公司2003年11月上海格尔软件股份有限公司2修改记录上海格尔软件股份有限公司3上海格尔软件股份有限公司4 目录1简介 (6)1.1目的 (6)1.2概述 (6)2加密Token接口标准 (6)2.1介绍 (6)2.1.1关于KPSDK及Token (6)2.1.2关于KPSDK插件Token开发包 (7)2.2使用说明 (8)2.2.1提供形式及环境要求 (8)2.2.2插件Token需要提供的功能 (8)2.2.3接口说明 (8)2.2.4类型和结构声明 (13)2.2.5函数声明 (17)2.3插件Token实现指南 (17)2.3.1插件Token程序结构 (17)2.3.2插件Token实现细节 (18)2.4接口函数说明 (18)2.4.1Initialize/Finalize (18)2.4.2Slot信息 (20)2.4.3设备/Token管理 (21)2.4.4PIN管理 (24)2.4.5数据管理 (27)2.4.6RSA算法 (30)2.4.7对称算法 (34)2.4.8摘要函数 (37)2.4.9随机数函数 (38)上海格尔软件股份有限公司52.4.10可选接口 (39)2.4.11预留接口 (41)2.5对接口的说明 (49)3加密Token信息格式标准及安全控制标准(可选) (51)3.1安全标准 (51)3.1.1文件结构 (51)3.1.2结构说明 (52)3.1.3PIN的保护机制 (55)3.1.4介质算法功能需求 (56)3.2接口形式 (56)3.2.1PCSC接口 (56)3.2.2COS手册 (56)3.2.3洗卡指令流水 (56)4关于Token接口和厂商CSP兼容性的说明 (56)4.1介绍 (56)4.2兼容性说明 (57)4.2.1关于应用主目录 (57)4.2.2关于文件ID (57)4.2.3关于Format函数 (57)上海格尔软件股份有限公司61.1目的本文档介绍上海格尔软件股份有限公司与Key等应用厂商的相关接口标准。

1.2概述格尔公司在现在信息CA，浙江CA项目等大量开发实践的指导下，借鉴业界标准（包括PKCS#11,微软CSP,PKCS#15,《中国金融集成电路（IC）卡规范》等），考虑Key应用兄弟厂商的工作量，定义了和Key应用厂商之间的加密token 接口表准和加密信息格式标准。

加密token接口标准规范了加密设备与加密应用之间的接口，也有利于各加密设备的协同工作。

加密token信息格式标准规范了私密信息在加密设备中的存取方式，也可据此实现私密信息的安全存取。

对于某些项目，用户可能更加看重兼容性方面的需求。

例如加密token信息接口标准和各厂商自己CSP之间的兼容等。

这时，加密token信息格式标准可不实现。

2.1介绍2.1.1关于KPSDK及TokenKPSDK的全称是KOAL PKI SDK，它是基于PKI应用而开发的软件开发包。

上海格尔软件股份有限公司7它为应用程序开发者提供安全平台接口，应用软件通过它可以使用KOAL证书及其它PKI应用。

KPSDK通过Token程序支持使用各种不同的加密设备，只要加密设备开发者提供使用加密设备的API，就可以编写针对这种加密设备的Token程序，之后KPSDK就可以使用这种加密设备。

2.1.2关于KPSDK插件Token开发包对于每一种具体的加密设备，KPSDK一般需要编写特定于这个加密设备的Token程序才能使用之，这需要不小的开发量，同时这种方式对于希望自己编写Token程序的用户也是不适合的。

KPSDK插件Token开发包的目的是尽可能减少用户开发Token程序的工作量，使得用户在程序中只需要关心与加密设备具体相关的操作，而无须考虑KPSDK的要求，就可以实现加密设备与KPSDK的集成。

上海格尔软件股份有限公司82.2使用说明2.2.1提供形式及环境要求KPSDK插件Token开发包包括以下三个组成部分：包含文件、使用说明。

其中包含文件是编译插件Token程序必需的，它规定了插件Token提供的函数的原型。

编译插件Token，首先需要安装一个支持编译Windows程序的C编译器，推荐使用Microsoft VC 6.0，开发包中的例子就是使用VC编写的。

2.2.2插件Token需要提供的功能插件Token一般需要提供两种类型的功能：数据管理和密码运算。

2.2.3接口说明PlugToken.h包含以下的部分：常量定义、类型和结构说明、函数声明。

2.2.3.1插件版本常量图表1 插件版本常量图表2 插件功能常量9上海格尔软件股份有限公司图表3 RSA位数常量2.2.3.4算法类型常量图表4 算法类型常量2.2.3.5算法模式常量图表5 算法模式常量10上海格尔软件股份有限公司上海格尔软件股份有限公司112.2.3.6 设备状态常量图表6 设备状态常量2.2.3.7 PIN 类型常量图表 7 PIN 类型常量2.2.3.8 函数返回值常量上海格尔软件股份有限公司12图表 8 函数返回值常量2.2.3.9 文件类型常量图表 9 文件类型常量2.2.3.10 文件访问权限常量上海格尔软件股份有限公司13图表10 文件访问权限常量读文件权限掩码和写文件权限掩码的含义是：在CreateFile时候指定了一个文件访问权限，这是一个DWORD，这个值是由读文件权限和写文件权限两部分组成，即：dwAccessPriviledge = dwReadPriviledge | dwWritePriviledge;插件在CreateFile的实现里面，需要获得具体的读文件权限和写文件权限，可以把访问权限和读文件权限掩码相与得到读文件权限，把访问权限和写文件权限掩码相与得到写文件权限，即：dwReadPriviledge = dwAccessPriviledge & READ_PRIVILEDGE_MASK;dwWritePriviledge = dwAccessPriviledge & WRITE_PRIVILEDGE_MASK;2.2.4类型和结构声明2.2.4.1PT_VERSION和PPT_VERSIONPT_VERSION定义了插件Token版本的类型，它实际上是一个DWORD（四字节字），当前使用PLUGTOKEN_V30。

PPT_VERSION是指向PT_VERSION的指针。

2.2.4.2PT_Slot_Info和PPT_Slot_InfoPT_Slot_Info定义了Slot的各种信息，具体包括：上海格尔软件股份有限公司14图表11 PT_Slot_Info结构成员PPT_Slot_Info是指向PT_Slot_Info的指针。

szManufacturerID填写厂商标志，必须是0结尾的字符串，比如：“IdeaBank Technology Co.,Ltd.”szSlotDescription填写Slot描述，必须是0结尾的字符串，比如IdeaBank EKey 加密模块，最后面的“加密模块”是统一的格式需要保留，前面填写硬件信息。

2.2.4.3PT_Token_Info和PPT_Token_InfoPT_Token_Info定义了Token的各种信息，具体包括：上海格尔软件股份有限公司15图表12 PT_Token_Info结构成员PPT_Token_Info是指向PT_Token_Info的指针。

nAlgoCap一般为0x2004(TP_HARDWARE_CRYPTO|TP_RSA_1024_BITS)，其他位数的RSA密钥不需要支持，如果支持可以在这里设置，对称算法不需要在这里设置。

szSerialNumber是一个0结尾的字符串，包含了唯一标识硬件的信息，里面最多可以放15个字符（因为需要0结尾），如果硬件序列号信息是二进制形式，需要编码为可读形式，比如使用“AABBCCDD”这个字符串表示0xAA,0xBB,0xCC,0xDD这四个字节的二进制信息，如果硬件信息较长，也可以使用Base64编码的方法以节省空间。

szManufacturerID、szSlotDescription、szSerialNumber和szLabel都是0结尾字符串。

szLabel的一个例子是IdeaBank KEY TOKEN(VER2.1.6)，后面的“TOKEN(2.1.6)”是统一的格式需要保留，前面可以填写具体的硬件信息。

2.2.4.4PT_PlugToken_Function_2_0和PPT_PlugToken_Function_2_0PT_PlugToken_Function_2_0定义了包括插件Token输出函数的结构的1.0版本，它包括以下成员：16 上海格尔软件股份有限公司上海格尔软件股份有限公司17图表13 PT_PlugToken_Function_2_0结构成员PPT_PlugToken_Function_2_0是指向PT_PlugToken_Function_2_0的指针。

上面表中，带下划线的函数是可选函数，由各应用产商根据实际情况决定是否实现；斜体函数是预留函数，目前可不用实现；里面打“*”的函数一般也需实现，只对于实现加密Token信息格式标准的厂商可不实现。

2.2.5函数声明PlugToken.h中包含了插件Token需要输出的函数的原型，并且定义了用于KPSDK调用插件Token的函数指针类型，具体情况参见下一节“插件Token实现指南”。

2.3插件Token实现指南2.3.1插件Token程序结构插件Token编译成一个Windows的动态链接库，由KPSDK调用其中的功能，上海格尔软件股份有限公司18它必须输出两个函数：PlugInitialize和PlugFinalize，其他函数不直接输出，KPSDK 通过调用PlugInitialize获取其它函数的指针。

2.3.2插件Token实现细节PlugInitialize返回的函数结构中，插件Token只需填写自己实现了的函数，未实现的函数的位置填写NULL即可。

Token至少需要实现数据管理功能。

插件Token程序在包含PlugToken之前，需要定义PLUGTOKEN_IMPLEMENT 宏。

各种接口函数的返回值一般为PLUG_RV类型，如果函数正确完成，则应该返回RV_OK（0），任何其他返回值都将被视作失败。

2.4接口函数说明2.4.1Initialize/Finalize2.4.1.1PlugInitialize（插件初始化）函数原型：PLUG_RVPlugInitialize(IN PLUGTYPE nPlugType,IN PLUG_VERSION dwVersionRequired,OUT PPLUG_VERSION pdwPlugVersion,OUT PVOID * ppPlugFunctions);参数：dwPlugType: 插件类型，对于Token插件应该传入PLUGTYPE_TOKEN上海格尔软件股份有限公司19dwVersionRequired: 外部要求的最低版本pdwPlugVersion: 返回当前Token使用的函数列表结构的版本ppPlugFunctions: 传出Token支持的函数列表的指针返回值：参见错误值列表函数功能及说明：本函数用于初始化插件，调用方传入需要调用插件的类型和插件的最低版本号，Token插件检测到传入的类型为PLUGTYPE_TOKEN并且自身支持的版本不低于外部要求的最低版本，则返回自身支持的函数列表的指针，并且返回自身的版本号。