新底层密钥体系详解2013.4.12

1、 1 使用流程以下写的都是针对新底层安全库部分的用法2 使用注意事项a.每次开机进入应用程序一定要做密码键盘初始化，初始化过程实现自动检测密码键盘类型和密码键盘bps。b.第一次装载密钥建议初始化密钥区，如果是825-6初始化时间大约30秒左右c.为显示上兼容，在密码键盘上显示时一行内容不要超过15个字节,显示完后请调用PubClrPinPad函数恢复默认显示。d.由于zt579e18不支持显示汉字，zt579c47显示汉字方式和nl系列密码键盘不同，建议在程序中不要显示汉字，都用英文显示，否则程序要增加判断密码键盘类型。e.nl825-6密码键盘支持0-167组密钥，由于考虑到x99 3de

2、s算法的兼容，在每装载一组密钥时库里面自动多装载一次，因此实际的密码组数是073，因新的密钥体系外接密码键盘部分支持Pin、Mac、Track、Data四组密钥，所以实际密码组数是0-36。f.在调用PubGetPin取密码时，如果按确认键返回表示无密码，此时可以通过第一个输出参数pszPin是否有内容来判断是否有密码。g.在中行IST版程序中如果是3DES密钥，由于主密钥不能参加MAC运算，因此需要将主密钥当作工作密钥再保存一次。3 接口说明3.1 PubInitSecrity函数名称：int PubInitSecrity(int nMode,const STPINPADPARAM* pst

3、PinpadParam);函数介绍：初始化安全库函数描述：完成密码键盘自适应、设置波特率、密码键盘类型的初始化工作，指定初始化内置还是外接密码键盘。入口参数：nMode 详见：EM_SECRITY_MODESTPINPADPARAM：密码键盘参数出口参数：无返 回 值：APP_SUCC成功 其它失败3.2 PubSetCurrentMainKeyIndex函数名称：int PubSetCurrentMainKeyIndex(int nIndex)函数介绍：设置当前主密钥索引号函数描述：无入口参数：nIndex索引号出口参数：无返 回 值：APP_SUCC成功 其它失败3.3 PubLoadMa

4、inKey函数名称：int PubLoadMainKey(int nIndex,const char* psKey, int nKeyLen)函数介绍：安装主密钥函数描述：无入口参数：nIndex索引号psKey 主密钥明文（BCD码）nKeyLen 主密钥长度 8字节或16字节出口参数：无返 回 值：APP_SUCC成功 其它失败3.4 PubLoadWorkKey函数名称：int PubLoadWorkKey(int nKeyType,const char* psKey, int nKeyLen,const char* psCheckValue)函数介绍：安装工作密钥函数描述：无入口参数：

5、nKeyType 安装的工作密钥类型（详见：EM_KEY_TYPE）psKey 工作密钥密文（BCD码）nKeyLen 工作密钥长度 8字节或16字节出口参数：psCheckValue 校验值返 回 值：APP_SUCC成功 其它失败3.5 PubGetPin函数名称：int PubGetPin(char *pszPin, int *pnPinLen, int nMode, const char *pszCardno,const char *pszAmount,int nMaxLen, int nMinLen);函数介绍：获取Pin函数描述：支持多种加密算法。实现密码最大最小长度的设置，显示无

6、密码时，按确认键。密码输入提示在第二行、输入时以星号显示，密码输完，清除屏幕到默认状态；入口参数：nMode 密码加密模式（详见：EM_PIN_TYPE）pszCardno 卡号pszAmount 金额nMaxLen 最大的密码长度nMinLen 最小的密码长度出口参数：pszPin 输入的PinpnPinLen 输入Pin的长度返 回 值：APP_SUCC成功 其它失败3.6 PubGetPinExtern函数名称：int PubGetPinExtern(char *pszPin, int *pnPinLen, int nMode, const char *pszCardno,int nMa

7、xLen, int nMinLen,void (*ShowFunc)();函数介绍：获取Pin函数描述：支持自定义POS界面显示函数入口参数：nMode 密码加密模式（详见：EM_PIN_TYPE）pszCardno 卡号nMaxLen 最大的密码长度nMinLen 最小的密码长度ShowFunc 显示函数出口参数：pszPin 输入的PinpnPinLen 输入Pin的长度返 回 值：APP_SUCC成功 其它失败3.7 PubCalcMac函数名称：int PubCalcMac(int nMode,const char * psData,int nDataLen,char * psMac)

8、;函数介绍：获取Mac函数描述：无入口参数：nMode 计算Mac算法类型（详见：EM_MAC_TYPE）psData 计算Mac的数据nDataLen 数据长度出口参数：psMac Mac值返 回 值：APP_SUCC成功 其它失败3.8 PubActiveKey函数名称：int PubActiveKey( int nMode, int nIndex, int nActiveKeyType);函数介绍：激活工作密钥函数描述：算及输入密码函数前需先调用此操作入口参数：nMode 激活模式（DESMODE_DES、DESMODE_3DES）nIndex索引号nActiveKeyType激活的类型

9、（0-KEY_TYPE_PIN / 1-KEY_TYPE_MAC /2-KEY_TYPE_TRACK）出口参数：无返 回 值：APP_SUCC成功 其它失败3.9 PubClearKey函数名称：int PubClearKey(void);函数介绍：清空密钥区函数描述：无入口参数：无出口参数：无返 回 值：APP_SUCC成功 其它失败3.10 PubDispPinPad 函数名称：int PubDispPinPad (int nLine, const char *pszData);函数介绍： 在密码键盘上显示数据函数描述：无入口参数：nLine 指定的行1,2pszData 待显示的字符串出

10、口参数：无返 回 值：APP_SUCC成功 其它失败3.11 PubClrPinPad函数名称：int PubClrPinPad(void);函数介绍： 密码键盘恢复默认显示界面函数描述：无入口参数：无出口参数：无返 回 值：APP_SUCC成功 其它失败3.12 PubDispDot函数名称：int PubDispDot(int nLine, const char *pszDotData, int nDataLen);函数介绍： 在密码键盘液晶屏的指定行，显示中文字符串函数描述：无入口参数：nLine 指定的行数1,2pszDotData 待显示的数据nDataLen 待显示的数据长度出口参

11、数：无返 回 值：APP_SUCC成功 其它失败3.13 PubGetSecrityVerion函数名称：void PubGetSecrityVerion(char *pszVer);函数介绍：获取安全模块版本函数描述：注意pszVer空间不能小于12个入口参数：无出口参数：pszVer 12字节版本号返 回 值：APP_SUCC成功 其它失败3.14 PubDes函数名称：int PubDes(int nKeyType,const char* psSrc,char *psDest);函数介绍：Des加密数据函数描述：无入口参数：nKeyType 密钥类型（详见：EM_KEY_TYPE）psS

12、rc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.15 PubUnDes函数名称：int PubUnDes(int nKeyType,const char* psSrc,char *psDest);函数介绍：Des解密数据函数描述：无入口参数：nKeyType 密钥类型（详见：EM_KEY_TYPE）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.16 PubDes3函数名称：int PubDes3(int nKeyType,const cha

13、r* psSrc,char *psDest);函数介绍：3Des加密数据函数描述：无入口参数：nKeyType 密钥类型（详见：EM_KEY_TYPE）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.17 PubUnDes3函数名称：int PubUnDes3(int nKeyType,const char* psSrc,char *psDest);函数介绍：3Des解密数据函数描述：无入口参数：nKeyType 密钥类型（详见：EM_KEY_TYPE）psSrc 数据（8字节BCD码）出口参数：psDest 密文

14、 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.18 PubSoftDes函数名称：int PubSoftDes(const char* psKey,const char* psSrc,char *psDest);函数介绍：Des软加密函数描述：无入口参数：psKey 明文密钥（8字节BCD码）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.19 PubSoftUnDes函数名称：int PubSoftUnDes(const char* psKey,const char* psSrc,char *

15、psDest);函数介绍：Des软解密函数描述：无入口参数：psKey 明文密钥（8字节BCD码）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败3.20 PubSoftDes3函数名称：int PubSoftDes3(const char* psKey,const char* psSrc,char *psDest);函数介绍：3Des软加密函数描述：无入口参数：psKey 明文密钥（16字节BCD码）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其

16、它失败3.21 PubSoftUnDes3函数名称：int PubSoftUnDes3(const char* psKey,const char* psSrc,char *psDest);函数介绍：3Des软解密函数描述：无入口参数：psKey 明文密钥（16字节BCD码）psSrc 数据（8字节BCD码）出口参数：psDest 密文 （8字节BCD码）返 回 值：APP_SUCC成功 其它失败 4 接口测试用例（举例） 4.1初始化密码键盘sPinPadMode = SECRITY_MODE_INSIDE；STPINPADPARAM stPinpadParam = PORT_NUM_COM2

17、,60,0x00,0x01,0x01,0x04," "/*<仅对证通的密码键盘有用*/"",PINPAD_HY, /*<PINPAD_HY,*/1,0,0,1,""nRes = PubInitSecrity(sPinPadMode,&stPinpadParam);if(nRes != APP_SUCC)PubMsgDlg("InitSecrity error", NULL, 0, 0);return -1;elsePubMsgDlg("InitSecrity SUCC", N

18、ULL, 0, 0); 4.2 安装主密钥nRet = PubLoadMainKey(nKeyIndex,szBcdMainKey, nLen);if (nRet != APP_SUCC)PubDispErr("安装密钥失败");return APP_FAIL;SetVarMainKeyNo(nKeyIndex); 4.3 安装工作密钥GetVarMainKeyNo(&nMainKeyNo);PubSetCurrentMainKeyIndex(nMainKeyNo);nRet = PubLoadWorkKey(KEY_TYPE_PIN, tpke, nKeyLen,

19、 tpkcv);if (nRet != APP_SUCC)PubMsgDlg(pszTitle, "PIN密钥下装失败", 3, 10);return APP_FAIL; 4.4 取PinGetVarMainKeyNo(&nMainKeyNo);PubSetCurrentMainKeyIndex(nMainKeyNo);nRet = PubActiveKey(DESMODE_3DES = GetVarEncyptMode() ? DESMODE_3DES : DESMODE_DES, nMainKeyNo, KEY_TYPE_PIN);if (nRet != APP

20、_SUCC)PubMsgDlg("输入密码", "密码键盘激活失败，请重新签到", 3, 10);return APP_FAIL;nRet = PubGetPin(pszPin, &nPinLen, nMode, pszPan, pszAmount, PIN_MAX_LEN, PIN_MIN_LEN);if (nRet != APP_SUCC)if (YES = GetVarIsPinpad()PubClrPinPad();if (nRet = APP_QUIT)return APP_QUIT;/调用密码错误信息PubDispErr("

21、输入密码");return APP_FAIL; 4.5 取MacGetVarMainKeyNo(&nMainKeyNo);PubSetCurrentMainKeyIndex(nMainKeyNo);nRet = PubActiveKey(DESMODE_3DES = GetVarEncyptMode() ? DESMODE_3DES : DESMODE_DES, nMainKeyNo, KEY_TYPE_MAC);if (nRet != APP_SUCC)PubMsgDlg("输入密码", "密码键盘激活失败，请重新签到", 3, 10

22、);return APP_FAIL;nRet = PubCalcMac(MAC_TYPE_ECB, psData, *pnDataLen, psData+(*pnDataLen);if (nRet != APP_SUCC)return nRet; 4.6 硬加密PubDes、PubUnDes、PubDes3、PubUnDes3nRet = PubDes3(KEY_TYPE_TRACK, szTrackBlock, szTrackBlock_Enc);if(nRet != APP_SUCC)PubMsgDlg(NULL,"磁道加密失败",3,30);return APP_FA

23、IL; 4.7 软加密 PubSoftDes、PubSoftUnDes、PubSoftDes3、PubSoftUnDes3PubSoftDes(szBcdMainKey, szBcdMainKey, szMainKey) 5 移植相关（重要） 新密钥体系的安全库推出的用意旨在提高开发效率，降低应用的难度，新安全库跟旧的密码键盘库的区别，及新安全库的特点 有以下几点：1、 新安全库支持外接和内置的用法，看到一些早期的应用程序内置的写法不统一，跟不同开发人员的风格就有一套自己的内置写法，有的甚至把工作密钥保存在文件中，或者以明文方式加载工作密钥，这是绝对不允许的；新安全库提供了内置和外接统一的接口

24、，可直接调用使用。2、 对#ifdef、#endif 彻底说NO，我讨厌各种标志；早期的应用程序里面看到最多的#ifdef(SUPPORT_PINPAD)。else#endif。现在不用这么写了，直接调用安装如上4.2、4.3的接口测试用例，只是要注意的是PubSetCurrentMainKeyIndex(nMainKeyNo)的索引要设置对，这个索引在安装完主密钥后要保存起来，在使用的时候在取出来设置这个索引；3、 安装主密钥的时候不用在清空对应索引的密钥了，直接调用；如需要清空全部的密钥区调用PubClearKey；4、 需要注意的是移植早期的应用程序在系统管理员操作设置内置还是外接密码键盘的的时候，要调用一下PubInitSecrity初始化，是内置还是外接是通过这个函数初始化传入的。当然在有的情况下如果不知道该用内置还是外接的时候PubInitSecrity这个函数的参数设置成SECRITY_MODE_ALL也是可以的，直接让系统去判断该内置还是外接，但是这做法不推荐。最好明确指定是内置还是外接，可以减少初始化时间；5、 从早期应用程序移植到安全库上涉及密钥的修改有以下几点（包括但不限于）： 1通过系统管理员手工输入主密钥 2通过系统管理员通过母POS导入主密钥 3通过系统管理员切换内置和外接时候注意要初始化 4签到时候工作密钥下发的安装